MCP服务器模板(Go)
用于构建的生产就绪模板 模型上下文协议(MCP) Go中的服务器,遵循官方最佳实践和指导方针。
特性
- 完成MCP实施 -工具、资源和提示
- 生产准备就绪 -优雅的关机、信号处理和错误处理
- 测试良好 -带示例的单元和集成测试
- 可配置的 -基于YAML的配置与验证
- 安全 -输入验证、净化和最佳实践
- Docker支持 -已准备好进行集装箱化部署
- 最佳实践 -遵循官方MCP实施指南
快速开始
先决条件
- 达到1.23或更高
- Make(可选,用于使用Makefile命令)
安装
- 克隆或使用此模板:```bash
git clone
cd mcp-server-template
1. **安装依赖项:**```bash
go mod download
- 🚨 重要提示:清理模板示例
此模板包括示例工具、资源和提示。 在开始项目之前,您应该删除这些。
看 CLAUDE.md 有关以下内容的详细说明:
- 要删除哪些文件
- 如何清理注册表功能
- 如何更新配置
- 如何为您的项目自定义CLAUDE.md
快速清理:```bash
Remove example implementations
rm internal/tools/{search,calculate,analyze}.go
rm internal/tools/{search,calculate,analyze}_test.go
rm internal/resources/files.go internal/resources/files_test.go
rm internal/prompts/greet.go internal/prompts/greet_test.go
rm tests/integration/server_test.go tests/testdata/fixtures.json
1. **配置服务器:**```bash
# Edit configs/config.yaml to customize
nano configs/config.yaml
- 构建并运行:```bash
make build
make run
或者直接:```bash
go run ./cmd/server
项目结构```
mcp-server-template/
├── cmd/
│ └── server/
│ └── main.go # Entry point with graceful shutdown
├── internal/
│ ├── tools/ # MCP tools (one per file)
│ │ ├── register.go # Tool registration
│ │ ├── search.go # Search tool
│ │ ├── search_test.go # Search tests (same package)
│ │ ├── calculate.go # Calculate tool
│ │ ├── calculate_test.go # Calculate tests
│ │ ├── analyze.go # Analyze tool
│ │ └── analyze_test.go # Analyze tests
│ ├── resources/ # MCP resources
│ │ ├── register.go # Resource registration
│ │ ├── files.go # File system resources
│ │ └── files_test.go # File tests
│ ├── prompts/ # MCP prompts
│ │ ├── register.go # Prompt registration
│ │ ├── greet.go # Greeting prompt
│ │ └── greet_test.go # Greeting tests
│ ├── config/ # Configuration management
│ │ ├── config.go # Config loading and validation
│ │ └── config_test.go # Config tests
│ └── services/ # Business logic (add your services here)
├── tests/
│ ├── integration/ # Integration tests
│ │ └── server_test.go # Full server tests
│ └── testdata/ # Test fixtures
│ └── fixtures.json
├── configs/
│ └── config.yaml # Server configuration
├── docs/
│ └── MCP_SERVER_IMPLEMENTATION_GUIDE.md # Complete implementation guide
├── go.mod # Go module definition
├── go.sum # Dependency checksums
├── Makefile # Build automation
├── Dockerfile # Container image
├── README.md # This file
└── CLAUDE.md # Instructions for Claude Code
## 包括示例
### 工具
1. **搜索** -搜索具有可配置限制的信息
1. **计算** -执行算术运算(加、减、乘、除)
1. **分析** -使用各种方法(情感、关键字、摘要)分析文本
### 资源
1. **文件系统** -通过访问本地文件 `file:///` URI
### 提示词
1. **问候** -生成不同风格的个性化问候
## 配置
编辑 `configs/config.yaml`:```yaml
server:
name: "your-server-name"
version: "1.0.0"
port: 8080
features:
enable_tools: true
enable_resources: true
enable_prompts: true
environment: "dev" # dev, staging, production
tools:
search_enabled: true
analyze_enabled: true
calculate_enabled: true
使用环境变量
对于机密和敏感数据,请使用环境变量:```yaml
configs/config.yaml
database:
password: ${DB_PASSWORD}
api:
api_key: ${API_KEY}
然后在运行前设置它们:```bash
export DB_PASSWORD="your-password"
export API_KEY="your-api-key"
./bin/server
发展
运行测试```bash
All tests with coverage
make test
Unit tests only
make test-unit
Integration tests only
make test-integration
Generate coverage report
make coverage
### 建筑```bash
# Build binary
make build
# Run locally
make run
# Clean build artifacts
make clean
代码质量```bash
Format code
make fmt
Run linters (requires golangci-lint)
make lint
### 码头工人```bash
# Build image
make docker-build
# Run container
make docker-run
添加新功能
添加新工具
- 创建
internal/tools/mytool.go:```go
package tools
import (
"context"
"fmt"
"github.com/modelcontextprotocol/go-sdk/mcp"
)
type MyToolInput struct {
Query string json:"query" jsonschema:"required,description=Your query"
}
type MyToolOutput struct {
Result string json:"result" jsonschema:"description=The result"
}
func registerMyTool(server *mcp.Server) {
mcp.AddTool(server, &mcp.Tool{
Name: "mytool",
Description: "Description of what your tool does",
}, myToolHandler)
}
func myToolHandler(ctx context.Context, req mcp.CallToolRequest, input MyToolInput) (
mcp.CallToolResult, MyToolOutput, error,
) {
// Validate inputs
if input.Query == "" {
return nil, MyToolOutput{}, fmt.Errorf("query is required")
}
// Check context cancellation
select {
case <-ctx.Done():
return nil, MyToolOutput{}, ctx.Err()
default:
}
// Your implementation here
result := processQuery(input.Query)
return nil, MyToolOutput{Result: result}, nil
}
2. 创建 `internal/tools/mytool_test.go` (同一包装内)
1. 更新 `internal/tools/register.go`:```go
func Register(server *mcp.Server, cfg *config.Config) {
// ...
registerMyTool(server)
}
- 在中添加配置选项
configs/config.yaml:```yaml
tools:
mytool_enabled: true
5. 运行测试:```bash
make test
添加资源或提示
遵循相同的模式 internal/resources/ 或 internal/prompts/.
测试
此模板包括全面的测试:
- 单元测试 -测试单个函数和处理程序
- 集成测试 -测试具有所有功能的完整服务器
- 表驱动测试 -易于添加新的测试用例
- 错误测试 -验证错误处理
- 上下文测试 -验证上下文取消
提交前运行测试:```bash
make test
## 部署
### 标准传输(默认)
该模板默认使用stdio传输,适用于:
- CLI工具
- 本地集成
- 子流程沟通
### HTTP传输
要使用HTTP传输,请修改 `cmd/server/main.go`:```go
// Change from stdio to HTTP
handler := mcp.NewStreamableHTTPHandler(
func(r *http.Request) *mcp.Server { return server },
nil,
)
log.Fatal(http.ListenAndServe(":8080", handler))
Docker部署```bash
Build image
docker build -t your-server:latest .
Run container (stdio)
docker run -i your-server:latest
Run container (HTTP)
docker run -p 8080:8080 your-server:latest
## 安全最佳实践
此模板遵循安全最佳实践:
- ✅ 所有工具的输入验证
- ✅ 文件路径清理
- ✅ 参数化查询(使用数据库时)
- ✅ 上下文取消支持
- ✅ 使用上下文包装时出错
- ✅ 没有硬编码的秘密
- ✅ Docker中的非root用户
**始终:**
- 验证并净化所有输入
- 对SQL使用参数化查询
- 永远不要将秘密提交给版本控制
- 对敏感数据使用环境变量
## 定制
### 重命名模块
1. 更新 `go.mod`:```go
module your-module-name
- 更新所有文件中的导入:```go
import "your-module-name/internal/config"
1. 运行:```bash
go mod tidy
删除示例功能
要删除示例工具/资源/提示:
- 从中删除相应的文件
internal/ - 更新
register.go文件 - 更新
configs/config.yaml - 运行测试以验证
文档
- 实施指南:参见
docs/MCP_SERVER_IMPLEMENTATION_GUIDE.md获取全面的指导方针 - MCP规范: https://modelcontextprotocol.io/specification
- Go SDK文档: https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk
贡献
欢迎投稿!拜托:
- 遵循现有的代码结构
- 为新功能添加测试
- 更新文档
- 跑
make test和make lint提交前
建筑原理
此模板遵循严格的架构原则:
- 每个文件一个工具 -可维护性和清晰度
- 注册模式 -集中功能注册
- 未导出处理程序 -清洁公共API
- 同一包装单元测试 -进入内部
- 单独的集成测试 -端到端测试
- 配置驱动 -没有硬编码值
- 上下文感知 -适当的取消支持
- 包装错误 -完整的错误上下文
看 CLAUDE.md 了解详细的架构指南。
许可证
[您的许可证在这里]
支持
如有疑问或问题:
- 查看中的实施指南
docs/ - 查看中的示例代码
internal/ - 在GitHub上打开一个问题
致谢
按照官方规定建造 MCP Go SDK 以及实施指南。
