house-proxy-api-mcp

v0.0.1

Published

3 months ago

Ultra-fast MCP API Proxy with RAM cache and JWT auth - HOUSE Framework Binary

0High
0Medium
0Low

cburtin

mcp model-context-protocol proxy api rust binary jwt cache house-framework cli

House Proxy API MCP v0.0.1

🎯 Description

MCP proxy ultra-performant pour Claude Desktop/Code - convertit automatiquement les APIs REST, GraphQL et SOAP en outils utilisables par les LLMs.

Caractéristiques techniques S03 FINAL :

Performance : P99 < 25ms, 25k+ RPS, <128MB RAM
Cache RAM natif : Gestion intelligente des tokens OAuth2 et mise en cache des réponses
JWT stateless : Authentification sécurisée sans état
Conversion automatique : Endpoints REST → outils MCP avec validation de schéma

🚀 Installation Rapide

Installation npm globale (recommandée)

# Installation via npm
npm install -g house-proxy-api-mcp

# Vérifier l'installation
house-proxy-api-mcp --version

Installation via npx (sans installation)

# Usage direct
npx house-proxy-api-mcp --help

# Démarrage avec configuration
npx house-proxy-api-mcp --config proxy.yaml --secrets secrets.yaml

Installation depuis les sources

# Cloner et compiler (Rust requis)
git clone https://github.com/house-flow/house-proxy-api-mcp.git
cd house-proxy-api-mcp
cargo build --release

⚡ Usage

Démarrage basique

# Configuration minimale
house-proxy-api-mcp --config proxy.yaml --secrets secrets.yaml

# Avec overrides CLI
house-proxy-api-mcp \
  --config config/proxy.yaml \
  --secrets config/secrets.yaml \
  --port 8080 \
  --host 0.0.0.0 \
  --log-level info

# Mode performance (production)
house-proxy-api-mcp \
  --config proxy.yaml \
  --secrets secrets.yaml \
  --workers 4 \
  --cache-size 1000 \
  --request-timeout 5000

Options CLI complètes

house-proxy-api-mcp [OPTIONS]

OPTIONS:
    -c, --config <FILE>         Fichier de configuration YAML [default: proxy.yaml]
    -s, --secrets <FILE>        Fichier des secrets YAML [default: secrets.yaml]
    -p, --port <PORT>           Port d'écoute [default: 3000]
    -h, --host <HOST>           Adresse d'écoute [default: 127.0.0.1]
    -w, --workers <N>           Nombre de workers [default: auto]
    -l, --log-level <LEVEL>     Niveau de log [default: info]
        --cache-size <SIZE>     Taille du cache RAM (MB) [default: 512]
        --request-timeout <MS>  Timeout des requêtes [default: 30000]
        --version               Afficher la version
        --help                  Afficher cette aide

📋 Configuration MCP

Claude Desktop (mcp.json)

{
  "mcpServers": {
    "house-proxy-api": {
      "command": "npx",
      "args": ["house-proxy-api-mcp", "--config", "config/proxy.yaml", "--secrets", "config/secrets.yaml"],
      "env": {
        "RUST_LOG": "house_proxy_api_mcp=info",
        "NODE_ENV": "production"
      }
    }
  }
}

Claude Code (.claude/mcp-servers.json)

{
  "house-proxy-api": {
    "command": "npx",
    "args": [
      "house-proxy-api-mcp", 
      "--config", "config/proxy.yaml", 
      "--secrets", "config/secrets.yaml",
      "--port", "3001",
      "--log-level", "debug"
    ],
    "env": {
      "JWT_SECRET": "your-jwt-secret-here-minimum-32-chars",
      "CACHE_REDIS_URL": "redis://localhost:6379/0"
    }
  }
}

Configuration avancée pour développement

