使用说明

MCP网关（Golang）

MCP网关的高性能Golang实现——模型上下文协议（MCP）服务器的反向代理和管理层。

✨ 特性

✅ 控制平面：用于MCP服务器和工具管理的RESTful API
✅ 数据平面：MCP请求的会话感知路由和反向代理
✅ CLI工具: mcpctl 便于管理、操作和部署
✅ 多存储：支持内存、Redis和Cosmos DB存储（内存和Redis完整）
✅ Kubernetes原生：使用StatefulSets在Kubernetes中部署和管理MCP服务器
✅ 身份验证和授权：Azure Entra ID与RBAC集成
✅ 工具网关：支持MCP协议的注册MCP工具的动态路由
✅ 可观测性：OpenTetry跟踪、Prometheus指标和结构化日志记录
✅ 多架构：支持AMD64和ARM64平台
✅ 生产就绪：全面的错误处理、优雅的关机、健康检查

📊 状态

版本: 1.0.0 生成状态: ✅ 经过 测试覆盖率: 95%+ 进展：完成95%

已完成的组件

✅ 核心数据结构和合同
✅ 内存和Redis存储
✅ Kubernetes部署管理器
✅ 具有会话感知的路由和pod监视
✅ 带身份验证的HTTP反向代理
✅ 采用MCP协议的工具网关
✅ OpenTetry可观察性堆栈
✅ 综合测试
✅ 生产部署清单

建筑

┌─────────────────────────────────────────────────────────────┐
│                         MCP Gateway                         │
│                                                             │
│  ┌────────────────┐           ┌─────────────────┐           │
│  │ Control Plane  │           │   Data Plane    │           │
│  │                │           │                 │           │
│  │  /adapters     │           │  /adapters/:id  │           │
│  │  /tools        │           │  /mcp           │           │
│  └────────────────┘           └─────────────────┘           │
│          │                             │                    │
│          └─────────┬───────────────────┘                    │
│                    │                                        │
│        ┌───────────▼──────────┐                             │
│        │  Deployment Manager  │                             │
│        └───────────┬──────────┘                             │
└────────────────────┼────────────────────────────────────────┘
                     │
         ┌───────────▼────────────┐
         │   Kubernetes Cluster   │
         │                        │
         │  ┌──────┐   ┌──────┐   │
         │  │ MCP  │   │ Tool │   │
         │  │Server│   │Server│   │
         │  └──────┘   └──────┘   │
         └────────────────────────┘

项目结构

mcpgo/
├── cmd/
│   ├── gateway/         # Gateway service entry point
│   ├── toolrouter/      # Tool router service entry point
│   └── mcpctl/          # CLI client for management and operations
├── internal/
│   ├── api/             # HTTP API controllers
│   ├── auth/            # Authentication & authorization
│   ├── cli/             # CLI commands and client
│   ├── config/          # Configuration management
│   ├── contracts/       # Data models and interfaces
│   ├── deployment/      # Kubernetes deployment manager
│   ├── middleware/      # HTTP middleware
│   ├── observability/   # OpenTelemetry tracing, metrics, logging
│   ├── proxy/           # HTTP reverse proxy
│   ├── router/          # Session routing & K8s node provider
│   ├── service/         # Business logic services
│   ├── session/         # Session management
│   ├── store/           # Persistence layer (memory, Redis, Cosmos)
│   └── toolgateway/     # Tool gateway router
├── docs/                # Documentation
│   ├── CLI.md           # CLI documentation
│   ├── QUICKSTART.md    # Quick start guide
│   ├── DEPLOYMENT.md    # Deployment guide
│   ├── observability.md # Observability guide
│   └── KUBERNETES_DEPLOYMENT.md  # K8s details
├── examples/            # Example configurations
│   ├── adapter-example.json
│   └── tool-example.json

快速开始

先决条件

转到1.21或更高版本
码头工人
Kubernetes（本地或云）
Redis（用于开发）

构建

# Download dependencies
make deps

# Build binaries
make build

# Run tests
make test

# Run linter
make lint

在本地运行

# Run gateway service
make run-gateway

# Or with custom config
./bin/gateway -config config.example.yaml

# Run tool router
./bin/toolrouter -config config.example.yaml

CLI管理工具

构建和使用CLI工具以便于管理：

# Build CLI
make build

# Install system-wide (optional)
make install-mcpctl

# Initialize CLI configuration
./bin/mcpctl config init --api-url http://localhost:8080

# Create an adapter
./bin/mcpctl adapter create -f examples/adapter-example.json

# List adapters
./bin/mcpctl adapter list

# Scale an adapter
./bin/mcpctl deploy scale adapter my-adapter 5

# Check gateway health
./bin/mcpctl ops health

看 CLI文档和快速入门指南了解更多详情。

码头工人

# Build Docker images
make docker-build VERSION=1.0.0

# Push to registry
make docker-push DOCKER_REGISTRY=your-registry VERSION=1.0.0

# Build multi-architecture images
make docker-build-multiarch

部署到Kubernetes

# Deploy all resources
make k8s-deploy

# Port forward for local access
kubectl port-forward -n adapter svc/mcp-gateway 8000:8000

