@scorehub/mcp-server 0.2.8 → 0.2.10

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 uses the same visual language as the ScoreHub OAuth login and consent pages, with a branded summary, local callback metadata, and state-specific guidance on 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,24 @@ 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");
+const callback_pages_js_1 = require("./pages/callback-pages.js");
+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 +65,62 @@ 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 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));
+}
+function createCallbackPageModel(input) {
+    return {
+        tone: input.tone,
+        eyebrow: input.eyebrow,
+        title: input.title,
+        message: input.message,
+        ...(input.detail ? { detail: input.detail } : {}),
+        summaryLabel: input.summaryLabel ?? "结果说明",
+        summaryText: input.summaryText,
+        metaLabel: "本地回调地址",
+        metaValue: input.callbackUrl,
+        resultLabel: input.resultLabel ?? "当前状态",
+        resultValue: input.resultValue,
+        steps: input.steps,
+        closeLabel: input.closeLabel ?? "关闭当前页面",
+        helperText: input.helperText ?? "如果浏览器无法自动关闭，请手动切回终端继续。",
+    };
+}
 // ── Token Exchange ───────────────────────────────────────────
 function tokenPostRequest(tokenEndpoint, body) {
     const url = new URL(tokenEndpoint);
@@ -91,7 +158,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 +166,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 +202,220 @@ 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}`);
+            const callbackUrl = buildLocalRedirectUri(callbackHost, actualPort, callbackPath);
+            if (url.pathname !== callbackPath) {
+                res.writeHead(204);
+                res.end();
+                return;
+            }
+            if (settled) {
+                res.writeHead(409, { "Content-Type": "text/html; charset=utf-8" });
+                res.end((0, callback_pages_js_1.buildCallbackPage)(createCallbackPageModel({
+                    tone: "error",
+                    eyebrow: "Request Closed",
+                    title: "授权请求已结束",
+                    message: "当前回调监听已经完成，不能再用这个页面继续授权流程。",
+                    summaryText: "这通常表示你刷新了已经处理过的 callback 页面，或者在授权完成后再次访问了同一地址。",
+                    resultValue: "本次请求已关闭，请回终端查看最终结果",
+                    steps: [
+                        "回到 MCP 客户端终端查看最近一次 authorize 的执行结果。",
+                        "如果仍需重新登录，请在终端重新执行 authorize，而不是刷新当前页面。",
+                    ],
+                    callbackUrl,
+                    closeLabel: "关闭当前页面",
+                })));
+                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}`, createCallbackPageModel({
+                            tone: "error",
+                            eyebrow: "Authorization Canceled",
+                            title: oauthError === "access_denied" ? "你已取消授权" : "授权未完成",
+                            message: "ScoreHub 没有返回可用的授权结果，本次登录不会写入本地 token。",
+                            detail: oauthErrorDescription ?? oauthError,
+                            summaryText: oauthError === "access_denied"
+                                ? "你在 OAuth 授权页拒绝了本次请求，ScoreHub MCP 不会继续交换 token。"
+                                : "远端授权流程返回了错误状态，本地不会保存任何新的授权信息。",
+                            resultValue: "未写入本地 token，可重新发起授权",
+                            steps: [
+                                "返回终端查看本次授权失败提示。",
+                                "如仍需使用 ScoreHub，请重新执行 authorize。",
+                            ],
+                            callbackUrl,
+                            closeLabel: "关闭后回终端",
+                        }));
+                    }
+                    const code = url.searchParams.get("code");
+                    if (!code) {
+                        throw new CallbackError("No authorization code in callback", createCallbackPageModel({
+                            tone: "error",
+                            eyebrow: "Missing Code",
+                            title: "没有收到授权码",
+                            message: "本地回调页已打开，但远端没有带回可交换 token 的授权码。",
+                            summaryText: "浏览器已经回到本地 callback，但缺少完成 token 交换必需的 authorization code。",
+                            resultValue: "授权结果不完整，本地未保存任何 token",
+                            steps: [
+                                "返回终端查看详细错误信息。",
+                                "重新执行 authorize，并确认浏览器完成了全部授权步骤。",
+                            ],
+                            callbackUrl,
+                            closeLabel: "关闭后回终端",
+                        }));
+                    }
+                    const returnedState = url.searchParams.get("state") ?? "";
+                    if (returnedState !== state) {
+                        throw new CallbackError("OAuth state mismatch — possible CSRF attack. Please restart the authorization flow.", createCallbackPageModel({
+                            tone: "error",
+                            eyebrow: "State Mismatch",
+                            title: "本地状态校验失败",
+                            message: "回调中的 state 与本地发起的请求不一致，本次授权已被拒绝写入。",
+                            summaryText: "为了避免把错误来源的授权结果写入本机，ScoreHub MCP 已主动丢弃这次回调。",
+                            resultValue: "安全校验未通过，需要重新发起授权",
+                            steps: [
+                                "关闭当前页面并返回终端。",
+                                "重新执行 authorize 发起一次新的授权流程。",
+                            ],
+                            callbackUrl,
+                            closeLabel: "关闭后回终端",
+                        }));
+                    }
+                    const actualRedirectUri = redirectUri ?? callbackUrl;
+                    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((0, callback_pages_js_1.buildCallbackPage)(createCallbackPageModel({
+                        tone: "success",
+                        eyebrow: "Authorization Complete",
+                        title: "ScoreHub 已完成授权",
+                        message: "本地 token 已写入当前终端配置，你现在可以返回 MCP 客户端继续使用工具。",
+                        summaryText: "ScoreHub MCP 已收到授权码并完成 token 交换，当前终端会直接复用这次新的本地授权。",
+                        resultValue: "授权成功，本地 token 已更新",
+                        steps: [
+                            "切回终端继续执行刚才的操作。",
+                            "如果当前客户端没有自动继续，可直接重新调用目标 ScoreHub 工具。",
+                        ],
+                        callbackUrl,
+                        closeLabel: "关闭当前页面",
+                    })));
+                    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), createCallbackPageModel({
+                            tone: "error",
+                            eyebrow: "Token Exchange Failed",
+                            title: "授权结果未能保存",
+                            message: "浏览器已经完成跳转，但本地未能成功换取或保存 ScoreHub token。",
+                            detail: error instanceof Error ? error.message : String(error),
+                            summaryText: "问题发生在本地 token 交换或保存阶段，而不是登录页或授权确认页本身。",
+                            resultValue: "未保存新的 token，请回终端重试",
+                            steps: [
+                                "返回终端查看失败原因。",
+                                "确认网络和远端状态后，重新执行 authorize。",
+                            ],
+                            callbackUrl,
+                            closeLabel: "关闭后回终端",
+                        }));
+                    res.writeHead(err.statusCode, { "Content-Type": "text/html; charset=utf-8" });
+                    res.end((0, callback_pages_js_1.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,8 +37,6 @@ 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
@@ -135,12 +133,6 @@ async function callRemoteTool(name, args, token) {
         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;
@@ -208,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);
@@ -321,12 +239,11 @@ 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。若浏览器未自动打开，请复制终端输出的授权链接到浏览器完成登录。",
                         },
                     ],
                 };
