以ピティナ・ピアノ曲事典为「正典（主数据）」，用于校正音乐会节目中曲名・作曲家名表记不一致的 MCP 服务器。
输入模糊的曲名，即可返回本家的正式标题・作曲家名・作品编号・演奏时长。
ℹ️ 这是ピティナ非官方的个人工具。曲事典的解说文等著作权归ピティナ／原作者所有。 个人使用・校正是可以的，但请不要转载输出内容或进行大量访问。
工具 | 用途 |
| 按曲名/作曲家关键词搜索乐曲。返回正式标题・作曲家・opus・演奏时长・曲ID的候选列表（校正的核心） |
| 通过乐曲ID获取详细信息（正式标题・原题・opus・解说开头） |
| 搜索作曲家名的正式表记・ID |
| 获取作曲家简介＋作品列表 |
节目中写有「ブルグミュラー 貴婦人の乗馬」→
search_pieces("ブルグミュラー 貴婦人の乗馬") →
返回正式标题 25の練習曲 貴婦人の乗馬、作曲家 ブルクミュラー（ブルグミュラー）、
作品编号 Op.100-25。以此作为正典采用。
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-mcp注册后，在 Claude Code 的对话中提出「用ピティナ查一下『◯◯』的正式表记」即可使用。
确认：claude mcp list 中出现 ptna-enc 即表示成功。
.venv/bin/python tests/test_parse.py # パーサ単体テスト(ネット不要)变量 | 默认值 | 含义 |
|
| 最小请求间隔（秒） |
|
| 页面缓存有效期（秒）。设为 |
|
| 缓存保存位置 |
| 工具名＋联系方式 | 发送的 User-Agent |
由于该网站不提供 API，因此采用 HTML 爬取。不进行预先爬取／不持有 DB， 仅通过 TTL 缓存「记住曾经看过的页面」（零运维）。
每次仅获取1条，明确标注自定义 User-Agent 并遵守请求间隔（礼貌层）。
高级筛选（类型/调性/步骤等级）由网站通过 JS 渲染，v1 暂不支持。
详见 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.
Find the songwriter behind a name or IPI name number, under every spelling and number.
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 MusicBrainz artists, releases, works, labels; resolve ISRC/ISWC/barcode; fetch cover art.
