内容
# 标签网格 MCP 服务器
[](https://www.npmjs.com/package/@labelgrid/mcp) [](https://github.com/labelgrid/labelgrid-mcp/actions/workflows/ci.yml) [](https://glama.ai/mcp/servers/@labelgrid/labelgrid-mcp)
`@labelgrid/mcp` — 官方的 [模型上下文协议](https://modelcontextprotocol.io) 服务器，为 [标签网格](https://labelgrid.com) 提供服务，这是一个音乐分发平台。将克劳德桌面、克劳德代码、光标或任何 MCP 客户端指向您自己的标签网格账户，并以自然语言管理您的音乐目录、发布、文件、分析、版税核算、网络钩子以及分发 — 它是 LabelGrid 公共 API 的一个薄且有类型的包装器，因此所有规则和验证都在服务器上进行。
## 快速入门
您需要一个 LabelGrid API 令牌（参见 [获取令牌](#获取令牌)）和 Node.js 20+。服务器按需通过 `npx` 运行 — 无需全局安装任何内容。
### 克劳德桌面 — 一键安装
最快捷的方式，无需配置文件的编辑：
1. 从 [最新版本](https://github.com/labelgrid/labelgrid-mcp/releases/latest) 下载 **`labelgrid.mcpb`**。
2. 双击它，或打开克劳德桌面 → **设置 → 扩展** 并将文件拖入其中。
3. 当提示时，粘贴您的 [LabelGrid API 令牌](#获取令牌) — 或留空并让聊天式引导设置帮助您创建令牌。
稍后要更新时，请下载更新的 `.mcpb` 并安装在旧版本上。更喜欢自己配置或使用不同的客户端？下面的手动 `npx` 设置在任何地方都适用。
### 克劳德桌面 — 手动配置
将以下内容添加到您的 `claude_desktop_config.json`（设置 → 开发者 → 编辑配置）：
```json
{
"mcpServers": {
"labelgrid": {
"command": "npx",
"args": ["-y", "@labelgrid/mcp"],
"env": {
"LABELGRID_API_TOKEN": "您的令牌"
}
}
}
}
```
重启克劳德桌面。您应该会看到标签网格工具出现。
### 克劳德代码
```bash
claude mcp add labelgrid -e LABELGRID_API_TOKEN=您的令牌 -- npx -y @labelgrid/mcp
```
### 光标
将以下内容添加到 `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（每个项目）：
```json
{
"mcpServers": {
"labelgrid": {
"command": "npx",
"args": ["-y", "@labelgrid/mcp"],
"env": {
"LABELGRID_API_TOKEN": "您的令牌"
}
}
}
}
```
### 首次运行 / 设置模式
如果您在没有 `LABELGRID_API_TOKEN` 的情况下启动服务器，它不会失败 — 它会以 **设置模式** 启动：完整的工具目录仍然列出，以便您查看服务器提供的内容，并且 `setup` 助手会引导您进行设置。 在此状态下，无法运行任何操作 — 每个目录工具都会返回设置指导。 只需让您的 AI 客户端 "设置标签网格"，它将帮助您创建令牌并将其添加到您的配置中。 一旦设置了令牌，请重启您的客户端，工具就会上线。
## 获取令牌
API 访问是 LabelGrid 的 [API 计划](https://help.labelgrid.com/en/integrations/api-overview) 的一部分 — 请参阅 [API 概述和快速入门](https://help.labelgrid.com/en/integrations/api-overview) 以了解 API 提供的内容以及如何激活它。
1. 登录到您的 LabelGrid 仪表板。
2. 进入 **个人资料 → API 令牌**。（如果您看不到此选项，则您的账户尚无 API 访问权限 — [API 概述](https://help.labelgrid.com/en/integrations/api-overview) 解释了如何获取它，或联系支持团队。）
3. 创建一个令牌并将其复制到您的客户端配置中作为 `LABELGRID_API_TOKEN`。
像对待密码一样保护令牌：它授予对您的目录的访问权限。 永远不要提交它或将其粘贴到共享聊天中。 您可以在同一屏幕上撤销令牌（或使用 `revoke_api_token` 工具）。
## 配置
所有配置都通过客户端配置中的环境变量进行。
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `LABELGRID_API_TOKEN` | — | **必填。** 您的 API 令牌。 |
| `LABELGRID_API_URL` | 生产 API | 覆盖 API 基本 URL。 |
| `LABELGRID_ENABLE_WRITES` | `true` | 安全写入（创建/更新草稿、标签、艺术家等）。设置为 `false` 仅读取。 |
| `LABELGRID_ENABLE_FULL_WRITES` | `false` | 启用完全写入 — 参见 [安全模型](#安全模型)。 还需要下面的确认。 |
| `LABELGRID_FULL_WRITES_ACK` | — | 必须与确认句子完全匹配才能启用完全写入。 |
| `LABELGRID_READ_ONLY` | `false` | 强制仅读取；覆盖两个写入标志。 |
| `LABELGRID_TOOLSETS` | 所有 | 以逗号分隔的工具集子集。 |
有效工具集：`identity`、`reference`、`catalog`、`releases`、`review`、`analytics`、`accounting`、`delivery`、`webhooks`、`distribution`。
## 工具参考
<!-- TOOLS:BEGIN -->
_10 个工具集中的 83 个工具。 此表格由 `npm run gen-docs` 从工具定义生成 — 请勿手动编辑。_
### 身份 `identity`
| 工具 | 门控 | 描述 |
| --- | --- | --- |
| `get_me` | 读取 | 返回身份验证的 LabelGrid 账户配置文件，包括发布提交限制/配额和条款接受状态。 使用此功能确认您的 API 令牌属于哪个账户，然后再进行其他调用。 |
| `revoke_api_token` | 写入 | 撤销 LabelGrid API 令牌。 传递 `token_id` 以撤销特定令牌；省略它以撤销当前正在使用的令牌。 警告：撤销当前令牌会立即终止此会话 — 服务器将失去访问权限并停止工作，直到您配置新的令牌。 |
### 参考数据 `reference`
| 工具 | 门控 | 描述 |
| --- | --- | --- |
| `list_reference_data` | 读取 | 获取 LabelGrid 参考数据集，用于解析目录和发布工具期望的 ID 和代码。 使用 `type` 选择一个数据集：`genres` 和 `genre_categories`（主要/次要/三级流派 ID 的值）、`languages`（音频和元数据语言代码）、`contributor_roles`（曲目贡献者的有效角色名称）、`instruments`、`distro_outlets`（您的账户可用的分发渠道/商店）或 `territories`（国家/地区代码）。 在创建或更新发布或曲目时，如果需要有效的 ID 或代码，请在此调用。 |
### 目录（标签、艺术家、作家、出版商、发布、曲目、文件） `catalog`
| 工具 | 门控 | 描述 |
| --- | --- | --- |
| `list_labels` | 读取 | 列出您的账户中的标签，分页。 标签分组您的发布，并携带默认版权、网站和渠道设置。 使用 `get_label` 获取一个标签的完整详细信息。 |
| `get_label` | 读取 | 检索一个标签的 ID，包括其设置和默认值。 |
| `list_artists` | 读取 | 列出您的账户中的艺术家，分页。 按 `artist_name` 过滤以查找特定艺术家。 使用 `get_artist` 获取一个艺术家的完整个人资料和链接。 |
| `get_artist` | 读取 | 检索一个艺术家的 ID，包括其简介、标识符和平台链接。 |
| `list_writers` | 读取 | 列出您的账户中的词曲作者，分页。 按 `name` 或 `ipi` 过滤。 词曲作者附加到曲目上以获取创作积分和版税分成。 |
| `get_writer` | 读取 | 检索一个词曲作者的 ID，包括 PRO/IPI 标识符和出版商链接。 |
| `list_publishers` | 读取 | 列出您的账户中的出版商，分页。 按 `name` 或 `ipi` 过滤。 出版商与词曲作者关联以进行出版管理。 |
| `get_publisher` | 读取 | 检索一个出版商的 ID。 |
| `list_releases` | 读取 | 列出您的账户中的发布，分页。 按 `label_id`、`is_live`（1 = 直播/分发）、`barcode_number`（UPC/EAN）或 `cat`（目录编号）过滤。 使用 `get_release` 获取一个发布的完整元数据和曲目列表。 |
| `get_release` | 读取 | 检索一个发布的 ID，包括其元数据、艺术作品状态和曲目列表。 |
| `list_tracks` | 读取 | 列出您的账户中的曲目，分页。 按 `release_id` 过滤以列出一个发布的曲目，或按 `isrc` 过滤。 使用 `get_track` 获取一个曲目的完整元数据、积分和分成。 |
| `get_track` | 读取 | 检索一个曲目的 ID，包括标题、贡献者、词曲作者、出版商和版税分成。 |
| `get_track_file` | 读取 | 检索一个曲目的资产文件的元数据（其立体声音频、Dolby Atmos 音频或歌词文件），包括其处理状态。 此调用返回文件信息，而非字节 — 使用 `get_track_audio_download_url` 获取可下载的链接。 |
| `get_track_audio_download_url` | 读取 | 返回一个时间有限的签名 URL，以下载一个曲目的音频资产。 `asset_type` 选择资产：`audio_16`、`audio_24` 和 `audio_32` 分别是该比特深度的 WAV 主音；`audio_preview_full` 和 `audio_preview_clip` 分别是生成的 MP3 预览（全长/片段）。 返回 `{ download_url, expires_in }`；URL 在发出后约 10 分钟过期，因此请在 URL 过期时请求一个新的。 直接获取 URL — 请勿将您的 API 令牌发送到 URL。 |
| `list_track_licenses` | 读取 | 列出附加到曲目的许可证（例如封面/机械或样本清除），分页。 |
| `get_track_license` | 读取 | 通过其许可证 ID 检索附加到曲目的一个许可证。 |
| `get_release_file` | 读取 | 检索发布动画封面（动态艺术作品）视频资产的元数据 — 方形或高/肖像封面视频 — 包括其处理状态。 |
| `create_label` | 写入 | 创建一个新标签。 在 `fields` 中传递其属性。 |
| `update_label` | 写入 | 更新一个标签。 在 `fields` 中仅提供要更改的字段。 |
| `delete_label` | 写入 | 删除一个标签。 API 拒绝删除仍然有发布的标签 — 首先删除或重新分配其发布。 |
| `upload_label_image` | 写入 | 从本地文件上传标签图像。 `image_type` 选择哪个资产：`logo`、`logo-dark`（深色模式变体）或 `background`。 `file_path` 必须是本地图像文件。 |
| `create_artist` | 写入 | 创建一个新艺术家。 在 `fields` 中传递其属性。 |
| `update_artist` | 写入 | 更新一个艺术家。 在 `fields` 中仅提供要更改的字段。 |
| `delete_artist` | 写入 | 删除一个艺术家。 当艺术家仍被发布或曲目引用时，API 拒绝删除。 |
| `upload_artist_photo` | 写入 | 从本地文件上传艺术家照片。 `file_path` 必须是本地图像文件。 |
| `create_writer` | 写入 | 创建一个新词曲作者。 在 `fields` 中传递其属性。 |
| `update_writer` | 写入 | 更新一个词曲作者。 在 `fields` 中仅提供要更改的字段。 |
| `delete_writer` | 写入 | 删除一个词曲作者。 当词曲作者仍被曲目引用时，API 拒绝删除。 |
| `create_publisher` | 写入 | 创建一个新出版商。 在 `fields` 中传递其属性。 |
| `update_publisher` | 写入 | 更新一个出版商。 在 `fields` 中仅提供要更改的字段。 |
| `delete_publisher` | 写入 | 删除一个出版商。 当出版商仍被词曲作者引用时，API 拒绝删除。 |
### 发布和曲目（草稿生命周期） `releases`
| 工具 | 门控 | 描述 |
| --- | --- | --- |
| `create_release` | 写入 | 创建一个处于 DRAFT 状态的新发布。 在 `fields` 中传递其元数据。 必需：`content_type`、`label_id`、`artists`、`titles`、`cat`（目录编号）、`artwork_ai_usage`、`primary_genre_id`。 传递 `idempotency_key` 并在重试调用时重用相同的 值，如果您没有观察到其结果 — 服务器在 24 小时内通过它进行重复数据删除；如果没有密钥，则每次调用都是一个新操作。 使用 `create_track` 添加曲目，然后在分发前验证发布。 |
| `update_release` | 写入 | 更新发布的元数据。 在 `fields` 中仅提供要更改的字段。 一旦发布被提交或分发，一些字段将被锁定：尝试更改锁定字段将返回 403，错误代码为 RELEASE_LOCKED_FIELDS，直接显示以便您查看哪些字段无法更改。 |
| `delete_release` | 写入 | 删除发布。 API 仅允许删除从未被提交的草稿；它拒绝删除已提交或分发的发布。 |
| `create_track` | 写入 | 在发布中创建一个曲目。 在 `fields` 中传递其元数据。 必需：`release_id`、`disc`、`track_num`、`composition_type`、`artists`、`audio_ai_usage`、`composition_ai_usage`、`commercial_samples`、`audio_language`、`contributors` 和 `recording_country`（必填 ISO 3166-1 alpha-2 国家/地区代码，例如“US”）。 传递 `idempotency_key` 并在重试调用时重用相同的值，如果您没有观察到其结果 — 服务器在 24 小时内通过它进行重复数据删除；如果没有密钥，则每次调用都是一个新操作。 |
| `update_track` | 写入 | 更新曲目的元数据。 在 `fields` 中仅提供要更改的字段。 与发布相同，一旦父发布被提交或分发，一些字段将被锁定。 |
| `delete_track` | 写入 | 删除曲目。 允许在父发布是可编辑草稿时进行；一旦发布被提交或分发，API 拒绝删除。 |
| `validate_release` | 写入 | 对发布进行验证并返回可能阻止分发的任何问题，既有可读的 `errors` 列表，也有可读的 `errors_structured` 列表。 这是一个接近读取的检查：它不会更改任何内容，可以安全重复。 在分发前运行。 |
| `refresh_quality_report` | 写入 | 重新运行预检 QC 自动检查并刷新发布的 quality 报告。 使用 `get_quality_report` 读取结果。 服务器每小时应用刷新预算，因此频繁调用可能会受到速率限制。 预检 QC 是可选附加项。 |
| `update_landing_config` | 写入 | 设置发布的智能链接登陆页面配置。 `actions` 使用当前的（v2）动作列表契约 — 每个条目描述登陆页面上的一个调用操作。 您可以设置 `links_page_enabled`、`config_mode`、`page_style`、`custom_cta_text`、`custom_description` 和 `pre_order_links`。 这将替换登陆配置。 |
| `create_release_short_url` | 写入 | 为发布的智能链接登陆页面创建（或返回现有）短 URL。 安全重复。 |
| `add_review_issue_note` | 写入 | 添加发布审核问题的注释 — 例如，解释修复或为审阅者添加上下文。 `review_issue_id` 是问题 ID（来自 `list_review_issues`）。 |
### 审查和质量 `review`
| 工具 | 门控 | 描述 |
| --- | --- | --- |
| `list_review_issues` | 读取 | 列出在自动质量检查期间对发布提出的审查问题。 需要 `release_id`。 每个问题都有一个代码（参见 `list_issue_definitions` 以了解每个代码的含义）、严重性和是否阻止分发。 使用此功能查看客户在发布前必须修复的内容。 |
| `list_issue_definitions` | 读取 | 检索审查问题定义的目录：每个代码的人性化标题、描述、严重性和是否阻止分发。 使用它来解释 `list_review_issues` 和质量报告返回的代码。 问题代码是字符串 slug。 |
| `get_quality_report` | 读取 | 检索发布的预检 QC 质量报告：自动检查发现的客户可见问题，以便您在确认发布到分发之前进行审查。 预检 QC 是可选附加项 — 如果您的账户未启用它，API 将返回 403，直接显示。 |
| `list_stream_radar_flags` | 读取 | 列出发布的 Stream Radar 标志，分页 — 来自流媒体完整性监控的早期警告标志，以帮助您尽早采取行动。 按状态、严重性、DSP、ISRC、发布 ID 和检测日期范围（`detected_from`/`detected_to`）进行过滤。 Stream Radar 是可选附加项；如果没有它，API 将返回 403，直接显示。 |
| `get_stream_radar_flag` | 读取 | 通过 ID 检索一个 Stream Radar 标志及其完整详细信息。 Stream Radar 是可选附加项；如果没有它，API 将返回 403，直接显示。 |
### 分析 `analytics`
| 工具 | 门控 | 描述 |
| --- | --- | --- |
| `get_analytics` | 读取 | 通过一次调用检索您的目录的流媒体分析摘要。 `start_date` 和 `end_date`（均为 YYYY-MM-DD）是必需的，服务器将窗口限制在 30 天内。 可选地，按 `platform`（SPOTIFY、ITUNES、APPLE_MUSIC）、`release_id`、`isrc`、`upc`或 `artist_names`缩小结果。 默认情况下，返回所有 15 个指标部分；传递 `metrics` 以请求仅子集。 可用指标：`streams`、`listeners`、`saves`、`skips`、`shares`、`completion_rate`、`lyrics_view_rate`、`canvas_view_rate`、`device_split`、`source_split`、`saves_by_tier`、`streams_by_country`、`streams_by_gender`、`streams_by_age`、`shares_by_country`。 此终端受到速率限制（约每分钟 60 次请求）；429 响应带有 `retry_after_seconds`。 直接获取 URL — 不要将您的 API 令牌发送到它。
### 记账 `accounting`
| 工具 | 接口 | 描述 |
| --- | --- | --- |
| `list_statements` | 读取 | 列出您的版税声明，按分页显示。可按标签 ID、发行 ID、ISRC、UPC 和开始日期/结束日期范围进行筛选。传递 `group_by="release"` 可按发行汇总总数。 使用 `get_statement` 获取单个声明，或使用 `download_statement_csv` 获取其行项。 |
| `get_statement` | 读取 | 按发票号码检索单个版税声明。 |
| `download_statement_csv` | 读取 | 以 CSV 格式下载声明行项。传递 `invoice_number` 获取单个声明，或传递开始日期/结束日期范围以导出多个声明。如果提供 `save_to_path`（一个绝对路径，其父目录存在），则将 CSV 文件写入该路径 - 绝不会覆盖现有文件（返回 `FILE_EXISTS`）- 并返回字节数。否则，内联返回 CSV 文件，截断为 100KB（带有 `truncated: true`）- 使用 `save_to_path` 进行大批量导出。 |
| `download_statement_invoice` | 读取 | 下载声明的发票 PDF。`save_to_path` 是必填项（PDF 为二进制），必须是一个绝对路径，其父目录存在；PDF 将写入该路径 - 绝不会覆盖现有文件（返回 `FILE_EXISTS`）- 并返回字节数。 |
| `list_transactions` | 读取 | 列出账户交易，按分页显示。可按标签 ID、发行 ID、ISRC、UPC 和开始日期/结束日期范围进行筛选；使用 `sort` 进行排序；传递 `group_by="release"` 可按发行汇总。 |
| `get_royalties_breakdown` | 读取 | 获取按一个或多个维度分组的版税明细。`group_by` 是必填项，是一个逗号分隔的有序子集：track、dsp、release、territory、period（例如 "release,dsp"）。可按标签 ID、发行 ID、ISRC、UPC 和开始日期/结束日期范围进行筛选。 |
| `list_artificial_streams` | 读取 | 列出为您的目录报告的人工流媒体记录，按分页显示 - 每个记录的详细信息，用于计算人工流媒体费用。可按 dsp（spotify 或 apple）、开始日期/结束日期范围、发行 ID 或 isrc 进行筛选。 |
| `get_artificial_fee_breakdown` | 读取 | 检索某个计费期间的人工流媒体费用的按发行分解的明细。`period` 为 YYYY-MM 格式的月份。 |
| `get_account_summary` | 读取 | 检索您的会计摘要 - 当前余额和相关的账户级财务总额。 |
### 投递 `delivery`
| 工具 | 接口 | 描述 |
| --- | --- | --- |
| `get_delivery_queue` | 读取 | 列出您账户的发行队列条目，按分页显示 - 每个（发行，出库）的交付及其当前状态（例如待审核、处理中、已调度、已完成、错误）。可按 `release_id`、`outlet_id` 或 `status` 进行筛选。 使用此功能查看某个发行在交付到每个商店的流程中的状态。 |
| `get_landing_config` | 读取 | 检索某个发行的智能链接登陆页面配置：链接页面是否启用，其样式/模式、自定义副本、操作列表和任何预购链接。 与 `update_landing_config` 配对使用以更改它。 |
### Webhooks `webhooks`
| 工具 | 接口 | 描述 |
| --- | --- | --- |
| `list_webhooks` | 读取 | 列出您账户配置的 webhook 订阅，每个订阅都有其 URL、订阅的事件和活动状态。 |
| `get_webhook` | 读取 | 按 ID 检索某个 webhook 订阅。 |
| `get_webhook_logs` | 读取 | 检索某个 webhook 的最近交付日志 - 尝试、响应代码和结果 - 以调试事件为何未到达您的端点。 |
| `list_webhook_event_types` | 读取 | 列出所有可用的 webhook 事件类型，每个类型都有其交付的负载的模式。 使用它来决定为哪些事件订阅 webhook。 |
| `create_webhook` | 写入 | 创建 webhook 订阅。`name` 和 `url`（将接收事件的 HTTPS 端点）必填，同时 `events` 选择要交付的事件类型。 API 在创建时返回一个签名密钥 - 请存储它以验证传入的负载。 |
| `update_webhook` | 写入 | 更新 webhook 订阅。仅提供要更改的字段：`name`、`url`、`events` 或 `is_active`（设置为 `false` 以暂停交付）。 |
| `delete_webhook` | 写入 | 永久删除 webhook 订阅。它将停止接收事件。 |
| `test_webhook` | 写入 | 向 webhook 的端点发送测试事件，以便您可以确认它可达且您的签名验证有效。 可以重复使用。 |
| `rotate_webhook_secret` | 写入 | 为 webhook 生成新的签名密钥并返回。警告：旧密钥立即停止工作 - 请立即用新密钥更新您的端点的签名验证，否则交付将失败验证。 |
### 分发（完全写入）`distribution`
| 工具 | 接口 | 描述 |
| --- | --- | --- |
| `upload_track_audio` | 完全写入 | 上传某个曲目的已完成音频文件（立体声 WAV/FLAC 或 Dolby Atmos）或歌词（LRC）文件。文件直接上传到存储，然后异步处理；可以使用 `get_track_file` 检查其状态。一旦发行已分发，文件是不可变的 - 在分发前上传正确的母带。 |
| `delete_track_audio` | 完全写入 | 删除某个曲目的资产文件（立体声、Dolby Atmos 或歌词）。仅在父发行仍是可编辑草稿时允许；一旦发行锁定或分发，API 将拒绝。 |
| `upload_release_asset` | 完全写入 | 上传某个发行的已完成动态封面（动态艺术）视频 - 方形或高/肖像封面视频。视频直接上传到存储，然后处理；可以使用 `get_release_file` 检查其状态。在分发前上传正确的视频 - 一旦发行上线，它就是不可变的。 对于静态封面艺术图像，请使用 `upload_release_artwork`。 |
| `delete_release_asset` | 完全写入 | 删除某个发行的动态封面（动态艺术）视频 - 方形或高/肖像封面视频。仅在发行仍是可编辑草稿时允许。 |
| `upload_release_artwork` | 完全写入 | 从本地文件上传或替换发行的静态封面艺术图像。封面艺术一旦发行分发后不可变 - 在分发前上传最终的艺术作品。 |
| `upload_track_license` | 完全写入 | 将许可证文档附加到某个曲目（用于翻唱或清理样本）。`file_path` 是本地许可证文件，`type` 是 "cover" 或 "sample"。可选记录 `license_id`、`license_provider`、`license_provider_name` 和 `original_track_link`。许可证一旦发行上线后不可变。 |
| `update_track_license` | 完全写入 | 替换现有曲目许可证的文件和/或元数据。`track_license_id` 是许可证的 ID（来自 `list_track_licenses`）；`file_path` 是要提交的许可证文件。可选更新 `license_id`、`license_provider`、`license_provider_name` 和 `original_track_link`。 |
| `delete_track_license` | 完全写入 | 永久删除某个曲目许可证及其文件。`track_license_id` 是许可证 ID（来自 `list_track_licenses`）。此操作无法撤销。 |
| `distribute_release` | 完全写入 | 将发行提交到商店/outlets 进行分发 - 这是最终的、具有后果的操作，会将发行发送出去；`validate_release` 应首先通过。服务器强制执行您的账户的每周提交限制，如果超过限制，则返回结构化错误。传递 `idempotency_key` 并在重试调用时重用相同的数值，如果您没有观察到结果 - 服务器在 24 小时内通过它进行重复消除；如果没有密钥，则每个调用都是新的提交。 |
| `takedown_release` | 完全写入 | 将发行从所有 outlets/stores 下架 - 一个最终的、具有后果的操作，会将其从所有已交付的位置删除。之后重新分发是一个新的提交。 |
| `confirm_review` | 完全写入 | 确认由 Preflight QC 暂停的发行，将其移入分发审核。使用此功能之前，请您已经审核了质量报告并接受发行原样。 可以重复使用。 |
| `enable_beatport` | 完全写入 | 为标签请求 Beatport 开通。此操作为一次性操作，提交后无法撤销，因此请首先确认标签正确。 |
## 安全模型
服务器有三个接口。每个接口都是失败关闭的：只有当其接口开启时，工具才会被注册并可调用。
1. **读取** - 始终开启。列出和获取您的目录、分析、声明等。
2. **安全写入** (`LABELGRID_ENABLE_WRITES`，默认为开启) - 可逆、草稿阶段更改：创建和编辑草稿发行和曲目、标签、艺术家、作者、出版商、webhooks、登陆页面和笔记。设置 `LABELGRID_ENABLE_WRITES=false`（或 `LABELGRID_READ_ONLY=true`）可关闭这些功能。
3. **完全写入** (`LABELGRID_ENABLE_FULL_WRITES`，默认为关闭) - 具有后果、难以撤销的操作。要启用它们，您必须同时设置：
```bash
LABELGRID_ENABLE_FULL_WRITES=true
LABELGRID_FULL_WRITES_ACK=I accept responsibility for AI-driven distribution actions
```
确认字符串必须完全匹配，否则完全写入功能将保持关闭。启用后，`distribution` 工具集将可用。这些工具可以：
- 上传最终的（不可变的）曲目音频和发行艺术作品，
- 上传、更新和删除曲目许可证，
- **将发行分发到商店** - 最终提交，受您的账户的每周限制，
- **将发行从所有商店下架**，
- 确认被阻止的发行进入审核，
- 请求一次性 Beatport 标签开通。
将 `LABELGRID_ENABLE_FULL_WRITES` 留空是安全的默认设置：您的 AI 助手可以准备和验证所有内容，但不可逆的提交是一个刻意、有条件的步骤。
## 速率限制和错误
每个工具都返回 API 的 JSON 负载或**结构化错误** - 从不返回原始协议失败 - 以便您的助手可以理解发生了什么。错误格式为：
```json
{
"error": {
"code": "VALIDATION_FAILED",
"message": "提交的数据无效。",
"status": 422,
"errors": { "title": ["标题字段是必填项。"] }
}
}
```
常见代码：`TOKEN_INVALID`（401 - 检查您的令牌）、`FORBIDDEN`（403 - 计划/权限或锁定字段，服务器代码通过）、`NOT_FOUND`（404）、`VALIDATION_FAILED`（422，带有 `errors`）、`RATE_LIMITED`（429）、`SERVER_ERROR`（5xx）、`NETWORK_ERROR` 和 `FILE_NOT_FOUND` / `UPLOAD_FAILED` 用于本地文件操作。
**速率限制。** 当达到限制时，将显示 `429` 并带有 `retry_after_seconds` 字段（来自 API 的 `Retry-After` 头）。服务器**不**自动重试 - 您的客户端决定何时重试。分析功能每分钟限制约为 60 次请求。
## 贡献
欢迎提出问题和拉取请求。API 覆盖率检查在 CI 中针对公共 API 文档的提交快照运行，当快照增加服务器未公开的端点时失败（使用 `node scripts/fetch-openapi.mjs` 刷新快照）。此仓库使用：
- **TypeScript** （严格 ESM）、Node 20+，仅使用 `@modelcontextprotocol/sdk` 和 `zod` 作为运行时依赖。
- **[Biome](https://biomejs.dev)** 用于 lint + format (`npm run lint`)。
- **[Vitest](https://vitest.dev)** 用于测试 (`npm test`)。
本地工作流：
```bash
npm ci
npm run build # tsc
npm test # 单元测试
npm run lint # biome
npm run leak-guard # 仓库卫生扫描
npm run gen-docs # 重新生成上面的工具表格（构建后）
```
每个工具都是一个薄封装 - 一个 HTTP 调用加上响应塑形，无客户端业务逻辑。请保持这一点：验证和规则应在服务器上，属于服务器。 此 README 中的工具表格已生成（`npm run gen-docs`）；在 `src/tools/` 中编辑工具描述，而不是表格。
## 法律声明
这些披露也在运行时显示：在 MCP `instructions` 字段中，您的客户端在初始化时接收，以及在启动时在 stderr 上显示。下面文本与 `src/legal.ts` 中的运行时常量相同。
- **摘要。** 本软件按原样提供，不提供任何类型的保证，明确或暗示。通过使用它，您接受对 LabelGrid API 的使用以及您连接到此服务器的任何 AI 客户端或代理的全部责任，包括对您的 LabelGrid 账户的写入操作。您通过此服务器使用 API 受 LabelGrid API 服务条款和可接受使用政策的约束。此服务器不会绕过服务器端保护，例如速率限制、计划权利或条款执行。参见 [LICENSE](./LICENSE)（MIT）。
- **完全写入。** 当完全写入功能启用时：由 AI 代理发起的分发提交、删除和不可变文件上传对您的发行在流媒体平台和商店具有实际、有潜在不可逆转的后果。通过设置 `LABELGRID_FULL_WRITES_ACK` 确认变量，您接受所有此类操作是您独自负责的。
- **数据处理。** 此服务器将您的 LabelGrid 目录和账户数据传输到您配置的 AI 客户端。选择该客户端并在需要时披露数据流是您的责任。
## 许可证
[MIT](./LICENSE) © LabelGrid
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器