Tiendanube MCP

tiendanube-mcp

用于开发 Tiendanube 和 Nuvemshop 应用及集成的 MCP 服务。

安装

claude mcp add tiendanube -- npx -y @commenteme/tiendanube-mcp

需要 Node >= 18。客户端会通过 npx 运行服务，因此无需安装。对于 Claude Desktop、Cursor、Windsurf、VS Code 和其他客户端，请参阅其他客户端。

快速使用

重启客户端，然后用自然语言提出你的需求。助手会选择合适的工具：

• “POST /orders/{id}/fulfillment-orders/{id}/tracking-events 需要什么 scope？”
• “为 order/paid 和 app/uninstalled 搭建 webhook 接收器，并验证签名”
• “生成应用 1234 的 OAuth 安装流程”
• “fulfillment orders 有哪些 webhook 事件？”
• “NubeSDK 的 checkout slots 如何运作？”

包含内容

适用于开发合作伙伴应用和自有集成的人员：Admin API、OAuth、webhook、NubeSDK、Admin 应用和主题。

• 实时官方文档：search-docs 和 read-doc 会读取 nuvemshop.dev 发布的 Markdown 页面，支持英语、葡萄牙语或西班牙语。每条回复都会附上页面 URL。
• Admin API 2025-03 离线索引：228 个 endpoint，包含所需 scope 及其参考页面、18 组 OAuth scope，以及 57 个 webhook 事件；此外还单独列出 3 个必需的隐私事件。
• 脚手架：webhook 接收器（基于原始 body 验证 x-linkedstore-hmac-sha256 签名、立即返回 200 并附带一项测试）和 OAuth 流程（带 state 的重定向，以及使用 JSON body 兑换 code）。工具会返回文件（路径和内容），供客户端写入。
• 无需凭据：不需要店铺 token，不会写入磁盘，只会连接 nuvemshop.dev 和 tiendanube.dev。

适用于 Claude Code、Claude Desktop、Codex、Cursor、Gemini CLI、GitHub Copilot、VS Code、Windsurf，以及任何使用 stdio 传输的 MCP 客户端。

为什么要开发

Tiendanube 提供了官方的 Admin MCP，可通过对话操作店铺：创建产品、调整库存和价格、查看订单、管理优惠券和促销活动。如果你需要操作店铺，请使用它。对于在该平台上构建产品的开发者，此前没有可用的服务：本项目会告诉你该使用哪个 endpoint、scope 和事件，并提供每个应用都会重复编写的部分代码。它与 tiendanube-skills 的 skills 搭配使用。

文档

其他客户端

在 claude_desktop_config.json（Claude Desktop）、~/.cursor/mcp.json 或 .cursor/mcp.json（Cursor），以及 ~/.codeium/windsurf/mcp_config.json（Windsurf）中：

{
  "mcpServers": {
    "tiendanube": {
      "command": "npx",
      "args": ["-y", "@commenteme/tiendanube-mcp"]
    }
  }
}

在 VS Code 中，使用 .vscode/mcp.json：

{
  "servers": {
    "tiendanube": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@commenteme/tiendanube-mcp"]
    }
  }
}

Codex，通过 CLI 配置（会写入 ~/.codex/config.toml）：

codex mcp add tiendanube -- npx -y @commenteme/tiendanube-mcp

或者，手动编辑 ~/.codex/config.toml 或项目中的 .codex/config.toml：

[mcp_servers.tiendanube]
command = "npx"
args = ["-y", "@commenteme/tiendanube-mcp"]

Gemini CLI，通过 CLI 配置（-s user 会将配置写入 ~/.gemini/settings.json；不加 -s 则写入项目中的 .gemini/settings.json）：

gemini mcp add -s user tiendanube npx -y @commenteme/tiendanube-mcp

GitHub Copilot CLI，配置在 ~/.copilot/mcp-config.json 或项目中的 .mcp.json，使用上方相同的 mcpServers JSON。在 VS Code 中，Copilot 使用 .vscode/mcp.json。

任何使用 stdio 传输的客户端都可以使用：命令为 npx，参数为 -y @commenteme/tiendanube-mcp。在 Claude Code 中，--scope project 会将配置写入 .mcp.json，以便与团队共享。

工具

工具	功能	网络
search-docs	搜索文档的 llms.txt 索引，并引用前三个页面中最相关的章节。	是
read-doc	按 URL 或网站路径读取页面或章节。其他域名会被拒绝。	是
lookup-endpoint	按路径（接受真实 ID、版本和 store ID）、资源或关键词查找：完整 URL、scope 和参考资料。	否
lookup-scope	查找 OAuth scope 及其开放的资源，或查找某个资源或路径对应的 scope。	否
lookup-webhook-event	按组查找 webhook 事件，以及如何注册和验证这些事件。	否
scaffold-webhook-handler	生成带签名验证的 TypeScript Express 接收器，以及一个 node:test 测试。	否
scaffold-oauth-callback	在 Express 中设置 OAuth：state、兑换 code，以及按应用和商店注册。	否

数据来源

nuvemshop.dev 文档没有开放许可，因此软件包不包含这些文档：search-docs 和 read-doc 会实时读取文档，并仅在进程运行期间将其保存在内存中。data/ 中的文件是由 scripts/ingerir.ts 根据这些页面构建的事实索引：方法、路径、资源名称、scope 和事件名称，以及对应页面的链接。软件包不包含任何文档文本。我们在文档中发现的矛盾列于 tiendanube-skills/docs/divergencias.md。

开发

git clone https://github.com/commentemeapp/tiendanube-mcp.git
cd tiendanube-mcp
npm ci
npm run check

npm run check 是质量门禁：Prettier、类型检查、构建、测试（文档工具会读取 test/fixtures/ 中的模拟页面，不会访问网络）、probar-mcp（通过 stdio 启动服务并将其作为客户端运行），以及痕迹搜索。要在客户端中测试：

claude mcp add tiendanube-local -- node /ruta/a/tiendanube-mcp/build/index.js

更新索引

运行 npm run ingerir：下载 2025-03 版本的资源页面、llms.txt、身份验证和 webhooks 页面，并重写 data/。随后运行 npm run check 并提交 data/：软件包需要这些文件。

分支与发布

在从 dev 分出的分支上开展工作，PR 目标分支为 dev。在本地测试后，将包含完整分支的合并提交从 dev 提升到 main。CI 会在 Node 18、20 和 22 上运行 npm run check。

要发布，请更新 package.json、server.json 和 CHANGELOG.md 中的版本，并推送 v* 标签：publish.yml 工作流会运行质量门禁、通过 provenance 发布到 npm、创建 GitHub Release，并将 server.json 发布到 MCP Registry。各版本的更改记录在 CHANGELOG.md 中。

贡献 · 许可证

向 dev 提交 PR，使用 Conventional Commits，并确保 npm run check 通过。

MIT。软件包包含和不包含的内容，请参阅 NOTICE。

---

由 commente.me 制作 · [email protected]