Commongrants MCP

CommonGrants MCP 服务器

用于逐步发现和验证CommonGrants API的模型上下文协议服务器。该服务器基于Cloudflare Workers构建，使用TypeScript和Zod进行验证。

特点

13个MCP工具 涵盖4个类别：

• 发现 (2): 列出API版本，获取版本元数据
• 探索 (5)：总结API，浏览端点，搜索操作，查看模式
• 验证 (4): 验证有效载荷，生成示例，获取验证规则（基于Zod）
• 公共事业（或公用设施） (2): 检查健康状态，比较版本

支持的API版本

• v0.3.0 （最新版）- 最新版本，端点已扩展
• v0.2.0 （stable）- 稳定版

建筑

┌─────────────────────────────────────────┐
│  13 MCP Tools (4 categories)            │
├─────────────────────────────────────────┤
│  • Cache (LRU, 1hr TTL)                 │
│  • API Client (CommonGrants)            │
│  • OpenAPI Parser (@scalar, YAML)       │
│  • Validator (Zod)                      │
├─────────────────────────────────────────┤
│  Cloudflare Workers Runtime             │
└─────────────────────────────────────────┘

工具

发现 (2)

• list_commongrants_apis 列出所有API版本
• get_api_version_info - 获取版本元数据

探索 (5)

• get_api_summary API概述
• list_api_endpoints - 列出带有过滤器的端点
• get_endpoint_details - 终端点规范
• get_api_schemas - 数据模型模式
• search_api_operations - 搜索行动

验证 (4)

• validate_request_payload - 验证请求
• validate_response_payload - 验证响应
• generate_example_payload - 生成示例
• get_validation_rules - 验证规则

公用事业 (2)

• check_api_health - 健康检查
• compare_api_versions - 版本对比

快速入门

# Install
npm install

# Start server
npm run dev

# Run tests
npm run test:all

# Deploy
npm run deploy

服务器运行于 http://localhost:8788/sse

测试

单元测试

npm run test:unit

集成测试

npm run dev              # Terminal 1
npm run test:integration # Terminal 2

所有测试

npm run test:all

MCP 检测器

npx @modelcontextprotocol/inspector@latest
# Open http://localhost:5173
# Connect to http://localhost:8788/sse

Claude 桌面配置

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "commongrants": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8788/sse"]
    }
  }
}

对于生产，使用 https://commongrants-mcp..workers.dev/sse

栈

• 运行时Cloudflare Workers（云防护网络工作者）
• 语言TypeScript 5.9
• MCP@modelcontextprotocol/sdk 1.19
• 验证Zod 3.25
• 解析器@scalar/openapi-parser 0.22（支持YAML）
• YAML（YAML Ain't Markup Language，即“YAML不是一种标记语言”）js-yaml 4.1
• 测试Vitest 3.2

缓存

• 具有1小时TTL（最多50个项目）的LRU缓存
• 自动清理过期条目

数据来源

• CommonGrants v0.3.0： https://commongrants.org/openapi/openapi.0.3.0.yaml
• CommonGrants v0.2.0： https://commongrants.org/openapi/openapi.0.2.0.yaml

项目结构

src/
├── index.ts              # MCP server
├── config/               # CommonGrants API configuration
├── services/             # Cache, API client, parser, validator (Zod)
├── tools/                # 13 MCP tools (4 files)
└── utils/                # Error formatting, example generation
test/
├── unit/                 # Unit tests (Workers pool)
└── integration/          # Integration tests (Node.js + HTTP)

资源

• CommonGrants 协议
• 通用授权API文档
• 模型上下文协议
• Cloudflare Workers（可译为“Cloudflare 工作线程”或“Cloudflare 无服务器函数”）

许可证

麻省理工学院（MIT）