MCP Go Boilerplate

MCP Go沸腾板

最低限度，生产就绪 模型上下文协议（MCP）工具服务器 使用Go编写 官方MCP Go SDK.

该项目为构建可由AI代理（Claude、本地代理等）或任何能够发出HTTP请求的客户端使用的MCP兼容工具服务器提供了干净的基础。

它包括：

• 使用官方SDK的结构化工具系统
• 通过以下方式自动发现工具 init() 注册
• 从Go结构标签推断JSON模式
• HTTP传输（流式HTTP）
• 可选JWT身份验证
• 结构化测井
• 测试套件
• 安全生产服务器配置
• 可重复的跨平台构建 Makefile

目标是提供 简单且可扩展的起点 对于MCP服务器。

项目结构

main.go
Makefile
internal/
  auth/
    jwt.go
  config/
    config.go
  httpserver/
    server.go
  middleware/
    auth.go
    logging.go
    requestid.go
  tools/
    register.go
    echo.go
  transport/
    mcp.go

快速开始

1.克隆项目

git clone https://github.com/andr1an/mcp-go-boilerplate
cd mcp-go-boilerplate

2.运行服务器

go run .

服务器将在以下时间启动：

http://localhost:8080

3.打印构建元数据

go run . version

输出示例：

version=dev commit=none date=unknown

对于发布二进制文件，元数据在构建时通过以下方式注入 -ldflags 在 Makefile.

这 version MCP服务器也会在协议响应中报告该值（例如，在 initialize).

端点

健康检查

GET /health

答复：

{
  "status": "ok"
}

MCP传输(/mcp)

/mcp 使用MCP流式HTTP传输(jsonrpc 请求通过 POST).

初始化请求示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "latest supported MCP version",
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    },
    "capabilities": {}
  }
}

列出工具：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

呼叫工具：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "echo_message",
    "arguments": {
      "message": "hello",
      "upper": true
    }
  }
}

添加工具

工具在内部实现：

internal/tools/

每个工具都使用官方的MCP Go SDK mcp.AddTool 具有类型化输入/输出结构的函数。

示例工具

示例实现（约30行）：

package tools

import (
	"context"
	"strings"

	"github.com/modelcontextprotocol/go-sdk/mcp"
)

type EchoInput struct {
	Message string `json:"message" jsonschema:"Message to echo back"`
	Upper   bool   `json:"upper,omitempty" jsonschema:"Whether to uppercase the message"`
}

type EchoOutput struct {
	Echo string `json:"echo"`
}

func init() {
	MustRegister(func(s *mcp.Server) {
		mcp.AddTool(s, &mcp.Tool{
			Name:        "echo_message",
			Description: "Returns the provided message",
		}, Echo)
	})
}

func Echo(ctx context.Context, req *mcp.CallToolRequest, input EchoInput) (*mcp.CallToolResult, EchoOutput, error) {
	out := input.Message
	if input.Upper {
		out = strings.ToUpper(out)
	}
	return nil, EchoOutput{Echo: out}, nil
}

主要特点：

• 输入/输出模式是从Go结构体标签中自动推断出来的
• jsonschema 标签提供字段描述
• 无字段 omitempty 在 json 标签是必需的
• 错误处理是自动的-返回错误并将其包装在结果中

自动工具注册

工具通过以下方式自动注册：

func init() {
	MustRegister(func(s *mcp.Server) {
		mcp.AddTool(s, &mcp.Tool{...}, handler)
	})
}

这意味着：

• server.go没有更改
• 将文件放入 internal/tools/ 自动公开该工具

工具命名约定

工具名称必须跟在后面：

lowercase_with_underscores

通过测试强制执行正则表达式：

^[a-z][a-z0-9_]*$

身份验证（可选）

服务器支持 JWT身份验证.

使用环境变量启用：

AUTH_MODE=jwt
JWT_PUBLIC_KEY=public.pem

启动服务器：

AUTH_MODE=jwt JWT_PUBLIC_KEY=public.pem go run .

客户必须包括：

Authorization: Bearer 

配置

服务器配置通过环境变量进行控制。

构建

生成本地二进制文件：

make build

常见OS/ARCH目标的交叉编译：

make build-all

测试

运行完整的测试套件：

make test

测试包括：

• 工具处理程序功能
• 传输处理器（MCP协议）
• HTTP服务器

许可证

MIT许可证