Puerta de enlace de datos MCP

Estado: Desarrollo inicial. El andamiaje del proyecto (configuración, dependencias, documentos) está listo. El código fuente en src/ aún no se ha implementado; consulte la Hoja de ruta de desarrollo para conocer el progreso actual. El plan de implementación está en docs/plan.md.

Un servidor del Protocolo de Contexto de Modelo (MCP) basado en Python que actúa como una puerta de enlace de datos unificada, permitiendo a Claude (y a otros clientes MCP) enviar y recibir datos a través de múltiples API externas mediante una única interfaz segura.

Descripción general

Este servidor MCP proporciona:

• Manejo genérico de datos para múltiples tipos de datos

• Puerta de enlace API genérica compatible con cualquier endpoint REST o GraphQL

• Autenticación OAuth 2.0 con flujo de inicio de sesión automático basado en navegador

• Almacenamiento seguro de credenciales utilizando el llavero del sistema

• Base para la evolución de la aplicación MCP en el futuro

Características

Arquitectura

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

Responsabilidades de los módulos

Servidor MCP central (src/server.py)

• Inicializa el servidor MCP utilizando el SDK de Python mcp

• Registra herramientas (fetch_data, send_data, execute_graphql, etc.)

• Maneja el ciclo de vida de ejecución de herramientas y las respuestas de error

Autenticación (src/auth/)

• oauth.py: Flujo de código de autorización OAuth 2.0 con ventana emergente automática del navegador. Inicia un servidor de devolución de llamada HTTP local para recibir el código de autenticación. Admite múltiples proveedores (Google, GitHub, personalizados).

• credentials.py: Almacenamiento seguro de tokens de acceso/actualización a través del llavero del sistema. Maneja la validación y caducidad de tokens.

Puerta de enlace API (src/gateway/)

• api_client.py: Cliente HTTP asíncrono genérico compatible con REST (GET/POST/PUT/DELETE) y GraphQL (consultas/mutaciones). Maneja tokens Bearer, claves API, autenticación básica.

• handlers.py: Normaliza las respuestas entre diferentes API y analiza los errores de GraphQL por separado de los errores HTTP.

Herramientas MCP (src/tools/mcp_tools.py)

Flujo de autenticación

Cuando Claude llama a una herramienta que requiere autenticación:

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

Stack tecnológico

• Python 3.10+

• mcp — SDK de Python para el Protocolo de Contexto de Modelo

• httpx — Cliente HTTP asíncrono (REST + GraphQL)

• keyring — Almacenamiento seguro de credenciales multiplataforma

• pydantic — Validación y modelado de datos

• python-dotenv — Gestión de variables de entorno

Configuración

Requisitos previos

• Python 3.10 o superior

• pip o uv (recomendado)

Instalación

# 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

Configuración

1. Variables de entorno (.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. Configuraciones de 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"}
      }
    }
  }
}

Uso

Ejecución del servidor MCP

python -m src.server

Conexión a Claude Code

Agregue esta configuración a sus ajustes de MCP de Claude Code:

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

Ejemplos de interacción

Una vez conectado, Claude puede:

• Listar API configuradas: "Muéstrame los servicios API disponibles"

• Obtener datos: "Obtén la lista de usuarios de example_api"

• Enviar datos: "Crea un nuevo registro en example_api con estos datos..."

• Ejecutar GraphQL: "Ejecuta esta consulta GraphQL contra mi API..."

La primera vez que Claude utiliza una herramienta que requiere autenticación, su navegador se abrirá automáticamente para el inicio de sesión OAuth.

Formato de respuesta

Todas las herramientas MCP devuelven JSON estructurado para un análisis consistente.

Éxito:

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

Error:

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

Códigos de error estándar: AUTH_REQUIRED, AUTH_FAILED, API_NOT_CONFIGURED, ENDPOINT_NOT_FOUND, RATE_LIMITED, UPSTREAM_ERROR, VALIDATION_ERROR, RESPONSE_TOO_LARGE.

