@scorehub/mcp-server 0.2.4 → 0.2.6

package/README.md

@@ -51,7 +51,7 @@ In `claude_desktop_config.json` or `.claude/mcp.json`:
       "command": "npx",
       "args": ["-y", "@scorehub/mcp-server"],
       "env": {
-        "SCOREHUB_REMOTE_MCP_URL": "https://mcp.scorehub.cn"
+        "SCOREHUB_REMOTE_MCP_URL": "https://app.scorehub.cn/mcp"
       }
     }
   }
@@ -69,7 +69,7 @@ In `mcp.json`:
       "command": "npx",
       "args": ["-y", "@scorehub/mcp-server"],
       "env": {
-        "SCOREHUB_REMOTE_MCP_URL": "https://mcp.scorehub.cn"
+        "SCOREHUB_REMOTE_MCP_URL": "https://app.scorehub.cn/mcp"
       }
     }
   }
@@ -91,17 +91,17 @@ In `mcp.json`:
 
 | Variable | Required | Default | Description |
 |---|---|---|---|
-| `SCOREHUB_REMOTE_MCP_URL` | No | `https://mcp.scorehub.cn` | Base URL of the remote ScoreHub MCP endpoint |
+| `SCOREHUB_REMOTE_MCP_URL` | No | `https://app.scorehub.cn/mcp` | Base URL of the remote ScoreHub MCP endpoint |
 
 ### Token storage
 
 OAuth tokens are stored at:
 
 ```
-~/.scorehub/<host>/oauth.json
+~/.scorehub/<endpoint>/oauth.json
 ```
 
-The `<host>` is derived from the `SCOREHUB_REMOTE_MCP_URL` (e.g., `mcp.scorehub.cn`). This means you can run staging and production side-by-side by pointing each configuration at a different URL — tokens are isolated per host.
+The `<endpoint>` is derived from the `SCOREHUB_REMOTE_MCP_URL` host and path (for example, `app.scorehub.cn_mcp`). This means you can run staging and production side-by-side by pointing each configuration at a different URL — tokens are isolated per endpoint.
 
 **Token file structure:**
 
@@ -158,7 +158,7 @@ These tools are **dynamically loaded** from the remote MCP endpoint at startup a
          ├─ POST /token ───────────────────▶│
          │◀── access_token + refresh_token  │
          │                                  │
-         ├─ saves to ~/.scorehub/<host>/oauth.json
+        ├─ saves to ~/.scorehub/<endpoint>/oauth.json
 ```
 
 ### Token lifecycle
@@ -169,12 +169,31 @@ These tools are **dynamically loaded** from the remote MCP endpoint at startup a
 | **Subsequent calls** | Read cached file → check expiry with 5-minute buffer |
 | **Near expiry** | Auto-refresh with `refresh_token` → write new token back to file |
 | **Refresh fails** | Returns an error message with the authorization URL — call `authorize` again |
-| **Manual logout** | Delete `~/.scorehub/<host>/oauth.json` or the entire `~/.scorehub/` directory |
+| **Manual logout** | Delete `~/.scorehub/<endpoint>/oauth.json` or the entire `~/.scorehub/` directory |
 
 ### 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.
 
+### Local remote development
+
+When testing a local `mcp-remote`, point this local proxy at the same local base URL:
+
+```bash
+SCOREHUB_REMOTE_MCP_URL=http://127.0.0.1:5201 npm start -w packages/mcp-server
+```
+
+Start `mcp-remote` with a matching `BASE_URL`:
+
+```bash
+cd packages/mcp-remote
+PORT=5201 BASE_URL=http://127.0.0.1:5201 npm start
+```
+
+`BASE_URL` controls where `mcp-remote` sends the browser after login, for example `http://127.0.0.1:5201/consent?...`. `SCOREHUB_REMOTE_MCP_URL` controls which remote endpoint this proxy uses for `/authorize`, `/token`, and `/mcp`. In production, `https://app.scorehub.cn/mcp` maps to externally visible `/mcp/authorize`, `/mcp/token`, and `/mcp/mcp` paths.
+
+OAuth tokens are isolated by endpoint under `~/.scorehub/<endpoint>/oauth.json`, so local tokens for `127.0.0.1:5201` do not overwrite production tokens for `app.scorehub.cn/mcp`.
+
 ## Architecture
 
 ```
@@ -189,13 +208,13 @@ If you're running on a server or in a headless environment where a browser canno
 │  │  client)     │            │  • Tool forwarding  │             │
 │  └──────────────┘            └─────────┬───────────┘             │
 │                                        │                         │
-│                              ~/.scorehub/<host>/oauth.json        │
+│                              ~/.scorehub/<endpoint>/oauth.json    │
 └────────────────────────────────────────┼──────────────────────────┘
                                          │ Streamable HTTP
                                          ▼
                               ┌─────────────────────┐
                               │ ScoreHub Remote MCP │
-                              │ (mcp.scorehub.cn)   │
+                              │ (app.scorehub.cn/mcp)│
                               └─────────┬───────────┘
                                         │
                                         ▼
@@ -227,7 +246,7 @@ Yes, absolutely. `@scorehub/mcp-server` is a standalone MCP server. Any MCP-comp
 Delete the token file:
 
 ```bash
