Skip to content

API Reference

Complete reference for all encoding-music-mcp tools.

Tool Catalog

Tool Parameters Returns Documentation
list_available_mei_files None dict with file lists Docs
get_mei_metadata filename: str dict with metadata Docs
analyze_key filename: str dict with key info Docs
get_notes filename: str dict with notes Docs
get_melodic_intervals filename: str dict with intervals Docs
get_harmonic_intervals filename: str dict with intervals Docs
get_melodic_ngrams filename: str, n: int = 4 dict with n-grams Docs

Discovery Tools

list_available_mei_files()

Discover all built-in MEI files.

Parameters: None

Returns: 

{
    "bach_inventions": List[str],      # 15 files
    "bartok_mikrokosmos": List[str],   # 19 files
    "morley_canzonets": List[str],     # 12 files
    "all_files": List[str]             # 46 files
}

Full Documentation →

Metadata Tools

get_mei_metadata(filename)

Extract metadata from MEI file header.

Parameters: - filename (str): MEI filename (e.g., "Bach_BWV_0772.mei")

Returns: 

{
    "title": str,
    "composer": str,
    "mei_editors": List[str],
    "xml_editors": List[str],
    "analysts": List[str],
    "publication_date": str | None,
    "copyright": str | None,
    "application": str | None
}

Full Documentation →

Analysis Tools

analyze_key(filename)

Detect musical key using music21.

Parameters: - filename (str): MEI filename

Returns: 

{
    "Key Name": str,              # e.g., "C major", "a minor"
    "Confidence Factor": float    # 0.0 to 1.0
}

Full Documentation →

get_notes(filename)

Extract all notes with pitch and octave.

Parameters: - filename (str): MEI filename

Returns: 

{
    "filename": str,
    "notes": str    # CSV representation
}

Full Documentation →

get_melodic_intervals(filename)

Calculate melodic intervals within voices.

Parameters: - filename (str): MEI filename

Returns: 

{
    "filename": str,
    "melodic_intervals": str    # CSV representation
}

Full Documentation →

get_harmonic_intervals(filename)

Calculate harmonic intervals between voices.

Parameters: - filename (str): MEI filename

Returns: 

{
    "filename": str,
    "harmonic_intervals": str    # CSV representation
}

Full Documentation →

get_melodic_ngrams(filename, n=4)

Find recurring melodic patterns.

Parameters: - filename (str): MEI filename - n (int, optional): N-gram length (default: 4)

Returns: 

{
    "filename": str,
    "n": int,
    "melodic_ngrams": str    # CSV representation
}

Full Documentation →

Common Patterns

Error Handling

All tools raise FileNotFoundError for invalid filenames:

try:
    result = analyze_key("nonexistent.mei")
except FileNotFoundError as e:
    print(f"File not found: {e}")

File Discovery Pattern

# Get all files
files = list_available_mei_files()

# Analyze each file
for filename in files["all_files"]:
    metadata = get_mei_metadata(filename)
    key_info = analyze_key(filename)
    print(f"{filename}: {metadata['title']} in {key_info['Key Name']}")

Interval Analysis Pattern

# Extract notes
notes = get_notes("Bach_BWV_0772.mei")

# Get melodic intervals
melodic = get_melodic_intervals("Bach_BWV_0772.mei")

# Get harmonic intervals
harmonic = get_harmonic_intervals("Bach_BWV_0772.mei")

# Find patterns
patterns = get_melodic_ngrams("Bach_BWV_0772.mei", n=4)

Data Formats

CSV Format

Interval tools return data in CSV format for efficient token usage:

Measure,Beat,1,2
1.0,1.0,Rest,Rest
1.0,1.25,C4,
1.0,1.5,D4,
  • Rows: Measure and beat positions (indexed)
  • Columns: Voice part numbers
  • Values: Notes, intervals, or patterns
  • Empty cells: Represented as blank (no NaN in CSV)

Interval Notation

  • Quality: M (major), m (minor), P (perfect), A (augmented), d (diminished)
  • Number: Scale degree (2, 3, 4, 5, 6, 7, 8+)
  • Direction: Positive (ascending), negative (descending)

Examples: M2, -m3, P5, M13

Type Hints

All tools use Python type hints:

from typing import Any

def analyze_key(filename: str) -> dict[str, Any]: ...
def get_melodic_ngrams(filename: str, n: int = 4) -> dict[str, Any]: ...