MCP Data Gateway

Статус: Ранняя разработка. Каркас проекта (конфигурация, зависимости, документация) готов. Исходный код в src/ еще не реализован — текущий прогресс см. в Дорожной карте разработки. План реализации находится в docs/plan.md.

MCP-сервер (Model Context Protocol) на базе Python, который выступает в качестве унифицированного шлюза данных, позволяя Claude (и другим MCP-клиентам) отправлять и получать данные через несколько внешних API через единый безопасный интерфейс.

Обзор

Этот MCP-сервер предоставляет:

• Универсальную обработку данных для различных типов данных

• Универсальный API-шлюз, поддерживающий любую конечную точку REST или GraphQL

• Аутентификацию OAuth 2.0 с автоматическим процессом входа через браузер

• Безопасное хранение учетных данных с использованием системной связки ключей (keyring)

• Фундамент для развития MCP-приложения в будущем

Функции

Архитектура

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)

• Инициализирует MCP-сервер с использованием Python 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: Универсальный асинхронный HTTP-клиент, поддерживающий REST (GET/POST/PUT/DELETE) и GraphQL (запросы/мутации). Обрабатывает Bearer-токены, API-ключи, базовую аутентификацию.

• handlers.py: Нормализует ответы от разных API и анализирует ошибки GraphQL отдельно от ошибок HTTP.

Инструменты MCP (src/tools/mcp_tools.py)

Поток аутентификации

Когда 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 для Model Context Protocol

• 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

Добавьте эту конфигурацию в настройки MCP вашего Claude Code:

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

Примеры взаимодействия

После подключения Claude может:

• Перечислить настроенные API: "Покажи мне доступные API-сервисы"

• Получить данные: "Получи список пользователей из example_api"

• Отправить данные: "Создай новую запись в example_api с этими данными..."

• Выполнить GraphQL: "Выполни этот GraphQL-запрос к моему API..."

При первом использовании 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.

JSON/текстовые ответы, превышающие MCP_MAX_RESPONSE_BYTES, обрезаются и возвращаются как успешные с metadata.truncated: true плюс курсоры пагинации. Только бинарные или потоковые полезные нагрузки выдают RESPONSE_TOO_LARGE (их нельзя безопасно обрезать). Бинарные данные кодируются в base64 с метаданными content_type. Ответы GraphQL отображают как data, так и errors, поэтому частичные успехи остаются пригодными для использования.

Подробности см. в CLAUDE.md.

Отладка

Быстрая диагностика

Включение режима отладки

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 для получения полной стратегии отладки.

Дорожная карта разработки

Фаза 1: Настройка проекта

• [x] requirements.txt с зафиксированными зависимостями

• [x] .gitignore для секретов и кэшей

• [x] .env.example с описанием переменных окружения

• [ ] Инициализация структуры пакета src/

• [ ] Начальный шаблон config/api_configs.json

Фаза 2: Основной MCP-сервер

• [ ] Инициализация MCP-сервера

• [ ] Определение схем инструментов

• [ ] Логирование и обработка ошибок

Фаза 3: Аутентификация

• [ ] Поток кода авторизации OAuth 2.0

• [ ] Локальный HTTP-сервер обратного вызова

• [ ] Хранение токенов на основе keyring

• [ ] Логика обновления токенов

Фаза 4: API-шлюз

• [ ] Универсальный REST-клиент

• [ ] Поддержка GraphQL-запросов/мутаций

• [ ] Поддержка нескольких методов аутентификации

• [ ] Обработчики запросов/ответов

Фаза 5: Инструменты и интеграция

• [ ] Реализация инструмента fetch_data

• [ ] Реализация инструмента send_data

• [ ] Реализация инструмента execute_graphql

• [ ] Реализация инструментов list_apis и get_status

Фаза 6: Тестирование и полировка

• [ ] Модульные тесты для каждого модуля

• [ ] Интеграционные тесты с фиктивными API

• [ ] Примеры конфигурации

• [ ] Документация для пользователей

Будущие улучшения

• MCP App: Автономный веб-интерфейс в качестве фронтенда поверх этого шлюза

• Постоянное хранилище: SQLite/PostgreSQL для истории данных и журналов аудита

• Ограничение скорости (Rate Limiting): Ограничение скорости и очередь запросов для каждого API

• Кэширование: Кэширование ответов с настраиваемым TTL

• Мультиарендность (Multi-Tenant): Поддержка нескольких пользователей с отдельными хранилищами учетных данных

• Вебхуки: Получение данных через входящие вебхуки

• Конвейеры преобразования данных: Цепочки преобразований между API

Безопасность

• Все учетные данные хранятся в безопасной системной связке ключей (Keychain в macOS, Диспетчер учетных данных в Windows, Secret Service в Linux)

• Файл .env исключен из системы контроля версий через .gitignore

• OAuth использует стандартный поток кода авторизации (без implicit grant)

• Токены никогда не логируются и не отображаются в сообщениях об ошибках

• Локальный сервер обратного вызова прослушивает только localhost и только во время процесса OAuth

Лицензия

Будет определено позже

Участие в разработке

Проект находится на ранней стадии разработки. Руководство по участию будет добавлено, как только основная реализация станет стабильной.