MCP Data Gateway

Status: Frühe Entwicklungsphase. Das Projektgerüst (Konfiguration, Abhängigkeiten, Dokumentation) steht. Der Quellcode unter src/ wurde noch nicht implementiert – siehe die Entwicklungs-Roadmap für den aktuellen Fortschritt. Der Implementierungsplan befindet sich unter docs/plan.md.

Ein auf Python basierender Model Context Protocol (MCP) Server, der als vereinheitlichtes Daten-Gateway fungiert und es Claude (sowie anderen MCP-Clients) ermöglicht, Daten über mehrere externe APIs hinweg über eine einzige, sichere Schnittstelle zu senden und zu empfangen.

Übersicht

Dieser MCP-Server bietet:

• Generische Datenverarbeitung für mehrere Datentypen

• Generisches API-Gateway, das jeden REST- oder GraphQL-Endpunkt unterstützt

• OAuth 2.0-Authentifizierung mit automatischem browserbasiertem Login-Ablauf

• Sichere Speicherung von Anmeldedaten unter Verwendung des System-Keyrings

• Grundlage für die zukünftige Entwicklung einer MCP-App

Funktionen

Architektur

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

Modulverantwortlichkeiten

Core MCP Server (src/server.py)

• Initialisiert den MCP-Server unter Verwendung des Python mcp SDK

• Registriert Tools (fetch_data, send_data, execute_graphql usw.)

• Behandelt den Ausführungslebenszyklus von Tools und Fehlerantworten

Authentifizierung (src/auth/)

• oauth.py: OAuth 2.0 Authorization-Code-Flow mit automatischem Browser-Popup. Startet einen lokalen HTTP-Callback-Server, um den Auth-Code zu empfangen. Unterstützt mehrere Anbieter (Google, GitHub, benutzerdefiniert).

• credentials.py: Sichere Speicherung von Zugriffs-/Aktualisierungs-Tokens über den System-Keyring. Behandelt Token-Validierung und Ablauf.

API Gateway (src/gateway/)

• api_client.py: Generischer asynchroner HTTP-Client, der REST (GET/POST/PUT/DELETE) und GraphQL (Queries/Mutations) unterstützt. Behandelt Bearer-Tokens, API-Keys und Basic Auth.

• handlers.py: Normalisiert Antworten über verschiedene APIs hinweg und analysiert GraphQL-Fehler getrennt von HTTP-Fehlern.

MCP Tools (src/tools/mcp_tools.py)

Authentifizierungsablauf

Wenn Claude ein Tool aufruft, das eine Authentifizierung erfordert:

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

Tech-Stack

• Python 3.10+

• mcp — Model Context Protocol Python SDK

• httpx — Asynchroner HTTP-Client (REST + GraphQL)

• keyring — Plattformübergreifende sichere Speicherung von Anmeldedaten

• pydantic — Datenvalidierung und -modellierung

• python-dotenv — Verwaltung von Umgebungsvariablen

Einrichtung

Voraussetzungen

• Python 3.10 oder höher

• pip oder uv (empfohlen)

Installation

# 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

Konfiguration

1. Umgebungsvariablen (.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-Konfigurationen (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"}
      }
    }
  }
}

Verwendung

Ausführen des MCP-Servers

python -m src.server

Verbindung zu Claude Code

Fügen Sie diese Konfiguration zu Ihren Claude Code MCP-Einstellungen hinzu:

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

Beispielinteraktionen

Sobald die Verbindung hergestellt ist, kann Claude:

• Konfigurierte APIs auflisten: "Zeige mir die verfügbaren API-Dienste"

• Daten abrufen: "Hole die Benutzerliste von example_api"

• Daten senden: "Erstelle einen neuen Datensatz in example_api mit diesen Daten..."

• GraphQL ausführen: "Führe diese GraphQL-Query gegen meine API aus..."

Wenn Claude zum ersten Mal ein Tool verwendet, das eine Authentifizierung erfordert, öffnet sich Ihr Browser automatisch für den OAuth-Login.

Antwortformat

Alle MCP-Tools geben strukturiertes JSON für eine konsistente Analyse zurück.

Erfolg:

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

Fehler:

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

Standard-Fehlercodes: AUTH_REQUIRED, AUTH_FAILED, API_NOT_CONFIGURED, ENDPOINT_NOT_FOUND, RATE_LIMITED, UPSTREAM_ERROR, VALIDATION_ERROR, RESPONSE_TOO_LARGE.

