@scorehub/mcp-server 0.3.2 → 0.4.0

package/README.en.md

@@ -10,7 +10,7 @@ Chinese version: [README.md](./README.md)
 
 ## Overview
 
-`@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:
+`@scorehub/mcp-server` runs on your computer between MCP clients such as WorkBuddy and Codex and the ScoreHub remote MCP server. It provides:
 
 - **OAuth login**: Opens a browser for authorization when needed and caches ScoreHub tokens locally.
 - **Token lifecycle management**: Checks token validity before calls, refreshes tokens within five minutes of expiry, and keeps long-running sessions alive every four hours.
@@ -19,7 +19,7 @@ Chinese version: [README.md](./README.md)
 ```
 ┌─────────────┐     stdio      ┌──────────────────┐   Streamable HTTP   ┌─────────────────┐
 │  AI client  │ ◄────────────► │  @scorehub/      │ ◄─────────────────► │  ScoreHub       │
-│  Claude etc.│                │  mcp-server      │                     │  Remote MCP     │
+│ WorkBuddy etc│               │  mcp-server      │                     │  Remote MCP     │
 └─────────────┘                └──────────────────┘                     └────────┬────────┘
                                                                                  │
                                                                           TikTok Shop
@@ -59,12 +59,22 @@ Common configuration locations are:
 
 | Client | Configuration file |
 |---|---|
-| Claude Code / Claude Desktop | The MCP configuration file used by the client, such as `claude_desktop_config.json` or `.claude/mcp.json` |
+| Other MCP clients | The MCP configuration file used by that client |
 | WorkBuddy | `mcp.json` |
 
 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.
 
-> When you install Tiky through `@scorehub/creator-outreach`, its installer writes this MCP configuration automatically. Manual setup is not required.
+> After you install Tiky through the WorkBuddy share link, Tiky's first-turn bootstrap gate writes or repairs this MCP configuration after the user's one-time confirmation. Manual editing is not required.
+
+### Startup self-check
+
+Before writing the WorkBuddy configuration, creator-outreach prefetches npm latest and runs:
+
+```bash
+npx -y @scorehub/mcp-server@latest --self-check --json
+```
+
+The command reports the package version, Node.js version, and executable entrypoint status, then exits immediately. It does not start stdio, contact the remote MCP endpoint, enter OAuth, or write tokens.
 
 ## Windows
 
@@ -76,7 +86,7 @@ Windows uses the same MCP JSON configuration as macOS and Linux. You do not need
 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**.
 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.
 
-If WorkBuddy uses its bundled Node.js, install through `@scorehub/creator-outreach`. The installer handles `npx` / `npx.cmd` and PATH differences for each platform.
+If WorkBuddy uses its bundled Node.js, install Tiky through the share link first, then let Tiky run `npx -y @scorehub/creator-outreach@latest` to complete the local bootstrap. That flow handles `npx` / `npx.cmd` and PATH differences for each platform.
 
 ## Optional: Global Installation
 
@@ -131,7 +141,7 @@ By default, `authorize` reuses a valid access token or refresh token and does no
 | Tool | Description |
 |---|---|
 | `authorize` | Checks ScoreHub OAuth. Use `force: true` to log in as another account or `switch_shop: true` to open the current account's shop picker. |
-| `status` | Returns the remote address, authorization state, current account/shop, and available tool count. |
+| `status` | Returns the local proxy version, runtime state, authorization state, remote-tool availability, current account/shop, and host-installation metadata. |
 
 ### Remote Tools
 
@@ -175,6 +185,16 @@ Local mcp-server                         ScoreHub Remote MCP
 | 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. |
 | 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. |
 
+Key `status` fields:
+
+- `server_version`: the local `@scorehub/mcp-server` version
+- `local_state`:
+  - `running_ready`: the local proxy is running, authorized, and remote tools are available
+  - `running_unauthorized`: the local proxy is running but ScoreHub OAuth is not complete yet
+  - `running_authorized_remote_unavailable`: the local proxy is running and authorized, but remote tool discovery is temporarily unavailable
+  - `running_authorized_no_remote_tools`: the local proxy is running and authorized, but no remote tools are currently discovered and no explicit remote error was captured
+- `config_source`: host and installation-source metadata. When it shows `client_host = "workbuddy"` and `managed_by = "@scorehub/creator-outreach"`, the configuration comes from Tiky's public WorkBuddy installation path; typically Tiky is first installed through the share link and then runs `npx -y @scorehub/creator-outreach@latest` to complete the local bootstrap
+
 ## FAQ
 
 ### Why do I need this package?
