Congress.gov API MCP 服务器

这是一个模型上下文协议 (MCP) 服务器，旨在通过混合方法提供对官方 Congress.gov API (v3) 的访问：

• MCP 资源： 用于使用标准化 URI 直接查找核心立法实体（法案、议员、国会、委员会、一般信息）。
• MCP 工具： 用于更复杂的操作，例如跨集合搜索 (congress_search) 和检索相关数据列表 (congress_getSubResource)。

该服务器充当桥梁，允许 MCP 客户端（如 AI 助手或开发工具）轻松查询和利用美国立法数据。

项目结构

• /src: 包含所有源代码。
  • /config: 配置管理 (ConfigurationManager.ts)。
  • /services: 与 Congress.gov API 交互的核心逻辑 (CongressApiService.ts, RateLimitService.ts)。
  • /tools: MCP 工具定义 (search/, subresource/, index.ts)。
  • /types: TypeScript 接口和 Zod 模式。
  • /utils: 共享实用程序函数（日志记录、错误等）。
  • resourceHandlers.ts: 用于处理核心实体资源请求的逻辑。
  • createServer.ts: 服务器实例创建、资源和工具注册。
  • server.ts: 主应用程序入口点。
• /dist: 编译后的 JavaScript 输出（由 npm run build 生成）。
• /docs: 项目文档（PRD、功能规范、RFC）。
• package.json: 项目元数据和依赖项。
• tsconfig.json: TypeScript 编译器选项。
• .eslintrc.json, .prettierrc.json: Linting 和格式化规则。
• .env: (未提交) 用于存储 CONGRESS_GOV_API_KEY。

快速开始

1. 安装依赖项：

   npm install
   

2. 设置 API 密钥： 在项目根目录中创建一个 .env 文件，并添加您的 Congress.gov API 密钥：

   CONGRESS_GOV_API_KEY=YOUR_API_KEY_HERE
   

   (从 https://api.data.gov/signup/ 获取密钥)

3. 构建服务器：

   npm run build
   

4. 运行服务器：

   npm start
   

   (这将运行 node dist/server.js)

或者，使用 npm run dev 在开发模式下运行（使用 ts-node 和 nodemon）。

与 MCP 客户端一起使用

将您的 MCP 客户端连接到正在运行的服务器（例如，如果本地运行，则通过 stdio）。

访问资源

使用带有适当 URI 的 access_mcp_resource 命令/方法。

示例：

• 获取法案 H.R. 3076（第 117 届国会）：

  <access_mcp_resource>
  <server_name>congress-server</server_name>
  <uri>congress-gov://bill/117/hr/3076</uri>
  </access_mcp_resource>
  

• 获取议员佩洛西：

  <access_mcp_resource>
  <server_name>congress-server</server_name>
  <uri>congress-gov://member/P000197</uri>
  </access_mcp_resource>
  

• 获取关于第 118 届国会的信息：

  <access_mcp_resource>
  <server_name>congress-server</server_name>
  <uri>congress-gov://congress/118</uri>
  </access_mcp_resource>
  

• 获取 API 概述：

  <access_mcp_resource>
  <server_name>congress-server</server_name>
  <uri>congress-gov://info/overview</uri>
  </access_mcp_resource>
  

使用工具

使用 use_mcp_tool 命令/方法。

!!! 关键工具工作流程：查找实体并获取相关数据 !!!

许多常见任务需要使用两个工具的强制性两步流程：

1. 步骤 1：使用 congress_search 查找实体 ID

   • 目的： 找到您需要的特定法案、议员、委员会等，并提取其唯一标识符（例如，memberId，或法案 URI 的 congress、billType、billNumber）。

   • 工具： congress_search

   • 示例： 查找议员 "John Kennedy"（可能返回多个结果，需要选择）：

     <use_mcp_tool>
       <server_name>congress-server</server_name>
       <tool_name>congress_search</tool_name>
       <arguments>
         {
           "collection": "member",
           "query": "John Kennedy"
         }
       </arguments>
     </use_mcp_tool>
     

   • 输出： 在结果中查找 memberId（例如，K000393）或其他必要的标识符。

   • !!! 警告 !!! 搜索可能会返回多个结果。您必须识别正确的实体，并在下一步中使用其特定 ID。

   • !!! API 限制 !!! 底层 API 不支持使用 filters 参数按 congress 过滤常规搜索（例如，对于 /v3/bill 或 /v3/member），并且将被忽略。特定于国会的过滤通常需要使用特定的 API 路径（例如，/v3/bill/117），而此工具不构建这些路径。

2. 步骤 2：使用 congress_getSubResource 获取相关数据

   • 目的： 使用在步骤 1 中找到的标识符来构建 parentUri 并获取相关详细信息（行动、发起人、文本等）。

   • 工具： congress_getSubResource

   • 先决条件： 您必须拥有来自步骤 1 的正确 parentUri（例如，congress-gov://member/K000393）。

   • 示例： 获取议员 K000393 发起的立法：

     <use_mcp_tool>
       <server_name>congress-server</server_name>
       <tool_name>congress_getSubResource</tool_name>
       <arguments>
         {
           "parentUri": "congress-gov://member/K000393",
           "subResource": "sponsored-legislation",
           "limit": 5
         }
       </arguments>
     </use_mcp_tool>
     

   • !!! 保证错误警告 !!! 您必须使用对于 parentUri 类型严格有效的 subResource 字符串（例如，议员的 'sponsored-legislation'，法案的 'actions'）。提供无效的组合将导致错误。检查工具描述以获取有效的组合。

遵循此两步流程对于可靠地获取相关信息至关重要。

工具示例：

• 搜索包含 "climate" 的法案（限制为 5）：

  <use_mcp_tool>
  <server_name>congress-server</server_name>
  <tool_name>congress_search</tool_name>
  <arguments>
  {
    "collection": "bill",
    "query": "climate",
    "limit": 5
  }
  </arguments>
  </use_mcp_tool>
  

• 列出议员（此处无法进行国会过滤）：

  • 注意：如上所述，API 不支持在 congress_search 中直接按 congress 过滤 'member' 集合。

    <use_mcp_tool>
    <server_name>congress-server</server_name>
    <tool_name>congress_search</tool_name>
    <arguments>
    {
      "collection": "member",
      "limit": 10
      // 如果需要，添加 "query" 或其他过滤器，如 "type"
    }
    </arguments>
    </use_mcp_tool>
    

• 获取法案 H.R. 3076 (117th) 的行动（需要来自搜索或已知信息的 URI）：

  <use_mcp_tool>
  <server_name>congress-server</server_name>
  <tool_name>congress_getSubResource</tool_name>
  <arguments>
  {
    "parentUri": "congress-gov://bill/117/hr/3076",
    "subResource": "actions",
    "limit": 10
  }
  </arguments>
  </use_mcp_tool>
  

• 获取议员 P000197 发起的立法：

  <use_mcp_tool>
  <server_name>congress-server</server_name>
  <tool_name>congress_getSubResource</tool_name>
  <arguments>
  {
    "parentUri": "congress-gov://member/P000197",
    "subResource": "sponsored-legislation",
    "limit": 5
  }
  </arguments>
  </use_mcp_tool>
  

Linting 和格式化

• Lint: npm run lint
• Format: npm run format

代码将在提交时通过 Husky 和 lint-staged 自动进行 linting 和格式化。