mcp-imslp

mcp-imslp

IMSLP（International Music Score Library Project）は、ペトルッチ音楽図書館とも呼ばれています。ボランティアが運営するクラシック音楽の無料図書館で、著作権が消滅した作品の楽譜、パート譜、編曲、録音と、各作曲家に関するページの記述を所蔵しています。各楽譜の著作権をカナダ、米国、欧州連合について個別に確認し、ページをCC BY-SA 4.0のもとで公開しています。

このサーバーはチャットクライアントを同図書館に接続します。所蔵作品や人物を検索したり、作品の作品番号、調、編成、作曲年を確認したり、所蔵する版をページごとに閲覧して出版社、編集者、著作権条件を確認したり、作曲家に関する図書館の記述を読んだり、ジャンル、調、編成を閲覧したりできます。図書館の情報を読み取り、リンクするもので、API キーもアカウントも必要ありません。

フランス語版

---

インストール

ワンクリックでインストール

Claude Code

claude mcp add imslp -- npx -y mcp-imslp

Claude Desktop、Cursor、および標準設定形式を使用するクライアント

{
  "mcpServers": {
    "imslp": {
      "command": "npx",
      "args": ["-y", "mcp-imslp"]
    }
  }
}

Node 24 以降が必要です。環境変数の設定は不要です。

Docker を使用する場合

{
  "mcpServers": {
    "imslp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-imslp:1.0.1"]
    }
  }
}

-i はプロトコルが流れる標準入力を開いたままにします。TTY はストリームを書き換えるため、-t は指定しません。コンテナに必要なのは imslp.org への HTTPS 送信接続だけです。ボリューム、ポート、認証情報は不要です。

npm を使わずにバンドルを使用する場合

最新リリースから mcp-imslp-1.0.1.mcpbをダウンロードして開きます。MCP バンドルに対応しているクライアントなら、npm も設定ファイルの編集も不要で、自動的にインストールされます。バンドルには依存関係が含まれているため、インストール時に何も取得しません。

質問できること

• 「IMSLP にはショパンの夜想曲がどのくらい収録されていますか？」
• 「エリック・サティのページを読んで、彼がいつ生きていたか教えてください。」
• 「ドビュッシーの《月の光》の版を、それぞれの出版者とともに一覧にしてください。」
• 「この曲のヘンレ版は、米国で自由に利用できますか？」
• 「ライブラリにある、チェロ独奏の作品を表示してください。」

通常は、検索から作品へと進みます。search_works で作品のページ名を調べ、get_work でそのページを読みます。人物の場合も同様に、search_people から get_person または list_person_works へと進みます。

ツール

ツール	機能
search_works	タイトル、作曲者、またはページ上の語句から作品のページを検索します。
search_people	作曲者、編集者、編曲者、演奏者が登録されているカテゴリを検索します。
get_work	作品の要素、セクション、著作権条件を読み取ります。
list_work_files	作品に収録されている版とそのファイルをページごとに表示します。
list_person_works	ライブラリで一人の人物に登録されている作品を読み取ります。
get_person	ライブラリにある人物の情報を読み取ります。
browse_category	ジャンル、調性、または楽器編成で登録されている作品を読み取ります。

作品は、ページのタイトルで指定します。形式は Work (Composer) で、たとえば Nocturnes, Op.9 (Chopin, Frédéric) のようになります。人物は、Category:Surname, Forename の形式でカテゴリを指定します。どちらも検索結果から取得でき、Category: のプレフィックスは省略できます。

ライブラリでは、作曲者が使用した言語で作品名を登録しています。そのため、Die Zauberflöte でオペラが見つかる一方、The Magic Flute ではその作品について書かれたページが見つかります。有名な作品の検索結果が少ない場合は、タイトルが別の言語で登録されていることを示しています。

search_works

作品のページ内のあらゆる場所にある語句を検索します。そのため、タイトル、作曲者、献辞のいずれからでも、該当する作品を検索できます。