@@ -193,6 +213,8 @@ With `npx -y ...@latest`, every launch resolves npm's current `latest` tag. For
 npm update -g @scorehub/mcp-server
 ```
 
+Because the public WorkBuddy configuration always follows `@latest`, releases under this package name must preserve backward compatibility for tool names, parameters, OAuth, and the `status` contract. An incompatible protocol must use a new package name.
+
 ## Related Packages
 
 | Package | Description |

package/README.md

@@ -10,7 +10,7 @@ English version: [README.en.md](./README.en.md)
 
 ## 概览
 
-`@scorehub/mcp-server` 运行在你的电脑上，位于 Claude Code、Claude Desktop、WorkBuddy 等 MCP 客户端与 ScoreHub 远程 MCP 之间，负责：
+`@scorehub/mcp-server` 运行在你的电脑上，位于 WorkBuddy、Codex 等 MCP 客户端与 ScoreHub 远程 MCP 之间，负责：
 
 - **账号与店铺切换**：`authorize(force=true)` 可重新登录切换账号；`authorize(switch_shop=true)` 可在当前账号下切换店铺，无需重新登录。
 - **Token 生命周期**：调用前检查 Token 有效期；距过期不足 5 分钟时自动刷新，并为长会话每 4 小时主动保活一次。
@@ -19,7 +19,7 @@ English version: [README.en.md](./README.en.md)
 ```
 ┌─────────────┐     stdio      ┌──────────────────┐   Streamable HTTP   ┌─────────────────┐
 │  AI 客户端  │ ◄────────────► │  @scorehub/      │ ◄─────────────────► │  ScoreHub       │
-│ Claude 等   │                │  mcp-server      │                     │  远程 MCP       │
+│ WorkBuddy 等│                │  mcp-server      │                     │  远程 MCP       │
 └─────────────┘                └──────────────────┘                     └────────┬────────┘
                                                                                  │
                                                                           TikTok Shop
@@ -59,12 +59,22 @@ npx --version
 
 | 客户端 | 配置文件 |
 |---|---|
-| Claude Code / Claude Desktop | 客户端使用的 MCP 配置文件，例如 `claude_desktop_config.json` 或 `.claude/mcp.json` |
+| 其他 MCP 客户端 | 该客户端使用的 MCP 配置文件 |
 | WorkBuddy | `mcp.json` |
 
 首次启动时，`npx` 会下载 `@scorehub/mcp-server` 并连接远程端点。首次调用远程工具时，按客户端提示调用 `authorize`：浏览器会打开 ScoreHub 登录页，授权完成后回调到 `127.0.0.1` 的随机端口并写入本地 Token。之后会复用缓存，不需要每次登录。
 
-> 使用 `@scorehub/creator-outreach` 安装 Tiky 时，安装器会自动写入这份 MCP 配置；无需手动配置。
+> 通过 WorkBuddy 分享链接安装 Tiky 后，Tiky 会在首轮 bootstrap 门禁中经用户首次确认后自动写入或修复这份 MCP 配置；无需手动编辑。
+
+### 启动前自检
+
+在写入 WorkBuddy 配置前，creator-outreach 会预拉取 npm latest 并执行：
+
+```bash
+npx -y @scorehub/mcp-server@latest --self-check --json
+```
+
+该命令返回包版本、Node.js 版本和可执行入口状态，然后立即退出。它不启动 stdio 服务、不访问远端 MCP、不进入 OAuth，也不写入 Token。
 
 ## Windows 使用说明
 
