AI导哈

MCP协议服务器

一个基于Go构建的模型上下文协议（MCP）服务器，支持stdio和HTTP两种传输模式，用于与MCP兼容客户端集成。

  • by lkendrickd
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 lkendrickd/mcp-server

使用说明

MCP服务器

使用Go构建的模型上下文协议（MCP）服务器，支持stdio和HTTP传输，以便与MCP兼容的客户端集成。

特性

  • 通过以下方式支持MCP协议 去sdk
  • 双传输模式：stdio（CLI）和HTTP（流式HTTP）
  • 用于HTTP传输的API密钥认证中间件
  • 带路径、方法和状态标签的Prometheus度量
  • 结构化JSON日志记录 slog
  • 通过环境变量进行配置
  • 分散Docker镜像以最小化攻击面
  • 使用表驱动模式的全面单元测试，仅使用标准库，不使用外部测试框架

工具

工具 说明
generate_uuid 生成UUID v4

想添加自己的工具吗？ 看看 开发者指南 以逐步演练。

MCP设计流程图： 流程图可以帮助您在新工具实施过程中提供指导。 流程图

需求

  • 码头工人 和 Docker Compose （推荐）
  • 转到1.25+ （仅适用于本地开发）
  • 制造 （可选，为方便起见）

端点（HTTP传输）

端点 方法 需要身份验证 描述
/health GET 否 健康检查
/metrics GET 否 普罗米修斯指标
/mcp POST 是* MCP HTTP端点

*何时 AUTH_ENABLED=true

快速开始

# 1. Configure environment
make config

# 2. Edit .env to set your API key (optional but recommended)
#    API_KEYS=your-secret-key

# 3. Start the server
make docker-up

# 4. Verify it's running
curl http://localhost:8080/health

# 5. View logs
make docker-logs

# 6. Check the health endpoint
curl http://localhost:8080/health

对于没有Docker的本地开发，请参阅 发展 部分。

配置

所有配置都是通过环境变量进行的。

变量 默认值 描述
PORT 8080 服务器端口
MCP_TRANSPORT stdio 运输方式： stdio 或 http
AUTH_ENABLED false 启用API密钥身份验证（仅限HTTP）
API_KEYS API有效密钥的逗号分隔列表 
# Example: Run HTTP with authentication
MCP_TRANSPORT=http AUTH_ENABLED=true API_KEYS="key1,key2" make run

运输方式

标准（默认）： 与Claude Desktop和CLI工具一起使用。服务器通过stdin/stdout进行通信。

make run

HTTP： 用于基于HTTP的部署。通过流式HTTP公开MCP协议。

MCP_TRANSPORT=http make run

认证

为了简单起见，API密钥认证是在中间件中实现的。这显然可以根据需要用更稳健的解决方案来代替。

当 AUTH_ENABLED=true，the /mcp 终结点需要中的有效API密钥 X-API-Key 头球

# Generate a secure API key
openssl rand -hex 32

# Request with API key
curl -X POST http://localhost:8080/mcp \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{...}}'

未经身份验证的请求返回 401 Unauthorized:

{"error":"missing API key"}

返回无效密钥：

{"error":"invalid API key"}

Claude代码集成-配置示例

对于使用HTTP传输的Claude Code：

{
  "mcpServers": {
    "mcp-server": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

卷发示例

健康检查：

curl http://localhost:8080/health

韵律学：

curl http://localhost:8080/metrics

MCP初始化（使用身份验证）：

curl -X POST http://localhost:8080/mcp \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

码头工人

Docker镜像使用多阶段构建，并使用无发行版运行时镜像来保证安全。

# Build and run standalone container (HTTP mode)
make docker-run

# Run with auth enabled
AUTH_ENABLED=true API_KEYS="secret-key" make docker-run

# Stop and remove container
make docker-clean

Docker Compose

# Start services
make docker-up

# View logs
make docker-logs

# Restart services
make docker-restart

# Stop services
make docker-down

项目结构

.
├── cmd/                      # Application entrypoint
│   └── mcp-server.go         # Main server with transport switching
├── internal/
│   ├── config/               # Environment configuration
│   ├── handlers/             # HTTP handlers (health)
│   ├── middleware/           # Auth and metrics middleware
│   └── tools/                # MCP tool implementations
│       └── uuid/             # UUID generation tool
├── example.env               # Example environment file
├── docker-compose.yml        # Docker Compose configuration
├── Dockerfile                # Multi-stage distroless build
├── Makefile                  # Build and run targets
├── DEVELOPER_GUIDE.md        # Guide for adding new tools
└── README.md                 # This file

发展

本地开发需要Go 1.24+。

# Build and run locally (stdio mode)
make run

# Run with HTTP transport
MCP_TRANSPORT=http make run

# Run tests
make test

# Run tests with verbose output
make test-verbose

# Run tests with coverage
make coverage

# Generate HTML coverage report
make coverage-html

# Run linter
make lint

# Format code
make fmt

添加工具

看 开发者_GUIDE.md 有关添加新工具的完整演练。

快速概述：

  1. 在中创建新包 internal/tools/<toolname>/
  2. 使用输入/输出结构实现该工具
  3. 通过注册 init() 和 tools.Register()
  4. 在中添加空白导入 cmd/mcp-server.go

例子：

package mytool

import (
    "context"

    "github.com/modelcontextprotocol/go-sdk/mcp"
    "github.com/lkendrickd/mcp-server/internal/tools"
)

type Input struct {
    Name string `json:"name" jsonschema:"description=The name to greet"`
}

type Output struct {
    Message string `json:"message"`
}

func Greet(_ context.Context, _ *mcp.CallToolRequest, input Input) (*mcp.CallToolResult, Output, error) {
    return nil, Output{Message: "Hello, " + input.Name}, nil
}

func init() {
    tools.Register(func(s *mcp.Server) {
        mcp.AddTool(s, &mcp.Tool{
            Name:        "greet",
            Description: "Greet someone by name",
        }, Greet)
    })
}

制定目标

make help  # Show all available targets
目标 描述
make 显示帮助
make config 从example.env创建.env
make build 构建二进制文件
make run 在本地构建和运行
make test 运行单元测试
make test-verbose 运行具有详细输出的测试
make coverage 运行覆盖率测试
make lint 运行golangci lint
make fmt 格式代码
make docker-build 构建Docker镜像
make docker-run 构建并运行容器
make docker-clean 停止并移除容器
make docker-up 从docker compose开始
make docker-down 停止docker编写
make docker-logs 查看docker编写日志
make docker-restart 重新启动docker编写

相关 MCP