mcp-suite

一个生产级的 TypeScript MCP 服务器，为 AI 代理（Claude Desktop、Cursor、Windsurf、自定义代理）提供跨四个领域的结构化真实世界数据访问：金融市场、Web3/DeFi、开发者工具和医疗保健 (FHIR)。

身份验证优先 — 默认启用 JWT 验证
域隔离 — 缺少 API 密钥只会禁用单个域，而不会影响整个服务器
响应缓存 (LRU + TTL) 和每个域的令牌桶速率限制
每个工具输入和输出均采用类型化模式 (Zod)
两种传输方式：stdio（本地）和 HTTP + SSE（远程/托管）

快速入门

# Run directly (no global install required)
npx mcp-suite

# Or install globally
npm install -g mcp-suite
mcp-suite

要求： Node.js ≥ 20, npm ≥ 10

安装

1. 设置环境变量

将 .env.example 复制为 .env 并填入您想要启用的域的密钥：

cp .env.example .env

# Authentication (required in production)
MCP_JWT_SECRET=your-secret-here

# Financial Markets (Alpha Vantage + CoinGecko)
ALPHA_VANTAGE_API_KEY=

# Web3 / DeFi (Alchemy + OpenSea + Blur)
ALCHEMY_API_KEY=
OPENSEA_API_KEY=

# Developer Tools (GitHub)
GITHUB_TOKEN=

# Healthcare / FHIR (optional — defaults to public HAPI sandbox)
FHIR_BASE_URL=https://hapi.fhir.org/baseR4

# Server
LOG_LEVEL=info         # debug | info | warn | error
MCP_PORT=3000          # HTTP transport only
AUTH_DISABLED=false    # set true for local dev only

您只需要为您使用的域提供密钥。缺少密钥的域在启动时会被静默禁用。

2. 生成开发令牌

npx mcp-suite gen-token
# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

3. 添加到 Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)：

{
  "mcpServers": {
    "mcp-suite": {
      "command": "npx",
      "args": ["mcp-suite"],
      "env": {
        "MCP_JWT_SECRET": "your-secret-here",
        "ALPHA_VANTAGE_API_KEY": "...",
        "ALCHEMY_API_KEY": "...",
        "OPENSEA_API_KEY": "...",
        "GITHUB_TOKEN": "..."
      }
    }
  }
}

4. 作为 HTTP 服务器启动（远程/托管部署）

npx mcp-suite --transport http --port 3000

这将暴露 GET /health、GET /tools 以及用于远程 MCP 客户端的 SSE 端点。

CLI 命令

命令	描述
`npx mcp-suite`	启动服务器（stdio 传输，默认）
`npx mcp-suite --transport http`	启动 HTTP + SSE 服务器
`npx mcp-suite gen-token`	生成开发用 JWT
`npx mcp-suite list-tools`	打印所有按域分组的活动工具

可用工具

金融市场

由 Alpha Vantage 和 CoinGecko 提供支持。需要：ALPHA_VANTAGE_API_KEY

工具	描述
`get_stock_quote`	美股价格、成交量、涨跌幅 %
`get_forex_rate`	货币对汇率 (ISO 4217)
`get_crypto_price`	加密货币价格、市值、24小时涨跌幅
`get_market_news`	带有情绪评分的金融头条新闻

示例：

{ "tool": "get_stock_quote", "arguments": { "ticker": "NVDA" } }

Web3 / DeFi

由 Alchemy、OpenSea 和 Blur 提供支持。需要：ALCHEMY_API_KEY, OPENSEA_API_KEY

工具	描述
`get_nft_floor`	OpenSea + Blur 上的最佳地板价 (ETH, Base, Arbitrum)
`get_nft_recent_sales`	最近 N 笔带有特征和市场信息的销售记录
`get_wallet_balances`	多链代币 + NFT 持仓，ENS 解析
`get_amm_reserves`	Uniswap V2/V3 池储备和价格比率
`get_dex_liquidity`	每笔交易的滑点估算

示例：

{ "tool": "get_nft_floor", "arguments": { "collection_slug": "boredapeyachtclub" } }

开发者工具

由 GitHub API 提供支持。需要：GITHUB_TOKEN

工具	描述
`get_repo_stats`	星标、分支、问题、语言、最后一次提交
`summarize_pr`	PR 差异摘要、审查者、CI 检查、合并状态
`get_pipeline_status`	每个分支的最新 GitHub Actions 运行情况
`get_deployment_health`	活动部署 URL 和状态

示例：

{ "tool": "get_pipeline_status", "arguments": { "repo": "vercel/next.js", "branch": "canary" } }

医疗保健 (FHIR)

由 HAPI FHIR R4 提供支持。需要：无（默认为公共沙箱）或自定义端点的 FHIR_BASE_URL。

