SuperAPI AI 工具集
合作ENAI 行业资讯收藏
全部工具AI开发平台gomcp

gomcp

GoMCP 是一个用于在 Go 语言中快速构建 MCP（Model Context Protocol，模型上下文协议）服务器的框架，定位类似“MCP 领域的 Gin”。它提供结构体标签自动生成 JSON Schema、类型化处理器、参数校验、组件版本管理、异步任务、中间件链（日志、恢复、限流、超时等）、认证与 RBAC 授权、工具分组，以及 Gin / OpenAPI / gRPC 三种适配器，可将已有 API 或服务方法一键导入为 MCP 工具。支持 stdio 与 Streamable HTTP（含 SSE）传输，内置 MCP Inspector 调试界面、YAML 热重载与 mcptest 测试包，可与 Claude Desktop、Cursor、VS Code Copilot 等 MCP 客户端配合使用。项目以 Apache 2.0 协议开源，个人与商业用途均可免费使用。

访问官网

工具介绍

用途

GoMCP 是一个用于构建 Model Context Protocol（MCP）服务器的 Go 框架，而不只是一个 SDK。MCP 是让 AI 应用（Claude Desktop、Cursor、Kiro、VS Code Copilot 等）调用外部工具、读取数据源、使用提示模板的开放协议。GoMCP 的目标是让构建这类服务器变得简单直接，被描述为“MCP 领域的 Gin”，提供类似 Gin 的开发体验。

主要能力

工具开发

  • 结构体标签自动 Schema：用 Go 结构体和 mcp 标签定义参数，自动生成 JSON Schema。
  • 类型化处理器：使用 func(*Context, Input) (Output, error) 形式的处理器，无需手动解析参数。
  • 参数校验：支持 required、min/max、enum、pattern，在处理函数执行前完成检查，无效参数会被提前拒绝。
  • 组件版本管理：可注册多个版本，客户端通过 name@version 调用。
  • 异步任务：长时间运行的工具返回任务 ID，支持轮询与取消。

适配器

  • Gin 适配器：一行代码将已有 Gin 路由导入为 MCP 工具。
  • OpenAPI 适配器：从 Swagger/OpenAPI 3.x 文档生成工具。
  • gRPC 适配器：将 gRPC 服务方法导入为 MCP 工具。

认证与授权

  • BearerAuth：通过自定义验证器做 Bearer token 检查（文档说明本库不解码 JWT，JWT 解析由使用者自行处理）。
  • APIKeyAuth：通过请求头校验 API Key。
  • BasicAuth：HTTP Basic 认证。
  • RequireRole / RequirePermission：在工具组上实现 RBAC 授权。

框架特性

  • 中间件链：Logger、Recovery、RequestID、Timeout、RateLimit、OpenTelemetry。
  • 工具分组：支持前缀命名与组级中间件、嵌套分组。
  • Resource 与 Prompt：完整 MCP 支持，包括 URI 模板与参数化提示，并可为提示/资源参数提供自动补全建议。

生产相关

  • 多种传输：stdio（Claude Desktop、Cursor、Kiro）与 Streamable HTTP（含 SSE）。
  • MCP Inspector：内置 Web 调试界面，用于浏览和测试工具。
  • 热重载：从 YAML 文件加载工具定义并监听文件变化。
  • mcptest 包：用于单元测试的内存客户端，支持快照测试。
  • 生命周期：Close()、会话空闲回收、异步并发控制。

使用方式

环境要求

  • go.mod 声明 go 1.25.0。若本地为 Go 1.21+ 且使用默认 GOTOOLCHAIN=auto，Go 会自动下载并使用匹配的工具链；若固定为 GOTOOLCHAIN=local，则需安装 Go 1.25+ 或取消固定。

基本用法

  • 定义输入结构体，使用 mcp 标签，例如组合写法 mcp:"required,desc=User email,pattern=^[^@]+@[^@]+$"。
  • 支持类型：string、int、float64、bool、[]T、嵌套结构体。
  • 可使用简单处理器或推荐的类型化处理器。

认证错误形态

当 BearerAuth / APIKeyAuth / BasicAuth / RequireRole / RequirePermission 中间件拒绝调用时，框架返回的是普通 JSON-RPC 结果，其中 isError = true，原因位于 content[0].text，而不是 JSON-RPC 错误对象，也不是 HTTP 401/403。客户端必须检查工具调用结果的 isError 来识别认证失败。

适配器示例

  • Gin：一行导入已有 API。
  • OpenAPI：从 Swagger 文档生成。