@@ -76,7 +86,7 @@ Windows 与 macOS、Linux 使用同一份 MCP JSON 配置，不需要改成 `npx
 4. 授权时会优先使用 `cmd.exe /c start` 打开默认浏览器。被系统策略拦截时，复制终端输出的授权 URL，在**运行 mcp-server 的同一台 Windows 电脑**上打开并完成授权。
 5. 回调固定使用 `127.0.0.1` 随机端口。不要在另一台电脑打开授权 URL；本机安全软件若拦截回环回调，应允许本地回环连接后重试。
 
-WorkBuddy 若使用其捆绑的 Node.js，建议通过 `@scorehub/creator-outreach` 安装器完成配置；该安装器会按平台处理 `npx` / `npx.cmd` 与 PATH。
+WorkBuddy 若使用其捆绑的 Node.js，建议先通过分享链接安装 Tiky，再由 Tiky 执行 `npx -y @scorehub/creator-outreach@latest` 完成本地引导；该流程会按平台处理 `npx` / `npx.cmd` 与 PATH。
 
 ## 可选：全局安装
 
@@ -131,7 +141,7 @@ Token 持久化在本机文件中；调用默认 ScoreHub 生产端点时，mcp-
 | 工具 | 说明 |
 |---|---|
 | `authorize` | 检查 ScoreHub OAuth 状态；`force: true` 重新登录以切换账号，`switch_shop: true` 打开当前账号的店铺选择页。 |
-| `status` | 返回远程地址、授权状态、当前账号/店铺和当前可用工具数量。 |
+| `status` | 返回本地代理版本、运行状态、授权状态、远端工具可用性、当前账号/店铺和宿主安装来源元数据。 |
 
 ### 远程工具
 
@@ -175,6 +185,16 @@ Token 持久化在本机文件中；调用默认 ScoreHub 生产端点时，mcp-
 | 浏览器无法自动打开 | 使用终端输出的授权 URL，并在运行 mcp-server 的同一台机器上完成回调。 |
 | Windows 授权页提示授权链接无效，或浏览器地址栏缺少 `redirect_uri` | 完全退出并重启 WorkBuddy，确认 `~/.workbuddy/mcp.json` 仍使用 `npx -y @scorehub/mcp-server@latest`；新版会通过 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` 完成本地引导
+
 ## 常见问题
 
 ### 为什么需要这个包？
