mcp-imslp

mcp-imslp

IMSLP 又称佩特鲁奇音乐图书馆（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 会保持标准输入处于打开状态，协议通过标准输入传输；不使用 -t，因为 TTY 会改写数据流。容器需要能够通过 HTTPS 访问 imslp.org，除此之外无需任何配置：不需要卷、端口或凭据。

打包版本，无需 npm

从最新版本下载 mcp-imslp-1.0.1.mcpb 并打开。支持 MCP bundles 的客户端会自动安装，无需 npm，也无需编辑配置文件。此 bundle 包含所需依赖，因此安装时不会下载任何内容。

可以询问的内容

• “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	读取按体裁、调性或编制归类的作品。

作品通过其页面标题指定，格式为 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。

返回内容： 包含 page 的行，可传给 get_work；work 和 composer，从标题中读取；page_url；snippet，即匹配内容前后的文字；以及图书馆提供的 size_bytes、words 和 last_edited。结果封装还包含 returned、has_more 和 next_offset，其中 next_offset 是继续读取时使用的偏移量。total 始终为 null：图书馆不会公布搜索匹配结果的数量。标题不符合 Work (Composer) 格式时，composer 为 null；搜索结果中没有摘要文字时，snippet 为 null。

search_people

按姓名查找作曲家、编辑、改编者和演奏者。该曲库以自己的方式记录姓名，姓氏在前，因此即使无法猜对拼写，也能通过搜索找到对应的人。

Argument	Type	Required	What it does
query	string, 1 to 300 characters	yes	要在曲库人物中查找的姓名。
limit	integer, 1 to 50, default 10	no	返回的行数。
offset	integer, 0 or more, default 0	no	要跳过的行数，使用先前答复中的 next_offset。

返回内容： 每行包含 category，供 get_person 和 list_person_works 使用；不含前缀的 name；page_url；snippet；以及 redirect_to。带有 redirect_to 的行代表另一个类别，且自身不包含任何作品，因此请使用它所指向的类别。返回封装与 search_works 相同，total 在此处也为 null，原因相同。

get_work

读取一部作品的信息：标题和其他标题、作曲家、作品编号和目录编号、创作年份和首次出版年份、题献、调性、语言、剧作家、配器、乐章、首演、风格和时期。

Argument	Type	Required	What it does
page	string, 1 to 300 characters	one of two	页面标题，格式为 Work (Composer)。
pageid	integer, positive	one of two	搜索返回的页面 ID，可替代 page。

返回内容： 上述所有信息；如果页面未填写某项，该项为 null；所有内容均采用页面中的原始措辞，因此 ca.1830 会保持为 ca.1830。此外还包括 genre_categories，供 browse_category 使用；external_links 和 authorities，即作品在 VIAF、LCCN、WorldCat、BNF 和 GND 中的记录； sections，包含网站统计的各部分条目数；以及 copyright_summary，每种不同声明各列一项，并附带采用该声明的版本数。editions 包含所有版本及其文件；如果作品包含的版本超过五个，则该字段为 null，并将 editions_truncated 设为 true，随后可使用 list_work_files 分页获取。redirected_from 指明跳转至此处时请求的标题；对于通过标题查询的作品，pageid 为 null。

list_work_files

逐个版本读取一部作品的乐谱和录音。一个版本是一组按同一套条款发布的文件：出版商、编辑和版权声明属于该版本，文件则归在该版本之下。一组录音会标注表演者，但不附带版权声明。

参数	类型	必填	作用
page	string，1 至 300 个字符	二选一	页面标题，格式为 Work (Composer)。
pageid	正整数	二选一	搜索结果返回的页面 ID，可替代 page。
section	string，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、扫描文件的图书馆的缩写和名称，以及 blocked；当 IMSLP 正在审核该文件的版权时，该值为 true。如果条目未显示下载计数器，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	整数，1 至 100，默认值为 25	否	返回的行数。
cursor	string，1 至 500 个字符	否	先前的回答中提供的 cursor，按原样传回。

返回内容： 包含 page、work、composer、pageid 和 page_url 的行，以及用于继续读取的 has_more 和 cursor。total 始终为 null：图书馆不会公布某个类别包含多少条目。如果图书馆没有该类别，返回结果与类别为空时相同，因此没有行时应通过 search_people 检查拼写。

get_person

读取资料库中关于某个人的信息：页面显示的姓名、页面注明的生卒日期、收录该人物时使用的其他名称、记录该人物的登记册，以及页面指向站外的地址。

Argument	Type	Required	What it does
category	string, 1 to 300 characters	yes	此人的类别，格式为 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

读取某个类别下收录的作品：体裁、调性、编制或时期。get_work 会通过作品的 genre_categories 返回这些名称，传入其中一个名称即可查阅资料库中该类别下的内容。

Argument	Type	Required	What it does
category	string, 1 to 300 characters	yes	要查阅的类别，使用资料库中的原文：For piano、Nocturnes、B-flat minor。
limit	integer, 1 to 100, default 25	no	返回的行数。
cursor	string, 1 to 500 characters	no	传回先前答复中给出的 cursor，保持原样。

返回内容： list_person_works 返回的行，包含相同的 has_more 和 cursor，total 为 null。资料库一次只查阅一个类别，因此，若问题同时指定体裁和乐器，可先查阅其中一个类别，再通过每部作品的 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，写入 stderr。

超出范围的值会回退到默认值，原因会写入 stderr。

错误

每个故障都带有六种错误代码之一、一条消息，以及在有帮助时说明下一步操作的提示。

