MCP工具服务器

🔧 MCP Tools

Lecture hub Mission843 : lecteur hub_read sans exécution MCP, activité filtrée et références/contenu des publications Files exactes. Candidat désactivé avec le hub ; qualification native843 encore attendue.

Bibliothèque d'outils exécutables pour agents IA — Serveur MCP Cloud Temple

English version

MCP Tools est un serveur MCP passif qui expose des outils (shell, réseau, HTTP, recherche IA…) aux agents autonomes via le protocole Streamable HTTP. C'est la « boîte à outils » de l'écosystème Cloud Temple.

Accès et activité PostgreSQL

Le profil explicite ACCESS_BACKEND=postgres fournit l'authentification fraîche, les mutations administratives sous CAS et l'activité durable, avec API, CLI et console. Le guide accès/activité décrit l'opérateur et le premier admin offline. #31/PR38 est livré (merge268a0e8d), avec preuves standalone et hub distinctes. Le nouveau parcours Compose/Python local ou externe reste candidat #45, sans nouvelle qualification moteur revendiquée.

Catalogue fichiers PostgreSQL (optionnel)

Le pilote S3 historique reste le défaut. FILES_METADATA_BACKEND=postgres sélectionne un catalogue unique, avec contenu S3 versionné, pages/batch et journal d'opérations incertaines. Installation et reprise publiques autonomes, en infrastructure propre ou base externe : guide, design. #30/PR37 est livré (merge11ef86ed), avec provenance app/opérateur et limites de reprise explicites. Les profils Compose PG et leur volume local restent à qualifier séparément.

Démarrage rapide

1. Configuration

cp .env.example .env
# Éditer .env avec vos credentials S3, Perplexity, etc.

2. Lancement (Docker Compose)

docker compose build
docker compose up -d

# Vérification
curl http://localhost:8082/health
# → {"status":"healthy","service":"mcp-tools","version":"0.6.0","transport":"streamable-http"}

# Console d'administration
open http://localhost:8082/admin

3. CLI