{
  "house-proxy-api-dev": {
    "command": "/usr/local/bin/house-proxy-api-mcp",
    "args": [
      "--config", "./mcp-config/proxy-dev.yaml",
      "--secrets", "./mcp-config/secrets-dev.yaml",
      "--workers", "1",
      "--cache-size", "128"
    ],
    "env": {
      "RUST_LOG": "house_proxy_api_mcp=debug,tower_http=trace",
      "ENABLE_METRICS": "true",
      "METRICS_PORT": "9090"
    }
  }
}

🔧 Configuration Files

proxy.yaml - Configuration principale

# House Proxy API MCP Configuration v0.0.1
version: "0.0.1"
name: "house-proxy-api-mcp"

# Configuration du serveur
server:
  port: 3000
  host: "127.0.0.1"
  workers: 4
  request_timeout: 30000
  keep_alive: true

# Configuration du cache
cache:
  type: "memory"  # memory | redis
  size_mb: 512
  ttl_seconds: 3600
  redis_url: "${CACHE_REDIS_URL}"  # Si type: redis

# Configuration des métriques
metrics:
  enabled: true
  port: 9090
  path: "/metrics"

# Services API à exposer
services:
  # API REST avec OpenAPI
  - name: "github_api"
    type: "openapi"
    base_url: "https://api.github.com"
    spec_path: "./specs/github-openapi.yaml"
    auth_ref: "github_auth"
    headers:
      "Accept": "application/vnd.github.v3+json"
      "User-Agent": "house-proxy-api-mcp/0.0.1"
    rate_limit:
      requests_per_minute: 5000
      burst: 100
    cache:
      enabled: true
      ttl_seconds: 300
    
  # API GraphQL
  - name: "hasura_api"
    type: "graphql"
    base_url: "https://api.hasura.io/v1/graphql"
    schema_path: "./specs/hasura-schema.graphql"
    auth_ref: "hasura_auth"
    timeout: 10000
    
  # API SOAP
  - name: "weather_soap"
    type: "soap"
    base_url: "https://webservice.weather.com/soap"
    wsdl_path: "./specs/weather.wsdl"
    auth_ref: "soap_basic_auth"
    
  # Webhook personnalisé
  - name: "custom_webhook"
    type: "webhook"
    base_url: "https://my-api.com/webhooks"
    spec_path: "./specs/webhooks-spec.yaml"
    auth_ref: "webhook_bearer"

# Configuration des routes personnalisées
custom_routes:
  - path: "/health"
    method: "GET"
    response: 
      status: 200
      body: '{"status": "healthy", "version": "0.0.1"}'
      
  - path: "/version"
    method: "GET"
    response:
      status: 200
      body: '{"version": "0.0.1", "build": "${BUILD_VERSION}"}'

# Configuration de sécurité
security:
  jwt_secret: "${JWT_SECRET}"
  cors_enabled: true
  cors_origins: ["https://claude.ai", "http://localhost:3000"]
  request_size_limit: "10MB"
  
# Configuration du logging
logging:
  level: "info"
  format: "json"
  output: "stdout"
  access_log: true

secrets.yaml - Configuration des secrets (sécurisée)

# House Proxy API MCP Secrets Configuration
# ⚠️ NE JAMAIS COMMITER CE FICHIER AVEC DE VRAIES CLÉS

# Authentifications par référence
auth_configs:
  github_auth:
    type: "bearer"
    token: "${GITHUB_TOKEN}"
    
  hasura_auth:
    type: "api_key"
    api_key: "${HASURA_API_KEY}"
    header: "X-Hasura-Admin-Secret"
    
  soap_basic_auth:
    type: "basic"
    username: "${SOAP_USERNAME}"
    password: "${SOAP_PASSWORD}"
    
  webhook_bearer:
    type: "bearer"
    token: "${WEBHOOK_TOKEN}"
    
  oauth2_api:
    type: "oauth2"
    client_id: "${OAUTH2_CLIENT_ID}"
    client_secret: "${OAUTH2_CLIENT_SECRET}"
    token_url: "https://auth.example.com/oauth/token"
    scopes: ["read", "write", "admin"]

