creator-analysis-mcp（Remote MCP Server）

將 Creator Recommendation API 以 remote MCP（Streamable HTTP）形式提供給 Claude 用戶。API key 只存在伺服器端，用戶只需一條 URL + bearer token。

部署到 Railway

1. 將本 repo push 到 GitHub（或用 railway up 直接部署）
2. Railway → New Project → Deploy from GitHub repo（Nixpacks 自動偵測 Node）
3. 在 Variables 設定：
   • CREATOR_API_BASE — 後端 API base URL
   • CREATOR_API_KEY — 後端 API key（絕不會傳給客戶端）
   • MCP_ACCESS_TOKENS — 客戶端 token，逗號分隔，每位用戶一條（留空 = 無驗證，不建議）
4. Settings → Networking → Generate Domain（或綁自訂域名，如 mcp.goodmalling.io）
5. Healthcheck：/healthz

Endpoint：https://<your-domain>/mcp

用戶連接方式

Claude Code

claude mcp add --transport http creator-analysis https://<your-domain>/mcp \
  --header "Authorization: Bearer <token>"

Claude Desktop / claude.ai / Cowork（自訂連接器，OAuth） Settings → Connectors → Add custom connector → 貼上 https://<your-domain>/mcp → 按 Connect。 瀏覽器會彈出授權頁，輸入你獲發的 access token（MCP_ACCESS_TOKENS 其中一條）即完成。 OAuth session 有效 30 日；從 MCP_ACCESS_TOKENS 移除該 token 並 redeploy 即同時撤銷其所有 OAuth session。

提供的工具

creator_research、creator_tagged_media、creator_contact、creator_suggest、similar_brands

技術說明

• Stateless Streamable HTTP：每個請求獨立建立 server+transport，可水平擴展，無需 session store／Redis
• 雙重驗證：Bearer token（MCP_ACCESS_TOKENS，支援 header 的客戶端）＋ OAuth 2.0 authorization code + PKCE（claude.ai／Desktop 連接器）；OAuth token 以 HMAC 簽名（OAUTH_SIGNING_SECRET）並綁定原 token 的 hash，撤銷原 token 即連帶失效
• Fail-closed：MCP_ACCESS_TOKENS 為空時拒絕所有請求（除非明確設 ALLOW_OPEN=1）
• Per-token rate limit：預設 30 req/min（RATE_LIMIT_PER_MIN），超過回 429
• 上游錯誤會以 isError tool result 回傳，不會洩漏 key
• 本地開發：cp .env.example .env 填好後 npm install && npm start，endpoint 在 http://localhost:8080/mcp

建議後續

• 在 Railway 對此服務設 usage alert；上游 embedding 服務建議加 keep-warm 避免 502 冷啟動
• 若要按用戶計量／計費，可在 authorized() 內按 token 記錄用量