@scorehub/mcp-server 0.2.11 → 0.2.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.en.md +205 -0
- package/README.md +111 -199
- package/dist/auth.js +15 -1
- package/package.json +6 -2
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ScoreHub
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.en.md
ADDED
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
# @scorehub/mcp-server
|
|
2
|
+
|
|
3
|
+
Chinese version: [README.md](./README.md)
|
|
4
|
+
|
|
5
|
+
> ScoreHub's local MCP proxy. It handles browser-based OAuth login, token caching, and forwarding tool calls from local AI clients to the ScoreHub remote MCP server.
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/@scorehub/mcp-server)
|
|
8
|
+
[](./LICENSE)
|
|
9
|
+
[](https://nodejs.org/)
|
|
10
|
+
|
|
11
|
+
## Overview
|
|
12
|
+
|
|
13
|
+
`@scorehub/mcp-server` runs on your computer between MCP clients such as Claude Code, Claude Desktop, and WorkBuddy and the ScoreHub remote MCP server. It provides:
|
|
14
|
+
|
|
15
|
+
- **OAuth login**: Opens a browser for authorization when needed and caches ScoreHub tokens locally.
|
|
16
|
+
- **Token lifecycle management**: Checks token validity before calls, refreshes tokens within five minutes of expiry, and keeps long-running sessions alive every four hours.
|
|
17
|
+
- **Tool forwarding**: Forwards TikTok Shop creator outreach tool calls to the ScoreHub remote MCP server over Streamable HTTP.
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
┌─────────────┐ stdio ┌──────────────────┐ Streamable HTTP ┌─────────────────┐
|
|
21
|
+
│ AI client │ ◄────────────► │ @scorehub/ │ ◄─────────────────► │ ScoreHub │
|
|
22
|
+
│ Claude etc.│ │ mcp-server │ │ Remote MCP │
|
|
23
|
+
└─────────────┘ └──────────────────┘ └────────┬────────┘
|
|
24
|
+
│
|
|
25
|
+
TikTok Shop
|
|
26
|
+
Partner API
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Prerequisites
|
|
30
|
+
|
|
31
|
+
- Node.js 18 or later. The current LTS release is recommended.
|
|
32
|
+
- npm and network access to the npm registry.
|
|
33
|
+
- A browser on the same machine as your MCP client, for the first OAuth authorization.
|
|
34
|
+
|
|
35
|
+
After installing Node.js, verify the tools in a terminal:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
node --version
|
|
39
|
+
npm --version
|
|
40
|
+
npx --version
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Quick Start
|
|
44
|
+
|
|
45
|
+
We recommend running the package on demand through `npx` whenever your MCP client starts. No global installation is required. Add the following to your client's MCP configuration file:
|
|
46
|
+
|
|
47
|
+
```json
|
|
48
|
+
{
|
|
49
|
+
"mcpServers": {
|
|
50
|
+
"scorehub": {
|
|
51
|
+
"command": "npx",
|
|
52
|
+
"args": ["-y", "@scorehub/mcp-server@latest"]
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Common configuration locations are:
|
|
59
|
+
|
|
60
|
+
| Client | Configuration file |
|
|
61
|
+
|---|---|
|
|
62
|
+
| Claude Code / Claude Desktop | The MCP configuration file used by the client, such as `claude_desktop_config.json` or `.claude/mcp.json` |
|
|
63
|
+
| WorkBuddy | `mcp.json` |
|
|
64
|
+
|
|
65
|
+
On the first launch, `npx` downloads `@scorehub/mcp-server` and connects it to the remote endpoint. When you first call a remote tool, invoke `authorize` when prompted by your client. A browser opens the ScoreHub login page; after authorization it returns to a random `127.0.0.1` port and stores the token locally. Later calls reuse the cached token and do not require another login.
|
|
66
|
+
|
|
67
|
+
> When you install Tiky through `@scorehub/creator-outreach`, its installer writes this MCP configuration automatically. Manual setup is not required.
|
|
68
|
+
|
|
69
|
+
## Windows
|
|
70
|
+
|
|
71
|
+
Windows uses the same MCP JSON configuration as macOS and Linux. You do not need `npx.cmd` or a separate global installation.
|
|
72
|
+
|
|
73
|
+
1. After installing Node.js 18+, reopen PowerShell or Windows Terminal and run the three version commands from the prerequisites section.
|
|
74
|
+
2. If `node`, `npm`, or `npx` cannot be found, Node.js is not available on the current process PATH. Close and reopen the client and terminal; if the problem remains, verify the Node.js installation.
|
|
75
|
+
3. If your MCP client shows no tools, closes the connection, or does not start the local MCP server, confirm access to the npm registry and fully restart the client. This is not an OAuth, shop authorization, or rate-limit issue.
|
|
76
|
+
4. Authorization uses PowerShell `Start-Process` to open your default browser, so OAuth URL parameters such as `redirect_uri` are preserved. If system policy blocks it, copy the authorization URL printed in the terminal and open it on the **same Windows computer that runs mcp-server**.
|
|
77
|
+
5. The callback always uses a random `127.0.0.1` port. Do not open the authorization URL on another computer. If local security software blocks the loopback callback, allow local loopback connections and try again.
|
|
78
|
+
|
|
79
|
+
If WorkBuddy uses its bundled Node.js, install through `@scorehub/creator-outreach`. The installer handles `npx` / `npx.cmd` and PATH differences for each platform.
|
|
80
|
+
|
|
81
|
+
## Optional: Global Installation
|
|
82
|
+
|
|
83
|
+
If you prefer to manage upgrades yourself and use a fixed `scorehub-mcp` command, install the package globally:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
npm install -g @scorehub/mcp-server
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Then change `command` in your MCP configuration to `scorehub-mcp` and remove `args`:
|
|
90
|
+
|
|
91
|
+
```json
|
|
92
|
+
{
|
|
93
|
+
"mcpServers": {
|
|
94
|
+
"scorehub": {
|
|
95
|
+
"command": "scorehub-mcp"
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Global installation requires npm's global bin directory to be on the MCP client's PATH. You must also run `npm update -g @scorehub/mcp-server` to upgrade. In most cases, prefer the `npx` configuration above.
|
|
102
|
+
|
|
103
|
+
## Configuration and Tokens
|
|
104
|
+
|
|
105
|
+
### Environment Variables
|
|
106
|
+
|
|
107
|
+
| Variable | Required | Default | Description |
|
|
108
|
+
|---|---|---|---|
|
|
109
|
+
| `SCOREHUB_REMOTE_MCP_URL` | No | `https://app.scorehub.cn/mcp` | Use only when ScoreHub provides a non-default remote endpoint. It is normally unnecessary. |
|
|
110
|
+
|
|
111
|
+
### Token Storage
|
|
112
|
+
|
|
113
|
+
OAuth tokens are stored under the current user's home directory:
|
|
114
|
+
|
|
115
|
+
```
|
|
116
|
+
~/.scorehub/<endpoint>/oauth.json
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
`<endpoint>` is generated from the host and path of `SCOREHUB_REMOTE_MCP_URL`, for example `app.scorehub.cn_mcp`. Tokens are therefore isolated when you use different production and test endpoints.
|
|
120
|
+
|
|
121
|
+
Tokens persist in a local file. When calling the default ScoreHub production endpoint, mcp-server sends the access token to the remote MCP server in an HTTPS `Authorization` header. Do not share or commit files under `~/.scorehub/`.
|
|
122
|
+
|
|
123
|
+
To sign out or switch accounts, delete the directory for the relevant endpoint, or all of `~/.scorehub/`, then invoke `authorize` again. On Windows, delete the directory in File Explorer; on macOS and Linux, you can also delete it from a terminal.
|
|
124
|
+
|
|
125
|
+
By default, `authorize` reuses a valid access token or refresh token and does not open a browser again. Only an explicit `force: true` clears the cached token for the current endpoint and starts a new login.
|
|
126
|
+
|
|
127
|
+
## Available Tools
|
|
128
|
+
|
|
129
|
+
### Local Tools
|
|
130
|
+
|
|
131
|
+
| Tool | Description |
|
|
132
|
+
|---|---|
|
|
133
|
+
| `authorize` | Checks the ScoreHub OAuth state. Reuses the cache by default; passing `force: true` opens the browser for a new login. |
|
|
134
|
+
| `status` | Returns the remote address, authorization state, and current number of available tools. |
|
|
135
|
+
|
|
136
|
+
### Remote Tools
|
|
137
|
+
|
|
138
|
+
Remote tools are discovered from the ScoreHub endpoint at startup and refreshed for every `ListTools` request. New remote tools normally become available without a local package upgrade. Common tools include:
|
|
139
|
+
|
|
140
|
+
| Tool | Description |
|
|
141
|
+
|---|---|
|
|
142
|
+
| `search_creators` | Searches TikTok Shop creators by keyword, GMV, sales, category, and other criteria. |
|
|
143
|
+
| `creator_performance` | Returns a creator's last 30 days of GMV, audience profile, and content performance data. |
|
|
144
|
+
| `get_categories` | Returns TikTok Shop product categories. |
|
|
145
|
+
| `create_conversation` | Creates an outreach conversation with a specified creator. |
|
|
146
|
+
| `send_message` | Sends text, product cards, collaboration invitations, sample invitations, or image messages. |
|
|
147
|
+
|
|
148
|
+
## Authorization and Error Handling
|
|
149
|
+
|
|
150
|
+
The authorization flow is:
|
|
151
|
+
|
|
152
|
+
```
|
|
153
|
+
Local mcp-server ScoreHub Remote MCP
|
|
154
|
+
│ │
|
|
155
|
+
├─ tools/call: authorize │
|
|
156
|
+
│ (checks and reuses local tokens) │
|
|
157
|
+
│ │
|
|
158
|
+
├─ listens on a random 127.0.0.1 port │
|
|
159
|
+
├─ creates state and PKCE parameters │
|
|
160
|
+
├─ opens browser → /authorize ───────────▶│
|
|
161
|
+
│ user logs in and authorizes
|
|
162
|
+
│◀── callback to 127.0.0.1:<random port> │
|
|
163
|
+
├─ POST /token (with code_verifier) ─────▶│
|
|
164
|
+
│◀── access_token and refresh_token │
|
|
165
|
+
└─ writes ~/.scorehub/<endpoint>/oauth.json
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
| Situation | What to do |
|
|
169
|
+
|---|---|
|
|
170
|
+
| Local MCP server does not start, tools are unavailable, or the connection closes | Check Node.js 18+, npm, npm registry access, and the client PATH, then fully restart the client. Do not reauthorize first. |
|
|
171
|
+
| `oauth_invalid` | The local OAuth authorization has expired. Invoke `authorize` to log in again. |
|
|
172
|
+
| `shop_auth_invalid` | Your local ScoreHub login may still be valid. Rebind the current shop in ScoreHub instead of repeatedly logging in locally. |
|
|
173
|
+
| `rate_limited` / `quota_exhausted` | Wait, split the operation into batches, or narrow the request. Do not reauthorize for rate limits. |
|
|
174
|
+
| `invalid_input` | Correct the tool parameters; do not start authorization. |
|
|
175
|
+
| Browser does not open automatically | Use the authorization URL printed in the terminal and complete the callback on the same machine that runs mcp-server. |
|
|
176
|
+
| The authorization page says the link is invalid, or the browser URL has no `redirect_uri` | Fully quit and restart WorkBuddy, and confirm `~/.workbuddy/mcp.json` still uses `npx -y @scorehub/mcp-server@latest`. Newer versions open the OAuth URL through PowerShell to avoid truncating query parameters. |
|
|
177
|
+
|
|
178
|
+
## FAQ
|
|
179
|
+
|
|
180
|
+
### Why do I need this package?
|
|
181
|
+
|
|
182
|
+
When you use `@scorehub/creator-outreach` (Tiky), this package provides the MCP tools needed to search creators, analyze their performance, and send outreach messages. You can also connect it directly to any compatible MCP client.
|
|
183
|
+
|
|
184
|
+
### What happens if the remote MCP server is unreachable?
|
|
185
|
+
|
|
186
|
+
Local `authorize` and `status` remain available. After a failed startup, remote tool discovery is retried on later `ListTools` requests. Once the remote server recovers, the local package discovers the tools again without a restart.
|
|
187
|
+
|
|
188
|
+
### How do I upgrade?
|
|
189
|
+
|
|
190
|
+
With `npx -y ...@latest`, every launch resolves npm's current `latest` tag. For a global installation, run:
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
npm update -g @scorehub/mcp-server
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## Related Packages
|
|
197
|
+
|
|
198
|
+
| Package | Description |
|
|
199
|
+
|---|---|
|
|
200
|
+
| [`@scorehub/creator-outreach`](https://www.npmjs.com/package/@scorehub/creator-outreach) | Tiky agent for TikTok Shop creator search, analysis, and outreach. |
|
|
201
|
+
| `scorehub-mcp-remote` | ScoreHub's privately deployed remote MCP endpoint. |
|
|
202
|
+
|
|
203
|
+
## License
|
|
204
|
+
|
|
205
|
+
[MIT](./LICENSE)
|
package/README.md
CHANGED
|
@@ -1,293 +1,205 @@
|
|
|
1
1
|
# @scorehub/mcp-server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
English version: [README.en.md](./README.en.md)
|
|
4
|
+
|
|
5
|
+
> ScoreHub 本地 MCP 代理，负责浏览器 OAuth 登录、Token 缓存，以及将本地 AI 客户端的工具调用转发至 ScoreHub 远程 MCP。
|
|
4
6
|
|
|
5
7
|
[](https://www.npmjs.com/package/@scorehub/mcp-server)
|
|
6
8
|
[](./LICENSE)
|
|
7
9
|
[](https://nodejs.org/)
|
|
8
10
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
## Overview
|
|
11
|
+
## 概览
|
|
12
12
|
|
|
13
|
-
`@scorehub/mcp-server`
|
|
13
|
+
`@scorehub/mcp-server` 运行在你的电脑上，位于 Claude Code、Claude Desktop、WorkBuddy 等 MCP 客户端与 ScoreHub 远程 MCP 之间，负责：
|
|
14
14
|
|
|
15
|
-
- **OAuth
|
|
16
|
-
- **Token
|
|
17
|
-
-
|
|
15
|
+
- **OAuth 登录**：首次需要授权时打开浏览器，登录 ScoreHub 后将 Token 缓存到本机。
|
|
16
|
+
- **Token 生命周期**：调用前检查 Token 有效期；距过期不足 5 分钟时自动刷新，并为长会话每 4 小时主动保活一次。
|
|
17
|
+
- **工具转发**：通过 Streamable HTTP 将 TikTok Shop 达人建联相关工具请求转发到 ScoreHub 远程 MCP。
|
|
18
18
|
|
|
19
19
|
```
|
|
20
20
|
┌─────────────┐ stdio ┌──────────────────┐ Streamable HTTP ┌─────────────────┐
|
|
21
|
-
│ AI
|
|
22
|
-
│
|
|
21
|
+
│ AI 客户端 │ ◄────────────► │ @scorehub/ │ ◄─────────────────► │ ScoreHub │
|
|
22
|
+
│ Claude 等 │ │ mcp-server │ │ 远程 MCP │
|
|
23
23
|
└─────────────┘ └──────────────────┘ └────────┬────────┘
|
|
24
24
|
│
|
|
25
25
|
TikTok Shop
|
|
26
26
|
Partner API
|
|
27
27
|
```
|
|
28
28
|
|
|
29
|
-
##
|
|
29
|
+
## 前置条件
|
|
30
30
|
|
|
31
|
-
|
|
31
|
+
- Node.js 18 或更高版本（建议使用当前 LTS 版本）
|
|
32
|
+
- npm 和可访问 npm registry 的网络
|
|
33
|
+
- 能运行 MCP 客户端的本机浏览器，用于完成首次 OAuth 授权
|
|
34
|
+
|
|
35
|
+
安装 Node.js 后可在终端验证：
|
|
32
36
|
|
|
33
37
|
```bash
|
|
34
|
-
|
|
38
|
+
node --version
|
|
39
|
+
npm --version
|
|
40
|
+
npx --version
|
|
35
41
|
```
|
|
36
42
|
|
|
37
|
-
|
|
43
|
+
## 快速开始
|
|
38
44
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
Add this to your MCP client configuration file:
|
|
42
|
-
|
|
43
|
-
### Claude Code / Claude Desktop
|
|
44
|
-
|
|
45
|
-
In `claude_desktop_config.json` or `.claude/mcp.json`:
|
|
45
|
+
推荐通过 `npx` 在 MCP 客户端启动时按需下载并运行，无需全局安装。将以下配置加入客户端的 MCP 配置文件：
|
|
46
46
|
|
|
47
47
|
```json
|
|
48
48
|
{
|
|
49
49
|
"mcpServers": {
|
|
50
50
|
"scorehub": {
|
|
51
51
|
"command": "npx",
|
|
52
|
-
"args": ["-y", "@scorehub/mcp-server"]
|
|
53
|
-
"env": {
|
|
54
|
-
"SCOREHUB_REMOTE_MCP_URL": "https://app.scorehub.cn/mcp"
|
|
55
|
-
}
|
|
52
|
+
"args": ["-y", "@scorehub/mcp-server@latest"]
|
|
56
53
|
}
|
|
57
54
|
}
|
|
58
55
|
}
|
|
59
56
|
```
|
|
60
57
|
|
|
61
|
-
|
|
58
|
+
配置位置通常为：
|
|
62
59
|
|
|
63
|
-
|
|
60
|
+
| 客户端 | 配置文件 |
|
|
61
|
+
|---|---|
|
|
62
|
+
| Claude Code / Claude Desktop | 客户端使用的 MCP 配置文件，例如 `claude_desktop_config.json` 或 `.claude/mcp.json` |
|
|
63
|
+
| WorkBuddy | `mcp.json` |
|
|
64
64
|
|
|
65
|
-
|
|
66
|
-
{
|
|
67
|
-
"mcpServers": {
|
|
68
|
-
"scorehub": {
|
|
69
|
-
"command": "npx",
|
|
70
|
-
"args": ["-y", "@scorehub/mcp-server"],
|
|
71
|
-
"env": {
|
|
72
|
-
"SCOREHUB_REMOTE_MCP_URL": "https://app.scorehub.cn/mcp"
|
|
73
|
-
}
|
|
74
|
-
}
|
|
75
|
-
}
|
|
76
|
-
}
|
|
77
|
-
```
|
|
65
|
+
首次启动时，`npx` 会下载 `@scorehub/mcp-server` 并连接远程端点。首次调用远程工具时，按客户端提示调用 `authorize`：浏览器会打开 ScoreHub 登录页，授权完成后回调到 `127.0.0.1` 的随机端口并写入本地 Token。之后会复用缓存，不需要每次登录。
|
|
78
66
|
|
|
79
|
-
|
|
67
|
+
> 使用 `@scorehub/creator-outreach` 安装 Tiky 时，安装器会自动写入这份 MCP 配置；无需手动配置。
|
|
80
68
|
|
|
81
|
-
|
|
82
|
-
2. It fetches the list of available tools
|
|
83
|
-
3. The first time you use a remote tool, you'll be prompted to run the `authorize` tool
|
|
84
|
-
4. Your browser opens to the ScoreHub login page
|
|
85
|
-
5. After authorizing, the browser redirects to `127.0.0.1:<random-port>/callback`, shows a local status page, and the token is saved
|
|
86
|
-
6. Subsequent calls use the cached token — no repeated login needed
|
|
69
|
+
## Windows 使用说明
|
|
87
70
|
|
|
88
|
-
|
|
71
|
+
Windows 与 macOS、Linux 使用同一份 MCP JSON 配置，不需要改成 `npx.cmd` 或另行全局安装。
|
|
89
72
|
|
|
90
|
-
|
|
73
|
+
1. 安装 Node.js 18+ 后，重新打开 PowerShell 或 Windows Terminal，运行前置条件中的三个版本命令。
|
|
74
|
+
2. 如果提示找不到 `node`、`npm` 或 `npx`，说明 Node.js 尚未加入当前进程的 PATH：关闭并重新打开客户端和终端；仍无法识别时，检查 Node.js 安装是否完成。
|
|
75
|
+
3. 如果 MCP 客户端显示工具不可见、连接关闭或本地 MCP 未启动，确认 npm registry 可访问后完全重启客户端再试。这不是 OAuth、店铺授权或限流问题。
|
|
76
|
+
4. 授权时会优先使用 `cmd.exe /c start` 打开默认浏览器。被系统策略拦截时，复制终端输出的授权 URL，在**运行 mcp-server 的同一台 Windows 电脑**上打开并完成授权。
|
|
77
|
+
5. 回调固定使用 `127.0.0.1` 随机端口。不要在另一台电脑打开授权 URL；本机安全软件若拦截回环回调，应允许本地回环连接后重试。
|
|
91
78
|
|
|
92
|
-
|
|
93
|
-
|---|---|---|---|
|
|
94
|
-
| `SCOREHUB_REMOTE_MCP_URL` | No | `https://app.scorehub.cn/mcp` | Base URL of the remote ScoreHub MCP endpoint |
|
|
79
|
+
WorkBuddy 若使用其捆绑的 Node.js，建议通过 `@scorehub/creator-outreach` 安装器完成配置；该安装器会按平台处理 `npx` / `npx.cmd` 与 PATH。
|
|
95
80
|
|
|
96
|
-
|
|
81
|
+
## 可选：全局安装
|
|
97
82
|
|
|
98
|
-
|
|
83
|
+
如果你希望自行管理升级并通过固定的 `scorehub-mcp` 命令启动，可以全局安装：
|
|
99
84
|
|
|
85
|
+
```bash
|
|
86
|
+
npm install -g @scorehub/mcp-server
|
|
100
87
|
```
|
|
101
|
-
~/.scorehub/<endpoint>/oauth.json
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
The `<endpoint>` is derived from the `SCOREHUB_REMOTE_MCP_URL` host and path (for example, `app.scorehub.cn_mcp`). This means you can run staging and production side-by-side by pointing each configuration at a different URL — tokens are isolated per endpoint.
|
|
105
88
|
|
|
106
|
-
|
|
89
|
+
全局安装后，将 MCP 配置中的 `command` 改为 `scorehub-mcp`，移除 `args`：
|
|
107
90
|
|
|
108
91
|
```json
|
|
109
92
|
{
|
|
110
|
-
"
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
93
|
+
"mcpServers": {
|
|
94
|
+
"scorehub": {
|
|
95
|
+
"command": "scorehub-mcp"
|
|
96
|
+
}
|
|
97
|
+
}
|
|
114
98
|
}
|
|
115
99
|
```
|
|
116
100
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
The `authorize` tool reuses cached credentials by default. If the cached access token is still valid, or the refresh token can renew it, `authorize` returns without opening the browser. To force a new browser login, call `authorize` with `force: true`.
|
|
120
|
-
|
|
121
|
-
## Available Tools
|
|
122
|
-
|
|
123
|
-
### Local tools
|
|
101
|
+
全局安装依赖 npm 全局 bin 目录位于客户端 PATH 中，并需要自行运行 `npm update -g @scorehub/mcp-server` 升级。一般情况下，优先使用前文的 `npx` 配置。
|
|
124
102
|
|
|
125
|
-
|
|
103
|
+
## 配置与 Token
|
|
126
104
|
|
|
127
|
-
|
|
128
|
-
|---|---|
|
|
129
|
-
| `authorize` | Checks ScoreHub OAuth status. Reuses cached credentials by default; pass `force: true` to open the browser for a fresh login. |
|
|
130
|
-
| `status` | Returns connection status: remote URL, authorization state, and count of available tools. |
|
|
131
|
-
|
|
132
|
-
### Remote tools
|
|
105
|
+
### 环境变量
|
|
133
106
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
|
137
|
-
|---|---|
|
|
138
|
-
| `search_creators` | Search TikTok Shop creators by keywords, GMV range, sales volume, category, and other filters |
|
|
139
|
-
| `creator_performance` | Analyze creator performance — 30-day GMV, follower demographics, content engagement data |
|
|
140
|
-
| `get_categories` | Fetch available TikTok Shop product categories |
|
|
141
|
-
| `create_conversation` | Create a collaboration conversation thread with a specific creator |
|
|
142
|
-
| `send_message` | Send a collaboration message (text, product card, collaboration invite, sample request, or image) |
|
|
107
|
+
| 变量 | 必填 | 默认值 | 说明 |
|
|
108
|
+
|---|---|---|---|
|
|
109
|
+
| `SCOREHUB_REMOTE_MCP_URL` | 否 | `https://app.scorehub.cn/mcp` | ScoreHub 提供非默认远程端点时使用；通常无需设置。 |
|
|
143
110
|
|
|
144
|
-
|
|
111
|
+
### Token 存储
|
|
145
112
|
|
|
146
|
-
|
|
113
|
+
OAuth Token 保存在当前用户目录下：
|
|
147
114
|
|
|
148
115
|
```
|
|
149
|
-
|
|
150
|
-
│ │
|
|
151
|
-
├─ tools/call: authorize ──────────┤
|
|
152
|
-
│ (clears any existing token) │
|
|
153
|
-
│ │
|
|
154
|
-
├─ opens local callback on 127.0.0.1:<random-port>
|
|
155
|
-
├─ generates random state + PKCE │
|
|
156
|
-
├─ opens browser → /authorize ────▶│
|
|
157
|
-
│ user logs in + grants access
|
|
158
|
-
│ ◀── redirect to 127.0.0.1:<random-port>
|
|
159
|
-
│ with authorization_code │
|
|
160
|
-
│ │
|
|
161
|
-
├─ POST /token (code_verifier) ───▶│
|
|
162
|
-
│◀── access_token + refresh_token │
|
|
163
|
-
│ │
|
|
164
|
-
├─ saves to ~/.scorehub/<endpoint>/oauth.json
|
|
116
|
+
~/.scorehub/<endpoint>/oauth.json
|
|
165
117
|
```
|
|
166
118
|
|
|
167
|
-
|
|
119
|
+
`<endpoint>` 根据 `SCOREHUB_REMOTE_MCP_URL` 的主机与路径生成，例如 `app.scorehub.cn_mcp`。因此生产和测试环境使用不同地址时，Token 会自动隔离。
|
|
168
120
|
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
| Stage | Behavior |
|
|
172
|
-
|---|---|
|
|
173
|
-
| **First use** | Browser OAuth → callback → write token to local file |
|
|
174
|
-
| **Subsequent calls** | Read cached file → check expiry with 5-minute buffer |
|
|
175
|
-
| **Near expiry** | Auto-refresh with `refresh_token` → write new token back to file |
|
|
176
|
-
| **Refresh fails** | Returns an error message with the authorization URL — call `authorize` again |
|
|
177
|
-
| **Manual logout** | Delete `~/.scorehub/<endpoint>/oauth.json` or the entire `~/.scorehub/` directory |
|
|
121
|
+
Token 持久化在本机文件中；调用默认 ScoreHub 生产端点时，mcp-server 会通过 HTTPS 的 `Authorization` 请求头将访问 Token 提供给远程 MCP。不要共享或提交 `~/.scorehub/` 下的文件。
|
|
178
122
|
|
|
179
|
-
|
|
123
|
+
如需退出登录或切换账号，删除对应端点目录或整个 `~/.scorehub/` 目录，然后重新调用 `authorize`。在 Windows 资源管理器中删除该目录即可；macOS/Linux 也可用终端删除。
|
|
180
124
|
|
|
181
|
-
|
|
125
|
+
`authorize` 默认复用有效的 access token 或 refresh token，不会重复打开浏览器。只有显式传入 `force: true` 时，才会清除当前端点缓存并要求重新登录。
|
|
182
126
|
|
|
183
|
-
|
|
127
|
+
## 可用工具
|
|
184
128
|
|
|
185
|
-
###
|
|
129
|
+
### 本地工具
|
|
186
130
|
|
|
187
|
-
|
|
131
|
+
| 工具 | 说明 |
|
|
132
|
+
|---|---|
|
|
133
|
+
| `authorize` | 检查 ScoreHub OAuth 状态；默认复用缓存，传入 `force: true` 才重新打开浏览器登录。 |
|
|
134
|
+
| `status` | 返回远程地址、授权状态和当前可用工具数量。 |
|
|
188
135
|
|
|
189
|
-
|
|
190
|
-
SCOREHUB_REMOTE_MCP_URL=http://127.0.0.1:5201 npm start -w packages/mcp-server
|
|
191
|
-
```
|
|
136
|
+
### 远程工具
|
|
192
137
|
|
|
193
|
-
|
|
138
|
+
远程工具由 ScoreHub 端点在启动时动态发现，并在每次 `ListTools` 请求时刷新；远端新增工具后通常无需升级本地包。当前常见工具包括：
|
|
194
139
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
140
|
+
| 工具 | 说明 |
|
|
141
|
+
|---|---|
|
|
142
|
+
| `search_creators` | 按关键词、GMV、销量、类目等条件搜索 TikTok Shop 达人。 |
|
|
143
|
+
| `creator_performance` | 获取达人近 30 天的 GMV、粉丝画像和内容表现数据。 |
|
|
144
|
+
| `get_categories` | 获取 TikTok Shop 商品类目。 |
|
|
145
|
+
| `create_conversation` | 与指定达人创建建联会话。 |
|
|
146
|
+
| `send_message` | 发送文本、商品卡、合作邀请、样品邀请或图片消息。 |
|
|
201
147
|
|
|
202
|
-
|
|
148
|
+
## 授权与错误处理
|
|
203
149
|
|
|
204
|
-
|
|
150
|
+
授权链路如下：
|
|
205
151
|
|
|
206
152
|
```
|
|
207
|
-
|
|
208
|
-
│
|
|
209
|
-
│
|
|
210
|
-
│
|
|
211
|
-
│
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
│
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
│
|
|
219
|
-
|
|
220
|
-
│ Streamable HTTP
|
|
221
|
-
▼
|
|
222
|
-
┌─────────────────────┐
|
|
223
|
-
│ ScoreHub Remote MCP │
|
|
224
|
-
│ (app.scorehub.cn/mcp)│
|
|
225
|
-
└─────────┬───────────┘
|
|
226
|
-
│
|
|
227
|
-
▼
|
|
228
|
-
┌─────────────────────┐
|
|
229
|
-
│ TikTok Shop │
|
|
230
|
-
│ Partner API │
|
|
231
|
-
└─────────────────────┘
|
|
153
|
+
本地 mcp-server ScoreHub 远程 MCP
|
|
154
|
+
│ │
|
|
155
|
+
├─ tools/call: authorize │
|
|
156
|
+
│ （默认检查并复用本地 Token） │
|
|
157
|
+
│ │
|
|
158
|
+
├─ 无有效 Token 时监听 127.0.0.1 随机端口 │
|
|
159
|
+
├─ 生成 state 与 PKCE 参数 │
|
|
160
|
+
├─ 打开浏览器 → /authorize ──────────────▶│
|
|
161
|
+
│ 用户登录并授权 │
|
|
162
|
+
│◀── 回调 127.0.0.1:<随机端口> │
|
|
163
|
+
├─ POST /token（携带 code_verifier） ────▶│
|
|
164
|
+
│◀── access_token 与 refresh_token │
|
|
165
|
+
└─ 写入 ~/.scorehub/<endpoint>/oauth.json
|
|
232
166
|
```
|
|
233
167
|
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
### Why do I need this package?
|
|
244
|
-
|
|
245
|
-
If you're using `@scorehub/creator-outreach` (the Tiky agent for TikTok creator outreach), this package is a **required prerequisite**. It provides the MCP tools the agent needs to search creators, analyze performance, and send messages.
|
|
246
|
-
|
|
247
|
-
### Can I use this without @scorehub/creator-outreach?
|
|
248
|
-
|
|
249
|
-
Yes, absolutely. `@scorehub/mcp-server` is a standalone MCP server. Any MCP-compatible client can use its tools directly.
|
|
250
|
-
|
|
251
|
-
### How do I log out?
|
|
252
|
-
|
|
253
|
-
Delete the token file:
|
|
168
|
+
| 场景 | 处理方式 |
|
|
169
|
+
|---|---|
|
|
170
|
+
| 本地 MCP 未启动、工具不可见或连接关闭 | 检查 Node.js 18+、npm、npm registry 网络和客户端 PATH，然后完全重启客户端；不要直接重新授权。 |
|
|
171
|
+
| `oauth_invalid` | 本地 OAuth 已失效；按提示调用 `authorize` 重新登录。 |
|
|
172
|
+
| `shop_auth_invalid` | ScoreHub 本地登录仍可能正常；前往 ScoreHub 重新绑定当前店铺，不要反复本地登录。 |
|
|
173
|
+
| `rate_limited` / `quota_exhausted` | 等待、分批执行或缩小请求范围；不要为了限流重新授权。 |
|
|
174
|
+
| `invalid_input` | 修正工具参数，不走授权流程。 |
|
|
175
|
+
| 浏览器无法自动打开 | 使用终端输出的授权 URL，并在运行 mcp-server 的同一台机器上完成回调。 |
|
|
176
|
+
| Windows 授权页提示授权链接无效，或浏览器地址栏缺少 `redirect_uri` | 完全退出并重启 WorkBuddy，确认 `~/.workbuddy/mcp.json` 仍使用 `npx -y @scorehub/mcp-server@latest`；新版会通过 PowerShell 打开授权 URL，避免 `cmd.exe start` 截断带 `&` 的参数。 |
|
|
254
177
|
|
|
255
|
-
|
|
256
|
-
rm ~/.scorehub/app.scorehub.cn_mcp/oauth.json
|
|
257
|
-
```
|
|
178
|
+
## 常见问题
|
|
258
179
|
|
|
259
|
-
|
|
180
|
+
### 为什么需要这个包？
|
|
260
181
|
|
|
261
|
-
|
|
262
|
-
rm -rf ~/.scorehub/
|
|
263
|
-
```
|
|
264
|
-
|
|
265
|
-
### How do I switch between staging and production?
|
|
182
|
+
使用 `@scorehub/creator-outreach`（Tiky）时，该包提供搜索达人、分析表现和发送建联消息所需的 MCP 工具。它也可以单独接入任何兼容 MCP 的客户端。
|
|
266
183
|
|
|
267
|
-
|
|
184
|
+
### 远程 MCP 不可达时会怎样？
|
|
268
185
|
|
|
269
|
-
|
|
186
|
+
本地 `authorize` 与 `status` 仍可用。远程工具列表会在启动失败后于后续 `ListTools` 请求时重试；远端恢复后，无需重启本地包即可重新发现工具。
|
|
270
187
|
|
|
271
|
-
|
|
272
|
-
- Remote tools return an error: `"Warning: Could not fetch remote tools"`
|
|
273
|
-
- The server retries fetching the tool list on each `ListTools` request
|
|
274
|
-
- Once the remote endpoint is reachable again, remote tools become available without restarting
|
|
188
|
+
### 如何升级？
|
|
275
189
|
|
|
276
|
-
|
|
190
|
+
使用 `npx -y ...@latest` 时，每次启动按 npm 当前 `latest` 标签解析。全局安装则执行：
|
|
277
191
|
|
|
278
192
|
```bash
|
|
279
193
|
npm update -g @scorehub/mcp-server
|
|
280
194
|
```
|
|
281
195
|
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
## Related Packages
|
|
196
|
+
## 相关包
|
|
285
197
|
|
|
286
|
-
|
|
|
198
|
+
| 包 | 说明 |
|
|
287
199
|
|---|---|
|
|
288
|
-
| [`@scorehub/creator-outreach`](https://www.npmjs.com/package/@scorehub/creator-outreach) | Tiky
|
|
289
|
-
| `scorehub-mcp-remote` |
|
|
200
|
+
| [`@scorehub/creator-outreach`](https://www.npmjs.com/package/@scorehub/creator-outreach) | Tiky 智能体，面向 TikTok Shop 达人搜索、分析和建联。 |
|
|
201
|
+
| `scorehub-mcp-remote` | ScoreHub 私有部署的远程 MCP 端点。 |
|
|
290
202
|
|
|
291
|
-
##
|
|
203
|
+
## 许可证
|
|
292
204
|
|
|
293
205
|
[MIT](./LICENSE)
|
package/dist/auth.js
CHANGED
|
@@ -210,7 +210,20 @@ function openBrowser(url) {
|
|
|
210
210
|
(0, node_child_process_1.execFileSync)("open", [url], { stdio: "ignore", timeout: 3000 });
|
|
211
211
|
}
|
|
212
212
|
else if (platform === "win32") {
|
|
213
|
-
|
|
213
|
+
try {
|
|
214
|
+
(0, node_child_process_1.execFileSync)("powershell.exe", [
|
|
215
|
+
"-NoProfile",
|
|
216
|
+
"-NonInteractive",
|
|
217
|
+
"-ExecutionPolicy",
|
|
218
|
+
"Bypass",
|
|
219
|
+
"-Command",
|
|
220
|
+
"Start-Process -FilePath ([string]$args[0])",
|
|
221
|
+
url,
|
|
222
|
+
], { stdio: "ignore", timeout: 3000 });
|
|
223
|
+
}
|
|
224
|
+
catch {
|
|
225
|
+
(0, node_child_process_1.execFileSync)("cmd.exe", ["/c", "start", "", `"${url}"`], { stdio: "ignore", timeout: 3000 });
|
|
226
|
+
}
|
|
214
227
|
}
|
|
215
228
|
else {
|
|
216
229
|
(0, node_child_process_1.execFileSync)("xdg-open", [url], { stdio: "ignore", timeout: 3000 });
|
|
@@ -407,6 +420,7 @@ async function authorize(params) {
|
|
|
407
420
|
authUrl.searchParams.set("response_type", "code");
|
|
408
421
|
if (scope)
|
|
409
422
|
authUrl.searchParams.set("scope", scope);
|
|
423
|
+
console.error(`[scorehub] Opening authorization URL: endpoint=${authEndpoint}, redirect_uri=${actualRedirectUri}`);
|
|
410
424
|
openBrowser(authUrl.toString());
|
|
411
425
|
timeoutId = setTimeout(() => {
|
|
412
426
|
if (settled)
|
package/package.json
CHANGED
|
@@ -1,14 +1,18 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@scorehub/mcp-server",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.13",
|
|
4
4
|
"description": "ScoreHub local MCP proxy — OAuth login, token caching, and tool forwarding to remote MCP endpoint",
|
|
5
|
+
"engines": {
|
|
6
|
+
"node": ">=18"
|
|
7
|
+
},
|
|
5
8
|
"main": "dist/index.js",
|
|
6
9
|
"bin": {
|
|
7
10
|
"scorehub-mcp": "./dist/index.js"
|
|
8
11
|
},
|
|
9
12
|
"files": [
|
|
10
13
|
"dist",
|
|
11
|
-
"README.md"
|
|
14
|
+
"README.md",
|
|
15
|
+
"README.en.md"
|
|
12
16
|
],
|
|
13
17
|
"publishConfig": {
|
|
14
18
|
"access": "public"
|