@@ -335,24 +252,22 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 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);
-                    const authUrl = generateAuthUrl();
                     return {
                         content: [
                             {
                                 type: "text",
-                                text: `⚠️ 授权已失效，已清除本地缓存。请调用 "authorize" 工具重新登录 ScoreHub。\n授权地址: ${authUrl}`,
+                                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。若浏览器未自动打开，请复制终端输出的授权链接到浏览器完成登录。",
                             },
                         ],
                     };

package/dist/pages/callback-pages.d.ts

@@ -0,0 +1,17 @@
+export interface CallbackPageModel {
+    tone: "success" | "error";
+    eyebrow: string;
+    title: string;
+    message: string;
+    detail?: string;
+    summaryLabel: string;
+    summaryText: string;
+    metaLabel: string;
+    metaValue: string;
+    resultLabel: string;
+    resultValue: string;
+    steps: string[];
+    closeLabel?: string;
+    helperText?: string;
+}
+export declare function buildCallbackPage(page: CallbackPageModel): string;

package/dist/pages/callback-pages.js

@@ -0,0 +1,426 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCallbackPage = buildCallbackPage;
+const SCOREHUB_CALLBACK_LOGO_DATA_URL = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Cdefs%3E%3ClinearGradient id='g' x1='8' y1='8' x2='56' y2='56' gradientUnits='userSpaceOnUse'%3E%3Cstop stop-color='%237C3AED'/%3E%3Cstop offset='1' stop-color='%23A78BFA'/%3E%3C/linearGradient%3E%3C/defs%3E%3Crect x='6' y='6' width='52' height='52' rx='16' fill='url(%23g)'/%3E%3Cpath d='M23 20h18c5 0 9 4 9 9 0 4-2 7-5 8 2 2 3 5 3 8v1H38v-2c0-4-3-7-7-7h-8V20Zm10 8h-4v9h4c4 0 7-2 7-5 0-3-3-4-7-4Z' fill='white'/%3E%3C/svg%3E";
+const CALLBACK_BASE_STYLES = `
+    * { margin:0; padding:0; box-sizing:border-box; }
+    body {
+      font-family:-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      min-height:100vh;
+      padding:28px;
+      display:flex;
+      justify-content:center;
+      align-items:center;
+      color:#211827;
+      background:
+        radial-gradient(ellipse at 22% 18%, rgba(124, 58, 237, 0.18) 0 12%, transparent 38%),
+        radial-gradient(ellipse at 82% 78%, rgba(139, 92, 246, 0.14) 0 10%, transparent 36%),
+        radial-gradient(ellipse at 18% 82%, transparent 0 34%, rgba(124, 58, 237, 0.055) 35%, transparent 36%, transparent 48%, rgba(124, 58, 237, 0.04) 49%, transparent 50%),
+        radial-gradient(ellipse at 82% 16%, transparent 0 30%, rgba(139, 92, 246, 0.05) 31%, transparent 32%, transparent 45%, rgba(139, 92, 246, 0.035) 46%, transparent 47%),
+        radial-gradient(circle at 50% 50%, rgba(124, 58, 237, 0.055) 1px, transparent 1.4px),
+        linear-gradient(135deg, #FDFBFF 0%, #F7F0FF 52%, #F0E7FF 100%);
+      background-size:auto, auto, 100% 100%, 100% 100%, 28px 28px, 100% 100%;
+      background-position:center;
+    }
+    .card {
+      position:relative;
+      width:min(100%, 920px);
+      margin:0 auto;
+      background:rgba(255, 255, 255, 0.94);
+      border:1px solid rgba(216, 180, 254, 0.76);
+      border-radius:22px;
+      box-shadow:0 28px 80px rgba(93, 52, 146, 0.18);
+      overflow:hidden;
+    }
+    .card::before {
+      content:"";
+      position:absolute;
+      inset:0 0 auto 0;
+      height:3px;
+      background:linear-gradient(90deg, #7C3AED, #A78BFA);
+    }
+    .brand { display:flex; align-items:center; gap:14px; margin-bottom:22px; }
+    .brand-logo {
+      width:48px;
+      height:48px;
+      border-radius:15px;
+      padding:7px;
+      background:rgba(255, 255, 255, 0.86);
+      border:1px solid rgba(216, 180, 254, 0.88);
+      box-shadow:0 12px 28px rgba(124, 58, 237, 0.18), inset 0 1px 0 rgba(255, 255, 255, 0.9);
+      object-fit:contain;
+    }
+    .brand-name { font-size:13px; color:#7C3AED; font-weight:800; margin-bottom:3px; }
+    h2 { font-size:26px; line-height:1.2; font-weight:800; color:#211827; margin-bottom:8px; }
+    .sub, p { font-size:13px; line-height:1.7; color:#665476; }
+    .callback-grid { display:grid; grid-template-columns:minmax(290px, 0.92fr) minmax(380px, 1.08fr); min-height:min(560px, calc(100vh - 56px)); }
+    .callback-info {
+      padding:34px;
+      background:linear-gradient(180deg, rgba(252, 250, 255, 0.88), rgba(248, 243, 255, 0.92));
+      border-right:1px solid #F0E6FF;
+    }
+    .callback-panel {
+      display:flex;
+      flex-direction:column;
+      min-width:0;
+      padding:34px 34px 0;
+    }
+    .request-summary,
+    .panel-card,
+    .next-card,
+    .detail-card,
+    .trust-item {
+      border-radius:16px;
+      border:1px solid rgba(216, 180, 254, 0.78);
+      background:rgba(255, 255, 255, 0.72);
+      box-shadow:inset 0 1px 0 rgba(255, 255, 255, 0.78);
+    }
+    .request-summary,
+    .panel-card,
+    .detail-card,
+    .next-card { padding:15px 16px; }
+    .request-label,
+    .section-title {
+      display:block;
+      color:#7C3AED;
+      font-size:11px;
+      font-weight:800;
+      line-height:1.3;
+      margin-bottom:7px;
+      text-transform:uppercase;
+      letter-spacing:0;
+    }
+    .request-copy { color:#372A45; font-size:13px; line-height:1.65; margin:0; }
+    .request-copy strong { color:#5B21B6; font-weight:800; }
+    .request-copy code,
+    .trust-copy code,
+    .meta-value code,
+    .detail-copy code {
+      font-family:ui-monospace, SFMono-Regular, Menlo, monospace;
+      font-size:0.92em;
+      color:#5B21B6;
+      background:rgba(124, 58, 237, 0.08);
+      border-radius:6px;
+      padding:1px 5px;
+    }
+    .trust-list {
+      display:grid;
+      gap:8px;
+      margin-top:22px;
+    }
+    .trust-item {
+      display:grid;
+      grid-template-columns:auto minmax(0, 1fr);
+      gap:10px;
+      align-items:start;
+      padding:12px 13px;
+    }
+    .trust-icon {
+      width:22px;
+      height:22px;
+      border-radius:8px;
+      display:flex;
+      align-items:center;
+      justify-content:center;
+      background:#F3E8FF;
+      color:#6D28D9;
+      font-size:12px;
+      font-weight:900;
+    }
+    .trust-title {
+      display:block;
+      color:#372A45;
+      font-size:12px;
+      font-weight:800;
+      line-height:1.35;
+      margin-bottom:2px;
+    }
+    .trust-copy {
+      display:block;
+      color:#665476;
+      font-size:12px;
+      line-height:1.45;
+    }
+    .account-pill {
+      max-width:100%;
+      padding:9px 12px;
+      border:1px solid #E9D5FF;
+      border-radius:12px;
+      background:#FCFAFF;
+      color:#5E4C6D;
+      font-size:12px;
+      font-weight:700;
+      overflow:hidden;
+      text-overflow:ellipsis;
+      white-space:nowrap;
+      margin-bottom:18px;
+    }
+    .status-badge {
+      display:inline-flex;
+      align-items:center;
+      justify-content:center;
+      min-height:26px;
+      font-size:11px;
+      line-height:1.2;
+      padding:4px 10px;
+      border-radius:999px;
+      font-weight:800;
+      white-space:nowrap;
+      margin-bottom:14px;
+    }
+    .status-badge-success {
+      color:#166534;
+      background:#DCFCE7;
+      border:1px solid #BBF7D0;
+    }
+    .status-badge-error {
+      color:#B42318;
+      background:#FEF3F2;
+      border:1px solid #FEE4E2;
+    }
+    .summary-copy {
+      color:#372A45;
+      font-size:13px;
+      line-height:1.65;
+      margin:0;
+    }
+    .summary-copy strong { color:#5B21B6; font-weight:800; }
+    .detail-card {
+      margin-top:14px;
+      border-color:#FEE4E2;
+      background:#FEF3F2;
+    }
+    .detail-copy {
+      color:#B42318;
+      font-size:12px;
+      line-height:1.55;
+      margin:0;
+      white-space:pre-wrap;
+      word-break:break-word;
+    }
+    .meta-grid {
+      display:grid;
+      grid-template-columns:repeat(2, minmax(0, 1fr));
+      gap:12px;
+      margin-top:18px;
+    }
+    .meta-label {
+      display:block;
+      color:#7C6A88;
+      font-size:11px;
+      font-weight:700;
+      margin-bottom:6px;
+      text-transform:uppercase;
+    }
+    .meta-value {
+      color:#372A45;
+      font-size:13px;
+      line-height:1.55;
+      word-break:break-word;
+    }
+    .next-card { margin-top:18px; }
+    .step-list {
+      display:grid;
+      gap:10px;
+      list-style:none;
+      padding:0;
+      margin:0;
+    }
+    .step-item {
+      display:grid;
+      grid-template-columns:auto minmax(0, 1fr);
+      gap:10px;
+      align-items:start;
+      color:#372A45;
+      font-size:13px;
+      line-height:1.55;
+    }
+    .step-index {
+      width:22px;
+      height:22px;
+      border-radius:999px;
+      display:flex;
+      align-items:center;
+      justify-content:center;
+      background:#F3E8FF;
+      color:#6D28D9;
+      font-size:12px;
+      font-weight:900;
+    }
+    .panel-spacer { flex:1; min-height:18px; }
+    .actions {
+      position:sticky;
+      bottom:0;
+      display:flex;
+      gap:12px;
+      margin:22px -34px 0;
+      padding:16px 34px 18px;
+      background:rgba(255, 255, 255, 0.92);
+      border-top:1px solid #F0E6FF;
+      backdrop-filter:blur(12px);
+    }
+    .btn {
+      flex:1;
+      min-height:44px;
+      padding:10px 16px;
+      border-radius:12px;
+      font-size:14px;
+      font-weight:800;
+      cursor:pointer;
+      border:1px solid transparent;
+      transition:background 0.15s, border-color 0.15s, box-shadow 0.15s, transform 0.15s;
+    }
+    .btn:hover { transform:translateY(-1px); }
+    .btn-primary {
+      background:#7C3AED;
+      color:#fff;
+      box-shadow:0 10px 24px rgba(124, 58, 237, 0.26);
+    }
+    .btn-primary:hover { background:#6D28D9; }
+    .btn-secondary {
+      background:#fff;
+      color:#5E4C6D;
+      border-color:#E9D5FF;
+    }
+    .btn-secondary:hover {
+      background:#FAF7FF;
+      border-color:#D8B4FE;
+    }
+    .helper-note {
+      margin-top:14px;
+      color:#7C6A88;
+      font-size:12px;
+      line-height:1.5;
+      text-align:center;
+    }
+    @media (max-width: 760px) {
+      body { min-height:100vh; padding:16px; align-items:flex-start; }
+      .card { width:100%; border-radius:18px; }
+      .callback-grid { display:block; min-height:0; }
+      .callback-info { padding:22px 18px; border-right:0; border-bottom:1px solid #F0E6FF; }
+      .callback-panel { padding:22px 18px 0; }
+      .brand { gap:12px; margin-bottom:18px; }
+      .brand-logo { width:44px; height:44px; border-radius:14px; }
+      h2 { font-size:22px; }
+      .meta-grid { grid-template-columns:1fr; }
+      .actions { position:sticky; bottom:0; margin:22px -18px 0; padding:14px 18px 16px; }
+      .btn { min-height:46px; }
+    }
+`;
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll("\"", "&quot;")
+        .replaceAll("'", "&#39;");
+}
+function buildCallbackPage(page) {
+    const statusClass = page.tone === "success" ? "status-badge-success" : "status-badge-error";
+    const detailBlock = page.detail
+        ? `<div class="detail-card">
+        <span class="section-title">错误详情</span>
+        <p class="detail-copy">${escapeHtml(page.detail)}</p>
+      </div>`
+        : "";
+    const stepItems = page.steps
+        .map((step, index) => `<li class="step-item"><span class="step-index">${index + 1}</span><span>${escapeHtml(step)}</span></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</title>
+  <link rel="icon" href="${SCOREHUB_CALLBACK_LOGO_DATA_URL}">
+  <style>${CALLBACK_BASE_STYLES}</style>
+</head>
+<body>
+  <div class="card">
+    <div class="callback-grid">
+      <div class="callback-info">
+        <div class="brand">
+          <img class="brand-logo" src="${SCOREHUB_CALLBACK_LOGO_DATA_URL}" alt="ScoreHub AI">
+          <div>
+            <div class="brand-name">ScoreHub AI</div>
+            <h2>本地授权回调</h2>
+          </div>
+        </div>
+        <div class="request-summary">
+          <span class="request-label">当前步骤</span>
+          <p class="request-copy"><strong>ScoreHub MCP</strong> 正在完成本机 OAuth 收尾流程。这个页面只负责接收授权结果、更新本地 token，并把状态反馈给终端里的 <strong>Tiky / MCP 客户端</strong>。</p>
+        </div>
+        <div class="trust-list">
+          <div class="trust-item">
+            <span class="trust-icon">1</span>
+            <span>
+              <span class="trust-title">仅本机处理</span>
+              <span class="trust-copy">本页只处理 <code>127.0.0.1</code> 本地回调，不会再次请求你的账号密码。</span>
+            </span>
+          </div>
+          <div class="trust-item">
+            <span class="trust-icon">2</span>
+            <span>
+              <span class="trust-title">结果已同步终端</span>
+              <span class="trust-copy">无论成功还是失败，最终状态都会回到当前终端进程，由 <code>authorize</code> 工具接收。</span>
+            </span>
+          </div>
+          <div class="trust-item">
+            <span class="trust-icon">3</span>
+            <span>
+              <span class="trust-title">异常可重新发起</span>
+              <span class="trust-copy">如果本次失败，请返回终端重新执行 <code>authorize</code>，而不是刷新当前页面。</span>
+            </span>
+          </div>
+        </div>
+      </div>
+
+      <div class="callback-panel">
+        <div class="account-pill" title="${escapeHtml(`${page.metaLabel}: ${page.metaValue}`)}">${escapeHtml(`${page.metaLabel}: ${page.metaValue}`)}</div>
+        <div class="status-badge ${statusClass}">${escapeHtml(page.eyebrow)}</div>
+        <div class="panel-card">
+          <h2>${escapeHtml(page.title)}</h2>
+          <p class="sub">${escapeHtml(page.message)}</p>
+          ${detailBlock}
+          <div class="meta-grid">
+            <div>
+              <span class="meta-label">${escapeHtml(page.summaryLabel)}</span>
+              <div class="meta-value">${escapeHtml(page.summaryText)}</div>
+            </div>
+            <div>
+              <span class="meta-label">${escapeHtml(page.resultLabel)}</span>
+              <div class="meta-value">${escapeHtml(page.resultValue)}</div>
+            </div>
+          </div>
+        </div>
+        <div class="next-card">
+          <span class="section-title">下一步</span>
+          <ol class="step-list">${stepItems}</ol>
+        </div>
+        <div class="panel-spacer"></div>
+        <div class="actions">
+          <button class="btn btn-secondary" type="button" id="close-button">${escapeHtml(page.closeLabel ?? "关闭当前页面")}</button>
+          <button class="btn btn-primary" type="button" id="focus-button">切回终端继续</button>
+        </div>
+        <div class="helper-note">${escapeHtml(page.helperText ?? "如果浏览器无法自动关闭，请手动切回终端继续。")}</div>
+      </div>
+    </div>
+  </div>
+  <script>
+    const closeButton = document.getElementById('close-button');
+    const focusButton = document.getElementById('focus-button');
+
+    closeButton.addEventListener('click', function() {
+      window.close();
+    });
+
+    focusButton.addEventListener('click', function() {
+      window.close();
+      setTimeout(function() {
+        window.focus();
+      }, 60);
+    });
+  </script>
+</body>
+</html>`;
+}

package/package.json

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