@scorehub/mcp-server 0.2.7 → 0.2.9

package/README.md

@@ -82,7 +82,7 @@ In `mcp.json`:
 2. It fetches the list of available tools
 3. The first time you use a remote tool, you'll be prompted to run the `authorize` tool
 4. Your browser opens to the ScoreHub login page
-5. After authorizing, the browser redirects to `localhost:19836` and the token is saved
+5. After authorizing, the browser redirects to `127.0.0.1:<random-port>/callback`, shows a local status page, and the token is saved
 6. Subsequent calls use the cached token — no repeated login needed
 
 ## Configuration
@@ -151,18 +151,21 @@ These tools are **dynamically loaded** from the remote MCP endpoint at startup a
          ├─ tools/call: authorize ──────────┤
          │  (clears any existing token)     │
          │                                  │
-         ├─ generates random state          │
+         ├─ opens local callback on 127.0.0.1:<random-port>
+         ├─ generates random state + PKCE   │
          ├─ opens browser → /authorize ────▶│
          │              user logs in + grants access
-         │  ◀── redirect to localhost:19836 │
+         │  ◀── redirect to 127.0.0.1:<random-port>
          │       with authorization_code    │
          │                                  │
-         ├─ POST /token ───────────────────▶│
+         ├─ POST /token (code_verifier) ───▶│
          │◀── access_token + refresh_token  │
          │                                  │
         ├─ saves to ~/.scorehub/<endpoint>/oauth.json
 ```
 
+After the redirect, the local callback page gives a clear success or failure state and tells the user whether to return to the terminal or rerun `authorize`.
+
 ### Token lifecycle
 
 | Stage | Behavior |
@@ -175,7 +178,9 @@ These tools are **dynamically loaded** from the remote MCP endpoint at startup a
 
 ### Headless environments
 
-If you're running on a server or in a headless environment where a browser cannot open automatically, the authorization URL will be printed to stderr. Copy it and open it manually in any browser. After login, the callback goes to `http://127.0.0.1:19836/callback` — make sure port 19836 is accessible on the machine running mcp-server.
+If you're running on a server or in a headless environment where a browser cannot open automatically, the authorization URL will be printed to stderr. Copy it and open it manually in any browser. After login, the callback goes to `http://127.0.0.1:<random-port>/callback` — make sure the local loopback port chosen by mcp-server is reachable on the same machine.
+
+On Windows, the same flow uses `cmd.exe /c start` to open the browser. If Windows blocks the automatic launch, use the printed authorization URL manually; the callback still lands on `127.0.0.1` and writes the token to your local profile.
 
 ### Local remote development
 

package/dist/auth.d.ts

@@ -10,20 +10,17 @@ export interface TokenStore {
     expires_at: number;
     updated_at: string;
 }
