使用说明
MCP Collection(可译为“MCP系列”或根据具体语境调整)
一个集中式、自托管的模型上下文协议(MCP)基础设施,运行在 WSL 2 原生 Docker实现GitHub Copilot(适用于VS Code和CLI)与自建的强大MCP服务器之间的无缝集成。
🎯 概述
MCP系列 是一个完整且可投入生产的MCP(微服务云原生应用)栈,使您能够:
- ✅ 运行一个 MCP网关 负责协调多个MCP服务器
- ✅ 构建MCP服务器 来自源头 作为Docker容器
- ✅ 连接 VS Code GitHub Copilot(VS 代码 GitHub Copilot) 访问46+个GitHub工具
- ✅ 连接 GitHub Copilot 命令行界面(CLI) 用于AI驱动的命令行辅助
- ✅ 使用 WSL 2 原生 Docker (无需Windows Docker Desktop)
- ✅ 使用简单脚本管理所有基础设施
📋 您将获得
MCP 服务器(当前包含)
| 服务器 | 工具 | 状态 | 用途 |
|---|---|---|---|
| (无对应中文) | (无对应中文) | (无对应中文) | (无对应中文) |
| 46个工具 | ✅ 运行中 | 仓库管理、问题追踪、拉取请求、代码搜索 | ** |
| - | 🔧 即将推出 | 浏览器自动化和测试 | ** |
| - | 🔧 即将推出 | 文件操作和系统命令 |
支持的AI客户端 | 客户 | 状态 | 设置 | |--------|--------|-------| | VS Code GitHub Copilot | ✅ 正常工作 | 查看 VS Code 安装设置 | | GitHub Copilot 命令行界面(CLI) | 🔧 进行中 | 查看 Copilot CLI 设置 | | Claude 桌面版 | 📋 计划中 | 即将推出 | | 其他MCP客户端
| 📋 计划中 | 通用SSE端点已可用 |
🚀 快速入门
- 先决条件 Windows 11/10
- 启用WSL 2后 WSL 2 Ubuntu 22.04+
- 已安装 Docker
- 安装在WSL 2中(原生Linux Docker,非Docker Desktop) VS Code
- (用于GitHub Copilot集成) GitHub 个人访问令牌 (见获取您的代币
)
git clone https://github.com/yourusername/mcp-collection.git
cd mcp-collection
1️⃣ 克隆仓库
2️⃣ 设置您的GitHub令牌 .env 创建或更新
# Copy the example
cp .env.example .env
# Edit with your GitHub token
nano .env
项目根目录下的文件:
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
添加您的GitHub个人访问令牌:
- 获取您的令牌:
- 访问 https://github.com/settings/tokens
- 点击“生成新令牌”→“生成新令牌(经典版)”
- 选择这些范围:
repo✅ - (对私有仓库的完全控制)
read:user✅ - (读取用户资料数据)
read:org✅ - (阅读组织和团队成员信息)
gist✅
- 选择这些范围:
- (创建代码片段)
.env将令牌复制到您的
文件 ⚠️ 重要提示: .env 永远不要承诺
进行版本控制!
cd mcp
bash scripts/up.sh
3️⃣ 启动MCP网关
- 这将会:
- 从源代码构建自定义MCP网关
- 启动配备46种工具的GitHub MCP服务器
http://localhost:7350/sse
启动SSE端点
docker ps | grep mcp-gateway
curl http://localhost:7350/sse
验证它是否正在运行:
event: endpoint
data: /sse?sessionid=...
预期输出:
4️⃣ 连接您的AI客户端
- 选择您的客户: VS Code GitHub Copilot(可译为“VS 代码 GitHub Copilot”或保持原名以体现其专有性,根据上下文选择是否翻译)
- - 完整的IDE集成 GitHub Copilot 命令行界面 (CLI)
- 命令行AI助手
📦 安装与设置
git clone https://github.com/yourusername/mcp-collection.git
cd mcp-collection
克隆仓库
拉取MCP服务器源代码
cd mcp/servers
# Clone GitHub MCP Server
git clone https://github.com/modelcontextprotocol/servers.git github-temp
mv github-temp/src/github ./github
rm -rf github-temp
# Clone Playwright MCP Server
git clone https://github.com/microsoft/playwright-mcp.git playwright
# Clone Docker MCP Gateway
git clone https://github.com/docker/mcp-gateway.git docker-gateway
cd ../..
由于MCP服务器未包含在仓库中(以避免与上游更新发生冲突),您需要手动克隆它们:
bash mcp/scripts/setup-servers.sh
或者使用提供的设置脚本:
- 为什么服务器不在仓库中?
- ✅ 保持你的仓库大小小巧(约10MB而非约500MB)
- ✅ 允许您从原始仓库拉取上游更新
- ✅ 防止与服务器更新时的Git冲突
✅ 每台服务器都可以独立更新
cd mcp
# Build all server images
bash scripts/build-servers.sh
# Or build individually
docker build -t mcp-server-github:latest ./servers/github
docker build -t mcp-server-playwright:latest ./servers/playwright
docker build -t mcp-gateway-custom:latest ./servers/docker-gateway
构建 Docker 镜像
🔧 VS Code 设置
步骤1:配置VS Code .vscode/settings.json 该项目已包含
带有MCP网关配置。
如果你要打开的是不同的项目,请在VS Code用户设置中添加此配置: Ctrl+Shift+P 新闻界
“首选项:打开用户设置(JSON)”
{
"mcp": {
"servers": {
"mcp-gateway": {
"type": "sse",
"url": "http://localhost:7350/sse",
"timeout": 600000
}
}
}
}
添加或更新:
Ctrl+Shift+P → Developer: Reload Window
步骤2:重新加载VS Code
步骤3:在Copilot Chat中使用GitHub工具 Ctrl+Alt+I 新闻界;媒体
### Available GitHub Tools
#### Repository Management
- `list_repositories` - List your GitHub repositories
- `create_repository` - Create a new repository
- `get_repository` - Get repository details
- `fork_repository` - Fork a repository
- `search_repositories` - Search across GitHub
#### Issues
- `create_issue` - Create new issues
- `list_issues` - List issues in repositories
- `update_issue` - Update issue status, labels, etc.
- `add_issue_comment` - Comment on issues
- `search_issues` - Search issues
#### Pull Requests
- `create_pull_request` - Create new PRs
- `list_pull_requests` - List PRs
- `merge_pull_request` - Merge PRs
- `review_pull_request` - Review and comment on PRs
- `update_pull_request` - Update PR details
#### Code Operations
- `search_code` - Search code across repositories
- `get_file_contents` - Read file contents
- `push_files` - Push file changes
#### User & Organization
- `get_me` - Get your GitHub profile
- `get_authenticated_user` - Get authentication details
- `search_users` - Search GitHub users
- And 20+ more tools!
## 🛠️ Copilot CLI Setup
### Step 1: Install GitHub CLI (if not installed)
```bash
# WSL 2 Ubuntu
sudo apt update
sudo apt install gh -y
# Authenticate
gh auth login
打开 GitHub Copilot Chat 并试用
copilot --version
步骤2:验证Copilot CLI
第三步:配置MCP网关
Copilot CLI 目前需要本地 MCP 服务器。您有两个选择: 选项B:使用GitHub直接API
(不含MCP)
# List your repositories
gh repo list
# Search for repositories
gh repo search "machine learning"
# Create an issue
gh issue create --repo owner/repo --title "Bug fix" --body "Description"
目前,直接使用 GitHub CLI:
🐳 管理网关
cd mcp
bash scripts/up.sh
启动网关
cd mcp
bash scripts/down.sh
阻止网关
cd mcp
bash scripts/status.sh
检查网关状态
docker logs -f mcp-gateway
查看网关日志
cd mcp
bash scripts/down.sh && bash scripts/up.sh
重启网关
┌─────────────────────────────────────────┐
│ Windows (Client Layer) │
├─────────────────────────────────────────┤
│ VS Code Copilot / Copilot CLI │
│ (localhost:7350/sse via │
│ WSL 2 port forwarding) │
└─────────────────┬───────────────────────┘
│ HTTP SSE
┌─────────────────▼───────────────────────┐
│ WSL 2 (Gateway & Server Layer) │
├─────────────────────────────────────────┤
│ ┌─────────────────────────────────┐ │
│ │ MCP Gateway (Docker) │ │
│ │ Port 7350/sse │ │
│ └──────────┬──────────────────────┘ │
│ │ stdio
│ ┌──────────▼──────────────────────┐ │
│ │ GitHub MCP Server (Docker) │ │
│ │ 46 tools, 2 prompts, 5 resources │
│ └──────────┬──────────────────────┘ │
│ │ HTTPS
└─────────────▼───────────────────────────┘
│
GitHub.com API
🔌 架构
🔐 安全与令牌管理
- 令牌存储工作区
/mnt/d/Projects/MCP Collection/.env - 储存在集装箱
- 作为Docker密钥挂载到网关传输
仅使用HTTPS连接到GitHub API
最佳实践 ✅
- DO:(意为“做”或“执行”)
.env将令牌存储在 - (已添加到git忽略文件中)
- 定期更换令牌
- 使用最小必要的范围
确保代币的安全与私密性 ❌
- 不要:
.env提交(或“提交更改”) - 进行版本控制
- 分享你的代币
- 在生产环境中使用个人账户令牌
将令牌以明文形式存储在其他位置
🐛 故障排除
# Check logs
docker logs mcp-gateway
# Restart
cd mcp
bash scripts/down.sh
bash scripts/up.sh
网关无法启动
# Check if gateway is running
docker ps | grep mcp-gateway
# Test connection
curl http://localhost:7350/sse
本地主机(localhost)7350端口“连接被拒绝”
-
“401 坏凭证”(GitHub 令牌错误)
.env验证令牌中的(内容/信息)grep GITHUB_PERSONAL_ACCESS_TOKEN .env -
文件:
-
在 https://github.com/settings/tokens 生成新令牌
.env更新cd mcp && bash scripts/down.sh && bash scripts/up.sh
并重启网关:
- VS Code Copilot 无法找到 MCP 服务器
Ctrl+Shift+P重新加载 VS Code: - → “开发者:重新加载窗口”
http://localhost:7350/sse - 检查设置JSON中的URL是否正确:
docker ps | grep mcp-gateway
验证网关是否正在运行:
# Find what's using port 7350
lsof -i :7350
# Or change port in docker-compose.yml and gateway.yaml
端口7350已被占用
mcp-collection/
├── README.md # This file
├── .env # Your GitHub token (gitignored)
├── .env.example # Token template
├── project_vision.json # Project architecture & goals
├── TECH.md # Technical details
├── mcp/
│ ├── docker-compose.yml # Gateway orchestration
│ ├── gateway/
│ │ ├── config/
│ │ │ └── gateway.yaml # MCP server catalog
│ │ └── README.md
│ ├── servers/
│ │ ├── docker-gateway/ # MCP Gateway source (Docker)
│ │ ├── github/ # GitHub MCP Server source
│ │ └── playwright/ # Playwright MCP Server (coming)
│ ├── scripts/
│ │ ├── up.sh # Start gateway
│ │ ├── down.sh # Stop gateway
│ │ ├── status.sh # Check status
│ │ └── setup-forwarding.bat # Windows port forwarding
│ └── clients/
│ ├── vscode/
│ │ └── README.md # VS Code setup guide
│ └── copilot-cli/
│ └── README.md # Copilot CLI setup guide
└── docs/
├── architecture.md
├── setup.md
└── troubleshooting.md
📚 项目结构
- 🎓 学习资源 MCP规范
- - 官方MCP文档 Docker MCP 网关
- - 网关源 GitHub MCP 服务器
- - GitHub 集成 VS Code MCP 支持
- - 与VS Code集成 GitHub Copilot 命令行界面(CLI)
- CLI 文档
🤝 贡献
- 我们欢迎投稿!以下是参与方式: 叉子
- 仓库 创建
git checkout -b feature/amazing-feature一个特性分支( - ) 提交(或“提交更改”)
git commit -m 'Add amazing feature'变化( - ) 推
git push origin feature/amazing-feature分支( - ) 开放
一个拉取请求(Pull Request)
📝 许可证 这个项目遵循MIT许可证授权——详见 许可证
文件中详述。
- 🙋 支持 📖 书籍文档
/docs见 - 文件夹 **🐛 表示“虫子”或“错误(bug)”。**问题
- 在GitHub上提交一个问题(或:创建一个GitHub问题) **💬(表示对话或评论的符号,无具体含义,可理解为“说”或“评论”)**讨论
- 使用GitHub讨论区 📧 电子邮件(electronic mail)的符号电子邮件
[你的邮箱@example.com]
- 🗺️ 路线图
- [ ] ✅ GitHub MCP 服务器(已完成!)
- [ ] ✅ MCP网关设置(已完成!)
- [ ] ✅ 与 VS Code 的集成(已完成!)
- [ ] 🔄 Copilot CLI HTTP 支持
- [ ] 🔧 Playwright MCP 服务器
- [ ] 🔧 桌面指挥官MCP服务器
- [ ] 📋 Claude Desktop 集成
- [ ] 📋 多个MCP网关实例
- [ ] 📋 自定义MCP服务器模板
[ ] 📋 管理用的网页仪表盘
- GitHub 集成
为MCP社区用心打造