MCP 数据网关

状态：早期开发阶段。 项目脚手架（配置、依赖、文档）已就绪。src/ 下的源代码尚未实现 —— 请参阅开发路线图了解当前进度。实现计划位于 docs/plan.md。

一个基于 Python 的 模型上下文协议 (MCP) 服务器，充当统一数据网关，使 Claude（及其他 MCP 客户端）能够通过单一、安全的接口在多个外部 API 之间发送和接收数据。

概述

此 MCP 服务器提供：

通用数据处理，适用于多种数据类型
通用 API 网关，支持任何 REST 或 GraphQL 端点
OAuth 2.0 身份验证，具有自动基于浏览器的登录流程
安全凭据存储，使用系统密钥环 (keyring)
未来 MCP 应用演进的基础

功能

功能	描述
多 API 支持	通过统一配置连接到任意数量的外部服务
REST + GraphQL	原生支持 REST 和 GraphQL API
OAuth 2.0	完整的授权码流程，带有自动浏览器弹出窗口
令牌刷新	过期时自动刷新令牌并重新验证
安全存储	凭据通过系统密钥环加密存储
通用数据模型	灵活的模式以处理任何数据形状
自动身份验证	工具在需要时自动提示登录

架构

MCP/
├── src/
│   ├── server.py              # MCP server entry point
│   ├── auth/
│   │   ├── __init__.py
│   │   ├── oauth.py           # OAuth 2.0 flow handler with popup
│   │   └── credentials.py     # Secure credential storage (keyring)
│   ├── gateway/
│   │   ├── __init__.py
│   │   ├── api_client.py      # Generic REST/GraphQL HTTP client
│   │   └── handlers.py        # Request/response transformation
│   ├── models/
│   │   ├── __init__.py
│   │   └── data_models.py     # Generic Pydantic data models
│   └── tools/
│       ├── __init__.py
│       └── mcp_tools.py       # MCP tool definitions for Claude
├── config/
│   └── api_configs.json       # API service configurations
├── tests/                     # Unit and integration tests
├── .env.example               # Environment variables template
├── .gitignore                 # Excludes secrets and build artifacts
├── requirements.txt           # Python dependencies
└── README.md                  # This file

模块职责

核心 MCP 服务器 (`src/server.py`)

使用 Python mcp SDK 初始化 MCP 服务器
注册工具（fetch_data、send_data、execute_graphql 等）
处理工具执行生命周期和错误响应

身份验证 (`src/auth/`)

oauth.py: 带有自动浏览器弹出窗口的 OAuth 2.0 授权码流程。启动一个本地 HTTP 回调服务器以接收授权码。支持多个提供商（Google、GitHub、自定义）。
credentials.py: 通过系统密钥环安全存储访问/刷新令牌。处理令牌验证和过期。

API 网关 (`src/gateway/`)

api_client.py: 支持 REST (GET/POST/PUT/DELETE) 和 GraphQL (查询/变更) 的通用异步 HTTP 客户端。处理 Bearer 令牌、API 密钥、基本身份验证。
handlers.py: 规范化不同 API 之间的响应，并将 GraphQL 错误与 HTTP 错误分开解析。

MCP 工具 (`src/tools/mcp_tools.py`)

工具	描述
`fetch_data`	从配置的 API 获取数据（如果需要，自动进行 OAuth）
`send_data`	向配置的 API 发送 POST/PUT 数据（如果需要，自动进行 OAuth）
`execute_graphql`	运行 GraphQL 查询或变更（如果需要，自动进行 OAuth）
`list_apis`	列出所有配置的 API 服务
`get_status`	显示身份验证和连接状态

身份验证流程

当 Claude 调用需要身份验证的工具时：

1. Claude invokes tool (e.g., fetch_data)
        ↓
2. MCP checks credentials in keyring
        ↓
3a. Valid token  →  Proceed with API call
3b. Missing/Expired  →  Open browser popup for OAuth
        ↓
4. User logs in via browser
        ↓
5. Local callback server receives auth code
        ↓
6. Exchange auth code for access token
        ↓
7. Store token in keyring
        ↓
8. Resume original tool call

技术栈

Python 3.10+
mcp — 模型上下文协议 Python SDK
httpx — 异步 HTTP 客户端 (REST + GraphQL)
keyring — 跨平台安全凭据存储
pydantic — 数据验证和建模
python-dotenv — 环境变量管理

设置

先决条件

Python 3.10 或更高版本
pip 或 uv（推荐）

安装

# Clone the repository
cd /Users/chawengwit/Documents/MCP

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env
# Edit .env with your OAuth credentials and API settings

配置

1. 环境变量 (`.env`)

# OAuth credentials (per provider)
OAUTH_CLIENT_ID=your_client_id
OAUTH_CLIENT_SECRET=your_client_secret
OAUTH_REDIRECT_URI=http://localhost:8765/callback

# Server settings
MCP_LOG_LEVEL=INFO              # DEBUG | INFO | WARN | ERROR
MCP_LOG_FILE=                   # Optional path to log file (default: stderr only)
MCP_DEBUG=false                 # Enable verbose request tracing
MCP_MAX_RESPONSE_BYTES=1048576  # Response size cap (1 MB default)
OAUTH_CALLBACK_PORT=8765

2. API 配置 (`config/api_configs.json`)