引数	型	必須	機能
query	文字列、1～300文字	はい	作品のページ全体から検索する語句です。
limit	整数、1～50、デフォルトは 10	いいえ	返す行数です。
offset	整数、0以上、デフォルトは 0	いいえ	前回の応答の next_offset を使って、読み飛ばす行数です。

返される内容： get_work で使用する page、そのタイトルから読み取った work と composer、page_url、一致した語句の前後の文章を示す snippet、およびライブラリに記載されている size_bytes、words、last_edited を含む行です。ラッパーには returned、has_more、続きから読み取るためのオフセットである next_offset が含まれます。ライブラリでは検索に一致した件数を公開していないため、total は常に null です。Work (Composer) の形式でないタイトルでは composer が null になり、検索結果の行の要約に内容がなかった場合、snippet は null になります。

search_people

作曲家、編者、編曲者、演奏者を名前で検索します。ライブラリでは名前を独自の形式で記載し、姓を先にしています。そのため、綴りを推測しても見つからない場合でも、人物を検索できます。

引数	型	必須	機能
query	文字列、1～300文字	はい	ライブラリに登録された人物の中から検索する名前です。
limit	整数、1～50、デフォルトは 10	いいえ	返す行数です。
offset	整数、0以上、デフォルトは 0	いいえ	直前の応答の next_offset を使ってスキップする行数です。

戻り値： get_person と list_person_works で使用する category、接頭辞のない name、page_url、snippet、redirect_to を含む行です。redirect_to を持つ行は別のカテゴリを示しており、独自の作品は含まないため、指定されたカテゴリをたどってください。応答の外側の形式は search_works が返すものと同じで、total は同じ理由によりここでは null です。

get_work

1つの作品について、タイトルと別タイトル、作曲家、作品番号とカタログ番号、作曲年と初版刊行年、献辞、調、言語、台本作家、編成、楽章、初演、様式、時代を取得します。

引数	型	必須	機能
page	文字列、1～300文字	2つのうち1つ	Work (Composer) 形式で記載されたページタイトルです。
pageid	正の整数	2つのうち1つ	page の代わりに指定する、検索結果で返されたページ ID です。

戻り値： 上記のすべての項目を含みます。ページに記載がない項目はそれぞれ null となり、記載がある場合はページで使われている表記のまま返されるため、ca.1830 は ca.1830 のままです。これらに加えて、browse_category で使用する genre_categories、VIAF、LCCN、WorldCat、BNF、GND における作品の記録である external_links と authorities、サイトが各セクションに含まれる項目数を数えた sections、および異なる著作権表記ごとに該当する版数を含む copyright_summary があります。editions にはファイルを含むすべての版が格納されます。作品に5つを超える版がある場合、editions は null となり、editions_truncated は true になります。その場合は list_work_files でページを切り替えて取得できます。ここにたどり着くきっかけとなったタイトルは redirected_from に記載され、タイトルで指定した作品の場合、pageid は null です。

list_work_files

作品の楽譜と録音を、版ごとに読み取ります。版とは、ひとまとまりの条件のもとで公開されたファイル群です。出版社、編集者、著作権表示は版に属し、ファイルはその版の下にまとめられています。録音のまとまりには演奏者が記載され、著作権表示はありません。

引数	型	必須	説明
page	string、1～300 文字	いずれか一方	ページのタイトルです。Work (Composer) の形式で指定します。
pageid	integer、正の整数	いずれか一方	page の代わりに指定する、検索で返されたページ ID です。
section	string、1～80 文字	いいえ	ページ内のセクションを、そのページ独自の表記で指定します。Scores、Parts、Recordings、Arrangements and Transcriptions です。大文字と小文字は区別せずに照合されます。
limit	integer、1～100、デフォルトは 10	いいえ	返す版の数です。
offset	integer、0 以上、デフォルトは 0	いいえ	スキップする版の数です。

