Cpage Pivotal MCP

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令牌权限

您的GitHub个人访问令牌需要以下最低权限：

• repo -存储库操作（对存储库的读/写访问）
• read:packages -包读取权限（如果使用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 

# 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扩展

# 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开发指南

🤝 贡献

1. 开发设置：参见 CLAUDE.md 用于开发环境设置
2. 建筑：评论 设计.md 有关系统架构的详细信息
3. 测试：使用提供的健康端点进行集成测试
4. 部署：关注 部署指南.md 用于部署程序

📄 许可证

该项目将GitHub MCP服务器与SSE传输连接起来。请参阅GitHub MCP Server项目以了解其许可条款。

🆘 支持

• 应用程序问题：通过以下方式检查应用程序日志 cf logs 或 docker logs
• 健康状况：监视器 /health 和 /debug/process 端点
• GitHub MCP服务器：请参阅
• MCP协议：参见 MCP规范
• Spring Boot：检查 Spring Boot文档

______________________________________________________________________

准备好部署了吗？ 从 快速开始 上面的部分！ 🚀