使用说明

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秒部署

# 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流

curl -N -H "Accept: text/event-stream" \
  https://your-app.com/sse

发送JSON-RPC消息

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

检查健康状况

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（推荐）

# 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

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

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

🔍 监控和故障排除

健康检查

# 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服务器未启动

# 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连接失败

# 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构建问题

# 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

日志分析

# Cloud Foundry logs
cf logs github-mcp-adapter --recent
cf logs github-mcp-adapter | grep -E "(ERROR|WARN)"

# Docker logs
docker logs <container-id>

# Key log patterns to look for:
# - "GitHub MCP Server started successfully"
# - "SSE connection established" 
# - "Bridging validated client message"
# - "MessageBridge" component logs

🛡️ 安全最佳实践

令牌安全
- 永远不要在配置文件中硬编码令牌
- 使用Cloud Foundry环境变量或Kubernetes机密
- 定期轮换代币（建议每季度轮换一次）
- 为开发/测试/生产环境使用单独的令牌
网络安全
- 为所有外部通信启用HTTPS
- 配置适当的Cloud Foundry安全组
- 考虑在敏感环境中使用VPN访问
- 监视并记录所有API访问
资源安全性
- 以非root用户身份运行（在容器中强制）
- 设置适当的内存和CPU限制
- 监控资源使用情况并设置警报
- 定期更新安全补丁的基础映像

📈 扩展

Cloud Foundry扩展

# 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文档