@scorehub/mcp-server 0.1.5 → 0.2.0

package/README.md

@@ -0,0 +1,267 @@
+# @scorehub/mcp-server
+
+> Local MCP proxy for ScoreHub — handles OAuth login, token caching, and tool forwarding to the remote ScoreHub MCP endpoint.
+
+[![npm version](https://img.shields.io/npm/v/@scorehub/mcp-server)](https://www.npmjs.com/package/@scorehub/mcp-server)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![node: >=18](https://img.shields.io/badge/node-%3E%3D18-green.svg)](https://nodejs.org/)
+
+---
+
+## Overview
+
+`@scorehub/mcp-server` is a **local MCP (Model Context Protocol) proxy** that sits between your AI agent (Claude Code, Claude Desktop, WorkBuddy, etc.) and the ScoreHub remote MCP endpoint. It handles:
+
+- **OAuth authentication** — opens your browser for one-time ScoreHub login, then caches tokens locally
+- **Token lifecycle** — automatic refresh 5 minutes before expiry, no repeated logins
+- **Tool forwarding** — proxies TikTok Shop creator outreach tools to the remote API over Streamable HTTP
+
+```
+┌─────────────┐     stdio      ┌──────────────────┐   Streamable HTTP   ┌─────────────────┐
+│  AI Agent   │ ◄────────────► │  @scorehub/      │ ◄─────────────────► │  ScoreHub       │
+│  (Claude)   │                │  mcp-server      │                     │  Remote MCP     │
+└─────────────┘                └──────────────────┘                     └────────┬────────┘
+                                                                                 │
+                                                                          TikTok Shop
+                                                                          Partner API
+```
+
+## Installation
+
+**Prerequisites**: Node.js >= 18
+
+```bash
+npm install -g @scorehub/mcp-server
+```
+
+This installs the `scorehub-mcp` command globally. You can also skip global install and use `npx` directly in your MCP client configuration (see [Quick Start](#quick-start)).
+
+## Quick Start
+
+Add this to your MCP client configuration file:
+
+### Claude Code / Claude Desktop
+
+In `claude_desktop_config.json` or `.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "scorehub": {
+      "command": "npx",
+      "args": ["-y", "@scorehub/mcp-server"],
+      "env": {
+        "SCOREHUB_REMOTE_MCP_URL": "https://mcp.scorehub.cn"
+      }
+    }
+  }
+}
+```
+
+### WorkBuddy
+
+In `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "scorehub": {
+      "command": "npx",
+      "args": ["-y", "@scorehub/mcp-server"],
+      "env": {
+        "SCOREHUB_REMOTE_MCP_URL": "https://mcp.scorehub.cn"
+      }
+    }
+  }
+}
+```
+
+### What happens on first run
+
+1. The server starts and connects to the remote MCP endpoint
+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
+6. Subsequent calls use the cached token — no repeated login needed
+
+## Configuration
+
+### Environment variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `SCOREHUB_REMOTE_MCP_URL` | No | `https://mcp.scorehub.cn` | Base URL of the remote ScoreHub MCP endpoint |
+
+### Token storage
+
+OAuth tokens are stored at:
+
+```
+~/.scorehub/<host>/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.
+
+**Token file structure:**
+
+```json
+{
+  "access_token": "eyJ...",
+  "refresh_token": "eyJ...",
+  "expires_at": 1710000000000,
+  "updated_at": "2026-07-10T08:00:00.000Z"
+}
+```
+
+To log out or switch accounts, delete the `~/.scorehub/` directory or just the host-specific subdirectory.
+
+## Available Tools
+
+### Local tools
+
+These tools run locally on your machine — they do not call the remote endpoint.
+
+| Tool | Description |
+|---|---|
+| `authorize` | Opens your browser for ScoreHub OAuth login. Forces a fresh authorization flow every time. |
+| `status` | Returns connection status: remote URL, authorization state, and count of available tools. |
+
+### Remote tools
+
+These tools are **dynamically loaded** from the remote MCP endpoint at startup and forwarded on every call. The current set includes:
+
+| Tool | Description |
+|---|---|
+| `search_creators` | Search TikTok Shop creators by keywords, GMV range, sales volume, category, and other filters |
+| `creator_performance` | Analyze creator performance — 30-day GMV, follower demographics, content engagement data |
+| `get_categories` | Fetch available TikTok Shop product categories |
+| `create_conversation` | Create a collaboration conversation thread with a specific creator |
+| `send_message` | Send a collaboration message (text, product card, collaboration invite, sample request, or image) |
+
+> **Note**: The remote tool list is fetched at server startup and refreshed on each `ListTools` request. If new tools are added to the remote endpoint, they become available without updating the local package.
+
+## Authentication Flow
+
+```
+  Local mcp-server                    ScoreHub Remote
+         │                                  │
+         ├─ tools/call: authorize ──────────┤
+         │  (clears any existing token)     │
+         │                                  │
+         ├─ generates random state          │
+         ├─ opens browser → /authorize ────▶│
+         │              user logs in + grants access
+         │  ◀── redirect to localhost:19836 │
+         │       with authorization_code    │
+         │                                  │
+         ├─ POST /token ───────────────────▶│
+         │◀── access_token + refresh_token  │
+         │                                  │
+         ├─ saves to ~/.scorehub/<host>/oauth.json
+```
+
+### Token lifecycle
+
+| Stage | Behavior |
+|---|---|
+| **First use** | Browser OAuth → callback → write token to local file |
+| **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 |
+
+### 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.
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  YOUR MACHINE                                                    │
+│                                                                  │
+│  ┌──────────────┐   stdio    ┌─────────────────────┐             │
+│  │ Claude Code  │ ◄────────► │ @scorehub/mcp-server │             │
+│  │ WorkBuddy    │            │                     │             │
+│  │ Codex        │            │  • OAuth login      │             │
+│  │ (any MCP     │            │  • Token cache      │             │
+│  │  client)     │            │  • Tool forwarding  │             │
+│  └──────────────┘            └─────────┬───────────┘             │
+│                                        │                         │
+│                              ~/.scorehub/<host>/oauth.json        │
+└────────────────────────────────────────┼──────────────────────────┘
+                                         │ Streamable HTTP
+                                         ▼
+                              ┌─────────────────────┐
+                              │ ScoreHub Remote MCP │
+                              │ (mcp.scorehub.cn)   │
+                              └─────────┬───────────┘
+                                        │
+                                        ▼
+                              ┌─────────────────────┐
+                              │ TikTok Shop         │
+                              │ Partner API         │
+                              └─────────────────────┘
+```
+
+### Why a local proxy?
+
+- **Browser-based OAuth** — The OAuth flow requires opening a browser on your machine. A local server can launch your browser, whereas a remote server cannot.
+- **Token stays local** — Your access token never leaves your machine. The remote endpoint only sees it in the `Authorization` header of forwarded requests.
+- **Cross-platform** — Automatically uses `open` (macOS), `start` (Windows), or `xdg-open` (Linux) to launch the browser.
+- **Minimal dependencies** — Only depends on `@modelcontextprotocol/sdk` (~1 MB). No database, no framework, no configuration files.
+
+## FAQ
+
+### Why do I need this package?
+
+If you're using `@scorehub/creator-outreach` (the Tiky agent for TikTok creator outreach), this package is a **required prerequisite**. It provides the MCP tools the agent needs to search creators, analyze performance, and send messages.
+
+### Can I use this without @scorehub/creator-outreach?
+
+Yes, absolutely. `@scorehub/mcp-server` is a standalone MCP server. Any MCP-compatible client can use its tools directly.
+
+### How do I log out?
+
+Delete the token file:
+
+```bash
+rm ~/.scorehub/mcp.scorehub.cn/oauth.json
+```
+
+Or delete the entire directory to clear all hosts:
+
+```bash
+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.
+
+### What happens if the remote MCP is unreachable?
+
+- Local tools (`authorize`, `status`) continue to work
+- Remote tools return an error: `"Warning: Could not fetch remote tools"`
+- The server retries fetching the tool list on each `ListTools` request
+- Once the remote endpoint is reachable again, remote tools become available without restarting
+
+### How do I upgrade?
+
+```bash
+npm update -g @scorehub/mcp-server
+```
+
+Or, if you're using `npx -y`, it will always fetch the latest version automatically.
+
+## Related Packages
+
+| Package | Description |
+|---|---|
+| [`@scorehub/creator-outreach`](https://www.npmjs.com/package/@scorehub/creator-outreach) | Tiky agent — AI-powered TikTok Shop creator outreach (search, analyze, message) |
+| `scorehub-mcp-remote` | Remote MCP endpoint (private — deployed on ScoreHub servers) |
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.js

@@ -14,6 +14,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 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 REMOTE_MCP_URL = process.env.SCOREHUB_REMOTE_MCP_URL || "https://mcp.scorehub.cn";
 const TOKEN_ENDPOINT = `${REMOTE_MCP_URL}/token`;
 const AUTHORIZE_URL = `${REMOTE_MCP_URL}/authorize`;
@@ -25,43 +27,39 @@ const node_path_1 = require("node:path");
 const node_fs_1 = require("node:fs");
 const HOST = new URL(REMOTE_MCP_URL).host;
 const CLIENT_ID = "scorehub-mcp";
-// ── Remote Tool Proxy ───────────────────────────────────────
-async function fetchRemoteTools() {
+// ── Remote Tool Proxy (MCP Streamable HTTP) ─────────────────
+async function fetchRemoteTools(token) {
     try {
-        const resp = await fetch(REMOTE_MCP_URL.replace(/\/$/, "") + "/mcp/tools/list");
-        if (!resp.ok)
-            throw new Error(`Remote tools fetch failed: ${resp.status}`);
-        const data = await resp.json();
-        return data.tools || [];
+        const transport = new streamableHttp_js_1.StreamableHTTPClientTransport(new URL(REMOTE_MCP_URL), {
+            requestInit: token ? { headers: { Authorization: `Bearer ${token}` } } : undefined,
+        });
+        const client = new index_js_2.Client({ name: "scorehub-mcp", version: "0.2.0" }, { capabilities: {} });
+        try {
+            await client.connect(transport);
+            const result = await client.listTools();
+            return result.tools;
+        }
+        finally {
+            await client.close();
+        }
     }
     catch {
-        // Return offline message when remote is not available
         return [];
     }
 }
 async function callRemoteTool(name, args, token) {
-    // Map tool names to remote endpoints
-    const toolEndpoints = {
-        search_creators: "/mcp/tools/search-creators",
-        creator_performance: "/mcp/tools/creator-performance",
-        create_conversation: "/mcp/tools/create-conversation",
-        send_message: "/mcp/tools/send-message",
-        get_categories: "/mcp/tools/get-categories",
-    };
-    const endpoint = toolEndpoints[name];
-    if (!endpoint) {
-        return JSON.stringify({ error: `Unknown tool: ${name}` });
-    }
-    const resp = await fetch(`${REMOTE_MCP_URL}${endpoint}`, {
-        method: "POST",
-        headers: {
-            "Content-Type": "application/json",
-            ...(token ? { Authorization: `Bearer ${token}` } : {}),
-        },
-        body: JSON.stringify(args),
+    const transport = new streamableHttp_js_1.StreamableHTTPClientTransport(new URL(REMOTE_MCP_URL), {
+        requestInit: { headers: { Authorization: `Bearer ${token}` } },
     });
-    const data = await resp.json();
-    return JSON.stringify(data, null, 2);
+    const client = new index_js_2.Client({ name: "scorehub-mcp", version: "0.2.0" }, { capabilities: {} });
+    try {
+        await client.connect(transport);
+        const result = await client.callTool({ name, arguments: args });
+        return JSON.stringify(result.content, null, 2);
+    }
+    finally {
+        await client.close();
+    }
 }
 // ── OAuth authorize helper ──────────────────────────────────
 function generateAuthUrl() {

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "@scorehub/mcp-server",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "ScoreHub local MCP proxy — OAuth login, token caching, and tool forwarding to remote MCP endpoint",
   "main": "dist/index.js",
   "bin": {
     "scorehub-mcp": "./dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc && node -e \"const fs=require('fs');const f='dist/index.js';fs.writeFileSync(f,'#!/usr/bin/env node\\n'+fs.readFileSync(f,'utf8'));fs.chmodSync(f,0o755)\"",
     "dev": "tsx src/index.ts",