JSON/Text-Antworten, die größer als MCP_MAX_RESPONSE_BYTES sind, werden gekürzt und als Erfolg zurückgegeben, mit metadata.truncated: true sowie Paginierungs-Cursorn. Nur binäre oder Streaming-Payloads geben RESPONSE_TOO_LARGE aus (sie können nicht sicher gekürzt werden). Binärdaten sind Base64-kodiert mit content_type-Metadaten. GraphQL-Antworten zeigen sowohl data als auch errors an, sodass Teilerfolge nutzbar bleiben.

Siehe CLAUDE.md für vollständige Details.

Debugging

Kurze Diagnose

Debug-Modus aktivieren

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

Dies gibt den vollständigen HTTP-Austausch (mit geschwärzten Geheimnissen) an stderr aus. Niemals an stdout – stdout überträgt den MCP JSON-RPC Protokoll-Stream.

Hinweise zur Protokollierung

• Alle Protokolle gehen an stderr (oder optional MCP_LOG_FILE).

• Tokens, API-Keys, Authorization-Header und Anmeldedaten werden vor der Protokollierung automatisch geschwärzt.

• Protokolle sind strukturiertes JSON (ein Ereignis pro Zeile) für eine einfache Analyse mit jq.

Siehe CLAUDE.md für die vollständige Debugging-Strategie.

Entwicklungs-Roadmap

Phase 1: Projekt-Setup

• [x] requirements.txt mit fixierten Abhängigkeiten

• [x] .gitignore für Geheimnisse und Caches

• [x] .env.example zur Dokumentation der Umgebungsvariablen

• [ ] Initialisierung der src/ Paketstruktur

• [ ] Initiales config/api_configs.json Template

Phase 2: Core MCP Server

• [ ] MCP-Server-Initialisierung

• [ ] Tool-Schemadefinitionen

• [ ] Protokollierung und Fehlerbehandlung

Phase 3: Authentifizierung

• [ ] OAuth 2.0 Authorization-Code-Flow

• [ ] Lokaler Callback-HTTP-Server

• [ ] Keyring-basierte Token-Speicherung

• [ ] Token-Aktualisierungslogik

Phase 4: API Gateway

• [ ] Generischer REST-Client

• [ ] GraphQL-Query/Mutation-Unterstützung

• [ ] Unterstützung für mehrere Auth-Methoden

• [ ] Request/Response-Handler

Phase 5: Tools & Integration

• [ ] fetch_data-Tool implementieren

• [ ] send_data-Tool implementieren

• [ ] execute_graphql-Tool implementieren

• [ ] list_apis und get_status-Tools implementieren

Phase 6: Testen & Feinschliff

• [ ] Unit-Tests pro Modul

• [ ] Integrationstests mit Mock-APIs

• [ ] Konfigurationsbeispiele

• [ ] Benutzerdokumentation

Zukünftige Erweiterungen

• MCP App: Eigenständige Weboberfläche als Frontend für dieses Gateway

• Persistente Speicherung: SQLite/PostgreSQL für Datenhistorie und Audit-Logs

• Ratenbegrenzung: API-spezifische Ratenbegrenzung und Request-Queuing

• Caching: Antwort-Caching mit konfigurierbarem TTL

• Multi-Tenant: Unterstützung mehrerer Benutzer mit separaten Anmeldedaten-Speichern

• Webhooks: Empfang von Daten über eingehende Webhooks

• Datentransformations-Pipelines: Verketten von Transformationen über APIs hinweg

Sicherheit

• Alle Anmeldedaten werden im betriebssystemeigenen sicheren Keyring gespeichert (Keychain unter macOS, Credential Manager unter Windows, Secret Service unter Linux)

• .env-Datei über .gitignore von der Versionskontrolle ausgeschlossen

• OAuth verwendet den Standard-Authorization-Code-Flow (kein impliziter Grant)

• Tokens werden niemals protokolliert oder in Fehlermeldungen offengelegt

• Lokaler Callback-Server hört nur auf localhost und nur während des OAuth-Ablaufs

Lizenz

Noch offen

Mitwirken

Dieses Projekt befindet sich in einer frühen Entwicklungsphase. Richtlinien für Beiträge werden hinzugefügt, sobald die Kernimplementierung stabil ist.