Google Maps API

GitHub v3 REST API MCP 服务器

这个MCP（模型内容协议）服务器通过STDIO传输模式与FastMCP一起，提供对GitHub v3 REST API功能的访问。

特点/特性

• 基于FastMCP且采用装饰器模式的服务器
• 通过@mcp.tool()装饰器实现工具的自动注册
• 类型安全的参数处理
• 全面的错误处理和日志记录
• 通过环境变量轻松配置

先决条件

• Python 3.10或更高版本
• pip包管理器

安装

1. 安装依赖项：

pip install -r requirements.txt

1. 配置环境变量：

export API_BASE_URL="https://your-api-base-url"
export BEARER_TOKEN="your-bearer-token"
# Alternative authentication options (use only one):
# export API_KEY="your-api-key"
# export BASIC_AUTH="your-basic-auth-credentials"

运行MCP服务器

STDIO 模式（默认）

服务器默认以STDIO模式运行，这非常适合与Cursor等AI助手直接集成：

python main.py

Cursor/Claude 桌面版配置

将此添加到您的MCP配置文件中（例如。， ~/Library/Application Support/Cursor/User/globalStorage/@anthropic/mcp-server-registry/mcp.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_URLAPI端点的基础URL

认证（使用以下其中一种方法）

• BEARER_TOKEN用于OAuth2/承载令牌认证的承载令牌
• API_KEYAPI密钥用于API密钥认证
• BASIC_AUTH基本认证凭据（base64编码）

注除非API明确不需要认证，否则应提供至少一个认证变量。

发展

对于支持自动重载的开发：

# Install development dependencies
pip install -r requirements.txt

# Run with Python
python main.py

项目结构

.
├── main.py              # Entry point with FastMCP server
├── config.py            # Configuration management
├── models.py            # Pydantic data models
├── tools/               # Auto-generated tools organized by category
│   ├── __init__.py
│   └── [category]/      # Tools grouped by API endpoint category
│       ├── __init__.py
│       └── *.py         # Individual tool implementations
├── requirements.txt     # Python dependencies
└── README.md           # This file

它是如何工作的

这个MCP服务器是使用FastMCP构建的，采用了基于装饰器的架构：

1. FastMCP 服务器在（某处）创建一个MCP服务器实例 main.py
2. 工具装饰器每件工具都装饰着 @mcp.tool() 用于自动注册
3. 自动导入当导入工具模块时，工具会自动注册
4. 类型安全使用Python类型提示进行参数验证
5. 错误处理使用JSON错误响应进行全面的错误处理

示例工具

from main import mcp

@mcp.tool()
def get_users(search: str = None, page: int = None) -> str:
    """
    Get users from the API.
    
    Args:
        search: Search query for filtering users
        page: Page number for pagination
        
    Returns:
        JSON string with user data
    """
    # Tool implementation...
    return json.dumps(result, indent=2)

认证方法

服务器支持多种认证方法：

Bearer Token（OAuth2）

export BEARER_TOKEN="your-bearer-token"

API密钥

export API_KEY="your-api-key"

基本认证

export BASIC_AUTH="base64-encoded-credentials"

记录（日志）

服务器包含对标准错误输出（stderr）的全面日志记录：

• INFO级别：一般操作，工具注册
• 警告级别：跳过操作，缺少参数
• ERROR级别：API错误，请求失败

在您的MCP客户端控制台或标准错误输出中查看日志。

故障排除

“缺少必需参数”错误

• 检查是否提供了所有必需的参数
• 验证参数名称是否与工具定义相匹配

认证错误

• 确保设置了正确的认证环境变量
• 验证您的凭证是否有效且未过期
• 检查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服务器遵循与生成工具相同的许可协议。