GitHub MCP Server Integration

GitHub MCP 服务集成

本项目展示了一个与 GitHub API 集成的 Model Context Protocol（MCP）服务。它允许 Claude 或 OpenAI GPT 等 AI 助手通过 MCP 与 GitHub 交互。

---

🌐 在线演示

👉 已部署的服务链接
👉 .well-known/ai-plugin.json 端点：

https://github-mcp-server-production.up.railway.app/.well-known/ai-plugin.json

---

📖 项目概述

此 MCP 服务提供了一个 REST API，允许 AI 助手：

• 获取用户的 GitHub 个人资料信息
• 列出用户的仓库
• 在仓库中创建议题

该服务遵循 Model Context Protocol（MCP） 标准，确保与 AI 系统互操作。

---

🔧 技术栈

• FastAPI（用于构建 API 的 Python 框架）
• OpenAPI（描述 REST API 的标准）
• ai-plugin.json（MCP 元数据配置）
• GitHub REST API v3
• 部署在 Railway 上

---

✨ 功能

• 符合 MCP 标准且提供 OpenAPI 文档的服务
• 使用个人访问令牌与 GitHub 安全交互
• AI 助手可以：
  • 获取 GitHub 用户详情
  • 按用户名列出仓库
  • 在仓库中创建议题

---

📂 项目结构

├── ai-plugin.json             # MCP Plugin metadata for AI Assistants
├── openapi.yaml               # OpenAPI spec describing the available endpoints
├── main.py                    # FastAPI MCP server code
├── requirements.txt           # Python dependencies
└── README.md                  # Project documentation (this file)

---

🚀 工作原理

1. FastAPI 服务

• 提供以下 REST API 端点：
  • /github/user
  • /github/repos/{username}
  • /github/repos/{owner}/{repo}/issues

2. ai-plugin.json

• 供 AI 助手了解 MCP 服务的元数据：
  • 插件名称、描述
  • 身份验证方式
  • OpenAPI URL 引用

3. openapi.yaml

• 定义 AI 助手进行交互所需的所有路由和参数。

---

🔐 身份验证

• GitHub 个人访问令牌（PAT）
  • 设置为环境变量：GITHUB_TOKEN
  • 在 .env 文件中设置，或直接在 Railway 的环境设置中配置。

---

⚙️ 设置说明（本地开发）

前置条件：

• Python 3.9+
• 具有 repo 权限的 GitHub 个人访问令牌（PAT）

克隆仓库：

git clone https://github.com/yourusername/github-mcp-server.git
cd github-mcp-server

安装依赖：

pip install -r requirements.txt

创建 .env 文件：

GITHUB_TOKEN=your_personal_access_token

运行 FastAPI 服务：

uvicorn main:app --reload

访问 http://localhost:8000/docs 查看 Swagger UI

---

🌍 部署（Railway）

1. 登录 Railway
2. 创建新项目 → 从 GitHub 部署 → 选择你的 MCP 仓库
3. 在 Railway 中将 GITHUB_TOKEN 添加为环境变量
4. 确认启动命令：

   uvicorn main:app --host 0.0.0.0 --port 8000
   

5. 部署并获取生产环境 URL（例如，https://github-mcp-server-production.up.railway.app）

---

🤖 使用 AI 助手进行演示

Claude AI / OpenAI GPT 插件（是否可用取决于访问权限）

• 在 AI 助手设置中注册 .well-known/ai-plugin.json URL。
• 使用自然语言提示词进行交互：

  "List my GitHub repositories."
  "Create an issue in my repo named 'sample-repo'."
  

---

📜 OpenAPI 端点

端点	方法	描述
/github/user	GET	获取已通过身份验证的用户信息
/github/repos/{username}	GET	列出用户的仓库
/github/repos/{owner}/{repo}/issues	POST	在仓库中创建议题

---

📝 请求示例

获取用户信息

curl -X GET https://github-mcp-server-production.up.railway.app/github/user

列出仓库

curl -X GET https://github-mcp-server-production.up.railway.app/github/repos/<username>

创建议题

curl -X POST https://github-mcp-server-production.up.railway.app/github/repos/<owner>/<repo>/issues \
  -H "Content-Type: application/json" \
  -d '{"title": "Bug found!", "body": "Please fix this bug."}'

---