组件版本与 YAML

  • 版本字段会重命名工具：非空 version 会让 Provider 以 name@version 注册（如 search@1.0），即客户端调用 tools/call 以及 tools/list 中显示的名称。若希望工具名为无版本的 search，则完全去掉 version 字段。
  • YAML 工具文件支持相应结构定义。

服务器生命周期、会话与异步任务

  • Server.Close()：当进程或测试拆除使用了 LoadDir(..., Watch: true) 或长驻 HTTP 的服务器时调用一次。它会停止 YAML 监听循环、会话回收后台 goroutine 与异步任务管理器回收循环，且是幂等的。
  • 会话：会话状态仅存于内存。标识来自客户端 Mcp-Session-Id 请求头。空闲 30 分钟（该 ID 无访问）的会话会被移除；同一 ID 的下一次请求会得到新的空会话。除非客户端保持流量或自行刷新状态，否则不要依赖长期空闲期间的会话存储。
  • SetMaxConcurrentTasks(n)：需在第一次 AsyncTool / AsyncToolFunc 之前设置；内部任务管理器创建后再调用则为无操作（以避免与进行中工作产生竞态）。
  • 关闭与异步工作：Close() 不会等待仍在运行的异步工具处理器；如需退出前的硬保证，应自行添加超时或等待。

HTTP 传输与认证要点

  • 中间件对每个 JSON-RPC 方法（除没有响应的通知 notifications/initialized 外）都会运行，包括 initialize、tools/list、tools/call、resources/read、prompts/get、tasks/*、completion/complete 等。暴露 POST /mcp 时应使用 BearerAuth / APIKeyAuth / BasicAuth。对于 APIKeyAuth，当没有发送请求头时，api_key（及其他合并参数）来自 tools/call 参数、prompts/get 参数或 resources/read 的 params JSON；生产环境建议使用请求头。
  • BearerAuthSkipHandshake / APIKeyAuthSkipHandshake / BasicAuthSkipHandshake（或 SkipAuthForMCPMethods）可让 initialize 与 ping 在无凭证下运行，同时保护其他方法，适合先协商后发送 token 的 MCP HTTP 客户端。
  • 请求上下文会传递到工具、资源与提示处理器中（截止时间、Authorization 及来自 Streamable HTTP 注入的请求头）。
  • SSE（GET /mcp）不会执行 MCP 中间件。应使用 WithSSEAuth 配合 SSEBearerAuth、SSEAPIKeyAuth、SSEBasicAuth 或自定义门控。若不使用 WithSSEAuth，任何能打开 GET 的客户端都会收到广播通知。
  • 浏览器 fetch：用 transport.WrapCORS(h, allowedOrigins)（来自 github.com/zhangpanda/gomcp/transport）包装 /mcp 处理器；切勿在带凭证时使用 *，只列出受信任来源。
  • 生产部署 Streamable HTTP 时，应结合 TLS、POST 上的认证中间件，以及在通知不应公开时使用 WithSSEAuth。

与 AI 客户端配合

可与 Claude Desktop、Cursor、Kiro、Windsurf、VS Code Copilot 以及任何兼容 MCP 的客户端配合使用。

适用场景

  • 需要以 Go 快速实现 MCP 服务器的开发者。
  • 希望把已有 Gin 路由、OpenAPI 文档或 gRPC 服务快速暴露为 MCP 工具。
  • 需要认证、RBAC、限流、超时、可观测性等生产级能力的 MCP 服务。
  • 需要 YAML 热重载、内置调试界面与内存测试客户端的开发与测试流程。

限制与注意事项

  • 会话状态仅存于内存，空闲 30 分钟会被回收。
  • Close() 不等候仍在运行的异步工具处理器。
  • SetMaxConcurrentTasks 必须在首次创建异步工具前调用。
  • SSE 通道不经过 MCP 中间件，需单独配置 SSE 认证。
  • BearerAuth 不负责 JWT 解码，需使用者自行实现验证器。
  • 认证失败以 isError=true 的 JSON-RPC 结果返回，而非 HTTP 401/403 或 JSON-RPC 错误对象。
  • 更多细节、逐步指南与代码示例请参见项目仓库文档。

版权与许可

Copyright © 2026 GoMCP Contributors。基于 Apache License 2.0 开源，个人与商业用途均可免费使用，需保留版权声明、许可证文本与归属声明。Apache 2.0 包含贡献者向用户的明确专利授权；向本项目贡献的代码同样以 Apache 2.0 授权。框架中部分特性（结构体标签 Schema 生成、HTTP-to-MCP 自动适配器、OpenAPI-to-MCP 自动适配器）有正在申请的专利，Apache 2.0 授予对这些特性作为本软件一部分使用的永久、全球、免版税的专利许可。

同类工具

查看分类