内容
# GitHub v3 REST API 服务器
这款 MCP（模型内容协议）服务器通过 FastMCP 的 STDIO 传输模式提供对 GitHub v3 REST API 功能的访问。
## 功能特点
- 基于 FastMCP 的服务器，采用装饰器模式
- 通过 `@mcp.tool()` 装饰器实现自动工具注册
- 类型安全的参数处理
- 全面的错误处理和日志记录
- 通过环境变量轻松配置
## 前置条件
- Python 3.10 或更高版本
- pip 包管理器
## 安装
1. 安装依赖：
```bash
pip install -r requirements.txt
```
2. 配置环境变量：
```bash
export API_BASE_URL="https://your-api-base-url"
export BEARER_TOKEN="your-bearer-token"
# 替代身份验证选项（仅使用一个）：
# export API_KEY="your-api-key"
# export BASIC_AUTH="your-basic-auth-credentials"
```
## 运行 MCP 服务器
### STDIO 模式（默认）
服务器默认在 STDIO 模式下运行，非常适合与 Cursor 等 AI 助手直接集成：
```bash
python main.py
```
### Cursor/Claude Desktop 配置
将以下内容添加到您的 MCP 配置文件（例如 `~/Library/Application Support/Cursor/User/globalStorage/@anthropic/mcp-server-registry/mcp.json`）：
```json
{
"mcpServers": {
"github-v3-rest-api-mcp-server": {
"command": "python",
"args": ["/path/to/your/project/main.py"],
"env": {
"API_BASE_URL": "https://your-api-base-url",
"BEARER_TOKEN": "your-bearer-token"
}
}
}
}
```
## 环境变量
### 必需
- `API_BASE_URL`：API 端点的基准 URL
### 身份验证（使用以下之一）
- `BEARER_TOKEN`：OAuth2/Bearer 身份验证的 Bearer Token
- `API_KEY`：API 密钥身份验证的 API 密钥
- `BASIC_AUTH`：基本身份验证凭证（base64 编码）
**注意**：除非 API 明确不需要身份验证，否则应提供至少一个身份验证变量。
## 开发
使用自动重载进行开发：
```bash
# 安装开发依赖
pip install -r requirements.txt
# 使用 Python 运行
python main.py
```
## 项目结构
```
.
├── main.py # FastMCP 服务器的入口点
├── config.py # 配置管理
├── models.py # Pydantic 数据模型
├── tools/ # 按类别组织的自动生成工具
│ ├── __init__.py
│ └── [category]/ # 按 API 端点类别分组的工具
│ ├── __init__.py
│ └── *.py # 单个工具实现
├── requirements.txt # Python 依赖
└── README.md # 本文件
```
## 工作原理
该 MCP 服务器使用具有基于装饰器的架构的 FastMCP 构建：
1. **FastMCP 服务器**：在 `main.py` 中创建 MCP 服务器实例
2. **工具装饰器**：每个工具都使用 `@mcp.tool()` 进行自动注册
3. **自动导入**：工具在导入其模块时自动注册
4. **类型安全**：使用 Python 类型提示进行参数验证
5. **错误处理**：具有 JSON 错误响应的全面错误处理
### 示例工具
```python
from main import mcp
@mcp.tool()
def get_users(search: str = None, page: int = None) -> str:
"""
从 API 获取用户。
参数：
search: 用于过滤用户的搜索查询
page: 用于分页的页码
返回：
包含用户数据的 JSON 字符串
"""
# 工具实现...
return json.dumps(result, indent=2)
```
## 身份验证方法
服务器支持多种身份验证方法：
### Bearer Token（OAuth2）
```bash
export BEARER_TOKEN="your-bearer-token"
```
### API 密钥
```bash
export API_KEY="your-api-key"
```
### 基本身份验证
```bash
export BASIC_AUTH="base64-encoded-credentials"
```
## 日志记录
服务器包含到 stderr 的综合日志记录：
- INFO 级别：常规操作、工具注册
- WARNING 级别：跳过的操作、缺失的参数
- ERROR 级别：API 错误、请求失败
在 MCP 客户端的控制台或 stderr 输出中查看日志。
## 故障排除
### “缺少必需参数”错误
- 检查是否提供了所有必需参数
- 验证参数名称是否与工具定义匹配
### 身份验证错误
- 确保设置了正确的身份验证环境变量
- 验证您的凭证是否有效且未过期
- 检查 API_BASE_URL 是否正确
### 导入错误
- 运行 `pip install -r requirements.txt` 以确保安装所有依赖
- 检查您是否正在使用 Python 3.10 或更高版本
### 工具未找到
- 验证工具名称是否与 MCP 客户端中显示的名称匹配
- 检查工具目录结构
- 确保所有 `__init__.py` 文件均存在
## 生成的工具
此服务器是根据 OpenAPI 规范自动生成的。每个 API 端点都作为 MCP 工具公开，具有：
- 自动参数提取和验证
- 类型安全的参数处理
- 全面的错误处理
- JSON 响应格式化
使用您的 MCP 客户端的工具列表功能查看所有可用的工具。
## 贡献
这是生成的 MCP 服务器。要修改工具行为：
1. 编辑 `tools/[category]/[tool_name].py` 中的工具实现
2. 保留 `@mcp.tool()` 装饰器进行注册
3. 保留函数签名进行参数验证
4. 通过在本地运行服务器来测试更改
## 许可证
此生成的 MCP 服务器遵循与生成器工具相同的许可证。