# Variables d'environnement requises
# Créer un fichier .env avec ces valeurs
environment_variables:
  required:
    - "JWT_SECRET"          # openssl rand -hex 32
    - "GITHUB_TOKEN"        # ghp_xxxx
    - "HASURA_API_KEY"      # hasura admin secret
    - "SOAP_USERNAME"       # soap basic auth user
    - "SOAP_PASSWORD"       # soap basic auth password
    - "WEBHOOK_TOKEN"       # bearer token for webhooks
  optional:
    - "CACHE_REDIS_URL"     # redis://localhost:6379/0
    - "BUILD_VERSION"       # git commit hash
    - "OAUTH2_CLIENT_ID"    # oauth2 client id
    - "OAUTH2_CLIENT_SECRET" # oauth2 client secret

.env.example - Exemple de variables d'environnement

# House Proxy API MCP Environment Variables
# Copier vers .env et remplir avec vos vraies valeurs

# Configuration obligatoire
JWT_SECRET=your-super-secure-jwt-secret-key-here-minimum-32-characters
GITHUB_TOKEN=ghp_your_github_personal_access_token
HASURA_API_KEY=your-hasura-admin-secret

# Configuration optionnelle
CACHE_REDIS_URL=redis://localhost:6379/0
BUILD_VERSION=0.0.1-dev
RUST_LOG=house_proxy_api_mcp=info,tower_http=debug

# APIs spécifiques
SOAP_USERNAME=soap_user
SOAP_PASSWORD=soap_password
WEBHOOK_TOKEN=bearer_token_for_webhooks
OAUTH2_CLIENT_ID=oauth2_client_id
OAUTH2_CLIENT_SECRET=oauth2_client_secret

# Métriques et monitoring
ENABLE_METRICS=true
METRICS_PORT=9090

📊 Performance & Monitoring

Métriques disponibles

Le serveur expose des métriques Prometheus sur /metrics :

# Vérifier les métriques
curl http://localhost:9090/metrics

# Métriques principales
http_requests_total                 # Nombre total de requêtes
http_request_duration_seconds      # Latence des requêtes
cache_hits_total                   # Succès du cache
cache_misses_total                # Échecs du cache
auth_success_total                # Authentifications réussies
auth_failures_total               # Échecs d'authentification

Dashboard de monitoring

# Configuration Grafana dashboard
version: 1
datasources:
  - name: prometheus
    type: prometheus
    url: http://localhost:9090
    
dashboards:
  - title: "House Proxy API MCP"
    panels:
      - title: "Requests per Second"
        target: "rate(http_requests_total[5m])"
      - title: "P99 Latency"
        target: "histogram_quantile(0.99, http_request_duration_seconds_bucket)"
      - title: "Cache Hit Rate"
        target: "cache_hits_total / (cache_hits_total + cache_misses_total) * 100"

Tests de charge

# Test de performance avec wrk
wrk -t12 -c400 -d30s --script=load-test.lua http://localhost:3000

# Résultats attendus (S03 FINAL)
# Requests/sec: 25000+
# Latency P99: <25ms
# Memory usage: <128MB
# CPU usage: <50% (4 cores)

🛡️ Sécurité

Authentification JWT

# Générer un secret JWT sécurisé
openssl rand -hex 32

# Test d'authentification
curl -H "Authorization: Bearer $(echo '{"typ":"JWT","alg":"HS256"}{"sub":"test"}' | jwt-encode --secret YOUR_SECRET)" \
  http://localhost:3000/health

Validation des schémas

Le serveur valide automatiquement :

Schémas OpenAPI : Validation stricte des paramètres et réponses
Schémas GraphQL : Validation des queries et mutations
WSDL SOAP : Validation des enveloppes SOAP
Formats d'entrée : JSON, XML, form-data

Sécurisation des secrets

# Chiffrement des secrets (optionnel)
age-keygen -o secrets.key
age -r $(cat secrets.key.pub) -e secrets.yaml > secrets.yaml.enc

