GitHub MCP协议适配器
一个Spring Boot应用程序,将服务器发送事件(SSE)传输桥接到GitHub MCP服务器的STDIO传输,实现与Cloud Foundry环境中的模型上下文协议(MCP)客户端的无缝集成。
🚀 快速开始
此适配器允许MCP客户端通过熟悉的HTTP/SSE接口与GitHub存储库通信,同时通过STDIO在内部管理GitHub MCP服务器进程。
先决条件
- GitHub个人访问令牌 具有适当的权限
- Cloud Foundry环境 或Docker运行时
- 访问容器注册表 (Docker Hub、Harbor等)
🏃♂️ 30秒部署```bash
1. Build the Docker image
docker buildx build --platform linux/amd64 -t your-registry/github-mcp-adapter:latest .
2. Push to registry
docker push your-registry/github-mcp-adapter:latest
3. Deploy to Cloud Foundry
cf push -f manifest.yml
4. Set your GitHub token
cf set-env github-mcp-adapter GITHUB_PERSONAL_ACCESS_TOKEN "your-github-token"
cf restart github-mcp-adapter
5. Test the deployment
curl https://your-app.apps.your-domain.com/health
## 🏗️ 建筑```
┌─────────────────┐ SSE ┌──────────────────┐ STDIO ┌─────────────────┐
│ MCP Client │ ◄─────────────────► │Protocol Adapter │ ◄────────────► │GitHub MCP Server│
│ (SSE Transport)│ HTTP/SSE │ (Spring Boot) │ Process │ (STDIO Transport)│
└─────────────────┘ └──────────────────┘ └─────────────────┘
适配器充当协议桥,在以下之间进行转换:
- 客户端:HTTP/SSE用于web友好集成
- 服务器端:STDIO用于直接GitHub MCP服务器通信
🌟 主要特点
- 🔄 协议转换:无缝SSE↔ STDIO消息桥接
- 📡 实时通信:服务器发送实时更新事件
- 🛡️ 流程管理:自动GitHub MCP服务器生命周期管理
- ✅ 健康监测:内置健康检查和流程状态
- 📋 JSON-RPC验证:全面的消息格式验证
- ☁️ 云就绪:针对Cloud Foundry部署进行了优化
- 🔐 安全:使用适当的令牌处理执行非根容器
📊 API终点
核心终点
GET /sse-服务器发送事件连接端点POST /message-JSON-RPC消息提交GET /health-应用程序运行状况GET /debug/process-GitHub MCP服务器进程状态
示例用法
连接到SSE流```bash
curl -N -H "Accept: text/event-stream" \
https://your-app.com/sse
#### 发送JSON-RPC消息```bash
curl -X POST \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}},"id":1}' \
https://your-app.com/message
检查健康状况```bash
curl https://your-app.com/health
Returns: {"status":"UP","activeSessions":1,"githubMcpServerRunning":true}
## ⚙️ 配置
### 所需的环境变量
|变量|描述|示例|
|----------|-------------|---------|
| `GITHUB_PERSONAL_ACCESS_TOKEN` |具有仓库访问权限的GitHub PAT| `ghp_xxxxxxxxxxxx` |
### 可选环境变量
|变量|默认值|描述|
|----------|---------|-------------|
| `GITHUB_HOST` | `https://github.com` |GitHub实例URL|
| `GITHUB_TOOLSETS` | `repos,issues,pull_requests,users,code_security,secret_protection,notifications` |启用MCP工具集|
| `LOG_LEVEL` | `INFO` |日志记录级别|
| `MAX_SSE_CONNECTIONS` | `100` |最大并发SSE连接数|
| `MESSAGE_BUFFER_SIZE` | `1000` |消息队列缓冲区大小|
| `PROCESS_RESTART_DELAY_MS` | `5000` |重启失败进程前的延迟|
### GitHub令牌权限
您的GitHub个人访问令牌需要以下最低权限:
- **`repo`** -存储库操作(对存储库的读/写访问)
- **`read:packages`** -包读取权限(如果使用GitHub包)
- **其他权限** 基于您选择的工具集
在以下位置创建令牌: GitHub设置→ 个人访问令牌
## 🚀 部署选项
### 选项1:Cloud Foundry(推荐)```bash
# Update manifest.yml with your registry and domain
cf push -f manifest.yml
cf set-env github-mcp-adapter GITHUB_PERSONAL_ACCESS_TOKEN "your-token"
cf restart github-mcp-adapter
选项2:Docker```bash
docker run -d \
-p 8080:8080 \
-e GITHUB_PERSONAL_ACCESS_TOKEN="your-token" \
-e GITHUB_TOOLSETS="repos,issues,pull_requests" \
your-registry/github-mcp-adapter:latest
### 选项3:Kubernetes```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: github-mcp-adapter
spec:
replicas: 1
selector:
matchLabels:
app: github-mcp-adapter
template:
metadata:
labels:
app: github-mcp-adapter
spec:
containers:
- name: adapter
image: your-registry/github-mcp-adapter:latest
ports:
- containerPort: 8080
env:
- name: GITHUB_PERSONAL_ACCESS_TOKEN
valueFrom:
secretKeyRef:
name: github-token
key: token
livenessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 60
periodSeconds: 30
🔍 监控和故障排除
健康检查```bash
Basic health
curl https://your-app.com/health
Detailed process status
curl https://your-app.com/debug/process
Example healthy response:
{
"status": "UP",
"activeSessions": 2,
"githubMcpServerRunning": true,
"detailedHealth": {
"githubMcpServerRunning": true,
"activeSessionCount": 2,
"bridgeStatus": "healthy"
}
}
### 常见问题
#### ❌ GitHub MCP服务器未启动```bash
# Check token permissions
curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user
# Verify environment variable is set
cf env github-mcp-adapter | grep GITHUB_PERSONAL_ACCESS_TOKEN
# Check process logs
cf logs github-mcp-adapter | grep "GithubMcpServerProcess"
❌ SSE连接失败```bash
Test SSE endpoint directly
curl -N -H "Accept: text/event-stream" https://your-app.com/sse
Check bridge status
curl https://your-app.com/debug/process
Verify message endpoint URL in SSE stream
#### ❌ Docker构建问题```bash
# Use correct architecture targeting
docker buildx build --platform linux/amd64 -t your-registry/github-mcp-adapter:latest .
# Verify binary architecture in container
docker run --rm your-registry/github-mcp-adapter:latest file /app/bin/github-mcp-server
日志分析```bash
Cloud Foundry logs
cf logs github-mcp-adapter --recent
cf logs github-mcp-adapter | grep -E "(ERROR|WARN)"
Docker logs
docker logs
Key log patterns to look for:
- "GitHub MCP Server started successfully"
- "SSE connection established"
- "Bridging validated client message"
- "MessageBridge" component logs
## 🛡️ 安全最佳实践
1. **令牌安全**
- 永远不要在配置文件中硬编码令牌
- 使用Cloud Foundry环境变量或Kubernetes机密
- 定期轮换代币(建议每季度轮换一次)
- 为开发/测试/生产环境使用单独的令牌
1. **网络安全**
- 为所有外部通信启用HTTPS
- 配置适当的Cloud Foundry安全组
- 考虑在敏感环境中使用VPN访问
- 监视并记录所有API访问
1. **资源安全性**
- 以非root用户身份运行(在容器中强制)
- 设置适当的内存和CPU限制
- 监控资源使用情况并设置警报
- 定期更新安全补丁的基础映像
## 📈 扩展
### Cloud Foundry扩展```bash
# Horizontal scaling
cf scale github-mcp-adapter -i 3
# Vertical scaling
cf scale github-mcp-adapter -m 2G -k 1G
# Auto-scaling (if supported)
cf enable-autoscaling github-mcp-adapter
性能调整
- SSE连接:调整
MAX_SSE_CONNECTIONS基于负载 - 记忆:从1GB开始,根据使用情况进行监控和调整
- 进程重新启动:调谐
PROCESS_RESTART_DELAY_MS为了您的环境 - 缓冲区大小:增加
MESSAGE_BUFFER_SIZE适用于高通量场景
📚 文档
- 设计.md -详细的架构和实现设计
- 部署指南.md -分步部署说明
- deployment_checklist.md -快速部署检查表
- CLAUDE.md -Claude Code开发指南
🤝 贡献
- 开发设置:参见 CLAUDE.md 用于开发环境设置
- 建筑:评论 设计.md 有关系统架构的详细信息
- 测试:使用提供的健康端点进行集成测试
- 部署:关注 部署指南.md 用于部署程序
📄 许可证
该项目将GitHub MCP服务器与SSE传输连接起来。请参阅GitHub MCP Server项目以了解其许可条款。
🆘 支持
- 应用程序问题:通过以下方式检查应用程序日志
cf logs或docker logs - 健康状况:监视器
/health和/debug/process端点 - GitHub MCP服务器:请参阅 GitHub MCP服务器文档
- MCP协议:参见 MCP规范
- Spring Boot:检查 Spring Boot文档
准备好部署了吗? 从 快速开始 上面的部分! 🚀