返される内容： section、publisher_info、editor、copyright、files を含む editions です。各ファイルには、imslp_id、description、format と format_code、pages、size_bytes、downloads、rating、uploader、uploaded_on、スキャンした図書館の略号と名称、およびそのファイルの著作権を IMSLP が審査中の場合に true となる blocked が含まれます。カウンターが表示されていない項目では downloads は null となり、投票がない場合は rating が null になります。さらに、editions_on_page、editions_in_section、returned、has_more、sections も返されます。指定した section に一致するものがない場合は、そのページに実際に存在するセクションが返されます。そのため、絞り込みを指定しても、楽譜のない作品として誤って読み取られることはありません。

list_person_works

図書館がある人物のもとに登録している作品を読み取ります。作曲家が書いた作品だけでなく、編集者、編曲者、演奏者としてクレジットされている作品も対象です。

引数	型	必須	説明
category	string、1～300 文字	はい	人物のカテゴリです。Category:Surname, Forename の形式で指定します。
limit	integer、1～100、デフォルトは 25	いいえ	返す行数です。
cursor	string、1～500 文字	いいえ	前回の応答で示された cursor を、提示されたとおりに渡します。

返される内容： page、work、composer、pageid、page_url を含む行と、続きを読み取るための has_more および cursor です。図書館はカテゴリ内の項目数を公開していないため、total は常に null です。図書館に存在しないカテゴリも、空のカテゴリと同じように応答します。そのため、行がない場合は search_people でスペルを確認してください。

get_person

図書館が人物について登録している内容を読み取ります。ページに表示される名前、記載されている生没年、登録時に使われている別の名前、その人物の記録を所蔵する目録、サイト外へのリンク先住所が含まれます。

引数	型	必須	説明
category	string, 1 to 300 characters	はい	人物のカテゴリです。Category:Surname, Forename の形式で指定します。

戻り値： category、姓を先にした catalogued_as、ページに表示される name、ページで使われている表現のままの life_dates、公開されている行のままの alternative_names と aliases、VIAF、LCCN、WorldCat、BNF、GND の目録と識別子を含む authorities、external_links、page_url です。生没年が記載されていないページでは、life_dates は null です。このツールは人物を読み取り、list_person_works は作品を読み取ります。

browse_category

1つのカテゴリ（ジャンル、調、編成、時代など）に登録されている作品を読み取ります。get_work は作品の genre_categories にこれらの名前を返し、そのいずれかを渡すと、図書館に登録されているカテゴリを取得できます。

引数	型	必須	説明
category	string, 1 to 300 characters	はい	図書館で使われている表記のカテゴリです。For piano、Nocturnes、B-flat minor などを指定します。
limit	integer, 1 to 100, default 25	いいえ	返す行数です。
cursor	string, 1 to 500 characters	いいえ	以前の回答で示された cursor を、そのまま渡します。

戻り値： list_person_works が返す行と、同じ has_more および cursor です。total は null です。図書館では一度に1つのカテゴリを読み取るため、ジャンルと楽器の両方を指定する質問には、どちらか一方を参照し、各作品についてもう一方を get_work で読み取って回答します。

著作権の状態

IMSLP の楽譜には管轄区域ごとの状態があり、図書館ではカナダ、米国、欧州連合を確認しています。Public Domain - Non-PD US と記されたファイルは、カナダと欧州連合では自由に利用できますが、米国では保護されています。このサーバーは、作品の copyright_summary と版の copyright に、管轄区域ごとに公開されている状態を報告します。また、restrictions には、その記載が対象外とする地域を示します。restrictions が空でも、IMSLP の確認対象外の国について何も示していません。

設定

すべての変数は任意です。クライアント設定の env ブロックで設定してください。