# Créer le venv Python
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Health check (pas d'auth requise)
python scripts/mcp_cli.py health

# Infos service
python scripts/mcp_cli.py about

# Traces d'activité (administrateur requis)
python scripts/mcp_cli.py activity --limit 50
# Afficher la chronologie de chaque appel et retrouver un incident précis
python scripts/mcp_cli.py activity --details
python scripts/mcp_cli.py activity --call-id call-123 --details
# Contrat JSON pour un agent ou un script ; --all ajoute le protocole MCP
python scripts/mcp_cli.py activity --trace-id tr_123 --json

# Exécuter une commande shell
python scripts/mcp_cli.py run-shell "hostname && uptime"

# Diagnostic réseau
python scripts/mcp_cli.py network ping google.com
python scripts/mcp_cli.py network dig google.com MX +short
python scripts/mcp_cli.py network nslookup google.com -type=mx

# Requête HTTP
python scripts/mcp_cli.py http https://httpbin.org/get

# Dates et heures
python scripts/mcp_cli.py date now --tz Europe/Paris
python scripts/mcp_cli.py date add 2026-03-06 --days 10
python scripts/mcp_cli.py date diff 2026-01-01 --date2 2026-03-06
python scripts/mcp_cli.py date day_of_week 2026-03-06

# Calculs mathématiques
python scripts/mcp_cli.py calc "2 + 3 * 4"
python scripts/mcp_cli.py calc "math.sqrt(144) + statistics.mean([10,20,30])"

# Recherche IA (Perplexity)
python scripts/mcp_cli.py search "Qu'est-ce que le protocole MCP ?"

# Documentation technique (Perplexity)
python scripts/mcp_cli.py doc "Python asyncio"
python scripts/mcp_cli.py doc "FastAPI" --context "middleware et dépendances"

# SSH (exécution distante)
python scripts/mcp_cli.py ssh exec myserver.com --user admin --password secret "uptime"
python scripts/mcp_cli.py ssh status myserver.com --user admin --password secret

# Fichiers S3
python scripts/mcp_cli.py files list --prefix logs/
python scripts/mcp_cli.py files read config/app.yaml
python scripts/mcp_cli.py files read rapports/complet.md --offset 0 --limit 30000 --json
python scripts/mcp_cli.py files write test.txt --content "Hello World"
python scripts/mcp_cli.py files concat --path rapports/complet.md --source rapports/00-synthese.md --source rapports/01-dns.md

# Gestion des tokens (admin)
python scripts/mcp_cli.py token create agent-prod --tools shell,date,calc --expires 90
python scripts/mcp_cli.py token create ct-user --email user@cloud-temple.com --expires 180
python scripts/mcp_cli.py token list
python scripts/mcp_cli.py token info agent-prod
python scripts/mcp_cli.py token revoke agent-prod

# Shell interactif
python scripts/mcp_cli.py shell

Concaténer des objets S3 sans recopier leur contenu

files concat lit des objets UTF-8 dans l'ordre déclaré, les assemble dans la sandbox puis écrit la destination seulement lorsque toutes les lectures sont validées. Les données ne transitent pas par MCP. La sortie est bornée à 5 MB et à 64 sources ; elle contient le SHA-256 du résultat ainsi qu'un manifeste de chaque source (path, offset d'octet dans la destination, size, sha256 et version_id lorsque S3 le fournit). Les séparateurs n'appartiennent à aucune source. La destination peut remplacer un objet existant, comme files write, mais ne peut pas figurer parmi les sources.

Lire un objet S3 paginé

Sans offset ni limit, files read conserve son comportement historique : le texte est borné afin de protéger le contexte MCP. Pour extraire intégralement un objet, passer offset et/ou limit (en octets). Chaque page utilise une requête S3 Range et retourne content_base64, offset, next_offset, end, size, etag et, quand S3 le fournit, version_id. La base64 est intentionnelle : une plage d'octets peut couper un caractère UTF-8 ou contenir du binaire.

Réutiliser next_offset jusqu'à end=true. Sur un bucket versionné, reprendre le version_id retourné pour figer les pages. Sinon, reprendre l'etag dans if_match : si l'objet change, la lecture échoue explicitement au lieu de mélanger deux générations.

4. Recette E2E

La recette E2E couvre les 13 outils, dont les cas négatifs (anti-SSRF, blocage RFC 1918, isolation réseau de la sandbox, injections, timeouts, refus d'entrées invalides, gardes de régression), la console /admin, le CLI Click et sa parité de catalogue avec l'admin. Les valeurs calculées sont comparées à l'exact, pas seulement l'absence d'erreur.

Ce qui tourne automatiquement en CI est hermétique ; les scénarios qui demandent des secrets restent à jouer avant chaque release : token et admin (identifiants S3), perplexity_search et perplexity_doc (clé API facturée), et les cas SSH positifs (cible réelle).

# Tous les tests (build + start + test + stop)
python scripts/test_service.py

# Sous-ensemble hermétique, celui de la CI
python scripts/test_service.py --test shell,network,http,date,calc,files,waf,cli,auth

# Test spécifique (16 catégories)
python scripts/test_service.py --test shell
python scripts/test_service.py --test network
python scripts/test_service.py --test http
python scripts/test_service.py --test ssh
python scripts/test_service.py --test files
python scripts/test_service.py --test token
python scripts/test_service.py --test admin
python scripts/test_service.py --test waf
python scripts/test_service.py --test date
python scripts/test_service.py --test calc

# Serveur déjà lancé
python scripts/test_service.py --no-docker

# Verbose (réponses complètes)
python scripts/test_service.py --test shell -v

5. Développement local (sans Docker)

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.lock
PYTHONPATH=src python -m mcp_tools

6. Build reproductible

requirements.txt est un contrat de compatibilité (bornes hautes obligatoires), pas la source d'installation. Ce sont requirements.lock — clôture transitive figée, outillage pip/setuptools/wheel inclus — et les images de base épinglées par digest qui garantissent qu'un rebuild d'un tag publié produit le même arbre de dépendances.

Après toute modification de requirements.txt, régénérer le lock dans l'image cible :

./scripts/lock_requirements.sh

Un pip freeze lancé depuis le poste de développement résoudrait d'autres versions que python:3.11-slim linux/amd64 et produirait un lock faux.

Contrôler les gardes (bornes, cohérence du lock, alignement mcp / mcp-types v2, imports serveur et client, CVE) :

python3 scripts/test_service.py --test reproducibility --no-docker

Architecture

Internet/LAN → :8082 (WAF Caddy+Coraza) → mcp-tools:8050 (interne)

Pile ASGI

ActivityMiddleware → AdminMiddleware → HealthCheckMiddleware → AuthMiddleware → LoggingMiddleware → MCPServer streamable_http_app

3 couches (pattern Cloud Temple)

Outils disponibles (13/28 — Phase 1)

Tous les paramètres de chaque outil sont documentés avec des descriptions détaillées via le protocole MCP. Les clients compatibles (Cline, Claude Desktop…) affichent automatiquement ces descriptions.

Console d'administration (/admin)

Une interface web d'administration est disponible sur /admin :

http://localhost:8082/admin

4 vues : Dashboard (état serveur), Tools (exécution interactive avec formulaires dynamiques), Tokens (CRUD), Activité (un appel corrélé de la réception HTTP à son verdict terminal, puis journal métier et journal HTTP). Les appels MCP et les routes Admin y partagent le même trace_id ; un call_id agent, s'il est fourni, permet de les retrouver. Les valeurs métier — arguments, commandes, sorties, corps et secrets — ne sont jamais affichées.

Le verdict « réponse MCP émise » signifie que l'application a remis une enveloppe JSON-RPC terminale à l'ASGI. Il ne prétend pas prouver la réception réseau par l'agent : cette dernière exige la corrélation avec les journaux WAF/proxy et agent.

Si les métadonnées d'un très gros appel MCP ne peuvent pas être inspectées sans retenir son corps, la trace exige conservativement une enveloppe terminale au lieu d'afficher un succès. Une annulation d'écriture HTTP ou S3 indique de même remote_result_uncertain : l'effet distant peut avoir eu lieu avant l'arrêt local.

Authentification admin requise (ADMIN_BOOTSTRAP_KEY ou token S3 avec permission admin). Design Cloud Temple (dark theme). Same-origin uniquement (pas de CORS cross-origin).

Sécurité

• Audit de sécurité : Rapport complet dans DESIGN/mcp-tools/SECURITY_AUDIT.md — architecture qualifiée "niveau Entreprise"
• WAF Caddy + Coraza : OWASP CRS en mode blocage (SecRuleEngine On), headers de sécurité, rate limiting (1000 req/min MCP) — 6 tests E2E (--test waf)
• Auth Bearer token : Chaque requête /mcp est authentifiée. Permissions access (appel d'outils) ou admin (tout)
• tool_ids : Le token peut restreindre l'accès à un sous-ensemble d'outils (whitelisting par outil)
• Sandbox Docker : Chaque commande shell/network/http dans un conteneur éphémère isolé (--cap-drop=ALL, --read-only, non-root)
• Token Manager S3 : Tokens stockés en S3 Dell ECS (_tokens/{sha256}.json), cache mémoire TTL 5min, isolation par tool_ids
• Admin same-origin : Console /admin sans CORS cross-origin, auth admin obligatoire sur l'API
• Traces sûres : aucune commande, sortie, corps HTTP, en-tête ou secret n'est copié dans le buffer d'activité ou dans stderr
• Anti-SSRF : Résolution DNS + blocage RFC 1918 / loopback / metadata cloud pour les tools http et network
• Utilisateur non-root dans Docker
• Timeouts et limites sur tous les outils
• Kill automatique des conteneurs sandbox en cas de timeout ou d'annulation MCP

Variables d'environnement

Serveur (.env)

Client CLI

Structure des fichiers

mcp-tools/
├── src/mcp_tools/
│   ├── server.py              # Serveur MCP + HealthCheck + bannière
│   ├── config.py              # Configuration pydantic-settings (sandbox, etc.)
│   ├── admin/                 # Console d'administration web (/admin)
│   ├── static/                # Fichiers statiques admin (HTML, CSS, JS)
│   ├── auth/                  # Middleware auth + Token Store S3
│   └── tools/                 # Outils MCP (shell, network, http, perplexity)
├── sandbox/
│   └── Dockerfile             # Image Alpine sandbox (python3, node, openssl…)
├── scripts/
│   ├── mcp_cli.py             # Point d'entrée CLI
│   ├── test_service.py        # Recette E2E (--test NOM pour cibler)
│   └── cli/                   # CLI Click + Shell + Display
├── waf/                       # WAF Caddy + Coraza
├── Dockerfile                 # Python 3.11 + docker CLI statique
├── docker-compose.yml         # sandbox + mcp-tools + waf + docker.sock
├── .env.example
└── VERSION

Configurer dans Cline (VS Code / VSCodium)

Pour connecter MCP Tools à Cline, ajoutez dans votre cline_mcp_settings.json (accessible via ⚙️ MCP Servers dans la sidebar Cline) :

{
  "mcpServers": {
    "mcp-tools": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "http://localhost:8082/mcp",
      "headers": {
        "Authorization": "Bearer VOTRE_TOKEN_ICI"
      }
    }
  }
}

Pour créer un token dédié à Cline avec des outils spécifiques :

python scripts/mcp_cli.py --token $ADMIN_BOOTSTRAP_KEY \
  token create cline-dev --tools shell,http,network,date,calc,perplexity_search --expires 365

Guide complet : voir starter-kit/CLINE_SETUP.md pour les chemins des fichiers de configuration par OS, le multi-serveurs, le debug, etc.

Roadmap

• Phase 1 (actuel) : shell, network, http, ssh, files, perplexity_search, perplexity_doc, date, calc — ✅
• Phase 1 (à faire) : docker, generate, mcp_call
• Phase 2 : git, s3, db, host_audit, ssh_diagnostics, sqlite, script_executor, email_send, pdf, doc_scraper
• Phase 3 : imap, perplexity_api, perplexity_deprecated

Licence

Apache 2.0 — Cloud Temple