代码	发生了什么	如何处理
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 }，并抛出携带六种错误代码之一的 ImslpError。这里同样遵循两秒的请求间隔下限。

请求频率与署名

IMSLP 在其 robots.txt 中发布了 Crawl-delay: 2，因此请求会逐个发出，且每个请求之间至少间隔两秒，无论服务器如何配置，这个下限都始终有效。User-Agent 始终以项目标识和可联系到真人的地址结尾。

读取通过 MediaWiki API 的 /api.php 以及 IMSLP 在其自身的 IMSLP:API 页面中记录的列表端点进行。robots.txt 禁止访问 /index.php、/images/、/imglnks/、/wiki/File:、/works 和 /library/，本服务不会构建指向其中任何位置的地址：它会返回作品页面的链接，回答中引用的正是该页面。

图书馆以 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 会为每条路由发出一个请求，并每晚针对网站本身运行。

贡献

欢迎通过代码仓库提交问题和拉取请求。请参阅 CONTRIBUTING.md。

许可证

MIT，详见 LICENSE。目录和页面归 IMSLP 及其贡献者所有，以 CC BY-SA 4.0 许可发布。

---

mcp-imslp（法语）

英文版本

IMSLP，即国际乐谱图书馆项目，也称为 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 会保持标准输入处于打开状态，它是协议通道；省略 -t 是因为 TTY 会重写数据流。容器只需能够通过 HTTPS 访问 imslp.org，除此之外无需任何设置：不需要卷、端口或凭据。

打包分发，无需 npm

下载 最新发布版本 中的 mcp-imslp-1.0.1.mcpb 并打开。支持 MCP bundle 的客户端会自动安装，无需 npm，也无需修改配置文件。bundle 已包含其依赖项，因此安装时不会下载任何内容。

可以询问什么

• “IMSLP 收录了哪些肖邦夜曲？”
• “给我读读 Erik Satie 的页面，并告诉我他生活在哪个时期。”
• “列出 Debussy《Clair de lune》的各个版本，并说明每个版本由谁出版。”
• “这首曲子的 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；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。

返回内容： 包含 category 的行，get_person 和 list_person_works 会用到该字段；不带前缀的 name；page_url；snippet； 以及 redirect_to。带有 redirect_to 的行会取代另一类别，且不包含任何作品，因此请转到它所指向的类别。其外层结构与 search_works 相同，total 出于相同原因会设为 null。

get_work

读取一部作品的信息：标题及其其他标题、作曲家、作品编号和目录编号、创作年份和首次出版年份、题献、调性、语言、剧本作者、配器、乐章、首演、风格和时期。

参数	类型	必填	作用
page	字符串，1 至 300 个字符	二选一	页面标题，格式为 作品 (作曲家)。
pageid	正整数	二选一	搜索返回的页面标识符。

返回内容： 上述各项信息；若页面中未填写，则为 null，并保留页面上的原始写法，因此 ca.1830 仍为 ca.1830。此外还包括 genre_categories，供 browse_category 使用；external_links 和 authorities，即作品在 VIAF、LCCN、WorldCat、BNF 和 GND 中的记录；sections，包含网站统计的各部分条目数；以及 copyright_summary，按不同版权声明逐项列出，并注明采用该声明的版本数量。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、将其数字化的图书馆的缩写和名称，以及 blocked；在 IMSLP 核实该文件的版权期间，blocked 为 true。没有计数器的条目中，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:Nom, Prénom。

返回： 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。图书馆一次只读取一个类别，因此，同时提及流派和乐器的问题，可以通过遍历其中一个类别，再用 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，输出到错误输出流。

超出范围的值会恢复为默认值，原因会写入错误输出流。

错误

每种失败都包含六种错误代码之一、一条消息，以及在有帮助时给出的后续操作提示。

代码	发生的情况	如何处理
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 }，并会抛出带有六种错误代码之一的 ImslpError。两次请求之间至少间隔两秒的限制在此同样适用。

访问频率与署名

IMSLP 在其 robots.txt 中设置了 Crawl-delay: 2，因此请求会逐个发送，且两次请求之间至少间隔两秒；无论如何配置，这一下限都始终适用。User-Agent 始终以项目标识和一个可联系到真人的地址结尾。

读取通过 MediaWiki API /api.php 和 IMSLP 在其 IMSLP:API 页面上说明的入口点进行。robots.txt 禁止访问 /index.php、/images/、/imglnks/、/wiki/File:、/works 和 /library/，此服务不会构造这些路径下的任何地址：它会返回作品页面的链接，而响应中注明的来源正是该页面。

图书馆页面采用 CC BY-SA 4.0 许可发布，因此此服务返回的所有内容都会注明来源为 IMSLP，并链接到原始页面。

隐私

此服务不会收集您的任何信息，也不会向其作者发送任何信息。它在您的计算机上运行，只连接 imslp.org，仅在运行期间将响应保存在内存中，也不会向磁盘写入任何内容。PRIVACY.md 说明了一次请求会携带哪些信息，以及哪些设置会改变这一点。

开发

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

测试使用生成的 fixtures 运行，不会发送任何请求。实时测试套件 npm run test:live 会为每条路由发送一个请求，并且每晚针对网站本身运行一次。

贡献

欢迎在代码仓库中提交问题和修改建议。请参阅 CONTRIBUTING.md。

许可证

MIT，详见 LICENSE。目录和页面归 IMSLP 及其贡献者所有，采用 CC BY-SA 4.0 许可发布。