変数	デフォルト	説明
IMSLP_USER_AGENT	プロジェクトの識別情報	アプリケーション名を指定します。IMSLP が担当者に連絡できるよう、プロジェクトの識別情報が追加されます。
IMSLP_MIN_INTERVAL_MS	2500	リクエスト間の間隔です。2000～60000 の範囲で指定します。下限を下回る値は拒否され、この値が使われます。
IMSLP_TIMEOUT_MS	30000	1 回のリクエストのタイムアウトです。1000～120000 の範囲で指定します。
IMSLP_MAX_RETRIES	3	一時的な失敗の後に再試行する回数です。0～10 の範囲で指定します。
IMSLP_CACHE_TTL_MS	900000	ページをメモリに保持する期間です。0～86400000 の範囲で指定します。
IMSLP_CACHE_MAX_ENTRIES	100	一度にメモリに保持するページ数です。0～10000 の範囲で指定します。
IMSLP_LOG_LEVEL	error	silent、error、info、debug のいずれかを指定します。stderr に出力されます。

範囲外の値はデフォルト値に戻され、その理由が stderr に出力されます。

エラー

すべての失敗には、6 種類のコードのいずれかとメッセージが含まれます。また、役立つ場合は次に行う操作を示すヒントも含まれます。

コード	発生したこと	対処方法
not_found	IMSLP から応答がありましたが、指定したページが見つかりません。	search_works でタイトルを確認してください。
invalid_input	リクエストが送信される前に引数が拒否されました。	引数名が記載されたメッセージを確認してください。
rate_limited	IMSLP がこのクライアントに速度を落とすよう求めました。	ヒントに示された秒数だけ待ち、同じ引数で再度呼び出してください。作品は引き続きライブラリにあります。
parse_failure	ページは読み込まれましたが、想定されたコンテンツがありませんでした。	イシュートラッカーで報告してください。
network_error	リクエストが完了しませんでした。	少し待ってから再試行してください。
timeout	リクエストがタイムアウトしました。	IMSLP_TIMEOUT_MS を増やすか、取得する行数を減らしてください。

ライブラリとして

IMSLP を読み取るレイヤーは、リクエスト間隔の制御、キャッシュ、エラー処理を備え、プロトコルに依存しない形で単独で公開されています。

import { ImslpClient } from "mcp-imslp/client";

const client = new ImslpClient();
const { data, cached } = await client.getWork({ page: "Nocturnes, Op.9 (Chopin, Frédéric)" });
console.log(data.title, data.copyright_summary, cached);

renderPage、getWork、search、categoryMembers、getPerson はそれぞれ { data, cached } を返し、6 種類のコードのいずれかを持つ ImslpError をスローします。ここでも、リクエスト間には 2 秒の下限が適用されます。

リクエスト間隔と出典表示

IMSLP は robots.txt で Crawl-delay: 2 を公開しているため、リクエストは一度に 1 件ずつ送信され、少なくとも 2 秒の間隔が空きます。この最低間隔は、サーバーの設定にかかわらず維持されます。User-Agent の末尾には常にプロジェクトの識別情報と、連絡可能な担当者のアドレスが含まれます。

読み取りには、/api.php の MediaWiki API と、IMSLP が独自の IMSLP:API ページで案内している一覧エンドポイントを使用します。robots.txt では /index.php、/images/、/imglnks/、/wiki/File:、/works、/library/ が禁止されており、このサーバーはこれらの配下に URL を生成しません。代わりに作品ページへのリンクを返し、回答ではそのリンクを出典として示します。

ライブラリのページは CC BY-SA 4.0 のもとで公開されているため、このサーバーから表示する内容には IMSLP を明記し、元のページへのリンクを付けます。

プライバシー

このサーバーはあなたに関する情報を収集せず、作成者に何も送信しません。お使いのマシン上で動作し、imslp.org のみに接続します。動作中は回答をメモリ上に保持し、ディスクには何も書き込みません。 PRIVACY.md では、リクエストに含まれる情報と、それらを変更する設定について説明しています。

開発

npm install
npm run build:fixtures
npm test
npm run check

テストは生成されたフィクスチャを使って実行され、ネットワークリクエストは行いません。ライブテストスイートの npm run test:live は、各ルートにつき 1 回リクエストを送信し、毎晩サイト自体を対象に実行されます。

貢献

リポジトリで、イシューやプルリクエストを歓迎しています。 CONTRIBUTING.mdをご覧ください。

ライセンス

