SPARDA & Next.js App Router : Zéro ligne de code modifiée, le MCP sans intrusion

Note (mise à jour) — SPARDA est aujourd'hui en v0.67.0 et se définit comme la couche de confiance du code écrit par l'IA (« AI writes. SPARDA proves. ») : il compile un backend en graphe de comportement déterministe et prouve ce qu'il ne peut pas casser (npx sparda-mcp prove / apocalypse). Ce billet est un retour d'expérience sur une de ses capacités — l'injection MCP file-based sur Next.js, toujours d'actualité — écrit à l'époque de la v0.6.0.

Chez Residual Labs, nous croyons qu'un outil de développement n'est crédible que s'il est utilisé par ses propres concepteurs. C'est pourquoi nous avons dogfoodé SPARDA sur notre propre site web : residual-labs.fr.

L'enjeu technique décrit ici ? Le support complet de Next.js App Router.

Et la bonne nouvelle pour tous les développeurs Next.js : sur Next, SPARDA ne touche pas à une seule ligne de votre code existant.

---

Le défi de l'injection : Express vs Next.js

Sur un serveur classique de type Express ou FastAPI, l'initialisation de SPARDA nécessite de modifier le fichier d'entrée (app.js ou main.py) pour monter le routeur de sécurité /mcp :

// >>> sparda-injection >>>
import { spardaRouter } from './sparda-router.js';
app.use('/mcp', spardaRouter);
// <<< sparda-injection <<<

Bien que cette modification soit entièrement automatisée via AST par la commande sparda init (et réversible au bit près avec sparda remove), modifier le code source écrit par un humain comporte toujours une part de friction psychologique.

Sur Next.js, cette friction disparaît complètement.

Next.js utilise le file-system routing : la structure de vos dossiers détermine vos routes d'API. Puisqu'il n'y a pas de script d'initialisation unique de type app = express() à modifier, nous avons pensé SPARDA différemment.

---

File-Based Injection : L'injection par fichier

Lorsque vous lancez npx sparda-mcp@latest init dans un projet Next.js App Router, SPARDA effectue les étapes suivantes :

1. Détection : Il repère la structure de l'App Router (présence du dossier /app ou /src/app).
2. Scan Statique (AST) : Il parcourt vos répertoires de routes d'API (route.js ou route.ts) pour extraire automatiquement les signatures de vos endpoints.
3. Génération d'un routeur catch-all : SPARDA crée un unique fichier de route générique sous le chemin suivant : app/mcp/[...sparda]/route.js (ou dans src/app/ selon votre configuration).

Ce fichier auto-généré contient l'intégralité du moteur d'immunité de SPARDA, le système de double-validation humaine (deux phases de commit pour les écritures), le cache RAM et le bridge Stdio.

Résultat : 0 ligne modifiée dans vos fichiers sources.

Si vous souhaitez retirer SPARDA, la commande npx sparda-mcp remove se contente de supprimer le répertoire app/mcp/[...sparda] et les fichiers de configuration locaux. Votre historique Git reste d'une propreté absolue.

---

Le test en conditions réelles sur residual-labs.fr

Nous avons exécuté la commande d'initialisation directement sur le dépôt de notre site hub :

npx sparda-mcp@latest init --yes

Voici ce que SPARDA a extrait en moins de 0.1 seconde :

T  SPARDA v0.6.0
|
o  Stack detected: Next.js (App Router) — app dir: app/, port: 3000
|
•  2 routes found — 1 high confidence, 1 partial
|
o  TOOLS TO GENERATE --------------------------------+
|                                                    |
|  ✗ POST   /api/contact   (disabled: write-safety)  |
|  ✓ GET    /api/warmup                              |
|                                                    |
+----------------------------------------------------+
|
*  Generated app/mcp/[...sparda]/route.js
|
*  File-based injection: your code was not modified (remove deletes the file)
|
*  Wrote sparda.json
|
—  Done in 0.1s.

SPARDA a immédiatement identifié notre API de formulaire de contact (POST /api/contact) et notre route de warmup serverless (GET /api/warmup).

Puisque le routeur catch-all généré n'a aucun import externe et n'utilise que l'API web standard Request / Response, il est compatible avec n'importe quel environnement de déploiement (y compris Vercel Edge Runtime ou Node.js standard).

---

Comment tester SPARDA sur votre projet Next.js ?

Si vous souhaitez donner des super-pouvoirs d'agent IA à votre application Next.js, suivez ces 3 étapes simples :

1. Initialisation :

   npx sparda-mcp init
   

   SPARDA va scanner vos fichiers, générer le routeur catch-all et écrire le fichier de configuration sparda.json.

2. Démarrage du pont Stdio :

   npx sparda-mcp dev
   

   Cette commande connecte votre client d'IA (comme Claude Desktop ou Claude Code) au processus local.

3. Vérification : Configurez votre client Claude Desktop en ajoutant le serveur local dans votre configuration. Votre agent peut désormais lire vos données de manière sécurisée et exécuter des actions via vos outils locaux.

L'injection MCP décrite ici reste l'une des portes d'entrée de SPARDA. Mais le cœur de l'outil aujourd'hui, c'est la preuve : compiler votre backend en graphe de comportement et démontrer, avant la mise en prod, qu'aucune garde n'a sauté et qu'aucun invariant n'est brisé — npx sparda-mcp prove. Déterministe, hors-ligne, et jamais un faux « prouvé ».