@scorehub/mcp-server 0.3.2 → 0.3.3

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,12 @@ 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 can run `npx -y @scorehub/creator-outreach@latest` when needed to complete the local bootstrap and write or repair this MCP configuration automatically. Manual editing is not required.
 
 ## Windows
 
@@ -76,7 +76,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 +131,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 +175,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?

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,12 @@ 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 会在需要时执行 `npx -y @scorehub/creator-outreach@latest` 完成本地引导，并自动写入或修复这份 MCP 配置；无需手动编辑。
 
 ## Windows 使用说明
 
@@ -76,7 +76,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 +131,7 @@ Token 持久化在本机文件中；调用默认 ScoreHub 生产端点时，mcp-
 | 工具 | 说明 |
 |---|---|
 | `authorize` | 检查 ScoreHub OAuth 状态；`force: true` 重新登录以切换账号，`switch_shop: true` 打开当前账号的店铺选择页。 |
-| `status` | 返回远程地址、授权状态、当前账号/店铺和当前可用工具数量。 |
+| `status` | 返回本地代理版本、运行状态、授权状态、远端工具可用性、当前账号/店铺和宿主安装来源元数据。 |
 
 ### 远程工具
 
@@ -175,6 +175,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` 完成本地引导
+
 ## 常见问题
 
 ### 为什么需要这个包？

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
@@ -45,6 +45,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 +293,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),
                     },
                 ],
             };

package/dist/startup-check.d.ts

@@ -0,0 +1,39 @@
+export declare const VERSION_CACHE_TTL_MS: number;
+export declare const VERSION_REQUEST_TIMEOUT_MS = 3000;
+export type StartupCheckStatus = "ready" | "restart_required" | "migration_required" | "verification_unavailable";
+export interface LatestVersions {
+    creatorOutreach?: string;
+    mcpServer?: string;
+    checkedAt: string;
+    error?: string;
+}
+export interface StartupCheckResult {
+    status: StartupCheckStatus;
+    creator_outreach: {
+        agent_version: string;
+        bootstrap_version: string | null;
+        latest_version: string | null;
+    };
+    mcp_server: {
+        running_version: string;
+        latest_version: string | null;
+    };
+    checked_at: string;
+    message: string;
+}
+interface GetLatestVersionsOptions {
+    registryUrl?: string;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    timeoutMs?: number;
+}
+interface EvaluateStartupCheckOptions {
+    agentVersion: string;
+    bootstrapVersion?: string;
+    mcpServerVersion: string;
+    latestVersions: LatestVersions;
+}
+export declare function getLatestVersions({ registryUrl, fetchImpl, now, timeoutMs, }?: GetLatestVersionsOptions): Promise<LatestVersions>;
+export declare function evaluateStartupCheck({ agentVersion, bootstrapVersion, mcpServerVersion, latestVersions, }: EvaluateStartupCheckOptions): StartupCheckResult;
+export declare function resetVersionCacheForTests(): void;
+export {};

package/dist/startup-check.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION_REQUEST_TIMEOUT_MS = exports.VERSION_CACHE_TTL_MS = void 0;
+exports.getLatestVersions = getLatestVersions;
+exports.evaluateStartupCheck = evaluateStartupCheck;
+exports.resetVersionCacheForTests = resetVersionCacheForTests;
+const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
+exports.VERSION_CACHE_TTL_MS = 15 * 60 * 1000;
+exports.VERSION_REQUEST_TIMEOUT_MS = 3000;
+const CREATOR_OUTREACH_PACKAGE = "@scorehub/creator-outreach";
+const MCP_SERVER_PACKAGE = "@scorehub/mcp-server";
+let versionCache = null;
+function normalizeRegistryUrl(value) {
+    const registry = (value || DEFAULT_NPM_REGISTRY).trim();
+    return registry.endsWith("/") ? registry : `${registry}/`;
+}
+async function fetchPackageVersion(packageName, registryUrl, fetchImpl, timeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    timeout.unref?.();
+    try {
+        const url = new URL(`${encodeURIComponent(packageName)}/latest`, registryUrl);
+        const response = await fetchImpl(url, {
+            headers: { accept: "application/json" },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`${packageName} returned HTTP ${response.status}`);
+        }
+        const payload = await response.json();
+        if (typeof payload.version !== "string" || payload.version.trim() === "") {
+            throw new Error(`${packageName} latest metadata did not include a version`);
+        }
+        return payload.version.trim();
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function getLatestVersions({ registryUrl = process.env.npm_config_registry, fetchImpl = fetch, now = Date.now, timeoutMs = exports.VERSION_REQUEST_TIMEOUT_MS, } = {}) {
+    const nowMs = now();
+    if (versionCache && versionCache.expiresAt > nowMs) {
+        return versionCache.value;
+    }
+    const checkedAt = new Date(nowMs).toISOString();
+    const normalizedRegistry = normalizeRegistryUrl(registryUrl);
+    const [creatorResult, mcpResult] = await Promise.allSettled([
+        fetchPackageVersion(CREATOR_OUTREACH_PACKAGE, normalizedRegistry, fetchImpl, timeoutMs),
+        fetchPackageVersion(MCP_SERVER_PACKAGE, normalizedRegistry, fetchImpl, timeoutMs),
+    ]);
+    const errors = [];
+    const value = { checkedAt };
+    if (creatorResult.status === "fulfilled") {
+        value.creatorOutreach = creatorResult.value;
+    }
+    else {
+        errors.push(`creator-outreach: ${String(creatorResult.reason)}`);
+    }
+    if (mcpResult.status === "fulfilled") {
+        value.mcpServer = mcpResult.value;
+    }
+    else {
+        errors.push(`mcp-server: ${String(mcpResult.reason)}`);
+    }
+    if (errors.length > 0) {
+        value.error = errors.join("; ");
+    }
+    versionCache = {
+        expiresAt: nowMs + exports.VERSION_CACHE_TTL_MS,
+        value,
+    };
+    return value;
+}
+function evaluateStartupCheck({ agentVersion, bootstrapVersion, mcpServerVersion, latestVersions, }) {
+    const result = {
+        creator_outreach: {
+            agent_version: agentVersion,
+            bootstrap_version: bootstrapVersion || null,
+            latest_version: latestVersions.creatorOutreach || null,
+        },
+        mcp_server: {
+            running_version: mcpServerVersion,
+            latest_version: latestVersions.mcpServer || null,
+        },
+        checked_at: latestVersions.checkedAt,
+    };
+    if (!bootstrapVersion) {
+        return {
+            status: "migration_required",
+            ...result,
+            message: "当前仍在使用旧版 MCP 启动配置。请执行一次 npx -y @scorehub/creator-outreach@latest，然后完全退出并重新打开客户端。",
+        };
+    }
+    if (agentVersion !== bootstrapVersion
+        || (latestVersions.creatorOutreach && bootstrapVersion !== latestVersions.creatorOutreach)
+        || (latestVersions.mcpServer && mcpServerVersion !== latestVersions.mcpServer)) {
+        return {
+            status: "restart_required",
+            ...result,
+            message: "检测到 Tiky 配置或 ScoreHub MCP 版本已变化。请完全退出并重新打开客户端，以加载已刷新的版本。",
+        };
+    }
+    if (latestVersions.error
+        || !latestVersions.creatorOutreach
+        || !latestVersions.mcpServer) {
+        return {
+            status: "verification_unavailable",
+            ...result,
+            message: "暂时无法连接 npm registry 确认是否为最新版；当前本地版本一致，可以继续使用。",
+        };
+    }
+    return {
+        status: "ready",
+        ...result,
+        message: "Tiky 配置与 ScoreHub MCP 均已就绪。",
+    };
+}
+function resetVersionCacheForTests() {
+    versionCache = null;
+}

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.3.3",
   "description": "ScoreHub local MCP proxy — OAuth login, token caching, and tool forwarding to remote MCP endpoint",
   "engines": {
     "node": ">=18"