🤖 xCloud MCP服务器
高性能 模型上下文协议（MCP）服务器 使用FastMCP构建，为AI代理和自动化工具提供强大的GitHub集成和DevOps自动化功能。
✨ 特性
- � 4个MCP工具 GitHub自动化
- 🧪 91%的测试覆盖率 具有全面的测试套件
- 🐳 集装箱化开发 与波德曼
- 🔍 实时调试 支持
- 📊 覆盖范围报告 带有HTML输出
- ⚡ 热重新加载 开发环境
🛠️ MCP工具可用
| 工具 | 描述 | 状态 |
|---|---|---|
create_workflow_issue | 为工作流失败创建GitHub问题 | ✅ 已测试 |
monitor_ci_status | 监控CI/CD管道状态 | ✅ 已测试 |
get_xcloud_repositories | 列出带有工作流的PageCloudv1存储库 | ✅ 已测试 |
github_api_request | 低级GitHub API交互 | ✅ 已测试 |
🚀 快速开始
先决条件
设置
- 克隆和设置：
git clone https://github.com/PageCloudv1/xcloud-mcp.git
cd xcloud-mcp- 安装uv（如果尚未安装）：
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"- 配置环境：
# Set environment variables
export GITHUB_TOKEN=ghp_your_github_token_here
export GEMINI_API_KEY=your_gemini_api_key_here # Optional
# Optional: override server transport/host/port
export X_CLOUD_MCP_TRANSPORT=http
export X_CLOUD_MCP_HOST=0.0.0.0
export X_CLOUD_MCP_PORT=8000启动MCP服务器
选项A：直接MCP服务器（推荐）
# Run the MCP server using uv and FastMCP
uv run --with fastmcp fastmcp run src/xcloud_mcp/main.py
# Server will be available for MCP clients选项B：开发环境（带调试）
# Using VS Code (recommended)
code xcloud-mcp.code-workspace
# Or using command line
podman-compose up --build🔧 MCP客户端配置
xCloud MCP服务器可以根据您的客户和要求以多种方式配置。
选项A：基于容器（推荐）
这是最可靠的方法，因为它包括所有依赖关系：
{
"xcloud-mcp": {
"command": "podman",
"args": [
"run",
"--rm",
"-i",
"--env-file",
"/absolute/path/to/xcloud-mcp/.env",
"localhost/xcloud-mcp_xcloud-mcp:latest",
"fastmcp",
"run",
"xcloud_mcp/main.py"
]
}
}选项B：直接紫外线执行
对于开发或当容器不是首选时：
{
"xcloud-mcp": {
"command": "uv",
"args": [
"run",
"--with",
"fastmcp",
"fastmcp",
"run",
"/absolute/path/to/xcloud-mcp/src/xcloud_mcp/main.py"
],
"env": {
"GITHUB_TOKEN": "ghp_your_token_here",
"GEMINI_API_KEY": "your_gemini_key_here"
}
}
}设置步骤
- 准备容器 （选项A）：
cd /path/to/xcloud-mcp
podman-compose build- 配置环境:
# Edit .env file with your tokens
GITHUB_TOKEN=ghp_your_github_token_here
GEMINI_API_KEY=your_gemini_api_key_here- 测试配置:
# Test container approach
podman run --rm -i --env-file .env localhost/xcloud-mcp_xcloud-mcp:latest fastmcp run xcloud_mcp/main.py
# Should show FastMCP banner and "Starting MCP server 'xcloud-bot'"客户端特定配置
克劳德桌面版
添加到您的 settings.json:
{
"mcpServers": {
"xcloud-mcp": {
"command": "podman",
"args": ["run", "--rm", "-i", "--env-file", "/path/to/.env", "localhost/xcloud-mcp_xcloud-mcp:latest", "fastmcp", "run", "xcloud_mcp/main.py"]
}
}
}带有MCP扩展的VS代码
使用上述选项A或B中的相应命令在工作区或用户设置中进行配置。
GitHub复制集成
GitHub Copilot集成的工作方式与其他MCP客户端不同。Copilot通过智能编排使用服务器的工具，而不是直接连接到MCP服务器。
它是如何工作的：
- 副驾驶说明：位于
- 工具编排：Copilot将自然语言请求转换为MCP工具调用
- 无直接连接：副驾驶不直接连接到MCP服务器
副驾驶设置：
- 确保MCP服务器正在运行 （使用上述任何选项）
- 副驾驶自动检测 中的说明
.github/copilot-instructions.md - 使用自然语言 通过Copilot与xCloud工具交互
Copilot命令示例：
"Analyze the xcloud-bot repository and tell me what can be improved"
"Create a CI workflow issue for the xcloud-mcp repository"
"Show me the last 10 builds for PageCloudv1/xcloud-docs"
"List all xCloud repositories that don't have workflows"通过Copilot提供的工具：
analyze_repository-存储库运行状况分析create_workflow_issue-为工作流自动创建问题monitor_ci_status-CI/CD管道监控get_xcloud_repositories-xCloud生态系统存储库列表
备注：MCP服务器必须在本地运行，以便Copilot访问工具。
🧠 让复印机更智能
您可以通过设置自定义指令、自定义开发环境和配置模型上下文协议（MCP）服务器来增强Copilot的功能。
自定义指令设置
- 存储库级别说明:
- 这 .github/copilot-instructions.md 该文件为Copilot提供了特定于项目的指导 - Copilot在此存储库中工作时会自动检测并使用这些指令 - 说明定义了xCloud MCP服务器的角色和可用工具
- 个人副驾驶配置:
# In VS Code, access Copilot settings:
# 1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
# 2. Search "Copilot: Open Settings"
# 3. Configure your preferences- 工作区特定设置:
// In .vscode/settings.json
{
"github.copilot.enable": {
"*": true,
"yaml": true,
"plaintext": false
},
"github.copilot.editor.enableAutoCompletions": true
}副驾驶MCP服务器配置
- 启用MCP集成:
# Ensure your MCP server is running
uv run --with fastmcp fastmcp run src/xcloud_mcp/main.py
# Or with container
podman run --rm -i --env-file .env localhost/xcloud-mcp_xcloud-mcp:latest fastmcp run xcloud_mcp/main.py- VS代码MCP扩展 （如有）：
# Install MCP extension for VS Code
code --install-extension mcp-extension-id- 在VS代码设置中配置MCP:
// In settings.json
{
"mcp.servers": {
"xcloud-mcp": {
"command": "podman",
"args": ["run", "--rm", "-i", "--env-file", ".env", "localhost/xcloud-mcp_xcloud-mcp:latest", "fastmcp", "run", "xcloud_mcp/main.py"]
}
}
}开发环境定制
- 工作空间配置:
# Open the xCloud MCP workspace
code xcloud-mcp.code-workspace- 环境变量:
# Ensure tokens are configured
export GITHUB_TOKEN=ghp_your_token_here
export GEMINI_API_KEY=your_gemini_key_here- 调试设置:
// In .vscode/launch.json (already configured)
{
"name": "Attach to MCP Server",
"type": "python",
"request": "attach",
"connect": {
"host": "localhost",
"port": 5678
}
}Copilot+MCP的最佳实践
- 使用自然语言：用简单的英语询问Copilot有关存储库分析、CI/CD状态或工作流管理的问题
- 利用上下文：Copilot了解项目结构，可以建议相关的xCloud操作
- 组合工具：要求同时使用多个MCP工具的复杂操作
- 迭代：使用Copilot的建议来完善您的自动化工作流程
了解更多:
Gemini集成
详细配置见 .gemini/README.md 用于Gemini特定设置。
GitHub和环境配置
服务器需要特定的配置：
.env：包含GitHub和Gemini API令牌（从不提交此文件）.github/：包含GitHub工作流和Copilot说明GEMINI.md：Gemini API集成的配置和使用指南- 环境变量：身份验证所需的令牌和API密钥
🧪 测试
该项目有一个全面的测试套件 91%的覆盖率:
运行测试
# Using VS Code Task
Ctrl+Shift+P → "Tasks: Run Task" → "Run Tests"
# Using command line
podman-compose -f podman-compose.test.yml up --build --abort-on-container-exit生成覆盖率报告
# Coverage report is automatically generated
open htmlcov/index.html # View detailed HTML report检验统计量
- 总共19次测试 -全部通过✅
- 4个MCP工具 -经过全面测试
- 覆盖区域：成功场景、错误处理、边缘案例
🐳 发展
开发服务器
podman-compose up --build
# Server runs on http://localhost:8000
# Debugger available on port 5678在VS代码中调试
- 启动开发容器：
Compose Up (Dev)任务 - 附加调试器：
Python: Attach to App - 设置断点并调试
可用命令
# Start services
podman-compose up --build
# Run tests
podman-compose -f podman-compose.test.yml up --build --abort-on-container-exit
# Stop services
podman-compose down
# View logs
podman-compose logs -f
# Run linting
podman-compose exec xcloud-mcp python -m flake8 src tests📁 项目结构
xcloud-mcp/
├── .github/ # GitHub workflows and configuration
│ ├── profile/
│ └── workflows/
├── .vscode/ # VS Code settings and tasks
├── deploy/ # Deployment configurations
│ ├── nginx.conf # Nginx configuration
│ └── xcloud-mcp.service # Systemd service
├── src/ # Source code
│ └── xcloud_mcp/ # Main application package
│ ├── __init__.py
│ └── main.py # MCP server implementation
├── tests/ # Test suite (91% coverage)
│ ├── test_server.py # Server functionality tests
│ └── test_tools.py # MCP tools comprehensive tests
├── CHANGELOG.md # Version history
├── CODE_OF_CONDUCT.md # Community guidelines
├── Containerfile # Container definition
├── CONTRIBUTING.md # Contribution guidelines
├── COVERAGE_REPORT.md # Detailed test coverage report
├── LICENSE # MIT License
├── podman-compose.yml # Development orchestration
├── podman-compose.test.yml # Test environment
├── podman-compose.debug-test.yml # Debug test environment
├── pytest.ini # Test configuration
├── README.md # This file
├── requirements.txt # Production dependencies
├── requirements-dev.txt # Development dependencies
├── setup-git-config.ps1 # Git configuration script
├── setup-workspace.ps1 # Workspace setup script
├── TODO.md # Project tasks and roadmap
└── xcloud-mcp.code-workspace # VS Code workspace configuration🔧 配置
环境变量
GITHUB_TOKEN=ghp_your_github_token_here
GEMINI_API_KEY=your_gemini_api_key_here # OptionalVS代码集成
- 工作区:
xcloud-mcp.code-workspace - 任务：构建、测试、调试、lint
- 调试：附在容器上
- 扩展：Python、Docker、MCP支持
📊 代码质量
- 测试覆盖率：91%（覆盖90/98行）
- 代码检查：符合flake8标准
- 类型提示：贯穿整个代码库
- 文档：全面的文档字符串
- 错误处理：强大的异常管理
🤝 贡献
- 复刻仓库
- 创建要素分支：
git checkout -b feature/amazing-feature - 运行测试：
podman-compose -f podman-compose.test.yml up - 确保保持80%以上的覆盖率
- 提交更改：
git commit -m 'Add amazing feature' - 推送分支：
git push origin feature/amazing-feature - 打开拉取请求
� 可用任务（VS代码）
Compose Up (Dev)-启动开发服务器Compose Down-停止所有服务Run Tests-执行测试套件Debug Tests-调试测试执行View Logs-显示容器日志Lint Python Code-运行代码lintingFormat Python Code-自动格式化代码
🔍 监控与调试
- 健康检查:
GET /health - 调试端口: 5678 （调试）
- 日志：实时通过
podman-compose logs -f - 测试报告：HTML覆盖率
htmlcov/
📈 演出
- 基于容器：分离和可重复
- 热重新加载：即时代码更改
- 高效测试：并行执行
- 资源优化：最小的容器占地面积
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
______________________________________________________________________
内置于❤️ PageCloudv1团队