MIT ライセンスです。詳細はLICENSEをご覧ください。カタログとページは IMSLP およびその貢献者に帰属し、CC BY-SA 4.0 のもとで公開されています。

---

mcp-imslp（フランス語）

英語版

IMSLP（International Music Score Library Project）は、Petrucci Music Library とも呼ばれています。ボランティアが運営するクラシック音楽の無料ライブラリで、パブリックドメインとなった作品の楽譜、パート譜、編曲、録音と、各作曲家についてページに記載された情報を集めています。各楽譜の権利をカナダ、米国、欧州連合について個別に確認し、ページを CC BY-SA 4.0 のもとで公開しています。

このサーバーは、会話型クライアントとこのライブラリをつなぎます。収録されている作品や人物を検索したり、作品の作品番号、調性、編成、作曲年を確認したり、出版社や権利条件を含む作品の版を閲覧したり、作曲家についてライブラリに記載された情報を読んだり、ジャンル、調性、編成を調べたりできます。API キーやアカウントは不要で、ライブラリを読み取り、そのページへ案内します。

インストール

ワンクリックインストール

Claude Code

claude mcp add imslp -- npx -y mcp-imslp

Claude Desktop、Cursor、および標準設定形式に対応するすべてのクライアント

{
  "mcpServers": {
    "imslp": {
      "command": "npx",
      "args": ["-y", "mcp-imslp"]
    }
  }
}

Node 24 以降が必要です。環境変数の設定は不要です。

Docker を使う

{
  "mcpServers": {
    "imslp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-imslp:1.0.1"]
    }
  }
}

-i は、プロトコルの通信路となる標準入力を開いたままにするために指定します。TTY はストリームを書き換えるため、-t は指定しません。コンテナには、imslp.org への HTTPS 外向きアクセスのみが必要です。ボリューム、ポート、認証情報は必要ありません。

npm なしでバンドルをインストール

最新のリリース から mcp-imslp-1.0.1.mcpb をダウンロードして開きます。MCP バンドルに対応したクライアントなら、npm も設定ファイルの編集も不要で、自動的にインストールされます。バンドルには依存関係が含まれているため、インストール時に何もダウンロードされません。

できること

• 「IMSLP にはショパンの夜想曲が何曲ありますか？」
• 「エリック・サティのページを読んで、いつ生きていたか教えてください。」
• 「ドビュッシーの『月の光』の版を、それぞれの出版社とともに一覧表示してください。」
• 「この曲の Henle 版は、米国でパブリックドメインですか？」
• 「ライブラリにある、チェロ独奏のための作品を表示してください。」

通常は検索から作品へ進みます。search_works で作品のページを見つけ、get_work でそのページを読みます。人物についても同様に、search_people から get_person または list_person_works へ進みます。

ツール

ツール	機能
search_works	タイトル、作曲者、または語句から作品のページを見つけます。
search_people	人物が分類されているカテゴリを見つけます。
get_work	作品の特徴、セクション、権利を読み取ります。
list_work_files	作品の版とそのファイルを確認します。
list_person_works	ライブラリが人物の作品として分類している作品を読み取ります。
get_person	ライブラリにある人物の情報を読み取ります。
browse_category	ジャンル、調性、編成ごとに分類された作品を読み取ります。

作品は、作品名 (作曲者) の形式で書かれたページタイトルを指定します。例：Nocturnes, Op.9 (Chopin, Frédéric)。人物は、Category:姓, 名 の形式で書かれたカテゴリを指定します。どちらも検索結果から取得でき、Category: の接頭辞は省略できます。

ライブラリでは、作品は作曲者の言語でタイトルが付けられています。そのため、Die Zauberflöte で検索するとオペラが見つかり、La Flûte enchantée ではその作品について書かれたページが見つかります。有名な作品なのに検索結果が少ない場合は、別の言語のタイトルで登録されている可能性があります。

search_works

作品のページ内にある語句を、場所を問わず検索します。タイトル、作曲者、献辞などで検索すると、それらを含む作品が見つかります。

