🔧 MCP Tools

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.

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

Related MCP server: GPT Commander

MCP Cybersec : service distinct en préparation

mcp-cybersec est une seconde boîte à outils MCP, séparée de mcp-tools. Elle sert aux évaluations de sécurité sous mandat approuvé : une campagne est créée en prepared, son manifeste est figé et hashé à l'approbation par un administrateur, puis chaque action réseau est recontrôlée par rapport à ce mandat.

Le service possède son image, son WAF, son port (8081 par défaut), ses réseaux et sa racine S3 propres. Il ne réutilise pas les tokens, secrets ou bucket du service historique. Les variables CYBERSEC_* sont injectées par Vault au runtime ; .env.example ne décrit que leurs noms et ne contient pas de valeur utilisable.

Le shell n'a volontairement pas d'accès réseau. Le donner au shell contournerait le contrôle de périmètre, l'approbation et les journaux des outils réseau. Un besoin réseau doit passer par network, http, nmap ou nuclei, qui portent tous un campaign_id et appliquent le mandat.

Lancement de la recette locale

La composition cybersec ne démarre aucun scan : elle ne fait que construire les images et démarrer le service. Utiliser exclusivement une identité S3 de recette dédiée et un CYBERSEC_ADMIN_BOOTSTRAP_KEY non par défaut, injectés par Vault ou un fichier d'environnement local non suivi.

install -d -m 1777 /tmp/mcp-cybersec-runtime
docker compose -f docker-compose.cybersec.yml up --build
curl http://localhost:8081/health
python scripts/mcp_cybersec_cli.py --url http://localhost:8081 about

CYBERSEC_RUNTIME_HOST_DIR doit être un répertoire temporaire dédié, préprovisionné en mode 01777 et monté au même chemin dans le service. Il est nécessaire aux bind mounts des runners Docker ; il ne porte aucune donnée durable, les preuves restent dans S3.

L'overlay docker-compose.cybersec.lab.yml ajoute une cible privée sans port exposé, dans 172.30.0.0/24. Il ne doit être utilisé qu'après un GO humain de recette, avec le manifeste cybersec/lab/manifest-5bis.json, des credentials S3 de test et une campagne portant laboratory=true. Il n'autorise ni cible Internet, ni réseau partagé.

Les détails d'architecture, le runbook d'arrêt et le gabarit de rapport sont dans DESIGN/mcp-cybersec/.

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