-export interface AuthorizationCodeResult {
-    code: string;
-    state: string;
-    port: number;
-}
 export interface AuthorizeParams {
     authEndpoint: string;
     tokenEndpoint: string;
     clientId: string;
-    redirectUri: string;
+    redirectUri?: string;
     port?: number;
     scope?: string;
     timeoutMs?: number;
     host?: string;
+    callbackHost?: string;
+    callbackPath?: string;
 }
 export interface AuthorizeResult {
     accessToken: string;
@@ -43,6 +40,5 @@ export declare function getValidAccessToken(host: string, tokenEndpoint: string,
 export declare function generateCodeVerifier(length?: number): string;
 export declare function generateCodeChallenge(verifier: string): string;
 export declare function generateState(length?: number): string;
-export declare function startCallbackServer(port: number, timeoutMs?: number): Promise<AuthorizationCodeResult>;
 export declare function openBrowser(url: string): void;
 export declare function authorize(params: AuthorizeParams): Promise<AuthorizeResult>;

package/dist/auth.js

@@ -9,7 +9,6 @@ exports.getValidAccessToken = getValidAccessToken;
 exports.generateCodeVerifier = generateCodeVerifier;
 exports.generateCodeChallenge = generateCodeChallenge;
 exports.generateState = generateState;
-exports.startCallbackServer = startCallbackServer;
 exports.openBrowser = openBrowser;
 exports.authorize = authorize;
 const node_https_1 = require("node:https");
@@ -17,12 +16,23 @@ const node_http_1 = require("node:http");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
-const node_http_2 = require("node:http");
 const node_crypto_1 = require("node:crypto");
 const node_child_process_1 = require("node:child_process");
+class CallbackError extends Error {
+    page;
+    statusCode;
+    constructor(message, page, statusCode = 400) {
+        super(message);
+        this.name = "CallbackError";
+        this.page = page;
+        this.statusCode = statusCode;
+    }
+}
 // ── Token Storage ────────────────────────────────────────────
 const SCOREHUB_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".scorehub");
 const TOKEN_FILE = (host) => (0, node_path_1.join)(SCOREHUB_DIR, host, "oauth.json");
+const DEFAULT_CALLBACK_HOST = "127.0.0.1";
+const DEFAULT_CALLBACK_PATH = "/callback";
 function ensureDir(filePath) {
     const dir = (0, node_path_1.dirname)(filePath);
     if (!(0, node_fs_1.existsSync)(dir)) {
@@ -54,6 +64,221 @@ function clearTokens(host) {
 function hasSignedTokenShape(token) {
     return token.split(".").length === 3;
 }
+function normalizeCallbackPath(path) {
+    if (!path || path === "/")
+        return DEFAULT_CALLBACK_PATH;
+    return path.startsWith("/") ? path : `/${path}`;
+}
+function buildLocalRedirectUri(host, port, path) {
+    const url = new URL(`http://${host}:${port}`);
+    url.pathname = normalizeCallbackPath(path);
+    return url.toString();
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll("\"", "&quot;")
+        .replaceAll("'", "&#39;");
+}
+function buildCallbackPage(page) {
+    const palette = page.tone === "success"
+        ? {
+            badgeBg: "#dcfce7",
+            badgeFg: "#166534",
+            accent: "#16a34a",
+            border: "rgba(22, 163, 74, 0.18)",
+        }
+        : {
+            badgeBg: "#fee2e2",
+            badgeFg: "#991b1b",
+            accent: "#dc2626",
+            border: "rgba(220, 38, 38, 0.16)",
+        };
+    const detail = page.detail
+        ? `<p class="detail">${escapeHtml(page.detail)}</p>`
+        : "";
+    const steps = page.steps
+        .map((step) => `<li>${escapeHtml(step)}</li>`)
+        .join("");
+    return `<!DOCTYPE html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>${escapeHtml(page.title)} | ScoreHub MCP</title>
+    <style>
+      :root {
+        color-scheme: light;
+        font-family: "SF Pro Display", "PingFang SC", "Microsoft YaHei", sans-serif;
+        background:
+          radial-gradient(circle at top left, rgba(168, 85, 247, 0.18), transparent 38%),
+          radial-gradient(circle at bottom right, rgba(59, 130, 246, 0.14), transparent 36%),
+          linear-gradient(180deg, #f5f3ff 0%, #eef4ff 100%);
+      }
+      * {
+        box-sizing: border-box;
+      }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        padding: 24px;
+        color: #1f2937;
+      }
+      .shell {
+        width: min(100%, 640px);
+        border-radius: 28px;
+        padding: 32px;
+        background: rgba(255, 255, 255, 0.92);
+        border: 1px solid rgba(148, 163, 184, 0.22);
+        box-shadow: 0 28px 80px rgba(76, 29, 149, 0.16);
+        backdrop-filter: blur(18px);
+      }
+      .brand {
+        display: inline-flex;
+        align-items: center;
+        gap: 10px;
+        font-size: 13px;
+        font-weight: 700;
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+        color: #6d28d9;
+      }
+      .brand-mark {
+        width: 12px;
+        height: 12px;
+        border-radius: 999px;
+        background: linear-gradient(135deg, #7c3aed, #2563eb);
+        box-shadow: 0 0 0 6px rgba(124, 58, 237, 0.12);
+      }
+      .panel {
+        margin-top: 28px;
+        border-radius: 24px;
+        padding: 28px;
+        border: 1px solid ${palette.border};
+        background:
+          linear-gradient(180deg, rgba(255, 255, 255, 0.96) 0%, rgba(248, 250, 252, 0.92) 100%);
+      }
+      .eyebrow {
+        display: inline-flex;
+        align-items: center;
+        padding: 7px 12px;
+        border-radius: 999px;
+        font-size: 12px;
+        font-weight: 700;
+        letter-spacing: 0.04em;
+        color: ${palette.badgeFg};
+        background: ${palette.badgeBg};
+      }
+      h1 {
+        margin: 18px 0 10px;
+        font-size: clamp(30px, 4vw, 38px);
+        line-height: 1.08;
+        color: #0f172a;
+      }
+      .message {
+        margin: 0;
+        font-size: 16px;
+        line-height: 1.7;
+        color: #334155;
+      }
+      .detail {
+        margin: 16px 0 0;
+        padding: 12px 14px;
+        border-radius: 16px;
+        font-size: 14px;
+        line-height: 1.6;
+        color: #475569;
+        background: rgba(248, 250, 252, 0.96);
+        border: 1px solid rgba(148, 163, 184, 0.16);
+      }
+      .next {
+        margin-top: 24px;
+        padding: 20px;
+        border-radius: 20px;
+        background: rgba(248, 250, 252, 0.94);
+      }
+      .next h2 {
+        margin: 0 0 12px;
+        font-size: 15px;
+        color: ${palette.accent};
+      }
+      ol {
+        margin: 0;
+        padding-left: 20px;
+        color: #334155;
+      }
+      li + li {
+        margin-top: 10px;
+      }
+      .footer {
+        margin-top: 22px;
+        font-size: 13px;
+        color: #64748b;
+      }
+      @media (max-width: 640px) {
+        .shell {
+          padding: 22px;
+          border-radius: 24px;
+        }
+        .panel {
+          padding: 22px;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <main class="shell">
+      <div class="brand">
+        <span class="brand-mark"></span>
+        <span>ScoreHub MCP</span>
+      </div>
+      <section class="panel">
+        <div class="eyebrow">${escapeHtml(page.eyebrow)}</div>
+        <h1>${escapeHtml(page.title)}</h1>
+        <p class="message">${escapeHtml(page.message)}</p>
+        ${detail}
+        <div class="next">
+          <h2>下一步</h2>
+          <ol>${steps}</ol>
+        </div>
+      </section>
+      <p class="footer">这是本机回调页。完成后可以直接关闭当前页面。</p>
+    </main>
+  </body>
+</html>`;
+}
+function getTokenErrorMessage(payload) {
+    if (payload && typeof payload === "object") {
+        const record = payload;
+        if (typeof record.error_description === "string" && record.error_description) {
+            return record.error_description;
+        }
+        if (typeof record.error === "string" && record.error) {
+            return record.error;
+        }
+    }
+    return JSON.stringify(payload);
+}
+function parseOAuthTokens(payload) {
+    if (payload && typeof payload === "object") {
+        const record = payload;
+        if (typeof record.access_token === "string"
+            && typeof record.refresh_token === "string"
+            && typeof record.expires_in === "number") {
+            return {
+                access_token: record.access_token,
+                refresh_token: record.refresh_token,
+                expires_in: record.expires_in,
+                ...(typeof record.scope === "string" ? { scope: record.scope } : {}),
+            };
+        }
+    }
+    throw new Error(getTokenErrorMessage(payload));
+}
 // ── Token Exchange ───────────────────────────────────────────
 function tokenPostRequest(tokenEndpoint, body) {
     const url = new URL(tokenEndpoint);
@@ -91,7 +316,7 @@ async function exchangeCodeForTokens(tokenEndpoint, code, codeVerifier, clientId
         client_id: clientId,
         redirect_uri: redirectUri,
     }).toString();
-    return tokenPostRequest(tokenEndpoint, body);
+    return parseOAuthTokens(await tokenPostRequest(tokenEndpoint, body));
 }
 async function refreshAccessToken(tokenEndpoint, refreshToken, clientId) {
     const body = new URLSearchParams({
@@ -99,7 +324,7 @@ async function refreshAccessToken(tokenEndpoint, refreshToken, clientId) {
         refresh_token: refreshToken,
         client_id: clientId,
     }).toString();
-    return tokenPostRequest(tokenEndpoint, body);
+    return parseOAuthTokens(await tokenPostRequest(tokenEndpoint, body));
 }
 async function getValidAccessToken(host, tokenEndpoint, clientId) {
     const cached = loadTokens(host);
@@ -135,125 +360,193 @@ function generateCodeChallenge(verifier) {
 function generateState(length = 16) {
     return (0, node_crypto_1.randomBytes)(length).toString("hex");
 }
-// ── Local Callback Server ────────────────────────────────────
-function startCallbackServer(port, timeoutMs = 120_000) {
-    return new Promise((resolve, reject) => {
-        let timeoutId;
-        const server = (0, node_http_2.createServer)((req, res) => {
-            const actualPort = server.address()?.port || port;
-            const requestUrl = req.url ?? "/";
-            const url = new URL(requestUrl, `http://127.0.0.1:${actualPort}`);
-            const code = url.searchParams.get("code");
-            const state = url.searchParams.get("state");
-            if (code) {
-                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-                res.end("<!DOCTYPE html><html><head><meta charset=\"utf-8\"><title>Authorization Complete</title></head>" +
-                    "<body style=\"font-family:sans-serif;text-align:center;padding-top:80px;\">" +
-                    "<h2>✅ Authorization Successful</h2>" +
-                    "<p>You may close this window and return to the terminal.</p>" +
-                    "</body></html>");
-            }
-            else {
-                res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
-                res.end("<!DOCTYPE html><html><head><meta charset=\"utf-8\"><title>Authorization Failed</title></head>" +
-                    "<body style=\"font-family:sans-serif;text-align:center;padding-top:80px;\">" +
-                    "<h2>❌ Authorization Failed</h2>" +
-                    "<p>No authorization code received from the provider.</p>" +
-                    "</body></html>");
-            }
-            if (timeoutId)
-                clearTimeout(timeoutId);
-            server.close();
-            if (code) {
-                resolve({ code, state: state ?? "", port: actualPort });
-            }
-            else {
-                reject(new Error("No authorization code in callback"));
-            }
-        });
-        server.on("error", (err) => {
-            if (timeoutId)
-                clearTimeout(timeoutId);
-            reject(err);
-        });
-        server.listen(port, "127.0.0.1", () => {
-            server.unref();
-            timeoutId = setTimeout(() => {
-                server.close();
-                reject(new Error(`Authorization timed out after ${timeoutMs / 1000}s. Please try again.`));
-            }, timeoutMs);
-        });
-    });
-}
 // ── Browser Launch ───────────────────────────────────────────
 function openBrowser(url) {
     try {
         const platform = process.platform;
         if (platform === "darwin") {
-            (0, node_child_process_1.execSync)(`open "${url}"`, { stdio: "ignore", timeout: 3000 });
+            (0, node_child_process_1.execFileSync)("open", [url], { stdio: "ignore", timeout: 3000 });
         }
         else if (platform === "win32") {
-            (0, node_child_process_1.execSync)(`start "" "${url}"`, { shell: "cmd.exe", stdio: "ignore", timeout: 3000 });
+            (0, node_child_process_1.execFileSync)("cmd.exe", ["/c", "start", "", url], { stdio: "ignore", timeout: 3000 });
         }
         else {
-            (0, node_child_process_1.execSync)(`xdg-open "${url}"`, { stdio: "ignore", timeout: 3000 });
+            (0, node_child_process_1.execFileSync)("xdg-open", [url], { stdio: "ignore", timeout: 3000 });
         }
     }
     catch {
-        console.error(`[scorehub] Could not open browser automatically.`);
+        console.error("[scorehub] Could not open browser automatically.");
         console.error(`[scorehub] Please visit this URL manually:\n  ${url}`);
     }
 }
 // ── Full OAuth Flow ──────────────────────────────────────────
 async function authorize(params) {
-    const { authEndpoint, tokenEndpoint, clientId, redirectUri, port = 19836, scope, timeoutMs = 120_000, host, } = params;
+    const { authEndpoint, tokenEndpoint, clientId, redirectUri, scope, timeoutMs = 120_000, host, } = params;
+    const redirectUrl = redirectUri ? new URL(redirectUri) : null;
+    const callbackHost = params.callbackHost ?? redirectUrl?.hostname ?? DEFAULT_CALLBACK_HOST;
+    const callbackPath = normalizeCallbackPath(params.callbackPath ?? redirectUrl?.pathname ?? DEFAULT_CALLBACK_PATH);
+    const listenPort = params.port ?? (redirectUrl?.port ? Number(redirectUrl.port) : 0);
     const storageHost = host ?? new URL(authEndpoint).host;
     const codeVerifier = generateCodeVerifier();
     const codeChallenge = generateCodeChallenge(codeVerifier);
     const state = generateState();
-    const authUrl = new URL(authEndpoint);
-    authUrl.searchParams.set("client_id", clientId);
-    authUrl.searchParams.set("redirect_uri", redirectUri);
-    authUrl.searchParams.set("code_challenge", codeChallenge);
-    authUrl.searchParams.set("code_challenge_method", "S256");
-    authUrl.searchParams.set("state", state);
-    authUrl.searchParams.set("response_type", "code");
-    if (scope)
-        authUrl.searchParams.set("scope", scope);
-    openBrowser(authUrl.toString());
-    let returnedCode;
-    let returnedState;
-    try {
-        const result = await startCallbackServer(port, timeoutMs);
-        returnedCode = result.code;
-        returnedState = result.state;
-    }
-    catch (err) {
-        clearTokens(storageHost);
-        throw err;
-    }
-    if (returnedState !== state) {
-        clearTokens(storageHost);
-        throw new Error("OAuth state mismatch — possible CSRF attack. Please restart the authorization flow.");
-    }
-    let tokens;
-    try {
-        tokens = await exchangeCodeForTokens(tokenEndpoint, returnedCode, codeVerifier, clientId, redirectUri);
-    }
-    catch (err) {
-        clearTokens(storageHost);
-        throw new Error(`Token exchange failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    saveTokens(storageHost, {
-        access_token: tokens.access_token,
-        refresh_token: tokens.refresh_token,
-        expires_at: Date.now() + (tokens.expires_in ?? 3600) * 1000,
-        updated_at: new Date().toISOString(),
+    return new Promise((resolve, reject) => {
+        let timeoutId;
+        let settled = false;
+        const stopServer = (server) => {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+                timeoutId = undefined;
+            }
+            server.close();
+        };
+        const server = (0, node_http_1.createServer)((req, res) => {
+            const actualPort = server.address()?.port ?? listenPort;
+            const requestUrl = req.url ?? "/";
+            const url = new URL(requestUrl, `http://${callbackHost}:${actualPort}`);
+            if (url.pathname !== callbackPath) {
+                res.writeHead(204);
+                res.end();
+                return;
+            }
+            if (settled) {
+                res.writeHead(409, { "Content-Type": "text/html; charset=utf-8" });
+                res.end(buildCallbackPage({
+                    tone: "error",
+                    eyebrow: "Request Closed",
+                    title: "授权请求已结束",
+                    message: "当前授权请求已经结束，请返回终端重新执行 authorize。",
+                    steps: [
+                        "回到 MCP 客户端终端查看最近一次授权结果。",
+                        "如果仍需登录，请重新执行 authorize。",
+                    ],
+                }));
+                return;
+            }
+            void (async () => {
+                try {
+                    const oauthError = url.searchParams.get("error");
+                    const oauthErrorDescription = url.searchParams.get("error_description") ?? undefined;
+                    if (oauthError) {
+                        throw new CallbackError(oauthError === "access_denied" ? "User denied authorization" : `OAuth callback returned error: ${oauthError}`, {
+                            tone: "error",
+                            eyebrow: "Authorization Canceled",
+                            title: oauthError === "access_denied" ? "你已取消授权" : "授权未完成",
+                            message: "ScoreHub 没有返回可用的授权结果，本次登录不会写入本地 token。",
+                            detail: oauthErrorDescription ?? oauthError,
+                            steps: [
+                                "返回终端查看本次授权失败提示。",
+                                "如仍需使用 ScoreHub，请重新执行 authorize。",
+                            ],
+                        });
+                    }
+                    const code = url.searchParams.get("code");
+                    if (!code) {
+                        throw new CallbackError("No authorization code in callback", {
+                            tone: "error",
+                            eyebrow: "Missing Code",
+                            title: "没有收到授权码",
+                            message: "本地回调页已打开，但远端没有带回可交换 token 的授权码。",
+                            steps: [
+                                "返回终端查看详细错误信息。",
+                                "重新执行 authorize，并确认浏览器完成了全部授权步骤。",
+                            ],
+                        });
+                    }
+                    const returnedState = url.searchParams.get("state") ?? "";
+                    if (returnedState !== state) {
+                        throw new CallbackError("OAuth state mismatch — possible CSRF attack. Please restart the authorization flow.", {
+                            tone: "error",
+                            eyebrow: "State Mismatch",
+                            title: "本地状态校验失败",
+                            message: "回调中的 state 与本地发起的请求不一致，本次授权已被拒绝写入。",
+                            steps: [
+                                "关闭当前页面并返回终端。",
+                                "重新执行 authorize 发起一次新的授权流程。",
+                            ],
+                        });
+                    }
+                    const actualRedirectUri = redirectUri ?? buildLocalRedirectUri(callbackHost, actualPort, callbackPath);
+                    const tokens = await exchangeCodeForTokens(tokenEndpoint, code, codeVerifier, clientId, actualRedirectUri);
+                    saveTokens(storageHost, {
+                        access_token: tokens.access_token,
+                        refresh_token: tokens.refresh_token,
+                        expires_at: Date.now() + (tokens.expires_in ?? 3600) * 1000,
+                        updated_at: new Date().toISOString(),
+                    });
+                    settled = true;
+                    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                    res.end(buildCallbackPage({
+                        tone: "success",
+                        eyebrow: "Authorization Complete",
+                        title: "ScoreHub 已完成授权",
+                        message: "本地 token 已写入当前终端配置，你现在可以返回 MCP 客户端继续使用工具。",
+                        steps: [
+                            "回到终端继续执行刚才的操作。",
+                            "如果当前客户端没有自动继续，可直接重新调用目标 ScoreHub 工具。",
+                        ],
+                    }));
+                    stopServer(server);
+                    resolve({
+                        accessToken: tokens.access_token,
+                        refreshToken: tokens.refresh_token,
+                        expiresIn: tokens.expires_in,
+                        scope: tokens.scope,
+                    });
+                }
+                catch (error) {
+                    settled = true;
+                    clearTokens(storageHost);
+                    const err = error instanceof CallbackError
+                        ? error
+                        : new CallbackError(error instanceof Error ? error.message : String(error), {
+                            tone: "error",
+                            eyebrow: "Token Exchange Failed",
+                            title: "授权结果未能保存",
+                            message: "浏览器已经完成跳转，但本地未能成功换取或保存 ScoreHub token。",
+                            detail: error instanceof Error ? error.message : String(error),
+                            steps: [
+                                "返回终端查看失败原因。",
+                                "确认网络和远端状态后，重新执行 authorize。",
+                            ],
+                        });
+                    res.writeHead(err.statusCode, { "Content-Type": "text/html; charset=utf-8" });
+                    res.end(buildCallbackPage(err.page));
+                    stopServer(server);
+                    reject(err);
+                }
+            })();
+        });
+        server.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTokens(storageHost);
+            stopServer(server);
+            reject(err);
+        });
+        server.listen(listenPort, callbackHost, () => {
+            server.unref();
+            const actualPort = server.address().port;
+            const actualRedirectUri = redirectUri ?? buildLocalRedirectUri(callbackHost, actualPort, callbackPath);
+            const authUrl = new URL(authEndpoint);
+            authUrl.searchParams.set("client_id", clientId);
+            authUrl.searchParams.set("redirect_uri", actualRedirectUri);
+            authUrl.searchParams.set("code_challenge", codeChallenge);
+            authUrl.searchParams.set("code_challenge_method", "S256");
+            authUrl.searchParams.set("state", state);
+            authUrl.searchParams.set("response_type", "code");
+            if (scope)
+                authUrl.searchParams.set("scope", scope);
+            openBrowser(authUrl.toString());
+            timeoutId = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTokens(storageHost);
+                stopServer(server);
+                reject(new Error(`Authorization timed out after ${timeoutMs / 1000}s. Please try again.`));
+            }, timeoutMs);
+        });
     });
-    return {
-        accessToken: tokens.access_token,
-        refreshToken: tokens.refresh_token,
-        expiresIn: tokens.expires_in,
-        scope: tokens.scope,
-    };
 }