引数	型	必須	機能
query	文字列、1～300文字	はい	作品のページ内で検索する語句です。
limit	整数、1～50、既定値 10	いいえ	取得する行数です。
offset	整数、0以上、既定値 0	いいえ	スキップする行数です。前回の応答の next_offset を指定できます。

返される内容： page を含む行。これは get_work で使用します。work と composer はページタイトルから読み取られた情報で、page_url はページの URL、snippet は一致した語句の前後のテキストです。size_bytes、words、last_edited はライブラリが公開している値です。応答のエンベロープには returned、has_more、および再開位置を示す next_offset が含まれます。ライブラリは検索結果の件数を公開していないため、total は常に null です。タイトルが 作品名 (作曲者) の形式で書かれていない場合、composer は null になります。検索結果の行に要約できる内容がない場合、snippet は null になります。

search_people

作曲家、出版社、編曲者、演奏者を名前で検索します。 ライブラリでは名前を独自の表記で、姓を先にして記載しているため、推測した綴りでは見つからない人物も検索できます。

引数	型	必須	説明
query	文字列、1～300文字	はい	ライブラリ内の人物から検索する名前。
limit	整数、1～50、既定値は 10	いいえ	返す行数。
offset	整数、0以上、既定値は 0	いいえ	前回の応答の next_offset を使ってスキップする行数。

返される内容： get_person と list_person_works が参照する category を持つ行、接頭辞のない name、page_url、snippet、redirect_to です。redirect_to を持つ行は別のカテゴリーの代わりとなるもので、作品を含まないため、指定されたカテゴリーを参照してください。応答の構造は search_works と同じで、同じ理由により total は null になります。

get_work

作品のタイトルと別タイトル、作曲家、作品番号とカタログ番号、作曲年と初版発行年、献辞、調性、言語、台本作家、編成、楽章、初演、様式、時代を取得します。

引数	型	必須	説明
page	文字列、1～300文字	いずれか一方	作品名 (作曲家) の形式で記述されたページタイトル。
pageid	正の整数	いずれか一方	検索結果で返されたページ ID。

返される内容： 上記の各情報です。ページに記載がない場合は null となり、ページ上の表記がそのまま使われます。そのため、ca.1830 は ca.1830 のままです。さらに、browse_category が参照する genre_categories、作品の VIAF、LCCN、WorldCat、BNF、GND のレコードを示す external_links と authorities、サイトが各セクションに数える項目数を含む sections、異なる著作権表記ごとに、その表記を持つエディション数を示す copyright_summary も返されます。editions には各エディションとそのファイルが含まれます。エディションが5件を超える場合、editions は null となり、editions_truncated は true になります。その場合は list_work_files で一覧を取得してください。リダイレクトされてこのページにたどり着いた場合、redirected_from に要求されたタイトルが示されます。また、タイトルで指定した作品では pageid が null になります。

list_work_files

作品の楽譜と録音を、版ごとに読み取ります。 版とは、同じ条件で公開されたファイルのまとまりです。 出版社、校訂者、著作権表示は版に属し、ファイルはその下にまとめられます。録音のまとまりには演奏者が記載され、著作権表示はありません。

引数	型	必須	説明
page	文字列、1～300文字	いずれか一方	ページのタイトルです。Œuvre (Compositeur) の形式で記述します。
pageid	正の整数	いずれか一方	検索結果で返されたページ識別子です。
section	文字列、1～80文字	いいえ	ページに記載された表記のセクションです：Scores、Parts、Recordings、Arrangements and Transcriptions。大文字と小文字は区別されません。
limit	整数、1～100、デフォルトは 10	いいえ	返す版の数です。
offset	0以上の整数、デフォルトは 0	いいえ	スキップする版の数です。

