插件管理 MCP

通过官网远程 MCP 查询、创建和修改插件、上传安装包、改价及上下架。

提交不等于发布

创建插件、修改资料和更新安装包须管理员审核后生效。改价、上下架直接生效；仅已审核的正式插件可上架。

接入准备

1. 使用已获得开发者资格的账号登录 BeikeShop 官网 (opens new window)。
2. 打开 个人中心 → 我的插件 (opens new window)，点击 MCP 接入。
3. 在「发布凭据」中填写名称、选择有效期并创建凭据。完整 Token 仅显示一次，请保存到 AI 工具的安全配置中。
4. 在 AI 工具中添加下方远程 MCP 地址和请求头，连接后确认能够发现插件管理工具。

凭据默认授权全部工具，仅可管理当前开发者名下的插件。凭据过期、撤销或开发者资格失效后不可调用。

连接配置

• MCP 地址：https://beikeshop.cn/api/mcp/developer
• 传输方式：Streamable HTTP，使用 POST / JSON 响应。
• 认证请求头：Authorization: Bearer <你的 MCP Token>。

配置示例（字段名以 AI 工具要求为准）：

{
  "mcpServers": {
    "beikeshop": {
      "url": "https://beikeshop.cn/api/mcp/developer",
      "headers": {
        "Authorization": "Bearer <你的 MCP Token>"
      }
    }
  }
}

使用官网生成的独立 MCP 凭据，不要填写店铺 Token、管理员凭据或网页登录 Cookie。目前不提供 OAuth 登录、SSE 或服务端推送，客户端需要支持 Bearer 请求头。

上传安装包需本地文件处理及 HTTPS 上传能力；远程 MCP 不能读取本地文件。

提供的工具

所有工具通过同一 MCP 地址发现和调用。

工具	主要参数	功能与结果
get_plugin_form_schema	无	获取字段规则、必填项、语言、插件类型和兼容版本选项，创建前先调用
list_my_plugins	可选 keyword、page	分页查询自己的插件；keyword 按插件编码搜索，返回正式资料及待审核信息
get_my_plugin	plugin_code	查询指定插件的正式资料、待审核内容和最近审核结果
prepare_plugin_update	operation、plugin_code、expected_version、file_size、sha256	申请安装包上传会话；operation 为 create 或 update，返回更新编号、上传地址、短期凭据和有效期
get_plugin_update_status	update_id	查询上传校验、提交和审核状态，以及错误或拒绝原因
create_plugin	plugin_code、update_id、idempotency_key、fields	使用已校验的安装包创建插件并提交审核，新插件不会自动上架
update_plugin	plugin_code、idempotency_key、fields，可选 update_id	修改指定资料或替换安装包并提交审核，未提供的字段保持原值
update_plugin_price	plugin_code、price，可选 origin_price	独立修改售价及原价，直接生效，售价不得低于 5 元
set_plugin_active	plugin_code、布尔值 active	true 上架、false 下架，直接生效，不改变审核状态

fields 支持多语言名称、简介、Markdown 描述、封面图、兼容版本、服务价格、标签及订阅配置等。通过 get_plugin_form_schema 获取实际字段要求；兼容版本使用返回的 版本 ID，不能填写版本字符串。

创建时名称、类型和图标可从安装包填充，仍需要补齐售价、各必填语言的描述和兼容版本等资料。update_plugin 不接受售价、原价或上架状态，请使用对应独立工具。

不提供删除插件、批准审核、直接发布新版本或自动同步 README 的工具，也不能操作其他开发者的插件。

AI 如何发现和调用工具

MCP 客户端自动执行 initialize → tools/list，将工具定义提供给 AI；AI 选择工具并生成参数后，由客户端通过 tools/call 执行。

tools/list 按凭据权限返回 result.tools，每项包含：

字段	用途
name	调用时使用的工具名
description	用途、调用时机及业务限制
inputSchema	参数类型、必填项及取值限制
annotations	行为提示，不替代服务端权限校验

手动查看工具清单

连接验证用 POST 请求（浏览器直接打开为 GET，不支持）。替换 Token 后执行：

curl 'https://beikeshop.cn/api/mcp/developer' \
  --header 'Authorization: Bearer <你的 MCP Token>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

无法发现工具时，检查 MCP 地址、传输方式和认证请求头。401 排查见「状态与常见问题」。

安装包上传与提交

1. 准备 ZIP

ZIP 的包根目录或单一顶层插件目录须包含 config.json 和 Static/ 下的图标。

