Skip to content

Tools Overview

encoding-music-mcp provides a suite of tools for analyzing MEI files. Tools work with the built-in MEI collection and MEI files registered during the current server session.

Available Tools

Discovery Tools

Tool Purpose Learn More
list_available_mei_files Browse and discover the 46 built-in MEI files Documentation

Upload Tools

Tool Purpose Learn More
register_mei_file_from_path Register a user-exposed local MEI path, with optional elicitation Documentation

Metadata Tools

Tool Purpose Learn More
get_mei_metadata Extract title, composer, editors, dates, and copyright info Documentation

Analysis Tools

Tool Purpose Learn More
analyze_key Detect musical key with confidence scores Documentation
get_notes Extract all notes with pitch and octave information Documentation
get_melodic_intervals Analyze melodic intervals within voices Documentation
get_harmonic_intervals Analyze harmonic intervals between voices Documentation
get_melodic_ngrams Find recurring melodic patterns Documentation
count_melodic_ngrams Count and rank melodic n-gram patterns Documentation
resolve_note_ids_for_highlight Resolve analysis locations to MEI note IDs for highlighting Documentation
get_melodic_ngram_matches Group note-ID spans by melodic n-gram pattern Documentation
get_first_occur_melodic_ngrams Find first-occurrence melodic patterns with playback positions Documentation
get_cadences Detect predicted cadences in Renaissance counterpoint Documentation

Notation Tools

Tool Purpose Learn More
show_notation Display rendered sheet music with interactive pagination Documentation
show_notation_highlight Display rendered notation with selected MEI note IDs highlighted Documentation

Visualisation Tools

Tool Purpose Learn More
plot_voice_ranges Display compact per-staff pitch ranges for a single score Documentation
plot_weighted_note_distribution Display a duration-weighted pitch-class radar chart for a single score Documentation
plot_melodic_ngram_heatmap Display top melodic n-gram spans across scores and staves Documentation
plot_sonority_ngram_progress Display low-line sonority n-grams by normalized score progress Documentation

Playback Tools

Tool Purpose Learn More
play_excerpt Render a score or excerpt to streamed audio playback Documentation
load_audio_resource Load prepared audio bytes for the playback widget Documentation

Tool Categories

Discovery

Tools for exploring the MEI collection:

Metadata

Tools for extracting descriptive information:

Musical Analysis

Tools for analyzing musical content:

  • analyze_key: Key detection using music21
  • Interval Analysis: Comprehensive interval analysis using CRIM Intervals
    • Notes extraction
    • Melodic intervals
    • Harmonic intervals
    • N-gram pattern matching
    • Cadence detection

Notation Display

Tools for viewing rendered sheet music:

Visualisation

Tools for viewing derived visual summaries:

Playback

Tools for listening to rendered score audio:

  • play_excerpt: Render an MEI score or excerpt as audio in an inline player

Tool Design Philosophy

All tools in encoding-music-mcp follow these principles:

1. Direct File Access

Tools read directly from disk with no intermediate caching, ensuring:

  • ⚡ Fast response times
  • 💾 Minimal memory usage
  • 🔄 Always up-to-date results

2. Structured Output

All tools return structured dictionaries with consistent keys:

{
    "filename": "Bach_BWV_0772.mei",  # Always included
    "key_name": "...",                 # Tool-specific data
    # ...
}

3. Error Handling

Tools provide clear error messages when files don't exist or can't be processed:

FileNotFoundError: Could not load MEI file: nonexistent.mei

4. Dataframe Format

Analysis tools return data in readable tabular format:

  • Rows: Measure and beat positions
  • Columns: Voice parts or analysis dimensions
  • Values: Musical data (notes, intervals, patterns)

Common Parameters

Most tools accept a filename parameter:

filename: str  # Name of the MEI file (e.g., "Bach_BWV_0772.mei")

For user-supplied files, call register_mei_file_from_path(file_path, filename) first, then pass the registered filename to analysis, notation, visualisation, or playback tools. Omit file_path to ask the user for it via elicitation when supported.

Analysis tools may accept additional parameters:

n: int  # For ngrams: length of patterns (default: 4)

Using Tools with AI Assistants

Natural Language Queries

Simply ask your AI assistant in natural language:

  • "What MEI files are available?"
  • "Analyze the key of Bach_BWV_0772.mei"
  • "Get melodic 5-grams from Bartok_Mikrokosmos_022.mei"

Direct Tool Invocation

MCP clients can also invoke tools directly:

{
  "tool": "get_mei_metadata",
  "arguments": {
    "filename": "Bach_BWV_0772.mei"
  }
}

Next Steps

  • Browse specific tool documentation using the navigation menu
  • Try the Quick Start guide for examples
  • Explore the MEI Resources available for analysis