storebridge-mcp

storebridge-mcp

面向 StoreBridge API 的远程 **MCP（Model Context Protocol）**连接器——该 API 统一提供 Apple App Store 与 Google Play 数据（搜索、应用详情、评论、相似应用、榜单、类别、开发者作品集、自动补全，以及方向性 ASO 关键词／排名套件）。

线上服务： https://storebridge-mcp.vercel.app/mcp（Vercel 项目 storebridge-mcp，团队 isaiahduprees-projects）——包含 13 个工具，已通过真实生产数据验证。由于上游 StoreBridge 部署按量计费（RapidAPI/Apify），此连接器使用相同的 Apify actor bearer（STOREBRIDGE_APIFY_BEARER）验证其对外调用，并实施软性 IP 速率限制（STOREBRIDGE_MCP_RATE_LIMIT，默认每小时 30 次工具调用，基于内存），确保免费的 MCP 层仍作为发现渠道，而不是绕过付费服务的无限制通道——参见 lib/ratelimit.js。

这是什么，以及为什么它是独立的连接器

StoreBridge API 是一个普通的 REST API，任何 HTTP 客户端都可以直接调用。本仓库之所以存在，是因为MCP 客户端（Claude、ChatGPT 和其他支持 MCP 的 Agent）不会使用任意 REST API——它们使用 MCP 工具。 storebridge-mcp 是一个轻量适配层，它：

• 将每个 StoreBridge 端点作为可发现、带类型的 MCP 工具公开（名称、描述、zod 输入架构、注解），让大模型能够理解并直接调用，而无需通过其他渠道另行了解 REST 接口。
• 使用单一的 /mcp 端点提供 MCP 可流式 HTTP传输，因此只需一个 URL，即可将其注册为 Claude、ChatGPT 或任何其他 MCP 客户端中的连接器。
• 不做其他任何事情。它不包含自己的业务逻辑——每次工具调用都会直接 fetch StoreBridge，并将 StoreBridge 返回的 JSON 响应原样作为工具结果返回。

身份验证：无（有意为之）

与本组织的其他 MCP 连接器（NotesBridge、GapRadar、EtsyOps 等）不同，这些连接器需要 OAuth，因为它们会访问已登录用户的私有 Mac／商店／账户数据，StoreBridge 的数据完全不涉及用户维度——它是公开的应用商店元数据（应用列表、评论、榜单、开发者页面）。没有需要按调用方限制访问的内容，因此此连接器特意采用以下设计：

• 无 OAuth、无登录、无 bearer token
• 无 Supabase／数据库
• 无计费、无套餐、无用量计量
• 无演示账户与真实账户之分——所有调用方获取的都是相同的实时真实数据

这使该连接器远比本组织基于 OAuth 的连接器简单：api/mcp.js 会为每个请求创建全新的无状态 McpServer，并在完全不进行身份验证检查的情况下提供服务。

已知注意事项（见下文）： 生产环境中的 StoreBridge API 部署（https://storebridge-api.vercel.app）目前在 /v1/* 路径前设有 RapidAPI 代理密钥保护（见“上游身份验证注意事项”）。这是上游部署／变现方面的细节，并非需要为此连接器添加身份验证的理由——它只意味着，在此连接器的默认配置能够端到端地提供真实生产流量之前，必须将上游基础 URL 指向开放部署（或放宽保护／在服务端注入代理密钥）。

工具列表

每个 StoreBridge 端点对应一个工具（来自 storebridge-api/openapi.yaml）：

工具	StoreBridge 端点	描述
search_apps	GET /v1/search	在 Apple App Store、Google Play 或两者中搜索应用。
get_apps_batch	GET /v1/apps	通过 bundle id 查找 Apple 应用，或按逗号分隔的 ID 批量获取多个应用。
get_app	GET /v1/apps/{id}	应用完整详情（描述、版本、评分分布、屏幕截图、大小、安装量等）。
get_app_reviews	GET /v1/apps/{id}/reviews	应用的分页评论。
get_similar_apps	GET /v1/apps/{id}/similar	“顾客也购买了”/相关应用。
get_app_permissions	GET /v1/apps/{id}/permissions	Google Play 声明的权限（仅限 Google Play）。
get_app_datasafety	GET /v1/apps/{id}/datasafety	Google Play 的“数据安全”部分（仅限 Google Play）。
get_charts	GET /v1/charts	畅销榜排名（免费/付费/收入榜，按类别划分）。
get_categories	GET /v1/categories	商店的类别/类型列表。
get_developer	GET /v1/developers/{id}	开发者记录及其已发布的应用。
autocomplete_suggest	GET /v1/suggest	为部分查询提供自动补全建议。
get_aso_keywords	GET /v1/aso/keywords	方向性关键词建议及难度（估算值，来自实时搜索，不是面板数据）。
get_aso_rank	GET /v1/aso/rank	应用在最多 20 个关键词下某一时点的排名（估算值）。

全部 13 个工具均为只读，并标注为 { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }——它们都不会写入任何内容，并且反映的都是实时且会在外部变化的应用商店数据。