HIPAA 注意事项： 所有医疗保健工具仅连接到仅包含合成数据的公共沙箱。不会访问任何真实的患者健康信息 (PHI)。对于生产环境，请将 FHIR_BASE_URL 替换为符合 HIPAA 标准的 EHR 端点，并配置适当的 SMART on FHIR OAuth 2.0 凭据。

工具	描述
`lookup_patient`	人口统计学患者搜索
`get_observations`	按患者查询生命体征和实验室结果
`get_medications`	按患者查询活动药物列表

示例：

{ "tool": "lookup_patient", "arguments": { "name": "Smith", "birth_date": "1980-01-15" } }

身份验证

身份验证默认启用。每次工具调用都必须携带有效的 JWT。

生产环境

将 MCP_JWT_SECRET 设置为一个强密钥。在生产模式下，如果没有该密钥，服务器将拒绝启动。

开发环境

选项 A — 完全禁用身份验证（仅限本地）：

AUTH_DISABLED=true

选项 B — 使用开发 JWT：

npx mcp-suite gen-token

在 MCP 请求的 _meta 字段（stdio）或 Authorization: Bearer 标头（HTTP）中传递生成的令牌。

JWT 结构

{
  "sub": "your-client-id",
  "scope": "mcp:tools",
  "iat": 1713484800,
  "exp": 1716076800
}

架构

MCP Clients (Claude Desktop · Cursor · Windsurf · Custom Agents)
        │  MCP Protocol
┌───────▼────────────────────────────────────────┐
│  Transport Layer  (stdio  |  HTTP + SSE)        │
├────────────────────────────────────────────────┤
│  Auth Middleware  (JWT validation / bypass)     │
├────────────────────────────────────────────────┤
│  Tool Registry    (register · list · route)     │
├──────────┬──────────┬──────────┬───────────────┤
│Financial │  Web3    │ DevTools │  Healthcare   │
├──────────┴──────────┴──────────┴───────────────┤
│  Shared: Rate Limiter · Cache · Logger · Errors │
└─────────────────────────────────────────────────┘
         │           │          │          │
   Alpha Vantage  Alchemy   GitHub API  HAPI FHIR
   CoinGecko      OpenSea
                  Blur

缓存： 进程内 LRU + TTL 缓存 (node-cache)。TTL 根据域进行调整（加密货币为 15 秒，GitHub 仓库统计为 300 秒）。
速率限制： 每个域的令牌桶保护免费层 API 配额。
错误类型： AuthError、ValidationError、DomainUnavailableError、UpstreamError、RateLimitError — 全部生成结构化的 MCP 错误响应。
日志记录： 每次工具调用均记录结构化 JSON：域、工具名称、延迟、缓存命中、状态。

添加域

每个域遵循相同的模式。要添加新域：

在 src/domains/[name]/ 中创建 index.ts、schemas.ts、client.ts 和 tools/
导出一个 Domain 对象：

export const myDomain: Domain = {
  name: 'my-domain',
  isAvailable: () => !!config.MY_API_KEY,
  registerTools: (server) => { /* server.tool(...) calls */ }
}

在 src/server.ts 中注册它
在 docs/API.md 中记录工具

请参阅 docs/TDD.md §5 和 docs/CODING_STANDARDS.md 以获取完整模式。

开发

git clone https://github.com/ayenisholah/mcp-suite.git
cd mcp-suite
npm install
cp .env.example .env   # fill in your API keys

npm run build          # compile TypeScript → dist/
npm run dev            # watch mode
npm run typecheck      # type check without emit
npm run lint           # ESLint
npm test               # unit tests (Vitest)
npm run test:coverage  # tests + coverage report

# Integration tests — hits real APIs, requires .env keys
RUN_INTEGRATION=true npm test

HTTP 传输端点

当使用 --transport http 运行时：

端点	身份验证	描述
`GET /health`	否	每个域的可用性状态
`GET /tools`	是	所有已注册的工具，按域分组
`POST /mcp`	是	MCP 协议端点 (SSE)

错误参考

代码	描述
`AUTH_ERROR`	JWT 缺失、过期或签名无效
`VALIDATION_ERROR`	输入未通过 Zod 模式验证
`DOMAIN_UNAVAILABLE`	启动时未配置域 API 密钥
`RATE_LIMITED`	超出每个域的速率限制
`UPSTREAM_ERROR`	外部 API 返回错误或超时

许可证

MIT — 请参阅 LICENSE

贡献

欢迎提交问题和 PR。提交前请阅读 docs/CODING_STANDARDS.md。

mcp-suite

mcp-suite

快速入门

安装

1. 设置环境变量

2. 生成开发令牌

3. 添加到 Claude Desktop

4. 作为 HTTP 服务器启动（远程/托管部署）

CLI 命令

可用工具

金融市场

Web3 / DeFi

开发者工具

医疗保健 (FHIR)

身份验证

生产环境

开发环境

JWT 结构

架构

添加域

开发

HTTP 传输端点

错误参考

许可证

贡献

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API