@scorehub/mcp-server

English version: README.en.md

ScoreHub 本地 MCP 代理，负责浏览器 OAuth 登录、Token 缓存，以及将本地 AI 客户端的工具调用转发至 ScoreHub 远程 MCP。

概览

@scorehub/mcp-server 运行在你的电脑上，位于 WorkBuddy、Codex 等 MCP 客户端与 ScoreHub 远程 MCP 之间，负责：

• 账号与店铺切换：authorize(force=true) 可重新登录切换账号；authorize(switch_shop=true) 可在当前账号下切换店铺，无需重新登录。
• Token 生命周期：调用前检查 Token 有效期；距过期不足 5 分钟时自动刷新，并为长会话每 4 小时主动保活一次。
• 工具转发：通过 Streamable HTTP 将 TikTok Shop 达人建联相关工具请求转发到 ScoreHub 远程 MCP。

┌─────────────┐     stdio      ┌──────────────────┐   Streamable HTTP   ┌─────────────────┐
│  AI 客户端  │ ◄────────────► │  @scorehub/      │ ◄─────────────────► │  ScoreHub       │
│ WorkBuddy 等│                │  mcp-server      │                     │  远程 MCP       │
└─────────────┘                └──────────────────┘                     └────────┬────────┘
                                                                                 │
                                                                          TikTok Shop
                                                                          Partner API

前置条件

• Node.js 18 或更高版本（建议使用当前 LTS 版本）
• npm 和可访问 npm registry 的网络
• 能运行 MCP 客户端的本机浏览器，用于完成首次 OAuth 授权

安装 Node.js 后可在终端验证：

node --version
npm --version
npx --version

快速开始

推荐通过 npx 在 MCP 客户端启动时按需下载并运行，无需全局安装。将以下配置加入客户端的 MCP 配置文件：

{
  "mcpServers": {
    "scorehub": {
      "command": "npx",
      "args": ["-y", "@scorehub/mcp-server@latest"]
    }
  }
}

配置位置通常为：

| 客户端 | 配置文件 | |---|---| | 其他 MCP 客户端 | 该客户端使用的 MCP 配置文件 | | WorkBuddy | mcp.json |

首次启动时，npx 会下载 @scorehub/mcp-server 并连接远程端点。首次调用远程工具时，按客户端提示调用 authorize：浏览器会打开 ScoreHub 登录页，授权完成后回调到 127.0.0.1 的随机端口并写入本地 Token。在 WorkBuddy 中，成功回调页可通过“切换到终端继续”唤起 Tiky；之后会复用缓存，不需要每次登录。

通过 WorkBuddy 分享链接安装 Tiky 后，Tiky 会在首轮 bootstrap 门禁中经用户首次确认后自动写入或修复这份 MCP 配置；无需手动编辑。

启动前自检

在写入 WorkBuddy 配置前，creator-outreach 会预拉取 npm latest 并执行：

npx -y @scorehub/mcp-server@latest --self-check --json

该命令返回包版本、Node.js 版本和可执行入口状态，然后立即退出。它不启动 stdio 服务、不访问远端 MCP、不进入 OAuth，也不写入 Token。

Windows 使用说明

手工配置普通 MCP 客户端时，Windows 与 macOS、Linux 一样使用前文的 "command": "npx"，不需要手工改成 npx.cmd 或另行全局安装。WorkBuddy 的公开安装路径由 Tiky 自动生成配置：它会使用 WorkBuddy 托管的 node.exe 直接加载同版本 npm 的 npx-cli.js，避免宿主原生进程 API 直接启动 .cmd / .bat 的兼容问题。

