# 插件管理 MCP

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

提交不等于发布

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

# 接入准备

使用已获得开发者资格的账号登录 BeikeShop 官网 (opens new window)。
打开个人中心 → 我的插件 (opens new window)，点击 MCP 接入。
在「发布凭据」中填写名称、选择有效期并创建凭据。完整 Token 仅显示一次，请保存到 AI 工具的安全配置中。
在 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_description_image`	`operation`、`plugin_code`	申请描述图片上传地址和短期凭据；`operation` 为 `create` 或 `update`，上传成功返回图片 URL
`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。"
    }
  }
}

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

# 图文描述与图片上传

描述支持 Markdown 图片语法。AI 可以先上传本地图片、取得公开链接，再替换说明中的图片路径，最后提交完整描述审核。安装包中的图标不会自动作为描述图片上传，README 也不会自动同步。

# 1. 申请图片上传凭据

调用 prepare_plugin_description_image：

{
  "operation": "update",
  "plugin_code": "example"
}

更新已有插件使用 update；新建插件使用 create，可在插件创建前上传图片。此工具不需要安装包、版本号、文件大小或 SHA-256。

返回结果包含 upload_url、method、headers、multipart_field、expires_at 及格式和大小限制。图片上传凭据有效期为 15 分钟，可在有效期内上传多张图片。申请和实际上传都会检查开发者资格、操作权限及插件归属；撤销 MCP 凭据后，对应的图片上传凭据也不可继续使用。

# 2. 上传图片并获取链接

按返回的地址发送 multipart 请求，字段名为 file，使用返回的短期请求头：

curl --request POST "$IMAGE_UPLOAD_URL" \
  --header "Authorization: $IMAGE_UPLOAD_AUTHORIZATION" \
  --header 'Accept: application/json' \
  --form "file=@$DESCRIPTION_IMAGE"

IMAGE_UPLOAD_URL = 返回的 upload_url；IMAGE_UPLOAD_AUTHORIZATION = 返回的 headers.Authorization 完整值（含 Bearer）；DESCRIPTION_IMAGE = 本地图片路径。不要使用长期 MCP Token 上传，不要将 Token 放入 URL，也不要向 MCP 传递本地路径或 Base64 图片内容。

上传成功同步返回 HTTP 200，例如：

{
  "url": "https://beikeshop.cn/storage/plugins/20261103/<随机文件名>.png",
  "value": "storage/plugins/20261103/<随机文件名>.png",
  "mime_type": "image/png",
  "width": 1200,
  "height": 800
}

图片上传无需轮询 get_plugin_update_status，也不会修改插件描述或自动提交审核。图片为公开资源，请勿上传敏感内容。图片和插件 Logo 均沿用网页上传的 plugins/日期/随机文件名 规则，每次上传生成新文件名。

# 3. 替换图片引用并提交描述

将说明中的本地图片路径替换为返回的 url，然后调用 update_plugin：

{
  "plugin_code": "example",
  "idempotency_key": "example-description-images-1",
  "fields": {
    "description": {
      "zh_cn": "## 功能介绍\n\n![功能截图](https://beikeshop.cn/storage/plugins/20261103/<随机文件名>.png)\n\n截图对应的功能说明。"
    }
  }
}

示例中的图片地址须替换为实际返回值。多张图片分别上传后替换各自引用；多语言描述填写对应语言字段。新建插件时，将图文描述放入 create_plugin 的 fields.description，同时提供已校验的安装包及其他必填资料。描述审核通过后生效。

# 图片限制与安全校验

支持 PNG、JPEG、GIF、WebP；拒绝 PHP 等脚本扩展名和 SVG，不依赖客户端声明的 MIME 类型判断文件内容。
图片默认最大 10 MiB；以工具返回及官网实际限制为准。
服务端检测 MIME 类型并读取图片信息，检查真实图片类型；仅将扩展名或客户端 MIME 改成图片的脚本文件不能通过校验。
校验通过后直接保存原始文件字节，不解码或重新编码，保留元数据和原格式，支持 GIF、WebP 动图并保留动画。存储文件名随机生成，扩展名由检测到的图片类型决定。
图片上传另有每 IP 每分钟 20 次限制，并受 API 总限流约束。图片校验不依赖 GD。

# 状态与常见问题

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

认证失败：检查 Token、有效期、撤销状态及开发者资格。
无法上传本地文件：检查本地文件处理和 HTTPS 上传能力。
校验失败：根据错误检查包结构、编码、版本、大小和 SHA-256，修复后重新申请上传会话。
已有待审核提交：可使用新的 idempotency_key 继续修改并提交，未修改的审核稿内容会保留，新安装包替换旧包；旧 MCP 提交标记为 superseded，后台审核最新稿。
网络中断或重试：先查询状态。对同一次提交使用相同 idempotency_key；不同提交使用不同键，避免重复创建或重复提交。
上传会话过期：默认有效期为一小时，每位开发者最多同时准备 10 个有效安装包会话，过期后重新申请。
图片上传失败：401 检查是否使用图片上传工具返回的短期凭据；410 表示其已过期，重新申请；422 根据错误检查格式、内容及大小；429 表示触发限流，稍后重试。

← 插件 README.md 说明数据字典 →