# Utilisation avec déchiffrement automatique
house-proxy-api-mcp --config proxy.yaml --secrets secrets.yaml.enc --decrypt-key secrets.key

🔍 API Endpoints

Endpoints système

# Health check
GET /health
Response: {"status": "healthy", "version": "0.0.1", "uptime": 3600}

# Version info
GET /version
Response: {"version": "0.0.1", "build": "a1b2c3d4", "rust_version": "1.75.0"}

# Métriques Prometheus
GET /metrics
Response: # Métriques en format Prometheus

# Liste des outils MCP disponibles
POST /mcp/tools/list
Request: {"jsonrpc": "2.0", "method": "tools/list", "id": 1}
Response: {"jsonrpc": "2.0", "result": {"tools": [...]}, "id": 1}

Endpoints API convertis

Les APIs configurées sont automatiquement converties en outils MCP :

# API GitHub - List repositories
POST /mcp/tools/call
Request: {
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "github_api_list_repos",
    "arguments": {"per_page": 10, "sort": "updated"}
  },
  "id": 2
}

# API GraphQL - Get user
POST /mcp/tools/call  
Request: {
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "hasura_api_getUser",
    "arguments": {"id": "123"}
  },
  "id": 3
}

🐳 Déploiement Production

Docker Compose

# docker-compose.prod.yml
version: '3.8'

services:
  house-proxy-api-mcp:
    image: house-proxy-api-mcp:0.0.1
    ports:
      - "3000:3000"
      - "9090:9090"
    environment:
      - RUST_LOG=house_proxy_api_mcp=info
      - JWT_SECRET=${JWT_SECRET}
      - GITHUB_TOKEN=${GITHUB_TOKEN}
    volumes:
      - ./config:/app/config:ro
      - ./specs:/app/specs:ro
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    deploy:
      resources:
        limits:
          memory: 128M
          cpus: '0.5'
        reservations:
          memory: 64M
          cpus: '0.25'

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    restart: unless-stopped

volumes:
  redis-data:

Kubernetes Deployment

# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: house-proxy-api-mcp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: house-proxy-api-mcp
  template:
    metadata:
      labels:
        app: house-proxy-api-mcp
    spec:
      containers:
      - name: house-proxy-api-mcp
        image: house-proxy-api-mcp:0.0.1
        ports:
        - containerPort: 3000
        - containerPort: 9090
        env:
        - name: JWT_SECRET
          valueFrom:
            secretKeyRef:
              name: proxy-secrets
              key: jwt-secret
        - name: GITHUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: proxy-secrets  
              key: github-token
        resources:
          limits:
            memory: "128Mi"
            cpu: "500m"
          requests:
            memory: "64Mi"
            cpu: "250m"
        livenessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 5
          periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: house-proxy-api-mcp-service
spec:
  selector:
    app: house-proxy-api-mcp
  ports:
  - name: http
    port: 3000
    targetPort: 3000
  - name: metrics
    port: 9090
    targetPort: 9090
  type: ClusterIP

Script de déploiement automatisé

#!/bin/bash
# deploy.sh - Script de déploiement production

set -euo pipefail

echo "🚀 Déploiement House Proxy API MCP v0.0.1"

# Validation des prérequis
command -v docker >/dev/null 2>&1 || { echo "Docker requis" >&2; exit 1; }
command -v docker-compose >/dev/null 2>&1 || { echo "Docker Compose requis" >&2; exit 1; }

# Construction de l'image
echo "📦 Construction de l'image Docker..."
docker build -t house-proxy-api-mcp:0.0.1 .

# Test de l'image
echo "🧪 Test de l'image..."
docker run --rm house-proxy-api-mcp:0.0.1 --version

# Validation des configurations
echo "🔍 Validation des configurations..."
docker run --rm -v "$(pwd)/config:/config" house-proxy-api-mcp:0.0.1 \
  --config /config/proxy.yaml --validate-only

# Déploiement
echo "🎯 Déploiement en production..."
docker-compose -f docker-compose.prod.yml up -d