（构建说明中列出了约 9–10 个示例工具名称；StoreBridge 实际经过验证的 openapi.yaml 接口包含 13 个 GET 端点，因此本次构建与全部 13 个端点一一对应，而不是为了凑整而舍弃其中 3 个真实端点。）

如何封装 storebridge-api

每个工具处理程序都会针对真实的 StoreBridge REST API 执行普通的 fetch(\${STOREBRIDGE_API_BASE_URL}${path}`, ...)`，并将解析后的 JSON 作为 MCP 工具结果内容返回：

{ content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }

上游 HTTP 错误（4xx/5xx）会被捕获，并通过 asError 辅助函数作为带类型的 MCP 错误结果返回，而不会导致请求崩溃。

STOREBRIDGE_API_BASE_URL（环境变量）用于控制上游基础 URL，默认值为 https://storebridge-api.vercel.app。

项目布局

api/mcp.js       MCP endpoint (StreamableHTTPServerTransport, stateless, no auth)
api/health.js    GET /api/health
lib/tools.js     All 13 tool definitions (zod schemas + fetch-and-forward handlers)
local-server.js  Plain-Node http server for local dev / smoke testing (not deployed)
test/smoke.mjs   Real end-to-end smoke test (initialize, tools/list, tools/call)
vercel.json      Routes /mcp -> api/mcp.js, /health -> api/health.js

本仓库有意不提供 .well-known / OAuth 元数据接口：该组织其他连接器中的 401 + WWW-Authenticate: Bearer resource_metadata=... 流程，以及 /.well-known/oauth-protected-resource / /.well-known/oauth-authorization-server 端点，纯粹是为了支持 OAuth 发现流程。没有身份验证的 MCP 可流式传输 HTTP 服务无需让客户端发现或授权任何内容——它只需接受 POST 请求即可。因此，完全跳过 OAuth 元数据是正确的做法，并非疏漏。

本地开发

npm install
npm run dev          # starts local-server.js on http://localhost:3900

本地端点：POST http://localhost:3900/mcp、GET http://localhost:3900/health。

如需使用可自托管/开放的 StoreBridge 实例，而非生产实例（在生产环境的 RapidAPI 防护机制启用期间很有用——见下文）：

STOREBRIDGE_API_BASE_URL=http://localhost:8080 npm run dev

冒烟测试

npm run dev &                 # terminal 1
npm run smoke                 # terminal 2

test/smoke.mjs 通过真实 HTTP/JSON-RPC 驱动运行中的服务，并验证：

1. GET /health 返回 { ok: true, ... }
2. initialize 成功，并报告 serverInfo.name === "storebridge"
3. tools/list 返回全部 13 个工具及其从 zod 派生的 JSON 架构
4. 使用 { term: "notes", store: "apple", limit: 3 } 调用 search_apps 的 tools/call 会返回实时获取的真实应用结果（并非模拟数据）

上游身份验证注意事项（部署前请阅读）

在开发此项目时，我阅读了 storebridge-api 自带的 server.js / src/guard.js：生产环境部署会通过 RapidAPI 代理密钥（rapidApiGuard）保护所有 /v1/* 路由，只有在未设置 RAPIDAPI_PROXY_SECRET 时（自托管/开发模式）才会开放。这意味着，按当前部署方式，在没有有效的 X-RapidAPI-Proxy-Secret 请求头的情况下，访问 https://storebridge-api.vercel.app/v1/search?... 会返回 403 forbidden——尽管数据本身是公开信息（应用商店列表），且长期目标（根据该组织的产品线）是提供完全公开、无需密钥的 API，但目前线上 URL 实际上并未开放。

这不会改变此连接器的架构——按照设计，storebridge-mcp 本身没有任何身份验证，因为没有需要保护的调用方状态。但这意味着，在 storebridge-mcp 的默认 STOREBRIDGE_API_BASE_URL（生产环境 URL）能够端到端处理真实流量之前，上游需要完成以下任一事项：

• 部署一个开放（未设置 RAPIDAPI_PROXY_SECRET）的 StoreBridge 实例，供此连接器调用；或
• 为不经过 RapidAPI 的 /v1/* 流量类别放宽保护限制；或
• 让此连接器在发出的请求中注入服务端 RapidAPI 代理密钥 / Apify bearer（需要在此处添加 RAPIDAPI_PROXY_SECRET 或 APIFY_BEARER 环境变量，并在 lib/tools.js 的 callStoreBridge 中将其转发为请求头）。

本仓库中的冒烟测试验证了 MCP 协议连接和工具调用机制，能够通过真实运行的自托管 StoreBridge 实例端到端完成测试（在 storebridge-api 仓库中运行 node server.js，且未设置 RAPIDAPI_PROXY_SECRET——此模式下其保护逻辑明确处于停用状态），并获取真实的 Apple App Store 数据——准确的实时响应请参阅构建报告中的冒烟测试输出。

部署

尚未部署（这是有意为之——请先验证）。验证完成后：

cd /Users/isaiahdupree/Software/storebridge-mcp
npx vercel --yes --prod

部署后，要在 Claude/ChatGPT/任意 MCP 客户端中注册的 MCP 连接器 URL 为：

https://<deployment-domain>/mcp