package/dist/index.js

@@ -37,12 +37,57 @@ function endpointTokenKey(baseUrl) {
 }
 // ── Auth State ──────────────────────────────────────────────
 const auth_js_1 = require("./auth.js");
-const node_http_1 = require("node:http");
-const node_child_process_1 = require("node:child_process");
 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
 const TOKEN_KEEPALIVE_INTERVAL = 4 * 60 * 60 * 1000;
+function isRemoteToolErrorType(value) {
+    return value === "oauth_invalid"
+        || value === "shop_auth_invalid"
+        || value === "rate_limited"
+        || value === "quota_exhausted"
+        || value === "invalid_input"
+        || value === "permission_denied"
+        || value === "upstream_error";
+}
+function parseRemoteToolEnvelope(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed.ok === true && Object.prototype.hasOwnProperty.call(parsed, "data")) {
+            return { ok: true, data: parsed.data };
+        }
+        if (parsed.ok === false
+            && isRemoteToolErrorType(parsed.error_type)
+            && typeof parsed.user_message === "string"
+            && typeof parsed.retryable === "boolean") {
+            return {
+                ok: false,
+                error_type: parsed.error_type,
+                user_message: parsed.user_message,
+                retryable: parsed.retryable,
+                ...(Object.prototype.hasOwnProperty.call(parsed, "upstream") ? { upstream: parsed.upstream } : {}),
+            };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function extractRemoteTextContent(content) {
+    if (!Array.isArray(content)) {
+        return [];
+    }
+    return content.flatMap((item) => {
+        if (item
+            && typeof item === "object"
+            && item.type === "text"
+            && typeof item.text === "string") {
+            return [item.text];
+        }
+        return [];
+    });
+}
 // ── Remote Tool Proxy (MCP Streamable HTTP) ─────────────────
 async function fetchRemoteTools(token) {
     try {
@@ -74,18 +119,20 @@ async function callRemoteTool(name, args, token) {
     try {
         await client.connect(transport);
         const result = await client.callTool({ name, arguments: args });
-        return JSON.stringify(result.content, null, 2);
+        const textBlocks = extractRemoteTextContent(result.content);
+        const rawText = textBlocks.length > 0
+            ? textBlocks.join("\n\n")
+            : JSON.stringify(result.content, null, 2);
+        const envelope = textBlocks
+            .map((text) => parseRemoteToolEnvelope(text))
+            .find((candidate) => candidate !== null)
+            ?? parseRemoteToolEnvelope(rawText);
+        return { rawText, envelope };
     }
     finally {
         await client.close();
     }
 }
-// ── OAuth authorize helper ──────────────────────────────────
-function generateAuthUrl(port = 19836) {
-    // Generate random state for CSRF protection
-    const state = Math.random().toString(36).substring(2);
-    return `${AUTHORIZE_URL}?client_id=scorehub-mcp&redirect_uri=http://127.0.0.1:${port}/callback&state=${state}`;
-}
 // ── Fetch remote tools on startup ───────────────────────────
 let remoteTools = [];
 let lastFetchError = null;
@@ -153,97 +200,23 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             else {
                 (0, auth_js_1.clearTokens)(TOKEN_STORE_KEY);
             }
-            // Port 0 lets the OS assign a random available port,
-            // avoiding conflicts when multiple MCP clients run simultaneously
-            let actualPort = 0;
-            return new Promise((resolve) => {
-                let timeoutId;
-                const callbackServer = (0, node_http_1.createServer)((req, res) => {
-                    const requestUrl = req.url ?? "/";
-                    const url = new URL(requestUrl, `http://127.0.0.1:${actualPort}`);
-                    // 只处理 /callback 路径的请求，忽略浏览器探测请求（favicon、安全检查等）
-                    if (url.pathname !== "/callback") {
-                        res.writeHead(204);
-                        res.end();
-                        return;
-                    }
-                    if (timeoutId)
-                        clearTimeout(timeoutId);
-                    const code = url.searchParams.get("code");
-                    if (code) {
-                        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-                        res.end("<!DOCTYPE html><html><head><meta charset=\"utf-8\"><title>Authorization Complete</title></head>" +
-                            "<body style=\"font-family:sans-serif;text-align:center;padding-top:80px;\">" +
-                            "<h2>✅ Authorization Successful</h2>" +
-                            "<p>You may close this window and return to the terminal.</p>" +
-                            "</body></html>");
-                        callbackServer.close();
-                        fetch(TOKEN_ENDPOINT, {
-                            method: "POST",
-                            headers: { "Content-Type": "application/json" },
-                            body: JSON.stringify({ grant_type: "authorization_code", code }),
-                        })
-                            .then((r) => r.json())
-                            .then((tokenData) => {
-                            if (!tokenData.access_token) {
-                                resolve({
-                                    content: [{ type: "text", text: `❌ Token 获取失败: ${JSON.stringify(tokenData)}` }],
-                                });
-                                return;
-                            }
-                            (0, auth_js_1.saveTokens)(TOKEN_STORE_KEY, {
-                                access_token: tokenData.access_token,
-                                refresh_token: tokenData.refresh_token ?? "",
-                                expires_at: Date.now() + (tokenData.expires_in ?? 3600) * 1000,
-                                updated_at: new Date().toISOString(),
-                            });
-                            resolve({
-                                content: [{ type: "text", text: "✅ 授权成功！可以开始使用工具了。" }],
-                            });
-                        })
-                            .catch((e) => resolve({
-                            content: [{ type: "text", text: `❌ Token 获取失败: ${String(e)}` }],
-                        }));
-                    }
-                    else {
-                        // 到达 /callback 但没有 code —— 真正的错误
-                        res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
-                        res.end("<!DOCTYPE html><html><head><meta charset=\"utf-8\"><title>Authorization Failed</title></head>" +
-                            "<body style=\"font-family:sans-serif;text-align:center;padding-top:80px;\">" +
-                            "<h2>❌ Authorization Failed</h2>" +
-                            "<p>No authorization code received from the provider.</p>" +
-                            "</body></html>");
-                        callbackServer.close();
-                        resolve({
-                            content: [{ type: "text", text: "❌ 授权失败: No authorization code in callback" }],
-                        });
-                    }
-                });
-                callbackServer.on("error", (err) => {
-                    if (timeoutId)
-                        clearTimeout(timeoutId);
-                    resolve({
-                        content: [{ type: "text", text: `❌ 授权失败: ${String(err)}` }],
-                    });
-                });
-                callbackServer.listen(0, "127.0.0.1", () => {
-                    actualPort = callbackServer.address().port;
-                    callbackServer.unref();
-                    const authUrl = generateAuthUrl(actualPort);
-                    const os = process.platform;
-                    const cmd = os === "darwin" ? "open" : os === "win32" ? "start" : "xdg-open";
-                    try {
-                        (0, node_child_process_1.execSync)(`${cmd} "${authUrl}"`);
-                    }
-                    catch { /* headless env: user opens manually */ }
-                    timeoutId = setTimeout(() => {
-                        callbackServer.close();
-                        resolve({
-                            content: [{ type: "text", text: "❌ 授权超时 (120s)。请重试。" }],
-                        });
-                    }, 120_000);
+            try {
+                await (0, auth_js_1.authorize)({
+                    authEndpoint: AUTHORIZE_URL,
+                    tokenEndpoint: TOKEN_ENDPOINT,
+                    clientId: CLIENT_ID,
+                    host: TOKEN_STORE_KEY,
+                    port: 0,
                 });
-            });
+                return {
+                    content: [{ type: "text", text: "✅ 授权成功！浏览器中的本地回调页已确认，可以直接继续使用 ScoreHub 工具。" }],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [{ type: "text", text: `❌ 授权失败: ${error instanceof Error ? error.message : String(error)}` }],
+                };
+            }
         }
         case "status": {
             const tokenResult = await (0, auth_js_1.getValidAccessToken)(TOKEN_STORE_KEY, TOKEN_ENDPOINT, CLIENT_ID);
@@ -266,31 +239,40 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             // Check authorization for remote tools — re-validates on every call
             const tokenResult = await (0, auth_js_1.getValidAccessToken)(TOKEN_STORE_KEY, TOKEN_ENDPOINT, CLIENT_ID);
             if (!tokenResult) {
-                const authUrl = generateAuthUrl();
                 return {
                     content: [
                         {
                             type: "text",
-                            text: `⚠️ 未授权。请先调用 "authorize" 工具登录 ScoreHub。\n授权地址: ${authUrl}`,
+                            text: "⚠️ 未授权。请先调用 \"authorize\" 工具登录 ScoreHub。若浏览器未自动打开，请复制终端输出的授权链接到浏览器完成登录。",
                         },
                     ],
                 };
             }
             try {
-                const result = await callRemoteTool(name, args, tokenResult.access_token);
-                if (result.includes("ScoreHub OAuth 授权已过期或无效")) {
+                const remoteResult = await callRemoteTool(name, args, tokenResult.access_token);
+                if (remoteResult.envelope?.ok === false && remoteResult.envelope.error_type === "oauth_invalid") {
+                    (0, auth_js_1.clearTokens)(TOKEN_STORE_KEY);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "⚠️ 授权已失效，已清除本地缓存。请调用 \"authorize\" 工具重新登录 ScoreHub。若浏览器未自动打开，请复制终端输出的授权链接到浏览器完成登录。",
+                            },
+                        ],
+                    };
+                }
+                if (remoteResult.rawText.includes("ScoreHub OAuth 授权已过期或无效")) {
                     (0, auth_js_1.clearTokens)(TOKEN_STORE_KEY);
-                    const authUrl = generateAuthUrl();
                     return {
                         content: [
                             {
                                 type: "text",
-                                text: `⚠️ 授权已失效，已清除本地缓存。请调用 "authorize" 工具重新登录 ScoreHub。\n授权地址: ${authUrl}`,
+                                text: "⚠️ 授权已失效，已清除本地缓存。请调用 \"authorize\" 工具重新登录 ScoreHub。若浏览器未自动打开，请复制终端输出的授权链接到浏览器完成登录。",
                             },
                         ],
                     };
                 }
-                return { content: [{ type: "text", text: result }] };
+                return { content: [{ type: "text", text: remoteResult.rawText }] };
             }
             catch (e) {
                 return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scorehub/mcp-server",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "ScoreHub local MCP proxy — OAuth login, token caching, and tool forwarding to remote MCP endpoint",
   "main": "dist/index.js",
   "bin": {