1. 安装 Node.js 18+ 后，重新打开 PowerShell 或 Windows Terminal，运行前置条件中的三个版本命令。
2. 如果提示找不到 node、npm 或 npx，说明 Node.js 尚未加入当前进程的 PATH：关闭并重新打开客户端和终端；仍无法识别时，检查 Node.js 安装是否完成。
3. 如果 MCP 客户端显示工具不可见、连接关闭或本地 MCP 未启动，确认 npm registry 可访问后完全重启客户端再试。这不是 OAuth、店铺授权或限流问题。
4. 授权时会优先使用 cmd.exe /c start 打开默认浏览器。被系统策略拦截时，复制终端输出的授权 URL，在运行 mcp-server 的同一台 Windows 电脑上打开并完成授权。
5. 回调固定使用 127.0.0.1 随机端口。不要在另一台电脑打开授权 URL；本机安全软件若拦截回环回调，应允许本地回环连接后重试。

WorkBuddy 若使用其捆绑的 Node.js，建议先通过分享链接安装 Tiky，再由 Tiky 执行 npx -y @scorehub/creator-outreach@latest 完成本地引导；该流程会自动解析托管的 node.exe、npx-cli.js 与 PATH，不需要创建包装脚本或手工编辑 mcp.json。

可选：全局安装

如果你希望自行管理升级并通过固定的 scorehub-mcp 命令启动，可以全局安装：

npm install -g @scorehub/mcp-server

全局安装后，将 MCP 配置中的 command 改为 scorehub-mcp，移除 args：

{
  "mcpServers": {
    "scorehub": {
      "command": "scorehub-mcp"
    }
  }
}

全局安装依赖 npm 全局 bin 目录位于客户端 PATH 中，并需要自行运行 npm update -g @scorehub/mcp-server 升级。一般情况下，优先使用前文的 npx 配置。

配置与 Token

环境变量

| 变量 | 必填 | 默认值 | 说明 | |---|---|---|---| | SCOREHUB_REMOTE_MCP_URL | 否 | https://app.scorehub.cn/mcp | ScoreHub 提供非默认远程端点时使用；通常无需设置。 |

Token 存储

OAuth Token 保存在当前用户目录下：

~/.scorehub/<endpoint>/oauth.json

<endpoint> 根据 SCOREHUB_REMOTE_MCP_URL 的主机与路径生成，例如 app.scorehub.cn_mcp。因此生产和测试环境使用不同地址时，Token 会自动隔离。

Token 持久化在本机文件中；调用默认 ScoreHub 生产端点时，mcp-server 会通过 HTTPS 的 Authorization 请求头将访问 Token 提供给远程 MCP。不要共享或提交 ~/.scorehub/ 下的文件。

如需退出登录，删除对应端点目录或整个 ~/.scorehub/ 目录，然后重新调用 authorize。在 Windows 资源管理器中删除该目录即可；macOS/Linux 也可用终端删除。

authorize 默认复用有效的 access token 或 refresh token，不会重复打开浏览器。传入 force: true 会清除当前端点缓存并要求重新登录，可用于切换账号；传入 switch_shop: true 会打开当前账号的店铺选择页，确认后直接替换本地 token，不要求再次登录。两个参数不能同时使用；店铺切换取消或失败时会保留原店铺 token。

可用工具

本地工具

| 工具 | 说明 | |---|---| | authorize | 检查 ScoreHub OAuth 状态；force: true 重新登录以切换账号，switch_shop: true 打开当前账号的店铺选择页。 | | status | 返回本地代理版本、运行状态、授权状态、远端工具可用性、当前账号/店铺和宿主安装来源元数据。 |

远程工具

远程工具由 ScoreHub 端点在启动时动态发现，并在每次 ListTools 请求时刷新；远端新增工具后通常无需升级本地包。当前常见工具包括：

| 工具 | 说明 | |---|---| | search_creators | 按关键词、GMV、销量、类目等条件搜索 TikTok Shop 达人。 | | creator_performance | 获取达人近 30 天的 GMV、粉丝画像和内容表现数据。 | | get_categories | 获取 TikTok Shop 商品类目。 | | create_conversation | 与指定达人创建建联会话。 | | send_message | 发送文本、商品卡、合作邀请、样品邀请或图片消息。 |

授权与错误处理

授权链路如下：

