@scorehub/mcp-server 0.3.3 → 0.4.0

package/README.en.md

@@ -64,7 +64,17 @@ Common configuration locations are:
 
 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.
 
-> 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.
+> 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
 
@@ -203,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

@@ -64,7 +64,17 @@ npx --version
 
 首次启动时，`npx` 会下载 `@scorehub/mcp-server` 并连接远程端点。首次调用远程工具时，按客户端提示调用 `authorize`：浏览器会打开 ScoreHub 登录页，授权完成后回调到 `127.0.0.1` 的随机端口并写入本地 Token。之后会复用缓存，不需要每次登录。
 
-> 通过 WorkBuddy 分享链接安装 Tiky 后，Tiky 会在需要时执行 `npx -y @scorehub/creator-outreach@latest` 完成本地引导，并自动写入或修复这份 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 使用说明
 
@@ -203,6 +213,8 @@ Token 持久化在本机文件中；调用默认 ScoreHub 生产端点时，mcp-
 npm update -g @scorehub/mcp-server
 ```
 
+由于 WorkBuddy 公开配置始终跟随 `@latest`，同一包名下的 latest 发布必须保持工具名、参数、OAuth 和 `status` 契约向后兼容。无法兼容的新协议必须使用新包名。
+
 ## 相关包
 
 | 包 | 说明 |

package/dist/index.js

@@ -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
@@ -378,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scorehub/mcp-server",
-  "version": "0.3.3",
+  "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"

package/dist/startup-check.d.ts

@@ -1,39 +0,0 @@
-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

@@ -1,120 +0,0 @@
-"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;
-}