Las respuestas JSON/texto más grandes que MCP_MAX_RESPONSE_BYTES se truncan y se devuelven como éxito con metadata.truncated: true además de cursores de paginación. Solo las cargas útiles binarias o de transmisión emiten RESPONSE_TOO_LARGE (no se pueden truncar de forma segura). Los datos binarios están codificados en base64 con metadatos content_type. Las respuestas de GraphQL muestran tanto data como errors para que los éxitos parciales sigan siendo utilizables.

Consulte CLAUDE.md para obtener todos los detalles.

Depuración

Diagnóstico rápido

Habilitación del modo de depuración

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

Esto vuelca los intercambios HTTP completos (con secretos redactados) a stderr. Nunca a stdout — stdout transporta el flujo del protocolo JSON-RPC de MCP.

Notas de registro

• Todos los registros van a stderr (o al MCP_LOG_FILE opcional).

• Los tokens, las claves API, los encabezados Authorization y las credenciales se redactan automáticamente antes de registrarse.

• Los registros son JSON estructurados (un evento por línea) para facilitar el análisis con jq.

Consulte CLAUDE.md para conocer la estrategia completa de depuración.

Hoja de ruta de desarrollo

Fase 1: Configuración del proyecto

• [x] requirements.txt con dependencias fijadas

• [x] .gitignore para secretos y cachés

• [x] .env.example documentando variables de entorno

• [ ] Inicializar la estructura del paquete src/

• [ ] Plantilla inicial config/api_configs.json

Fase 2: Servidor MCP central

• [ ] Inicialización del servidor MCP

• [ ] Definiciones de esquema de herramientas

• [ ] Registro y manejo de errores

Fase 3: Autenticación

• [ ] Flujo de código de autorización OAuth 2.0

• [ ] Servidor HTTP de devolución de llamada local

• [ ] Almacenamiento de tokens basado en llavero

• [ ] Lógica de actualización de tokens

Fase 4: Puerta de enlace API

• [ ] Cliente REST genérico

• [ ] Soporte para consultas/mutaciones GraphQL

• [ ] Soporte para múltiples métodos de autenticación

• [ ] Manejadores de solicitud/respuesta

Fase 5: Herramientas e integración

• [ ] Implementar la herramienta fetch_data

• [ ] Implementar la herramienta send_data

• [ ] Implementar la herramienta execute_graphql

• [ ] Implementar las herramientas list_apis y get_status

Fase 6: Pruebas y pulido

• [ ] Pruebas unitarias por módulo

• [ ] Pruebas de integración con API simuladas

• [ ] Ejemplos de configuración

• [ ] Documentación de usuario

Mejoras futuras

• Aplicación MCP: Interfaz web independiente como frontend sobre esta puerta de enlace

• Almacenamiento persistente: SQLite/PostgreSQL para historial de datos y registros de auditoría

• Limitación de tasa: Limitación de tasa por API y cola de solicitudes

• Almacenamiento en caché: Almacenamiento en caché de respuestas con TTL configurable

• Multi-inquilino: Soporte para múltiples usuarios con almacenes de credenciales separados

• Webhooks: Recibir datos a través de webhooks entrantes

• Canalizaciones de transformación de datos: Encadenar transformaciones entre API

Seguridad

• Todas las credenciales almacenadas en el llavero seguro a nivel de SO (Keychain en macOS, Administrador de credenciales en Windows, Secret Service en Linux)

• Archivo .env excluido del control de versiones mediante .gitignore

• OAuth utiliza el flujo de código de autorización estándar (sin concesión implícita)

• Los tokens nunca se registran ni se exponen en mensajes de error

• El servidor de devolución de llamada local solo escucha en localhost y solo durante el flujo OAuth

Licencia

Por determinar

Contribución

Este proyecto está en desarrollo inicial. Las pautas de contribución se agregarán una vez que la implementación central sea estable.