@@ -193,6 +213,8 @@ Token 持久化在本机文件中；调用默认 ScoreHub 生产端点时，mcp-
 npm update -g @scorehub/mcp-server
 ```
 
+由于 WorkBuddy 公开配置始终跟随 `@latest`，同一包名下的 latest 发布必须保持工具名、参数、OAuth 和 `status` 契约向后兼容。无法兼容的新协议必须使用新包名。
+
 ## 相关包
 
 | 包 | 说明 |

package/dist/index.js

@@ -5,7 +5,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * ScoreHub MCP Server — Local MCP Proxy
  *
  * Architecture (mirrors @lessie/mcp-server):
- *   Agent (WorkBuddy/Claude)  ──stdio──  Local MCP Server  ──Streamable HTTP──  Remote MCP Server
+ *   Agent (WorkBuddy/other MCP client)  ──stdio──  Local MCP Server  ──Streamable HTTP──  Remote MCP Server
  *
  * The local server handles:
  * 1. OAuth 2.1 Authorization Code + PKCE — browser-based login to ScoreHub
@@ -18,11 +18,12 @@ const index_js_2 = require("@modelcontextprotocol/sdk/client/index.js");
 const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-function readPackageVersion() {
-    const packageJson = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "../package.json"), "utf-8"));
-    return packageJson.version;
+const self_check_js_1 = require("./self-check.js");
+function readPackageMetadata() {
+    return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "../package.json"), "utf-8"));
 }
-const SERVER_VERSION = readPackageVersion();
+const PACKAGE_METADATA = readPackageMetadata();
+const SERVER_VERSION = PACKAGE_METADATA.version;
 const DEFAULT_SCOREHUB_BASE_URL = "https://app.scorehub.cn/mcp";
 const SCOREHUB_BASE_URL = normalizeBaseUrl(process.env.SCOREHUB_REMOTE_MCP_URL || DEFAULT_SCOREHUB_BASE_URL);
 // OAuth endpoints are at the root path
@@ -45,6 +46,7 @@ function endpointTokenKey(baseUrl) {
 }
 // ── Auth State ──────────────────────────────────────────────
 const auth_js_1 = require("./auth.js");
+const status_js_1 = require("./status.js");
 const TOKEN_STORE_KEY = endpointTokenKey(SCOREHUB_BASE_URL);
 const CLIENT_ID = "scorehub-mcp";
 // Proactively refresh token every 4 hours to prevent expiry during long sessions
@@ -292,19 +294,20 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
         case "status": {
             const tokenResult = await (0, auth_js_1.getValidAccessToken)(TOKEN_STORE_KEY, TOKEN_ENDPOINT, CLIENT_ID);
             const tokenStore = (0, auth_js_1.loadTokens)(TOKEN_STORE_KEY);
+            const payload = (0, status_js_1.buildStatusPayload)({
+                serverVersion: SERVER_VERSION,
+                remoteUrl: REMOTE_MCP_URL,
+                tokenStoreKey: TOKEN_STORE_KEY,
+                tokenResult,
+                tokenStore,
+                remoteToolsCount: remoteTools.length,
+                lastFetchError,
+            });
             return {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify({
-                            remote_url: REMOTE_MCP_URL,
-                            token_store_key: TOKEN_STORE_KEY,
-                            authorized: !!tokenResult,
-                            ...(tokenStore?.account ? { account: tokenStore.account } : {}),
-                            ...(tokenStore?.selected_shop ? { selected_shop: tokenStore.selected_shop } : {}),
-                            tools_count: remoteTools.length,
-                            ...(lastFetchError ? { error: lastFetchError } : {}),
-                        }, null, 2),
+                        text: JSON.stringify(payload, null, 2),
                     },
                 ],
             };
@@ -376,6 +379,23 @@ function startTokenKeepAlive() {
 }
 // ── Start ───────────────────────────────────────────────────
 async function main() {
+    if (process.argv.includes("--self-check")) {
+        const payload = (0, self_check_js_1.buildSelfCheckPayload)({
+            packageName: PACKAGE_METADATA.name,
+            serverVersion: SERVER_VERSION,
+        });
+        if (process.argv.includes("--json")) {
+            process.stdout.write(`${JSON.stringify(payload)}\n`);
+        }
+        else {
+            process.stdout.write(payload.ok
+                ? `ScoreHub MCP Server v${payload.server_version} is ready (Node.js ${payload.node_version}).\n`
+                : `Node.js ${payload.minimum_node_major}+ is required. Detected ${payload.node_version}.\n`);
+        }
+        if (!payload.ok)
+            process.exitCode = 1;
+        return;
+    }
     // Set process title for easy identification in ps/task manager
     process.title = 'scorehub-mcp';
     // Gracefully exit when parent AI agent closes stdin (normal shutdown or crash).

package/dist/self-check.d.ts

@@ -0,0 +1,18 @@
+export declare const MIN_NODE_MAJOR = 18;
+export interface SelfCheckPayload {
+    schema_version: 1;
+    ok: boolean;
+    package_name: string;
+    server_version: string;
+    node_version: string;
+    node_supported: boolean;
+    minimum_node_major: number;
+    entrypoint: "scorehub-mcp";
+}
+export interface SelfCheckInput {
+    packageName: string;
+    serverVersion: string;
+    nodeVersion?: string;
+}
+export declare function getNodeMajorVersion(nodeVersion: string): number;
+export declare function buildSelfCheckPayload(input: SelfCheckInput): SelfCheckPayload;

package/dist/self-check.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_NODE_MAJOR = void 0;
+exports.getNodeMajorVersion = getNodeMajorVersion;
+exports.buildSelfCheckPayload = buildSelfCheckPayload;
+exports.MIN_NODE_MAJOR = 18;
+function getNodeMajorVersion(nodeVersion) {
+    return Number.parseInt(nodeVersion.split(".")[0], 10);
+}
+function buildSelfCheckPayload(input) {
+    const nodeVersion = input.nodeVersion ?? process.versions.node;
+    const nodeSupported = getNodeMajorVersion(nodeVersion) >= exports.MIN_NODE_MAJOR;
+    return {
+        schema_version: 1,
+        ok: nodeSupported,
+        package_name: input.packageName,
+        server_version: input.serverVersion,
+        node_version: nodeVersion,
+        node_supported: nodeSupported,
+        minimum_node_major: exports.MIN_NODE_MAJOR,
+        entrypoint: "scorehub-mcp",
+    };
+}

package/dist/status.d.ts

@@ -0,0 +1,35 @@
+import type { OAuthAccount, OAuthShop, TokenStore } from "./auth.js";
+export type LocalStatusState = "running_ready" | "running_unauthorized" | "running_authorized_remote_unavailable" | "running_authorized_no_remote_tools";
+export type AuthorizationState = "authorized" | "unauthorized";
+export type RemoteToolsState = "available" | "unavailable";
+export interface StatusPayload {
+    server_version: string;
+    remote_url: string;
+    token_store_key: string;
+    local_state: LocalStatusState;
+    authorization_state: AuthorizationState;
+    remote_tools_state: RemoteToolsState;
+    authorized: boolean;
+    tools_count: number;
+    config_source: {
+        client_host: string;
+        managed_by: string;
+        creator_outreach_version?: string;
+    };
+    account?: OAuthAccount;
+    selected_shop?: OAuthShop;
+    error?: string;
+}
+export interface StatusInput {
+    serverVersion: string;
+    remoteUrl: string;
+    tokenStoreKey: string;
+    tokenResult: {
+        access_token: string;
+    } | null;
+    tokenStore: Pick<TokenStore, "account" | "selected_shop"> | null;
+    remoteToolsCount: number;
+    lastFetchError: string | null;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function buildStatusPayload(input: StatusInput): StatusPayload;

package/dist/status.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildStatusPayload = buildStatusPayload;
+function getLocalState(authorized, remoteToolsCount, lastFetchError) {
+    if (!authorized) {
+        return "running_unauthorized";
+    }
+    if (lastFetchError) {
+        return "running_authorized_remote_unavailable";
+    }
+    if (remoteToolsCount === 0) {
+        return "running_authorized_no_remote_tools";
+    }
+    return "running_ready";
+}
+function buildStatusPayload(input) {
+    const env = input.env ?? process.env;
+    const authorized = !!input.tokenResult;
+    const remoteToolsState = input.remoteToolsCount > 0 && !input.lastFetchError
+        ? "available"
+        : "unavailable";
+    return {
+        server_version: input.serverVersion,
+        remote_url: input.remoteUrl,
+        token_store_key: input.tokenStoreKey,
+        local_state: getLocalState(authorized, input.remoteToolsCount, input.lastFetchError),
+        authorization_state: authorized ? "authorized" : "unauthorized",
+        remote_tools_state: remoteToolsState,
+        authorized,
+        tools_count: input.remoteToolsCount,
+        config_source: {
+            client_host: env.SCOREHUB_CLIENT_HOST || "unknown",
+            managed_by: env.SCOREHUB_MANAGED_BY || "direct",
+            ...(env.SCOREHUB_CREATOR_OUTREACH_VERSION
+                ? { creator_outreach_version: env.SCOREHUB_CREATOR_OUTREACH_VERSION }
+                : {}),
+        },
+        ...(input.tokenStore?.account ? { account: input.tokenStore.account } : {}),
+        ...(input.tokenStore?.selected_shop ? { selected_shop: input.tokenStore.selected_shop } : {}),
+        ...(input.lastFetchError ? { error: input.lastFetchError } : {}),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scorehub/mcp-server",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "ScoreHub local MCP proxy — OAuth login, token caching, and tool forwarding to remote MCP endpoint",
   "engines": {
     "node": ">=18"
@@ -18,7 +18,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc && node -e \"const fs=require('fs');const f='dist/index.js';fs.writeFileSync(f,'#!/usr/bin/env node\\n'+fs.readFileSync(f,'utf8'));fs.chmodSync(f,0o755)\"",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc && node -e \"const fs=require('fs');const f='dist/index.js';fs.writeFileSync(f,'#!/usr/bin/env node\\n'+fs.readFileSync(f,'utf8'));fs.chmodSync(f,0o755)\"",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
     "test": "tsx --test test/*.test.ts"