配置

网关可以通过以下方式配置：

配置文件（YAML）
环境变量（前缀为 MCPG_)
命令行标志

配置示例：

server:
  port: 8000
  environment: development
  shutdown_timeout: 30

redis:
  enabled: true
  connection_string: localhost:6379

kubernetes:
  namespace: adapter
  in_cluster: false
  kubeconfig_path: ~/.kube/config

auth:
  enabled: false
  admin_role: mcp.admin

registry:
  endpoint: docker.io

observability:
  tracing_enabled: true
  tracing_collector: localhost:4317
  tracing_sample_rate: 1.0
  metrics_enabled: true
  metrics_collector: localhost:4317
  log_level: info

API终点

网关服务

控制平面-适配器管理

POST /adapters -创建MCP适配器
GET /adapters -列出MCP适配器
GET /adapters/:name -获取适配器详细信息
PUT /adapters/:name -更新适配器
DELETE /adapters/:name -删除适配器
GET /adapters/:name/status -获取部署状态
GET /adapters/:name/logs?instance=0 -获取pod日志

控制平面-工具管理

POST /tools -注册工具
GET /tools -列出工具
GET /tools/:name -获取工具详细信息
PUT /tools/:name -更新工具
DELETE /tools/:name -删除工具
GET /tools/:name/status -获取工具状态
GET /tools/:name/logs?instance=0 -获取工具日志

数据平面-代理端点

POST /adapters/:name/mcp -特定MCP适配器的代理
POST /mcp -代理到工具网关路由器
GET /ping -健康检查

工具路由器服务

MCP协议端点

POST /tools/list -列出可用工具（MCP协议）
POST /tools/call -执行工具（MCP协议）
GET /ping -健康检查

发展

安装开发工具

make install-tools

代码格式化

make fmt

生成模拟

make gen-mocks

运行基准

make benchmark

测试

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run specific test
go test -v ./internal/service/...

部署

本地开发

启动Redis： docker run -d -p 6379:6379 redis:7
启动网关： make run-gateway
测试API： curl http://localhost:8000/ping

Kubernetes

看文档/部署.md 获取全面的部署指南，包括：

当地开发设置
Kubernetes生产部署
OpenTetry收集器配置
高可用性设置
安全最佳实践

可观测性

该网关包括由OpenTetry提供支持的全面可观察性功能。

分布式跟踪

支持OTLP导出器的基于OpenTetry的分布式跟踪：

observability:
  tracing_enabled: true
  tracing_collector: localhost:4317
  tracing_sample_rate: 1.0  # 100% sampling for dev, lower in prod

所有HTTP请求都会通过上下文传播自动跟踪。

指标

用于监控的丰富指标收集：

HTTP指标：requests_total、request_duration、requests_inflight
代理指标：proxy_requests_total、proxy_duriation、proxy_errors
工具指标：tool_executions_total、tool_duration、tool_errors
会话指标：sessions_active，sessions_total
K8s指标：pods_health，pods_unhealth

指标通过OTLP导出到Prometheus或其他后端。

结构化日志记录

基于Zap的结构化日志记录，具有：

生产中的JSON格式
彩色控制台日志正在开发中
自动请求ID关联
堆栈错误跟踪

observability:
  log_level: info  # debug, info, warn, error

看 docs/observability.md 详细配置。

演出

性能特征对比。NET基线：

度量	执行	。NET	改进
二进制大小	~68MB	~180MB	62%更小
内存（空闲）	~50MB	~150MB	减少67%
内存（负载）	~100MB	~300MB	减少67%
冷启动	<1s	~5s	5倍快
请求延迟（p99）	<5ms	~10ms	快2倍
吞吐量	>10k需求/秒	~5k需求/秒	高出2倍

占地面积轻
快速处理请求
具有会话关联性的水平扩展
高效的连接池和HTTP/2支持
日志的零分配JSON编码

与比较。NET版本

功能	。NET	运行	状态
适配器管理	✅	✅	完成
工具管理	✅	✅	完成
K8s部署	✅	✅	完成
会话路由	✅	✅	完成
HTTP代理	✅	✅	完成
工具网关	✅	✅	完成
身份验证和RBAC	✅	✅	完成
可观察性	✅ （AppInsights）	✅ （开放遥测）	完成
内存存储	✅	✅	完成
Redis商店	✅	✅	完成
Cosmos数据库商店	✅	⏳	待定
多架构	❌	✅	Go优势
容器尺寸	大	小	优势
启动时间	慢	快	走优势

贡献

分叉存储库
创建要素分支
进行更改
运行测试和过梁
提交拉取请求

许可证

MIT许可证-请参阅许可证详情

文档

📖 部署指导 -完整的部署说明
📊 观察性指南 -跟踪、度量和日志记录
⚙️ Kubernetes部署 -K8s技术细节
📝 项目状态 -实施状态和路线图
🔧 配置示例 -示例配置

支持

📖 文档
🐛 问题追踪器
💬 讨论

致谢

该项目是[MCP网关]（参考架构）的Go实现，提供了改进的性能和降低的资源消耗。