@scorehub/mcp-server 0.2.12 → 0.2.14
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/README.en.md +205 -0
- package/README.md +3 -0
- package/dist/auth.js +11 -15
- package/package.json +5 -3
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,5 +1,7 @@
|
|
|
1
1
|
# @scorehub/mcp-server
|
|
2
2
|
|
|
3
|
+
English version: [README.en.md](./README.en.md)
|
|
4
|
+
|
|
3
5
|
> ScoreHub 本地 MCP 代理，负责浏览器 OAuth 登录、Token 缓存，以及将本地 AI 客户端的工具调用转发至 ScoreHub 远程 MCP。
|
|
4
6
|
|
|
5
7
|
[](https://www.npmjs.com/package/@scorehub/mcp-server)
|
|
@@ -171,6 +173,7 @@ Token 持久化在本机文件中；调用默认 ScoreHub 生产端点时，mcp-
|
|
|
171
173
|
| `rate_limited` / `quota_exhausted` | 等待、分批执行或缩小请求范围；不要为了限流重新授权。 |
|
|
172
174
|
| `invalid_input` | 修正工具参数，不走授权流程。 |
|
|
173
175
|
| 浏览器无法自动打开 | 使用终端输出的授权 URL，并在运行 mcp-server 的同一台机器上完成回调。 |
|
|
176
|
+
| Windows 授权页提示授权链接无效，或浏览器地址栏缺少 `redirect_uri` | 完全退出并重启 WorkBuddy，确认 `~/.workbuddy/mcp.json` 仍使用 `npx -y @scorehub/mcp-server@latest`；新版会通过 PowerShell 打开授权 URL，避免 `cmd.exe start` 截断带 `&` 的参数。 |
|
|
174
177
|
|
|
175
178
|
## 常见问题
|
|
176
179
|
|
package/dist/auth.js
CHANGED
|
@@ -1,4 +1,7 @@
|
|
|
1
1
|
"use strict";
|
|
2
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
3
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
4
|
+
};
|
|
2
5
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
6
|
exports.loadTokens = loadTokens;
|
|
4
7
|
exports.saveTokens = saveTokens;
|
|
@@ -17,7 +20,7 @@ const node_fs_1 = require("node:fs");
|
|
|
17
20
|
const node_path_1 = require("node:path");
|
|
18
21
|
const node_os_1 = require("node:os");
|
|
19
22
|
const node_crypto_1 = require("node:crypto");
|
|
20
|
-
const
|
|
23
|
+
const open_1 = __importDefault(require("open"));
|
|
21
24
|
const callback_pages_js_1 = require("./pages/callback-pages.js");
|
|
22
25
|
class CallbackError extends Error {
|
|
23
26
|
page;
|
|
@@ -204,22 +207,14 @@ function generateState(length = 16) {
|
|
|
204
207
|
}
|
|
205
208
|
// ── Browser Launch ───────────────────────────────────────────
|
|
206
209
|
function openBrowser(url) {
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
else if (platform === "win32") {
|
|
213
|
-
(0, node_child_process_1.execFileSync)("cmd.exe", ["/c", "start", "", url], { stdio: "ignore", timeout: 3000 });
|
|
214
|
-
}
|
|
215
|
-
else {
|
|
216
|
-
(0, node_child_process_1.execFileSync)("xdg-open", [url], { stdio: "ignore", timeout: 3000 });
|
|
217
|
-
}
|
|
218
|
-
}
|
|
219
|
-
catch {
|
|
210
|
+
// Delegate to `open`, which spawns the platform launcher with the URL as a
|
|
211
|
+
// single argument. This avoids shell interpretation of `&`/`?` — the source
|
|
212
|
+
// of the earlier Windows bugs (cmd `start` truncating at `&`, PowerShell
|
|
213
|
+
// `$args` not populating under -Command and treating the URL as a file path).
|
|
214
|
+
void (0, open_1.default)(url).catch(() => {
|
|
220
215
|
console.error("[scorehub] Could not open browser automatically.");
|
|
221
216
|
console.error(`[scorehub] Please visit this URL manually:\n ${url}`);
|
|
222
|
-
}
|
|
217
|
+
});
|
|
223
218
|
}
|
|
224
219
|
// ── Full OAuth Flow ──────────────────────────────────────────
|
|
225
220
|
async function authorize(params) {
|
|
@@ -407,6 +402,7 @@ async function authorize(params) {
|
|
|
407
402
|
authUrl.searchParams.set("response_type", "code");
|
|
408
403
|
if (scope)
|
|
409
404
|
authUrl.searchParams.set("scope", scope);
|
|
405
|
+
console.error(`[scorehub] Opening authorization URL: endpoint=${authEndpoint}, redirect_uri=${actualRedirectUri}`);
|
|
410
406
|
openBrowser(authUrl.toString());
|
|
411
407
|
timeoutId = setTimeout(() => {
|
|
412
408
|
if (settled)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@scorehub/mcp-server",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.14",
|
|
4
4
|
"description": "ScoreHub local MCP proxy — OAuth login, token caching, and tool forwarding to remote MCP endpoint",
|
|
5
5
|
"engines": {
|
|
6
6
|
"node": ">=18"
|
|
@@ -11,7 +11,8 @@
|
|
|
11
11
|
},
|
|
12
12
|
"files": [
|
|
13
13
|
"dist",
|
|
14
|
-
"README.md"
|
|
14
|
+
"README.md",
|
|
15
|
+
"README.en.md"
|
|
15
16
|
],
|
|
16
17
|
"publishConfig": {
|
|
17
18
|
"access": "public"
|
|
@@ -29,7 +30,8 @@
|
|
|
29
30
|
],
|
|
30
31
|
"license": "MIT",
|
|
31
32
|
"dependencies": {
|
|
32
|
-
"@modelcontextprotocol/sdk": "^1.29.0"
|
|
33
|
+
"@modelcontextprotocol/sdk": "^1.29.0",
|
|
34
|
+
"open": "^8.4.2"
|
|
33
35
|
},
|
|
34
36
|
"devDependencies": {
|
|
35
37
|
"@types/node": "^22.0.0",
|