-rm ~/.scorehub/mcp.scorehub.cn/oauth.json
+rm ~/.scorehub/app.scorehub.cn_mcp/oauth.json
 ```
 
 Or delete the entire directory to clear all hosts:
@@ -238,7 +257,7 @@ rm -rf ~/.scorehub/
 
 ### How do I switch between staging and production?
 
-Set different `SCOREHUB_REMOTE_MCP_URL` values in separate MCP client configurations. Tokens are isolated per host, so staging and production credentials won't interfere with each other.
+Set different `SCOREHUB_REMOTE_MCP_URL` values in separate MCP client configurations. Tokens are isolated per endpoint, so staging and production credentials won't interfere with each other.
 
 ### What happens if the remote MCP is unreachable?
 

package/dist/index.js

@@ -16,18 +16,33 @@ const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const index_js_2 = require("@modelcontextprotocol/sdk/client/index.js");
 const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
-const SCOREHUB_BASE_URL = process.env.SCOREHUB_REMOTE_MCP_URL || "https://mcp.scorehub.cn";
+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
-const TOKEN_ENDPOINT = `${SCOREHUB_BASE_URL}/token`;
-const AUTHORIZE_URL = `${SCOREHUB_BASE_URL}/authorize`;
+const TOKEN_ENDPOINT = joinUrl(SCOREHUB_BASE_URL, "/token");
+const AUTHORIZE_URL = joinUrl(SCOREHUB_BASE_URL, "/authorize");
 // MCP Streamable HTTP transport endpoints are at /mcp
-const REMOTE_MCP_URL = `${SCOREHUB_BASE_URL}/mcp`;
+const REMOTE_MCP_URL = joinUrl(SCOREHUB_BASE_URL, "/mcp");
+function normalizeBaseUrl(value) {
+    return value.replace(/\/+$/, "");
+}
+function joinUrl(baseUrl, path) {
+    return `${baseUrl}/${path.replace(/^\/+/, "")}`;
+}
+function endpointTokenKey(baseUrl) {
+    const url = new URL(baseUrl);
+    const path = url.pathname.replace(/^\/+|\/+$/g, "");
+    const endpoint = path ? `${url.host}/${path}` : url.host;
+    return endpoint.replace(/[^A-Za-z0-9.-]+/g, "_");
+}
 // ── 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 HOST = new URL(REMOTE_MCP_URL).host;
+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;
 // ── Remote Tool Proxy (MCP Streamable HTTP) ─────────────────
 async function fetchRemoteTools(token) {
     try {
@@ -79,7 +94,7 @@ const server = new index_js_1.Server({ name: "scorehub-mcp", version: "0.1.0" },
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
     // Refresh remote tools on each list
     try {
-        const tokenResult = await (0, auth_js_1.getValidAccessToken)(HOST, TOKEN_ENDPOINT, CLIENT_ID);
+        const tokenResult = await (0, auth_js_1.getValidAccessToken)(TOKEN_STORE_KEY, TOKEN_ENDPOINT, CLIENT_ID);
         const freshTools = await fetchRemoteTools(tokenResult?.access_token);
         if (freshTools.length > 0 || remoteTools.length === 0) {
             remoteTools = freshTools;
@@ -122,7 +137,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
     switch (name) {
         case "authorize": {
             // Always force fresh OAuth flow when user explicitly authorizes
-            (0, auth_js_1.clearTokens)(HOST);
+            (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;
@@ -148,8 +163,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                             "<p>You may close this window and return to the terminal.</p>" +
                             "</body></html>");
                         callbackServer.close();
-                        const baseUrl = new URL(REMOTE_MCP_URL).origin;
-                        fetch(`${baseUrl}/token`, {
+                        fetch(TOKEN_ENDPOINT, {
                             method: "POST",
                             headers: { "Content-Type": "application/json" },
                             body: JSON.stringify({ grant_type: "authorization_code", code }),
@@ -162,7 +176,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                                 });
                                 return;
                             }
-                            (0, auth_js_1.saveTokens)(HOST, {
+                            (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,
@@ -217,13 +231,14 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             });
         }
         case "status": {
-            const tokenResult = await (0, auth_js_1.getValidAccessToken)(HOST, TOKEN_ENDPOINT, CLIENT_ID);
+            const tokenResult = await (0, auth_js_1.getValidAccessToken)(TOKEN_STORE_KEY, TOKEN_ENDPOINT, CLIENT_ID);
             return {
                 content: [
                     {
                         type: "text",
                         text: JSON.stringify({
                             remote_url: REMOTE_MCP_URL,
+                            token_store_key: TOKEN_STORE_KEY,
                             authorized: !!tokenResult,
                             tools_count: remoteTools.length,
                             ...(lastFetchError ? { error: lastFetchError } : {}),
@@ -234,7 +249,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
         }
         default: {
             // Check authorization for remote tools — re-validates on every call
-            const tokenResult = await (0, auth_js_1.getValidAccessToken)(HOST, TOKEN_ENDPOINT, CLIENT_ID);
+            const tokenResult = await (0, auth_js_1.getValidAccessToken)(TOKEN_STORE_KEY, TOKEN_ENDPOINT, CLIENT_ID);
             if (!tokenResult) {
                 const authUrl = generateAuthUrl();
                 return {
@@ -258,6 +273,24 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
         }
     }
 });
+// ── Token Keep-Alive ────────────────────────────────────────
+// Proactively refresh the access token on a fixed interval so long-running
+// sessions never hit an expiry mid-call. Uses timer.unref() so the keep-alive
+// loop does not prevent the process from exiting normally.
+function startTokenKeepAlive() {
+    const timer = setInterval(async () => {
+        try {
+            const result = await (0, auth_js_1.getValidAccessToken)(TOKEN_STORE_KEY, TOKEN_ENDPOINT, CLIENT_ID);
+            if (result?.source === "refresh") {
+                console.error("[keep-alive] access token refreshed proactively");
+            }
+        }
+        catch {
+            // Non-fatal: will retry on next interval
+        }
+    }, TOKEN_KEEPALIVE_INTERVAL);
+    timer.unref(); // Don't block process exit when no other work remains
+}
 // ── Start ───────────────────────────────────────────────────
 async function main() {
     // Set process title for easy identification in ps/task manager
@@ -271,7 +304,7 @@ async function main() {
         process.exit(0);
     });
     try {
-        const tokenResult = await (0, auth_js_1.getValidAccessToken)(HOST, TOKEN_ENDPOINT, CLIENT_ID);
+        const tokenResult = await (0, auth_js_1.getValidAccessToken)(TOKEN_STORE_KEY, TOKEN_ENDPOINT, CLIENT_ID);
         remoteTools = await fetchRemoteTools(tokenResult?.access_token);
         if (remoteTools.length === 0 && lastFetchError) {
             console.error(`Warning: Could not fetch remote tools on startup: ${lastFetchError}. Retrying on first ListTools request.`);
@@ -283,6 +316,7 @@ async function main() {
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
     console.error(`ScoreHub MCP Server started (remote: ${REMOTE_MCP_URL})`);
+    startTokenKeepAlive();
 }
 main().catch((err) => {
     console.error("Fatal:", err);

package/package.json

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