返される内容： editions。それぞれに section、publisher_info、 editor、copyright、files が含まれます。ファイルには imslp_id、 description、format、format_code、pages、size_bytes、downloads、 rating、uploader、uploaded_on、デジタル化した図書館の略称と名称、 およびそのファイルの権利をIMSLPが確認している間は真となる blocked が含まれます。 カウンターのない項目では downloads は null、投票がない場合は rating は null です。さらに、editions_on_page、 editions_in_section、returned、has_more、sections も返されます。 該当するものがない section を指定すると、そのページにあるセクションが返されます。 そのため、絞り込み結果を「作品に楽譜がない」と誤読することはありません。

list_person_works

図書館が人物に関連付けている作品を読み取ります。作曲家が作曲した作品だけでなく、 校訂者、編曲者、演奏者としてクレジットされている作品も含まれます。

引数	型	必須	説明
category	文字列、1～300文字	はい	人物のカテゴリです。Category:Nom, Prénom の形式で記述します。
limit	整数、1～100、デフォルトは 25	いいえ	返す行数です。
cursor	文字列、1～500文字	いいえ	前回の応答で示された cursor を、そのまま再指定します。

返される内容： page、work、composer、pageid、page_url を含む行と、 続きの取得に使う has_more および cursor です。total は常に null です。 図書館はカテゴリの内容数を公開していません。存在しないカテゴリは空のカテゴリとして応答するため、 行が返されなかった場合は search_people で綴りを確認してください。

get_person

ライブラリーにある人物の情報を読み取ります。ページに掲載された名前、生没年月日、分類に使われている別名、その人物の記録がある登録簿、サイト外へのリンク先を取得します。

引数	型	必須	説明
category	文字列、1～300文字	はい	人物のカテゴリーです。Category:姓, 名 の形式で指定します。

返される内容： category、姓を先にした catalogued_as、ページに掲載されたとおりの name、ページの表記どおりの life_dates、公開されている行をそのまま示す alternative_names と aliases、登録簿名と VIAF、LCCN、WorldCat、BNF、GND の識別子を含む authorities、external_links、page_url です。生没年月日の記載がないページでは、life_dates は null になります。このツールは人物を読み取り、list_person_works は作品を読み取ります。

browse_category

カテゴリーに分類された作品を読み取ります。カテゴリーにはジャンル、調性、編成、時代などがあります。get_work は作品のこれらの名前を genre_categories で返すため、その名前を渡すと、ライブラリーに収録されているカテゴリーを検索できます。

引数	型	必須	説明
category	文字列、1～300文字	はい	読み取るカテゴリーです。ライブラリーでの表記を指定します。例：For piano、Nocturnes、B-flat minor。
limit	整数、1～100、既定値 25	いいえ	返す行数です。
cursor	文字列、1～500文字	いいえ	前回の応答で返された cursor をそのまま指定します。

返される内容： list_person_works が返す行と、同じ has_more および cursor が返されます。total は null です。ライブラリーでは一度に1つのカテゴリーを検索するため、ジャンルと楽器の両方を指定する質問には、どちらか一方で検索し、もう一方は各作品の get_work で読み取ります。

著作権ステータス

IMSLP では、楽譜に管轄区域ごとのステータスが付与されており、ライブラリーではカナダ、米国、欧州連合を確認します。Public Domain - Non-PD US と表示されたファイルは、カナダと欧州連合ではパブリックドメインですが、米国では保護されています。このサーバーは、作品については copyright_summary、版については copyright に、管轄区域ごとに公開されているステータスを返します。また、restrictions には、表示から除外される地域が示されます。restrictions が空でも、IMSLP が確認対象としていない国について何かを示すわけではありません。

設定

すべての変数は任意です。クライアント設定の env ブロックに設定します。

変数	デフォルト	説明
IMSLP_USER_AGENT	プロジェクトの識別情報	アプリケーション名を指定します。IMSLP が担当者に連絡できるよう、プロジェクトの識別情報が追加されます。
IMSLP_MIN_INTERVAL_MS	2500	リクエスト間隔です。2000～60000 の範囲で指定します。下限を下回る値は拒否され、この値が適用されます。
IMSLP_TIMEOUT_MS	30000	リクエストのタイムアウトです。1000～120000 の範囲で指定します。
IMSLP_MAX_RETRIES	3	一時的な失敗後の再試行回数です。0～10 の範囲で指定します。
IMSLP_CACHE_TTL_MS	900000	ページをメモリに保持する期間です。0～86400000 の範囲で指定します。
IMSLP_CACHE_MAX_ENTRIES	100	同時にメモリへ保持するページ数です。0～10000 の範囲で指定します。
IMSLP_LOG_LEVEL	error	silent、error、info、debug のいずれかを指定します。エラー出力に書き込まれます。

