Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ireal-mcp Create a chord chart for 'Blue Bossa' with 4 measures per line"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Builds piano-friendly iReal Pro chord charts — laid out at a fixed 4 measures per line, the way a player reads them off the stand. It produces a tappable irealb:// import link, a standalone HTML chart, a harmonic analysis (Roman numerals + chord-scales + jam plan), and an ASCII layout preview.
Open ireal-studio.html in any web browser (double-click it). Type a song, press Make chart, and tap Open in iReal Pro on your phone/iPad. It's one self-contained file — works offline, nothing to install, no server, your charts never leave the page.
Don't have the file yet? Run
npm run build:webonce (or double-clicksetup.commandon a Mac) to producedist-web/ireal-studio.html, then share/keep that single file.
The rest of this README is for the Claude (MCP) integration and the optional always-on LAN server — power-user routes. On a Mac you can just double-click setup.command, which installs everything and prints exactly what to paste into Claude.
Related MCP server: midi-composer-mcp
iReal Pro lays a chart out as a grid of 16 cells per line; a chord or a space takes one cell, while barlines, time signatures, rehearsal marks and staff text are free. Left alone, the app packs measures of differing widths and the line breaks wander.
This server makes the layout deterministic: every measure is padded to exactly 16 / measuresPerLine cells (4 cells with the default 4 measures/line), so the app always wraps where you expect. The result reads like a clean fake-book page. You can change the density with measuresPerLine (must divide 16: 1, 2, 4, 8, 16).
The server is plain Node + stdio + the official MCP SDK, so it runs anywhere Node runs and works with any MCP client that supports stdio servers (Claude Code, Claude Desktop, Cursor, Windsurf, …).
Once published to npm (see "Publishing" below), no clone or build is needed — point any client at npx. This config is identical on every OS:
{
"mcpServers": {
"ireal": { "command": "npx", "args": ["-y", "ireal-mcp"] }
}
}Claude Code: claude mcp add ireal -- npx -y ireal-mcp (the -- is required so the flags go to npx, not to claude).
From source (until it's on npm) — same on all three OSes:
git clone <repo> && cd ireal-mcp
npm install # runs the build automatically (prepare script)Then point your client at the absolute path:
{ "mcpServers": { "ireal": { "command": "node", "args": ["/abs/path/ireal-mcp/dist/index.js"] } } }Or via the CLI (note the -- before the command): claude mcp add ireal -- node /abs/path/ireal-mcp/dist/index.js
Mac shortcut: double-click
setup.command— it installs, builds, and prints the exact config. (Windows/Linux: use thegit clonesteps above; a one-click installer for those is a TODO. The optional always-on LAN server's auto-start is currently Mac-only via launchd — on Windows/Linux runnpm run servemanually, or wire it to Task Scheduler / systemd.)
npx install everywhere)npm publish ships the built dist/ (the prepare script builds it; prepublishOnly runs typecheck + tests first). After that, anyone on any OS installs via the npx config above — no clone, no build.
The companion HTTP server makes every saved chart reachable from other devices (your iPad/phone with iReal Pro) at a stable address:
npm run serve # binds 0.0.0.0:1357, prints the LAN URLs to useIt reads the chart library on disk per request, so charts the MCP tools save appear immediately. On startup it prints something like:
ireal-mcp HTTP server listening on port 1357
Reachable at:
http://192.168.68.73:1357
http://your-mac.local:1357Open that URL on a device with iReal Pro and tap import to load a chart.
Route | Purpose |
| Index of every chart + "open all as one iReal Pro playlist" |
| View a chart (layout preview + import button) |
| Redirects straight to the |
| Redirects to an |
Config (env vars): IREAL_PORT (default 1357), IREAL_LIBRARY (default
~/.ireal-mcp/charts).
npm run install-service # writes & loads a launchd LaunchAgent (macOS)This installs ~/Library/LaunchAgents/com.ireal-mcp.server.plist with
KeepAlive so the server starts at login and restarts if it dies. Logs go to
~/.ireal-mcp/server.log. To preview the plist without installing:
node scripts/gen-launchd.mjs. To remove:
launchctl unload ~/Library/LaunchAgents/com.ireal-mcp.server.plist.
Add to your client config (Claude Desktop / Claude Code .mcp.json, etc.):
{
"mcpServers": {
"ireal": {
"command": "node",
"args": ["/absolute/path/to/ireal-mcp/dist/index.js"]
}
}
}Or run directly with npx ireal-mcp once published.
Tool | What it does |
| Build a chart from structured |
| ASCII layout grid only — fast iteration while writing chords (no save). |
| List saved charts with their slugs and served URLs. |
| Remove a chart from the library by slug. |
| Report the library path, port, and LAN URLs where the server is reachable, plus the start command. |
| Parse an existing |
| The built-in iReal Pro styles (Jazz / Latin / Pop). |
| Valid chord roots, qualities, keys, and time signatures, so generated charts use legal symbols. |
A chart is title + optional composer/style/key/bpm/timeSignature/measuresPerLine, plus either:
measures (preferred): an array where each measure is { chords: ["A-7","D7"], section?, open?, close?, ending?, staffText?, noChord?, ... }. The server owns the layout and encoding.
raw: a raw iReal Pro progression string, used verbatim (power users).
A 12-bar B♭ blues:
{
"title": "Blues for Probe",
"composer": "Chris Farrell",
"style": "Medium Swing",
"key": "Bb",
"measures": [
{"chords": ["Bb7"]}, {"chords": ["Eb7"]}, {"chords": ["Bb7"]}, {"chords": ["Bb7"]},
{"chords": ["Eb7"]}, {"chords": ["Eb7"]}, {"chords": ["Bb7"]}, {"chords": ["G7"]},
{"chords": ["C-7"]}, {"chords": ["F7"]}, {"chords": ["Bb7","G7"]}, {"chords": ["C-7","F7"]}
]
}Produces:
| Bb7 | Eb7 | Bb7 | Bb7 |
| Eb7 | Eb7 | Bb7 | G7 |
| C-7 | F7 | Bb7 G7 | C-7 F7 |Root + quality + optional /bass: C, C-7, C^7, C7b9, C-7/Bb. Alternate chords in parentheses: (Db^7). No chord: use "noChord": true. Custom/free-text qualities: wrap in asterisks, e.g. C*lyd*. Call list_chord_qualities for the full vocabulary.
{"chords": ["C^7"], "section": "A", "open": "{"} // start an A section + repeat
{"chords": ["G7"], "ending": 1, "close": "}"} // first ending, close repeat
{"chords": ["G7"], "staffText": "D.C. al Coda", "coda": true}obfuscate.ts — port of the irealb:// scrambling (magic prefix 1r34LbKcu7 + literal substitutions + the symmetric 50-byte "hussle"). Verified against the published reference vector and round-tripped.
layout.ts — distributes each measure's chords across the fixed cell budget (1/2/4 chords map cleanly; dense measures comma-pack at small size) and assembles the progression with barlines, sections, time signatures and endings.
url.ts — builds and parses both URL schemes (10-field modern, 6-field legacy), composer/title sort-ordering, percent-encoding.
render.ts — ASCII grid + standalone HTML.
npm test # vitest: obfuscation vectors, layout cell-counts, URL round-trips
npm run typecheck
npm run dev # run from source with tsxFormat details from the iReal Pro custom-URL protocol and the reference
implementations under docs/ (pyrealpro, Data::iRealPro, musicxml-irealpro).
MIT
Harmonic analysis to help plan a solo: Roman numerals, chord function, a chord-scale recommendation per chord (with the actual scale notes), detected ii–V(–I) cells, and a short jam plan. Pass slug to analyze a saved chart, or pass key + measures to analyze inline.
| Name | Required | Description | Default |
|---|---|---|---|
| bpm | No | Tempo in BPM (optional). | |
| key | No | Key signature, e.g. "Bb" or "D-" for minor. Default "C". | |
| raw | No | Raw iReal Pro progression string (power users). Used verbatim; mutually exclusive with `measures`. | |
| slug | No | Slug of a saved chart to analyze (see list_charts). | |
| style | No | iReal Pro style, e.g. "Medium Swing". See list_styles. Default "Medium Swing". | |
| title | Yes | Song title. | |
| variant | No | Which reading this is. By convention chart every song twice: 'straight' (real transcription, not dumbed down) and 'embellished' (richer qualities/substitutions, SAME harmonic rhythm — no faster to play). Sets the slug suffix and a badge. | |
| composer | No | Composer "First Last" (reordered to "Last First" for sorting). | |
| measures | No | Structured measures (preferred). Mutually exclusive with `raw`. | |
| timeSignature | No | Default time signature "n/d". Default "4/4". | |
| measuresPerLine | No | Measures per line; padded so the app wraps consistently. Must divide 16. Default 4 (piano-reading sweet spot). | |
| reorderComposer | No | Reorder composer to "Last First" for sorting. Default true. Set false for band names (e.g. "Black Sabbath"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the main outputs and the two input modalities. With no annotations, the description carries full burden for behavioral traits. It is transparent about what the tool returns but does not mention potential errors, prerequisites, or side effects. Still, the core behavior is well-covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise (~50 words), front-loaded with the main purpose, and each sentence adds distinct value. No redundant or superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (12 parameters, no output schema), the description explains the output content and the primary input modes. It omits some optional parameters (bpm, style, etc.), but these are fully documented in the schema. Overall, it provides enough context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds a high-level summary of the two input modes but does not significantly deepen understanding of individual parameters beyond what the schema already provides. Minimal extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it performs harmonic analysis for solo planning, listing specific outputs (Roman numerals, chord function, chord-scale recommendations, ii-V-I detection, jam plan). Distinguishes two input modes (slug vs inline key+measures). No sibling tool does analysis, so purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes when to use (for harmonic analysis) and how to use (via slug or key+measures). Does not explicitly state when not to use, but no alternative analysis tool exists among siblings, so context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build an iReal Pro chord chart from structured measures (or a raw progression). Every measure is padded to a fixed cell width so iReal Pro wraps to exactly measuresPerLine measures per line (default 4). By default the chart is SAVED to the on-disk library and served by the standalone HTTP server (so it's reachable from other devices on the network). Returns a modern irealb:// import link, a legacy irealbook:// link, the served URLs, an ASCII layout preview, and validation warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| bpm | No | Tempo in BPM (optional). | |
| key | No | Key signature, e.g. "Bb" or "D-" for minor. Default "C". | |
| raw | No | Raw iReal Pro progression string (power users). Used verbatim; mutually exclusive with `measures`. | |
| save | No | Save to the library and serve over HTTP. Default true. Set false for a one-off (use preview_chart for pure iteration). | |
| slug | No | URL/file slug for the saved chart (defaults to a slug of the title). Reusing a slug overwrites. | |
| style | No | iReal Pro style, e.g. "Medium Swing". See list_styles. Default "Medium Swing". | |
| title | Yes | Song title. | |
| variant | No | Which reading this is. By convention chart every song twice: 'straight' (real transcription, not dumbed down) and 'embellished' (richer qualities/substitutions, SAME harmonic rhythm — no faster to play). Sets the slug suffix and a badge. | |
| composer | No | Composer "First Last" (reordered to "Last First" for sorting). | |
| measures | No | Structured measures (preferred). Mutually exclusive with `raw`. | |
| timeSignature | No | Default time signature "n/d". Default "4/4". | |
| outputHtmlPath | No | If set, also write a standalone HTML copy to this arbitrary path. | |
| measuresPerLine | No | Measures per line; padded so the app wraps consistently. Must divide 16. Default 4 (piano-reading sweet spot). | |
| reorderComposer | No | Reorder composer to "Last First" for sorting. Default true. Set false for band names (e.g. "Black Sabbath"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses padding behavior, default saving to disk and serving over HTTP, overwriting on slug reuse, and return types including warnings. However, it does not mention potential destructive side effects of overwriting or permission requirements, which would warrant a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that front-loads the core purpose and then logically explains padding, saving behavior, and return value. It is concise and avoids redundancy, though splitting into bullet points could enhance readability for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main behavioral aspects and return value adequately, but does not summarize the 14 parameters into logical groups (e.g., metadata, structure, output options). Given the high parameter count and no output schema, the description could be more complete by giving an overview of parameter categories to help the agent understand the tool's full capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter has a description. The tool description adds context beyond the schema, such as the padding mechanism, default measuresPerLine division constraint, and the variant convention (straight vs embellished). This extra value justifies a score above baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool builds an iReal Pro chord chart from structured measures or raw progression, and explicitly distinguishes preview_chart for iteration. It uses a specific verb ('Build') and identifies the resource ('iReal Pro chord chart') and the input format, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies when to use this tool (building charts from measures or raw progression) and when not to (use preview_chart for one-off previews). It explains the default save and serve behavior, mutual exclusivity of 'raw' and 'measures', and the return value, providing clear guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse an existing irealb:// or irealbook:// URL (or HTML containing one) back into its title, composer, style, key, the raw progression, and a best-effort measure list — useful for editing an existing chart.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | An irealb:// or irealbook:// URL, or HTML/text containing one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions a 'best-effort measure list' which acknowledges potential limitations, but does not explicitly confirm the operation is read-only or describe other behavioral aspects like error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a clear verb and list of outputs, making it concise and front-loaded. It could be slightly more structured, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description lists the return components (title, composer, etc.) sufficiently. It covers input format and output, but lacks details on error cases or edge scenarios, which are less critical for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'url', and the description's explanation matches the schema description exactly, adding no additional value beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool parses an iReal Pro URL into components like title, composer, style, etc. It uses specific verbs and resources, but does not explicitly differentiate from sibling tools like create_chart or analyze_chart, which could have overlapping contexts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for editing existing charts by decoding their URLs, but does not explicitly state when to use this over siblings or provide exclusions. The context is implied but not detailed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a chart from the library by slug (deletes its .json and .html).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The slug of the chart to delete (see list_charts). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides some behavioral context by mentioning specific deleted files (.json and .html). However, it does not disclose whether deletion is permanent, requires authentication, or has other side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is direct and free of extraneous information. All parts earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (1 param, no output schema, no annotations), the description is fairly complete. It covers what gets deleted but would benefit from stating that the action is irreversible.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the slug parameter described as 'The slug of the chart to delete (see list_charts)'. The description adds no further semantic meaning to the parameter beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (remove), the resource (chart from library), and specifics about what files are deleted (.json and .html). It effectively distinguishes from sibling tools like create_chart or list_charts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. It implicitly references list_charts for obtaining the slug, but lacks context on prerequisites, when not to use, or potential impacts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all charts in the on-disk library, with their slugs and served URLs.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description must convey behavioral traits. It indicates a read-only operation ('List all charts'), implying no side effects. However, it does not disclose details like permission requirements, rate limits, or whether the list is subject to pagination, leaving some uncertainty for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded with the key action. It contains no redundant words and efficiently conveys the purpose and output. Every part of the sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and the simplicity of the tool (zero parameters), the description is mostly complete. It explains what the tool lists and what information is returned. However, it could be improved by noting behavior when the library is empty or if there are any error conditions, but for a trivial listing tool, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters with 100% schema description coverage (since there are none). The description adds no parameter details, but this is acceptable as there are no parameters to explain. A score of 4 reflects that the description does not need to compensate for missing parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List all charts in the on-disk library, with their slugs and served URLs.' It uses a specific verb ('List'), specifies the resource ('charts'), and includes scope ('on-disk library') and output details ('slugs and served URLs'), clearly distinguishing it from siblings like 'create_chart' or 'analyze_chart'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., when to list all charts vs. using 'analyze_chart' or 'preview_chart'). It also lacks context on prerequisites or limitations, such as the need for a populated library or performance considerations for large datasets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the chord roots, qualities, time signatures, and key signatures iReal Pro understands, so generated charts use valid symbols. Chord = root + quality + optional /bass (e.g. C-7/Bb).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, but the description only explains what is listed and does not disclose any behavioral traits such as read-only nature, authentication needs, or rate limits. The 'list' action implicitly suggests no side effects, but this is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the action ('List...'), and provides an illustrative example without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description is reasonably complete, specifying what is listed. However, it does not detail the output structure (e.g., list of strings vs objects), but the context signals (0 param, no nested objects) suggest simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the description does not need to explain inputs. The baseline for 0 parameters is 4, and the description adds value by explaining the output format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists chord roots, qualities, time signatures, and key signatures used by iReal Pro, and provides an example of chord notation. It distinguishes from siblings like list_styles and list_charts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage before generating charts with 'so generated charts use valid symbols', but it does not explicitly state when to use vs alternatives or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the built-in iReal Pro play-along styles, grouped by family (Jazz / Latin / Pop).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should fully describe behavior. It only mentions grouping by family but omits output format, whether it returns all styles, or any pagination. Insufficient for a standalone description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, efficient, front-loaded with verb and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description covers the essential purpose. However, it could be slightly more complete by mentioning that it returns a list of style names and families.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; baseline is 4. The description adds no parameter-specific meaning, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool lists built-in iReal Pro styles, grouped by family. Distinguishes from sibling tools like list_charts (which lists user charts) and list_chord_qualities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to guidance. The purpose is clear, but there is no discussion of alternatives or context for when to choose this over other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render only the ASCII layout grid for a chart (measuresPerLine per row) without building the import links. Fast way to check the 4-bars-per-line layout while iterating on chords.
| Name | Required | Description | Default |
|---|---|---|---|
| bpm | No | Tempo in BPM (optional). | |
| key | No | Key signature, e.g. "Bb" or "D-" for minor. Default "C". | |
| raw | No | Raw iReal Pro progression string (power users). Used verbatim; mutually exclusive with `measures`. | |
| style | No | iReal Pro style, e.g. "Medium Swing". See list_styles. Default "Medium Swing". | |
| title | Yes | Song title. | |
| variant | No | Which reading this is. By convention chart every song twice: 'straight' (real transcription, not dumbed down) and 'embellished' (richer qualities/substitutions, SAME harmonic rhythm — no faster to play). Sets the slug suffix and a badge. | |
| composer | No | Composer "First Last" (reordered to "Last First" for sorting). | |
| measures | No | Structured measures (preferred). Mutually exclusive with `raw`. | |
| timeSignature | No | Default time signature "n/d". Default "4/4". | |
| measuresPerLine | No | Measures per line; padded so the app wraps consistently. Must divide 16. Default 4 (piano-reading sweet spot). | |
| reorderComposer | No | Reorder composer to "Last First" for sorting. Default true. Set false for band names (e.g. "Black Sabbath"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses it does not build import links and outputs ASCII layout, but lacks details on permissions, error behavior, or output format specifics. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with main action, no filler. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters and no output schema, the description adequately explains the tool's purpose and output type but lacks details on output format or error handling. Adequate for a simple preview tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add parameter-specific meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Render' and resource 'ASCII layout grid for a chart', clearly stating what it outputs and what it omits ('without building the import links'). It implicitly distinguishes from siblings like create_chart by focusing on preview/layout checking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Fast way to check the 4-bars-per-line layout while iterating on chords', providing clear usage context. However, it does not explicitly state when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the library directory, the configured port, and the LAN URLs where the chart server is (or will be) reachable from other devices. Also gives the command to start the server.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description hints that the server may not be running ('or will be') but lacks details on side effects, permissions, or output format. For a reporting tool, more could be added.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy, front-loaded with key outputs. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the main reported items. Lacks any indication of output format or structure, which would be helpful for a reporting tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline of 4 applies. Description adds no param info, but none needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as reporting server information (library directory, port, LAN URLs) and the start command, distinguishing it from sibling tools that deal with charts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage: when you need server info versus chart operations. No explicit when-not-to-use or alternatives, but the simplicity reduces the need.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct operation: creating, analyzing, decoding, deleting, listing charts, querying chord qualities/styles, previewing layout, and server info. No functional overlap.
All tool names follow a consistent verb_noun snake_case pattern (e.g., analyze_chart, list_charts, list_styles). No mixing of conventions.
9 tools cover the core workflow of iReal Pro chart management without being excessive. Each tool serves a clear purpose, and the count is well-scoped.
The tool set covers create, read (list, decode, preview), analyze, and delete. A minor gap is the lack of an update/edit tool, requiring delete+create for modifications.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Create, validate, edit, export (markdown/svg/png/mermaid), and search JSON Canvas files.
Create narrated presentations from HTML, poll build status, list them, read one back as text.
Create, inspect, manage, and render charts and data visualizations as SVG/PNG or interactive embeds.
Excel analytics: inspect, query (JSON rows), charts, and JSON-to-xlsx workbook writing.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/seajaysec/ireal-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server