AI导哈

HTTP MCP服务器

一个生产就绪的HTTP MCP服务器，实现模型上下文协议，并与SAM.gov Opportunities API集成，提供12小时内存缓存。

  • by vitaminR
  • Go
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 vitaminR/Sam-Gov-MCP

使用说明

SAM.gov MCP 服务器（Go 语言）

概述

  • 已准备好投入生产的HTTP MCP服务器，实现模型上下文协议
  • 与SAM.gov机遇API集成，采用12小时内存缓存
  • 端点：/health（健康检查）、/mcp/tools（工具）、/mcp/call（调用）、/mcp/scheduled（计划任务）
  • 在/mcp/*上使用承载令牌认证；为/mcp/scheduled单独设置计划令牌
  • Docker 容器、GitHub Actions 持续集成（CI）和每日两次的调度器

建筑学

  • cmd/sam-mcp-http：主入口点，读取环境变量，连接服务器和TLS
  • 内部/服务器：
    • server.go: 路由、认证中间件、处理程序（工具、调用、计划任务）
    • types.go: MCP的Tool和CallRequest结构体
    • cache.go: 简单的线程安全TTL缓存
    • sam.go：用于SAM.gov机会搜索的最小化HTTP客户端
  • 内部/SAM：服务器处理程序使用的更丰富的SAM.gov客户端

安全

  • MCP_TOKEN 保护 /mcp/tools 和 /mcp/call
  • SCHEDULE_TOKEN 用于保护 /mcp/scheduled（也可能接受 MCP_TOKEN）
  • 建议所有部署使用TLS；挂载证书组合

环境变量

  • 端口：服务器端口（默认3000）
  • MCP_TOKEN：用于MCP端点的承载令牌
  • 计划令牌：用于计划端点的承载令牌
  • SAM_API_KEY: SAM.gov的API密钥（可选；如果未设置，则返回模拟数据）
  • PREFETCH_Q: 预定预取的默认查询（例如，“软件”）
  • PREFETCH_NAICS：CSV格式的NAICS代码（例如，541511,541512,541519）
  • PREFETCH_DAYS：向前追溯的整数天数以进行搜索（例如，7天）
  • PREFETCH_LIMIT：整数页面大小（例如，25）
  • PREFETCH_NOTICE_TYPE：可选的通知类型过滤器
  • PREFETCH_ORG：可选的组织过滤器
  • TLS_CERT_FILE：服务器证书（PEM）的路径
  • TLS_KEY_FILE：服务器密钥（PEM）的路径

本地运行（Go 语言）

  1. 复制 .env.local 文件并编辑其中的值（至少包括 MCP_TOKEN 和 SCHEDULE_TOKEN）
  2. 选项A：HTTP（仅限开发）
  • 运行 ./cmd/sam-mcp-http 命令
  1. 选项B：HTTPS（推荐）
  • 生成证书到 ./certs 目录（参见下面的 TLS 部分），并设置 TLS_CERT_FILE/TLS_KEY_FILE
  • 运行 ./cmd/sam-mcp-http 命令

Docker

  • docker compose up --build 翻译为中文是：“使用 Docker Compose 启动并构建（镜像）”
  • 编写 `.env.local` 文件，挂载 `./certs` 目录，并将环境变量传递给容器

TLS（本地自签名） 在 ./certs 目录中生成开发证书：

  • 证书/server.crt
  • 证书/server.key 然后设置：
  • TLS证书文件路径=./certs/server.crt
  • TLS_KEY_FILE=./certs/server.key 翻译为中文是：“TLS 密钥文件路径为 ./certs/server.key”

HTTP 端点

  • GET /health 翻译为中文是：“获取/健康（状态）”
    • 200 {"状态":"正常"}
  • GET /mcp/tools（认证：Authorization: Bearer <MCP_TOKEN>）
    • 列出可用工具和输入模式
  • POST /mcp/call (认证)
    • 主体：{"name":"sam_search","arguments":{...}}（注：这里的“...”表示省略了具体的参数内容，在实际翻译中应根据具体的参数填充完整。）
    • 将请求路由到工具处理程序
  • POST /mcp/scheduled（认证：Bearer <计划任务令牌> 或 MCP_TOKEN）
    • 使用 PREFETCH_* 默认值触发缓存预热

工具：sam_search 输入参数（除非另有说明，所有参数均为可选）：

  • q: 字符串（搜索文本）
  • NAICS（北美行业分类系统）: 字符串数组
  • 天数：整数（默认模式下为必填项）
  • 限制：整数（1..100）
  • noticeType: 字符串
  • 组织：字符串

Curl 示例 列出工具： `curl -H "Authorization: Bearer $MCP_TOKEN" https://` 翻译成中文是：“使用 curl 命令，添加头部信息 'Authorization: Bearer $MCP_TOKEN'，访问 https://...”。不过，由于原句是一个命令的开头部分，且没有给出完整的 URL，所以中文翻译也保留了这种不完整性，实际使用时需要根据具体的 URL 来补全/mcp/tools 翻译为中文是：“/mcp/工具” 或者更自然的表达可能是 “/mcp 工具目录”（如果这是指一个文件夹或目录名的话）。不过，具体翻译可能还需根据上下文来确定最准确的表述

调用工具： `curl -H "Authorization: Bearer $MCP_TOKEN"` 翻译成中文是：使用带有“Bearer $MCP_TOKEN”授权头的curl命令
-H "Content-Type: application/json" 翻译为中文是：“-H '内容类型: 应用程序/JSON'” 或更自然的表达为：“-H '设置内容类型为：application/json'”。其中，“-H”通常用于命令行中指定请求头（如在使用curl等工具时），表示后面跟着的是要设置的请求头信息
-d '{"name":"sam_search","arguments":{"q":"software","days":7,"limit":25}}' 翻译成中文是：“以数据格式传递一个包含名称和参数的JSON对象，其中名称为'sam_search'，参数包括查询词'q'为'software'，天数'days'为7，限制'limit'为25”
https:///mcp/call 翻译成中文是：“/mcp/呼叫” 或者根据上下文，也可以翻译为“/mcp/联系”、“/mcp/通话”等，具体取决于“call”在该语境中的具体含义。但最直接的翻译是“/mcp/呼叫”

触发计划预取： `curl -H "Authorization: Bearer $SCHEDULE_TOKEN" https://` 翻译成中文为：“使用curl命令，添加头部信息'Authorization: Bearer $SCHEDULE_TOKEN'，然后访问https://（网址需后续补充）”/mcp/scheduled 翻译成中文是：“/mcp/计划/安排” 或者 “/mcp/预定/调度”。具体翻译可能根据上下文有所调整，但基本意思是与“计划”或“预定/调度”相关的/mcp路径或功能

GitHub Actions 调度器

  • .github/workflows/scheduled.yml 在 UTC 时间 06:00 和 18:00 运行
  • 在部署后设置这些仓库密钥：
    • MCP_SCHEDULE_URL：用于POST的完整URL（例如，https:///mcp/scheduled）
    • 计划令牌：用于计划身份验证的承载令牌
  • 这一步是有条件的，只有在两个密钥都设置好时才会执行

CI（企业识别系统/企业形象标识）

  • 在推送/拉取请求（Push/PR）时，持续集成（CI）工作流会构建并审查代码
  • Trivy、revive 和 Semgrep 是通过 Codacy MCP 工具集来使用的

开发快速入门（无TLS，用于隧道连接）

  • 通过HTTPS隧道进行快速Agent Builder测试：
    • Linux/WSL：运行 ./run_dev.sh 脚本
    • Windows：运行 run_dev.bat 脚本
    • 这会设置 ALLOW_INSECURE_HTTP=1 并启动 http://localhost:3000
    • 然后通过您的HTTPS隧道/代理暴露到https:///mcp 翻译成中文是“/mcp”（注：由于“/mcp”本身是一个特定的指令或代码，在中文中没有直接的翻译，因此保持原样）。不过，如果“/mcp”是某个特定上下文中的指令或代码，可能需要根据具体语境进行翻译或解释。但在此通用语境下，直接翻译为“/mcp”是合适的

测试

  • 运行测试。/。。。

与OpenAI Agent Builder（MCP）一起使用 你可以在OpenAI Agent Builder中将此服务器连接为MCP工具。

先决条件

  • 已部署可通过OpenAI访问的HTTPS终端节点
  • 已配置 MCP_TOKEN

步骤

  1. 打开Agent Builder用户界面（platform.openai.com/agents）并创建/编辑您的代理
  2. 前往“工具”>“添加工具”>“模型上下文协议 (MCP)”
  3. 输入：
  • 基础URL: https:///mcp 翻译成中文是“/mcp”（注：由于“/mcp”本身可能是一个特定语境或命令下的代码或缩写，没有直接的中文翻译，所以保持原样）。如果“/mcp”在特定上下文中有特定含义，需要根据具体语境进行翻译或解释
  • 认证：HTTP头部
  • 头部名称：授权
  • 头部值：Bearer ${MCP_TOKEN}
  1. 保存工具并进行测试：
  • 询问代理：“在SAM.gov上搜索过去7天内的软件采购机会”
  • 代理将使用您的参数调用 sam_search

故障排除

  • 401 未授权：请验证授权头和令牌值
  • 空结果：如果希望获取实时数据，请确保已设置SAM_API_KEY；否则将返回模拟结果
  • 调度器未触发：请确认密钥 MCP_SCHEDULE_URL 和 SCHEDULE_TOKEN 已设置，且 URL 可访问
  • TLS问题：验证证书/密钥路径，并确保证书与主机名匹配

相关 MCP