本地 mcp-server                         ScoreHub 远程 MCP
      │                                        │
      ├─ tools/call: authorize                  │
      │  （默认检查并复用本地 Token）            │
      │                                        │
      ├─ 无有效 Token 时监听 127.0.0.1 随机端口  │
      ├─ 生成 state 与 PKCE 参数                │
      ├─ 打开浏览器 → /authorize ──────────────▶│
      │                用户登录并授权            │
      │◀── 回调 127.0.0.1:<随机端口>             │
      ├─ POST /token（携带 code_verifier） ────▶│
      │◀── access_token 与 refresh_token         │
      └─ 写入 ~/.scorehub/<endpoint>/oauth.json

| 场景 | 处理方式 | |---|---| | 本地 MCP 未启动、工具不可见或连接关闭 | 检查 Node.js 18+、npm、npm registry 网络和客户端 PATH，然后完全重启客户端；不要直接重新授权。 | | oauth_invalid | 本地 OAuth 已失效；按提示调用 authorize 重新登录。 | | shop_auth_invalid | ScoreHub 本地登录仍可能正常；前往 ScoreHub 重新绑定当前店铺，不要反复本地登录。 | | rate_limited / quota_exhausted | 等待、分批执行或缩小请求范围；不要为了限流重新授权。 | | invalid_input | 修正工具参数，不走授权流程。 | | 浏览器无法自动打开 | 使用终端输出的授权 URL，并在运行 mcp-server 的同一台机器上完成回调。 | | Windows 授权页提示授权链接无效，或浏览器地址栏缺少 redirect_uri | 完全退出并重启 WorkBuddy，确认 ~/.workbuddy/mcp.json 的 scorehub 参数仍包含 @scorehub/mcp-server@latest，且配置由 @scorehub/creator-outreach 托管；若不符合，重新运行 Tiky bootstrap 修复。新版会通过 PowerShell 打开授权 URL，避免 cmd.exe start 截断带 & 的参数。 |

status 的关键字段说明：

• server_version：当前本地 @scorehub/mcp-server 版本
• local_state：
  • running_ready：本地代理已启动、已授权，且远端工具可用
  • running_unauthorized：本地代理已启动，但尚未完成 ScoreHub OAuth
  • running_authorized_remote_unavailable：本地代理已启动且已授权，但远端工具发现暂时不可用
  • running_authorized_no_remote_tools：本地代理已启动且已授权，但当前尚未发现远端工具，且没有明确抓到远端错误
• config_source：宿主与安装来源元数据。若显示 client_host = "workbuddy" 且 managed_by = "@scorehub/creator-outreach"，表示当前配置来自 Tiky 的 WorkBuddy 公开安装路径；通常先由分享链接把 Tiky 装入 WorkBuddy，再由 Tiky 执行 npx -y @scorehub/creator-outreach@latest 完成本地引导

常见问题

为什么需要这个包？

使用 @scorehub/creator-outreach（Tiky）时，该包提供搜索达人、分析表现和发送建联消息所需的 MCP 工具。它也可以单独接入任何兼容 MCP 的客户端。

远程 MCP 不可达时会怎样？

本地 authorize 与 status 仍可用。远程工具列表会在启动失败后于后续 ListTools 请求时重试；远端恢复后，无需重启本地包即可重新发现工具。

如何升级？

使用 npx -y ...@latest 时，每次启动按 npm 当前 latest 标签解析。全局安装则执行：

npm update -g @scorehub/mcp-server

由于 WorkBuddy 公开配置始终跟随 @latest，同一包名下的 latest 发布必须保持工具名、参数、OAuth 和 status 契约向后兼容。无法兼容的新协议必须使用新包名。

相关包

| 包 | 说明 | |---|---| | @scorehub/creator-outreach | Tiky 智能体，面向 TikTok Shop 达人搜索、分析和建联。 | | scorehub-mcp-remote | ScoreHub 私有部署的远程 MCP 端点。 |

许可证

MIT