# Vérification de santé
echo "💚 Vérification de santé..."
sleep 10
curl -f http://localhost:3000/health || { echo "Échec du health check" >&2; exit 1; }

echo "✅ Déploiement réussi !"
echo "📊 Métriques disponibles sur http://localhost:9090/metrics"
echo "🔍 Logs: docker-compose -f docker-compose.prod.yml logs -f"

📚 Exemples Avancés

Configuration multi-environnements

# Développement
house-proxy-api-mcp --config config/dev.yaml --secrets secrets/dev.yaml --log-level debug

# Staging  
house-proxy-api-mcp --config config/staging.yaml --secrets secrets/staging.yaml --workers 2

# Production
house-proxy-api-mcp --config config/prod.yaml --secrets secrets/prod.yaml --workers 4 --cache-size 1024

Intégration avec Claude via MCP

# Exemple d'utilisation depuis Python avec MCP client
import asyncio
from mcp_client import McpClient

async def test_proxy_api():
    # Connexion au serveur MCP
    async with McpClient("npx house-proxy-api-mcp --config proxy.yaml") as client:
        
        # Lister les outils disponibles
        tools = await client.list_tools()
        print(f"Outils disponibles: {[tool.name for tool in tools]}")
        
        # Appeler l'API GitHub via le proxy
        result = await client.call_tool(
            "github_api_list_repos",
            {"per_page": 5, "sort": "updated"}
        )
        print(f"Repositories: {result}")
        
        # Appeler l'API GraphQL via le proxy
        user = await client.call_tool(
            "hasura_api_getUser", 
            {"id": "123"}
        )
        print(f"Utilisateur: {user}")

# Exécuter le test
asyncio.run(test_proxy_api())

Configuration avancée avec load balancing

# Configuration pour haute disponibilité
server:
  port: 3000
  workers: 8
  load_balancer:
    strategy: "round_robin"  # round_robin | least_connections | weighted
    health_check: true
    health_check_interval: 30

services:
  - name: "api_cluster"
    type: "openapi"
    spec_path: "./specs/api.yaml"
    endpoints:
      - url: "https://api1.example.com"
        weight: 3
      - url: "https://api2.example.com"  
        weight: 2
      - url: "https://api3.example.com"
        weight: 1
    fallback:
      enabled: true
      cache_stale_responses: true
      timeout: 5000

🤝 Contribution

Développement local

# Cloner le projet
git clone https://github.com/house-flow/house-proxy-api-mcp.git
cd house-proxy-api-mcp

# Installation des dépendances de développement
cargo install cargo-watch cargo-tarpaulin

# Développement avec rechargement automatique  
cargo watch -x "run -- --config examples/dev.yaml --secrets examples/secrets-dev.yaml"

# Tests
cargo test
cargo tarpaulin --out Html  # Couverture de code

Structure du projet

house-proxy-api-mcp/
├── Cargo.toml                 # Configuration Rust
├── src/
│   ├── main.rs               # Point d'entrée
│   ├── config/               # Gestion de configuration
│   ├── mcp/                  # Implémentation du protocole MCP
│   ├── proxy/                # Gestionnaire de proxy HTTP
│   ├── auth/                 # Système d'authentification
│   ├── cache/                # Système de cache
│   ├── metrics/              # Métriques Prometheus
│   └── schema/               # Parseurs de schémas (OpenAPI, GraphQL, WSDL)
├── config/                   # Exemples de configuration
├── specs/                    # Exemples de spécifications API
├── tests/                    # Tests d'intégration
└── docs/                     # Documentation détaillée

Guidelines de contribution

Format du code : cargo fmt
Linting : cargo clippy
Tests : Minimum 80% de couverture
Documentation : Documenter toutes les APIs publiques
Changelog : Mettre à jour CHANGELOG.md

House Proxy API MCP v0.0.1 - Le pont ultra-performant entre vos APIs et Claude ! 🚀

Pour plus d'informations : Documentation complète | Issues GitHub | Discord Community