{
  "apis": {
    "example_api": {
      "base_url": "https://api.example.com",
      "type": "rest",
      "auth": {
        "method": "oauth2",
        "provider": "custom",
        "authorize_url": "https://auth.example.com/oauth/authorize",
        "token_url": "https://auth.example.com/oauth/token",
        "scopes": ["read", "write"]
      },
      "endpoints": {
        "get_users": {"method": "GET", "path": "/users"},
        "create_user": {"method": "POST", "path": "/users"}
      }
    }
  }
}

使用方法

运行 MCP 服务器

python -m src.server

连接到 Claude Code

将此配置添加到您的 Claude Code MCP 设置中：

{
  "mcpServers": {
    "data-gateway": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/Users/chawengwit/Documents/MCP"
    }
  }
}

交互示例

连接后，Claude 可以：

列出已配置的 API：“显示可用的 API 服务”
获取数据：“从 example_api 获取用户列表”
发送数据：“使用此数据在 example_api 中创建新记录...”
执行 GraphQL：“针对我的 API 运行此 GraphQL 查询...”

Claude 首次使用需要身份验证的工具时，您的浏览器将自动打开以进行 OAuth 登录。

响应格式

所有 MCP 工具都返回结构化的 JSON 以实现一致的解析。

成功：

{
  "data": <api response>,
  "metadata": { "source": "...", "endpoint": "...", "timestamp": "...", "duration_ms": 142 }
}

错误：

{
  "error": { "code": "AUTH_REQUIRED", "message": "...", "details": { ... } }
}

标准错误代码： AUTH_REQUIRED, AUTH_FAILED, API_NOT_CONFIGURED, ENDPOINT_NOT_FOUND, RATE_LIMITED, UPSTREAM_ERROR, VALIDATION_ERROR, RESPONSE_TOO_LARGE。

大于 MCP_MAX_RESPONSE_BYTES 的 JSON/文本响应将被截断并作为成功返回，并带有 metadata.truncated: true 和分页游标。只有二进制或流式负载会发出 RESPONSE_TOO_LARGE（它们无法安全截断）。二进制数据使用 content_type 元数据进行 base64 编码。GraphQL 响应会同时显示 data 和 errors，因此部分成功仍然可用。

有关详细信息，请参阅 CLAUDE.md。

调试

快速诊断

症状	尝试
工具在第一次调用时挂起	检查 `OAUTH_CALLBACK_PORT` 是否空闲
`keyring.errors.NoKeyringError`	安装 `keyrings.alt` (无头 Linux)
之前工作正常后出现 401	删除密钥环条目，重新验证
GraphQL “成功”但没有数据	检查响应体中的 `errors[]`
响应被截断	使用分页或提高 `MCP_MAX_RESPONSE_BYTES`

启用调试模式

MCP_DEBUG=true MCP_LOG_LEVEL=DEBUG python -m src.server

这会将完整的 HTTP 交换（已屏蔽机密信息）转储到 stderr。绝不要转储到 stdout — stdout 承载 MCP JSON-RPC 协议流。

日志记录说明

所有日志都发送到 stderr（或可选的 MCP_LOG_FILE）。
令牌、API 密钥、Authorization 标头和凭据在记录前会自动屏蔽。
日志是结构化的 JSON（每行一个事件），便于使用 jq 进行解析。

有关完整的调试策略，请参阅 CLAUDE.md。

开发路线图

第一阶段：项目设置

[x] 带有固定依赖项的 requirements.txt
[x] 用于机密和缓存的 .gitignore
[x] 记录环境变量的 .env.example
[ ] 初始化 src/ 包结构
[ ] 初始 config/api_configs.json 模板

第二阶段：核心 MCP 服务器

[ ] MCP 服务器初始化
[ ] 工具模式定义
[ ] 日志记录和错误处理

第三阶段：身份验证

[ ] OAuth 2.0 授权码流程
[ ] 本地回调 HTTP 服务器
[ ] 基于密钥环的令牌存储
[ ] 令牌刷新逻辑

第四阶段：API 网关

[ ] 通用 REST 客户端
[ ] GraphQL 查询/变更支持
[ ] 多种身份验证方法支持
[ ] 请求/响应处理程序

第五阶段：工具与集成

[ ] 实现 fetch_data 工具
[ ] 实现 send_data 工具
[ ] 实现 execute_graphql 工具
[ ] 实现 list_apis 和 get_status 工具

第六阶段：测试与完善

[ ] 每个模块的单元测试
[ ] 使用模拟 API 的集成测试
[ ] 配置示例
[ ] 用户文档

未来增强功能

MCP 应用：作为此网关前端的独立 Web 界面
持久存储：用于数据历史记录和审计日志的 SQLite/PostgreSQL
速率限制：针对每个 API 的速率限制和请求排队
缓存：具有可配置 TTL 的响应缓存
多租户：支持具有单独凭据存储的多个用户
Webhooks：通过传入的 Webhooks 接收数据
数据转换管道：跨 API 链接转换

安全性

所有凭据都存储在操作系统级的安全密钥环中（macOS 上的 Keychain，Windows 上的 Credential Manager，Linux 上的 Secret Service）
.env 文件通过 .gitignore 从版本控制中排除
OAuth 使用标准的授权码流程（无隐式授权）
令牌绝不会被记录或在错误消息中暴露
本地回调服务器仅在 localhost 上监听，且仅在 OAuth 流程期间监听

许可证

待定

贡献

本项目处于早期开发阶段。一旦核心实现稳定，将添加贡献指南。