範囲外の値はデフォルトに戻され、その理由がエラー出力に書き込まれます。

エラー

各エラーには、6種類のコードのいずれかとメッセージが含まれます。次に取るべき対応が役立つ場合は、その案内も含まれます。

コード	発生したこと	対応
not_found	IMSLP から応答がありましたが、要求したページがありません。	search_works でタイトルを確認してください。
invalid_input	リクエストを送る前に引数が拒否されました。	引数名が記載されたメッセージを確認してください。
rate_limited	IMSLP がこのクライアントに速度を落とすよう求めています。	指定された秒数だけ待ってから、同じ引数で再度呼び出してください。作品は引き続きライブラリにあります。
parse_failure	ページは読み込まれましたが、想定した内容がありません。	イシュートラッカーで報告してください。
network_error	リクエストが完了しませんでした。	少し待ってから再試行してください。
timeout	リクエストがタイムアウトしました。	IMSLP_TIMEOUT_MS を増やすか、取得する行数を減らしてください。

ライブラリとして使用する

IMSLP を読み取るレイヤーは、プロトコルに依存せず、リクエスト間隔、キャッシュ、エラー処理を備えた単独のパッケージとして公開されています。

import { ImslpClient } from "mcp-imslp/client";

const client = new ImslpClient();
const { data, cached } = await client.getWork({ page: "Nocturnes, Op.9 (Chopin, Frédéric)" });
console.log(data.title, data.copyright_summary, cached);

renderPage、getWork、search、categoryMembers、getPerson はそれぞれ { data, cached } を返し、6種類のコードのいずれかを持つ ImslpError をスローします。リクエスト間に2秒の下限を設ける制限も、ここで適用されます。

アクセス頻度と帰属表示

IMSLP の robots.txt には Crawl-delay: 2 が設定されているため、リクエストは 1 件ずつ送信され、少なくとも 2 秒の間隔が空きます。この最低間隔は設定に かかわらず適用されます。User-Agent の末尾には、常にプロジェクトの識別情報と 担当者への連絡先が記載されます。

読み取りには MediaWiki API の /api.php と、IMSLP が IMSLP:API ページで 案内しているエンドポイントを使用します。robots.txt は /index.php、 /images/、/imglnks/、/wiki/File:、/works、/library/ を禁止しており、 このサーバーはこれらのパスを含む URL を生成しません。代わりに、作品ページへの リンクを返します。これはレスポンスで出典として示されるページです。

ライブラリのページは CC BY-SA 4.0 のもとで公開されているため、 このサーバーが返すものにはすべて IMSLP の帰属表示と元のページへのリンクが含まれます。

プライバシー

このサーバーはユーザーに関する情報を収集せず、作成者に情報を送信することも ありません。お使いのマシン上で動作し、imslp.org とのみ通信します。動作中は レスポンスをメモリに保持し、ディスクには何も書き込みません。PRIVACY.md では、 リクエストに含まれる情報と、それを変更する設定について説明しています。

開発

npm install
npm run build:fixtures
npm test
npm run check

テストは生成されたフィクスチャに対して実行され、リクエストは一切送信しません。 ライブテストの npm run test:live は、各ルートにつき 1 件のリクエストを送信し、 毎晩サイト自体に対して実行されます。

貢献

リポジトリで、課題の報告や変更の提案を歓迎します。 CONTRIBUTING.mdをご覧ください。

ライセンス

MIT です。LICENSEをご覧ください。カタログとページの権利は IMSLP と その貢献者に帰属し、CC BY-SA 4.0 のもとで公開されています。