• config.json.code 必须与目标 plugin_code 一致，版本必须与 expected_version 一致。
• 更新已有插件时，安装包版本必须与当前正式版本不同；只改资料不要求升级版本。
• 图标由 config.json.icon 指定，路径相对 Static/；未指定时默认使用 Static/image/logo.png。
• 图标支持 PNG、JPEG、GIF、WebP，最大 5 MiB、4096 × 4096。
• 默认 ZIP 上限为 100 MiB，解压总量为 500 MiB，最多 10000 个条目；以官网实际限制为准。
• 不接受加密包、符号链接和越界路径。官网只校验安装包，不运行插件代码。

插件结构与配置详见 插件开发。

2. 申请上传会话

计算本次 ZIP 的文件大小（字节）和 SHA-256，调用 prepare_plugin_update：

{
  "operation": "update",
  "plugin_code": "example",
  "expected_version": "2.0.0",
  "file_size": 12345,
  "sha256": "<本次 ZIP 的 64 位小写 SHA-256>"
}

创建新插件时将 operation 改为 create。文件大小和校验值必须使用实际计算结果。

3. 上传文件并等待校验

返回结果包含 update_id、upload_url、method、headers 和 expires_at。按照返回的地址和请求头发送 multipart 上传，文件字段名为 file：

curl --request POST "$UPLOAD_URL" \
  --header "Authorization: $UPLOAD_AUTHORIZATION" \
  --form "file=@$PLUGIN_ZIP"

UPLOAD_URL = 返回的 upload_url；UPLOAD_AUTHORIZATION = 返回的 headers.Authorization 完整值（含 Bearer）；PLUGIN_ZIP = 本地 ZIP 路径。

上传使用本次会话的短期上传凭据，不要使用长期 MCP Token，不要把 Token 放入 URL，也不要向 MCP 参数传递本地路径或 Base64 文件内容。

随后调用 get_plugin_update_status，参数为 {"update_id":"<本次更新编号>"}。等待状态变为 ready 后，才能提交审核。

4. 提交审核

只更新安装包时，调用 update_plugin：

{
  "plugin_code": "example",
  "update_id": "<本次更新编号>",
  "idempotency_key": "example-2.0.0-release-1",
  "fields": {}
}

创建新插件时，先获取字段要求，再调用 create_plugin，例如：

{
  "plugin_code": "example",
  "update_id": "<本次更新编号>",
  "idempotency_key": "example-create-1",
  "fields": {
    "price": 99,
    "description": {
      "zh_cn": "插件的中文功能说明。",
      "en": "Plugin features and usage instructions."
    },
    "versions": [1]
  }
}

此例使用安装包中的名称、类型和图标作为默认值；versions 中的 1 只是示例 ID，请替换为字段规则工具返回的真实 ID，语言也以返回的必填语言为准。

提交成功返回 pending_review。继续通过 get_plugin_update_status 查询结果；approved 表示审核通过，rejected 表示审核拒绝，可查看原因后修订并重新提交。

只修改资料

无需准备上传会话或上传安装包，调用 update_plugin 时省略 update_id，只提供要修改的字段：

{
  "plugin_code": "example",
  "idempotency_key": "example-description-1",
  "fields": {
    "description": {
      "zh_cn": "更新后的中文说明，支持 Markdown。"
    }
  }
}

兼容版本和服务价格的修改同样需要审核。

状态与常见问题

状态	含义
awaiting_upload	等待上传安装包
validating	文件已接收，正在校验
ready	校验通过，尚未提交审核
failed / expired	处理失败或上传会话已过期
pending_review	已提交，等待管理员审核
approved / rejected / ban	审核通过、审核拒绝或被冻结
applied	独立改价或上下架已直接生效

• 认证失败：检查 Token、有效期、撤销状态及开发者资格。
• 无法上传本地文件：检查本地文件处理和 HTTPS 上传能力。
• 校验失败：根据错误检查包结构、编码、版本、大小和 SHA-256，修复后重新申请上传会话。
• 已有待审核提交：不能覆盖已有审核稿，包括网页提交的审核稿；等待审核结果，拒绝后可以修订并重新提交。
• 网络中断或重试：先查询状态。对同一次提交使用相同 idempotency_key；不同提交使用不同键，避免重复创建或重复提交。
• 上传会话过期：默认有效期为一小时，每位开发者最多同时准备 10 个有效安装包会话，过期后重新申请。