Click on "Deploy 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., "@ptna-enc-mcp 「貴婦人の乗馬」の正式タイトルと作曲家名をピティナで調べて"
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.
An MCP server for correcting notation inconsistencies in concert program piece names and composer names, using the Ptina Piano Music Encyclopedia as the canonical source.
When you submit an ambiguous piece name, it returns the official title, composer name, opus number, and performance duration from the source.
ℹ️ This is an unofficial personal tool for Ptina. The copyright of the encyclopedia's explanatory texts belongs to Ptina / the original authors. Please use it for personal proofreading only; do not republish the output or make excessive requests.
Tool | Purpose |
| Search for pieces by piece/composer keyword. Returns a list of candidates with official title, composer, opus, duration, and piece ID (core proofreading tool) |
| Retrieve details by piece ID (official title, original title, opus, opening description) |
| Search for composer names in official notation and IDs |
| Retrieve composer profile and list of works |
If a program says "ブルグミュラー 貴婦人の乗馬" →
search_pieces("ブルグミュラー 貴婦人の乗馬") →
returns official title 25の練習曲 貴婦人の乗馬, composer ブルクミュラー（ブルグミュラー）,
opus Op.100-25. Adopt this as the canonical notation.
Related MCP server: MusicBrainz MCP Server
cd /Users/miku/ptna-enc-mcp
python3 -m venv .venv
.venv/bin/pip install -e .claude mcp add ptna-enc -- /Users/miku/ptna-enc-mcp/.venv/bin/ptna-enc-mcpAfter registration, you can use it by asking Claude Code, e.g., "Look up the official notation for '◯◯' in the Ptina encyclopedia."
Check: if ptna-enc appears in claude mcp list, it is ready.
.venv/bin/python tests/test_parse.py # パーサ単体テスト(ネット不要)Variable | Default | Meaning |
|
| Minimum request interval (seconds) |
|
| Page cache validity period (seconds). |
|
| Cache storage location |
| Tool name + contact info | User-Agent sent with requests |
Since the site does not provide an API, this tool uses HTML scraping. It does not pre-crawl or maintain a database; it only "remembers pages it has seen" via a TTL cache (zero ongoing operation).
It fetches only one item at a time, sends a clearly identified custom User-Agent, and respects request intervals (politeness layer).
Advanced filters (genre/key/step level) are not supported in v1 because the site renders them via JavaScript.
For details, see docs/superpowers/specs/2026-08-07-ptna-enc-mcp-design.md.
作曲家IDからプロフィール概要と作品リストを取得する。
Args: composer_id: ピティナ曲事典の作曲家ID(URLの /persons/ の数字)。
Returns: {composer_id, name, profile, works: [{piece_id, title, url}], url}
| Name | Required | Description | Default |
|---|---|---|---|
| composer_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint. The description adds useful behavioral detail by specifying the exact return shape, including the works array structure and profile summary, and clarifies that the ID comes from the URL /persons/<ID>. No contradiction with annotations.
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 compact and well-structured, with a clear one-line purpose followed by Args and Returns sections. Every part adds necessary information with no redundancy.
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?
For a single-parameter read-only lookup, the description provides the input format and a complete return shape, which is sufficient despite the absence of an output schema. It does not mention pagination or limits, but those are not strongly implied for this operation.
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 0%, so the description must fully explain the parameter. It does: composer_id is identified as the Pitina composer encyclopedia ID and tied to the URL /persons/<ID> number format, which is precise and actionable.
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 a specific verb (取得する/retrieve) and resource (profile summary and work list for a composer by ID). It distinguishes itself from sibling tools like search_composers and search_pieces by focusing on lookup by a known composer ID rather than search.
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 use when the caller already has a composer_id, especially given the URL pattern hint. However, it does not explicitly state when to prefer this over search_composers or mention any alternative/exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
楽曲IDから詳細(正式タイトル・作曲家・作品番号・解説冒頭・URL)を取得する。
search_pieces で見つけた piece_id を渡し、1曲の正式情報を確定する用途。
Args: piece_id: ピティナ曲事典の楽曲ID(URLの /musics/ の数字)。
Returns: {piece_id, title, opus, composer, composer_id, description, url}
| Name | Required | Description | Default |
|---|---|---|---|
| piece_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=trueがアノテーションで示されており、このツールが読み取り専用であることは既知。その上で説明文は、返り値のフィールド一覧を提示している。ピースをIDで取得して正式情報を確定するという挙動がはっきりしており、追加文脈として有用。ただし、件が存在しない場合の挙動やエラーについては書かれていない。
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?
「取得する」を冒頭に置き、必要な仕様が簡潔にまとめられている。ArgsとReturnsが明快で、情報も重複せず、無駄なく本質的な内容だけが含まれている。
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?
1パラメータのみの単純な読み取り操作であり、説明文は入れない返り値のフィールドも挙げて、利用のタイミングとパラメータ参照元を提供している。返値の欠落やエラー処理までは触れていないが、このレベルの簡単な取得ツールにしては十分に完結している。
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?
input-schemaのpiece_idはinteger型のみの情報しかなく、パラメータ語法の説明が0%であるため、文章の説明の負荷が高い。しかしDescriptionは「権威に曲辞典のID」「URLの/musics/<ID>の数字」と、パラメーターの由来と意味を補っており、agentが正しいIDを渡すために十分な情報を提供している。
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?
「楽曲IDから詳細を取得する」と具体的な動詞とリソースを示しており、タイトル・作曲家・作品番号・URLなど取得内容も列挙している。「1曲の正式情報を確定する」という用途がsearch_piecesと明確に区別されており、ピアノの楽曲IDが対象であることも一意に分かる。
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?
「search_pieces で見つけた piece_id を渡し」と、利用する際の前提条件が明記され、どのようにIDを入手するかが示されている。一方で、search_piecesやget_composerなどの代替ツールを明示的に「この場合は使わない」と排除していない点はあり、完全な使い分けガイドとは言えない。
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
作曲家名で検索し、本家の正式名・作曲家ID・URLの候補を返す。
作曲家名の表記揺れ校正用(例:「ブルグミュラー」→正式表記の確認)。 内部的には楽曲検索結果から作曲家をユニーク抽出する。
Args: name: 作曲家名またはその断片。 limit: 返す件数の上限(既定20)。
Returns: {"count": int, "composers": [{composer_id, name, url}]}
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context beyond the readOnlyHint annotation: it explains that results are extracted uniquely from piece search results and that this is for spelling-variant verification. No contradiction with annotations is present.
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 well-organized with a clear purpose statement, usage context, and structured Args/Returns sections. Every sentence adds value, and the key use case is front-loaded.
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 two simple parameters, no output schema, and readOnly annotations, the description covers purpose, parameters, return format, and usage rationale. Nothing essential for an agent to call the tool correctly is missing.
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?
With 0% schema description coverage, the description fully explains both parameters: name as 'composer name or fragment' and limit as 'max results returned, default 20'. This meaning is entirely absent from the schema, which only holds type and default.
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's function: searching by composer name and returning official name, composer ID, and URL candidates. It also specifies its intended use case (correcting orthographic variations) with an example, which distinguishes it from the sibling tools that target pieces or specific composers.
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 a concrete usage context (notation variation correction) and implicitly separates this from piece-search tools. However, it does not explicitly mention when to prefer get_composer over this or when not to use the tool, leaving some routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
曲名・作曲家名のキーワードでピティナ曲事典の楽曲を検索する。
表記揺れ校正の中心ツール。手元の曖昧な曲名(例:「ブルクミュラー 25の練習曲」)を 渡すと、本家の正式タイトル・作曲家名・作品番号・演奏時間・曲IDの候補一覧を返す。
Args: keyword: 検索語(曲名/作曲家名/その断片)。 limit: 返す件数の上限(既定20)。
Returns: {"count": int, "results": [{piece_id, title, title_en, composer, composer_id, opus, duration, url}]}
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| keyword | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already signal read-only and open-world behavior, so the bar is lower. The description adds meaningful context: it returns a candidate list of official titles, composer names, opus numbers, durations, and piece IDs, which would have been missing without an output schema. Some details like pagination or rate limits are omitted, but these are not essential here.
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 efficiently structured with a one-line purpose, a short usage scenario, and clear Args/Returns sections. Every sentence earns its place, and the output format is explicitly described.
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?
For a two-parameter read-only search tool with no output schema, the description is complete: it explains what input it expects, what the output looks like, and the intended use case. There are no significant missing details an agent would need to select and call this 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 0%, so the description must explain parameters, and it does. It clarifies 'keyword' as a piece title, composer name, or fragment, which is more semantically meaningful than the schema property alone, and it defines 'limit' as the maximum number of returned items.
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 a specific verb and resource: searching ピティナ曲事典 pieces by keyword in the title or composer name, and clearly frames that this is the 'center tool' for normalizing orthographic variants. The scope on 楽曲 makes it distinct from sibling tools like get_piece or search_composers.
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 gives a clear usage scenario: it is the central tool for 表記揺れ correction, and you should pass an ambiguous piece name to get official candidates. It does not explicitly name alternatives or exclusion criteria, though the sibling list and the scope statement make those inferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_composerget_piecesearch_composerssearch_piecesScored across 4 tools
Each tool targets a distinct resource and action: search_pieces and get_piece operate on pieces, while search_composers and get_composer operate on composers. There is no overlap or ambiguity between the search and retrieval functions.
All tool names follow a consistent verb_noun pattern: search_pieces, get_piece, search_composers, get_composer. The verbs 'search' and 'get' are used uniformly to distinguish query operations from detail retrieval.
Four tools is a well-scoped set for a music encyclopedia lookup service. Each tool serves a clear, non-redundant purpose without feeling sparse or bloated.
The tool surface provides complete coverage for browsing the encyclopedia: searching and retrieving both pieces and composers. Search results expose IDs that feed into the get_* tools, and get_composer includes a works list, closing the loop for composer-to-piece exploration.
Repertoire & program archive for classical vocalists. Match works from posters, save, search.
Audio features + harmonic set-building for tracks by name/ISRC. Spotify audio-features replacement.
Search and resolve Naturepedia, Robbie's Razor, and GC-MRD-v2.0 canonical resources.
Search MusicBrainz artists, releases, works, labels; resolve ISRC/ISWC/barcode; fetch cover art.
