sparda-mcp 0.1.0 → 0.4.0

package/src/detect.js

@@ -1,6 +1,7 @@
 // detect.js — framework, entry file, port detection (spec: blueprint 03-PARSING §A)
 import fs from 'node:fs';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 
 const err = (message, hint) => Object.assign(new Error(message), { code: 'USER', hint });
 
@@ -21,10 +22,102 @@ export function detectStack(cwd) {
   for (const f of ['requirements.txt', 'pyproject.toml']) {
     const p = path.join(cwd, f);
     if (fs.existsSync(p) && fs.readFileSync(p, 'utf8').toLowerCase().includes('fastapi')) {
-      throw err('FastAPI detected — Python support lands next release.', 'Watch the repo: github.com/zyx77550/sparda');
+      const entryFile = findFastAPIEntry(cwd);
+      const port = detectFastAPIPort(cwd, entryFile);
+      const pythonCmd = detectPython();
+      return { framework: 'fastapi', entryFile, port, pythonCmd };
     }
   }
-  throw err('No supported framework found (Express, FastAPI).', 'Run sparda inside your project root, next to package.json.');
+  throw err('No supported framework found (Express, FastAPI).', 'Run sparda-mcp inside your project root, next to package.json.');
+}
+
+function detectPython() {
+  const cmds = ['python3', 'python', 'py'];
+  for (const cmd of cmds) {
+    const args = cmd === 'py' ? ['-3', '--version'] : ['--version'];
+    try {
+      const res = spawnSync(cmd, args, { encoding: 'utf8', timeout: 2000 });
+      if (res.status === 0) {
+        const out = (res.stdout || res.stderr || '').trim();
+        const m = out.match(/Python\s+(\d+\.\d+\.\d+)/i);
+        if (m) {
+          const ver = m[1];
+          const [major, minor] = ver.split('.').map(Number);
+          if (major === 3 && minor >= 9) {
+            return cmd;
+          }
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+  throw err('Python 3 (>= 3.9) introuvable dans le PATH.', 'Installe Python >= 3.9 pour utiliser SPARDA sur un projet FastAPI.');
+}
+
+function findFastAPIEntry(cwd) {
+  const candidates = [
+    'main.py', 'app.py', 'src/main.py', 'app/main.py'
+  ];
+  for (const rel of candidates) {
+    const abs = path.resolve(cwd, rel);
+    if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
+      const src = fs.readFileSync(abs, 'utf8');
+      if (src.includes('FastAPI(')) {
+        return path.relative(cwd, abs).split(path.sep).join('/');
+      }
+    }
+  }
+  
+  const entry = searchPyFiles(cwd, cwd);
+  if (entry) {
+    return path.relative(cwd, entry).split(path.sep).join('/');
+  }
+
+  throw err('Could not locate your FastAPI entry file (the one calling FastAPI()).', 'Specify it manually, or make sure FastAPI() is declared in one of your python files.');
+}
+
+function searchPyFiles(dir, root, countRef = { val: 0 }) {
+  const EXCLUDE = new Set(['node_modules', '.git', 'venv', '.venv', 'tests', '__pycache__']);
+  let items;
+  try {
+    items = fs.readdirSync(dir);
+  } catch {
+    return null;
+  }
+
+  for (const item of items) {
+    const abs = path.join(dir, item);
+    let stat;
+    try {
+      stat = fs.statSync(abs);
+    } catch {
+      continue;
+    }
+
+    if (stat.isDirectory()) {
+      if (EXCLUDE.has(item)) continue;
+      const found = searchPyFiles(abs, root, countRef);
+      if (found) return found;
+    } else if (stat.isFile() && item.endsWith('.py')) {
+      countRef.val++;
+      if (countRef.val > 200) return null;
+      const src = fs.readFileSync(abs, 'utf8');
+      if (src.includes('FastAPI(')) {
+        return abs;
+      }
+    }
+  }
+  return null;
+}
+
+function detectFastAPIPort(cwd, entryFile) {
+  const abs = path.resolve(cwd, entryFile);
+  if (!fs.existsSync(abs)) return 8000;
+  const src = fs.readFileSync(abs, 'utf8');
+  const m = src.match(/uvicorn\.run\([^)]*port\s*=\s*(\d+)/s);
+  if (m) return Number(m[1]);
+  return 8000;
 }
 
 function findExpressEntry(cwd, pkg) {
@@ -77,6 +170,9 @@ function detectExpressPort(cwd, entryFile) {
       }
     }
   }
+  // env fallback literal, wrapped or not: Number(process.env.PORT ?? 4477), process.env.APP_PORT || 4488
+  m = src.match(/process\.env\.\w*PORT\w*\s*(?:\?\?|\|\|)\s*(\d{2,5})/i);
+  if (m) return Number(m[1]);
   // PORT env var or const PORT = 3000 pattern
   m = src.match(/(?:PORT|port)\s*=\s*(?:process\.env\.\w+\s*(?:\|\||\?\?)\s*)?(\d{2,5})/);
   if (m) return Number(m[1]);

package/src/generator/express.js

@@ -5,13 +5,14 @@ import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { parse } from '@babel/parser';
 import { toolNameFor } from '../parser/express.js';
+import { carryOverManifest } from './manifest.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const MARK_START = '// >>> sparda-injection (do not edit this block) >>>';
 const MARK_END = '// <<< sparda-injection <<<';
 
 export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
-  const taken = new Set(['sparda_info', 'sparda_list_disabled_tools']);
+  const taken = new Set(['sparda_info', 'sparda_list_disabled_tools', 'sparda_get_context']);
   const tools = {};
   for (const r of routes) {
     const name = toolNameFor(r, taken);
@@ -25,8 +26,10 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
       confidence: r.confidence,
     };
   }
+  const prev = carryOverManifest(cwd, tools);
 
-  const localKey = crypto.randomUUID();
+  // stable across re-runs so a running bridge/host pair never desyncs
+  const localKey = prev?.localKey ?? crypto.randomUUID();
   const entryAbs = path.resolve(cwd, entryFile);
   const entryDir = path.dirname(entryAbs);
   const ext = entryFile.endsWith('.ts') ? '.ts' : entryFile.endsWith('.mjs') ? '.mjs' : entryFile.endsWith('.cjs') ? '.cjs' : '.js';
@@ -36,20 +39,49 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
   // --- render router from template
   let tpl = fs.readFileSync(path.join(__dirname, '..', '..', 'templates', 'express-router.txt'), 'utf8');
   const isESM = moduleType === 'esm';
+  const isTS = ext === '.ts';
+
+  let importLine = '';
+  let reqType = '';
+  let resType = '';
+  let nextType = '';
+
+  if (isTS) {
+    reqType = ': Request';
+    resType = ': Response';
+    nextType = ': NextFunction';
+    if (isESM) {
+      importLine = "import express, { Request, Response, NextFunction } from 'express';";
+    } else {
+      importLine = "import type { Request, Response, NextFunction } from 'express';\nconst express = require('express');";
+    }
+  } else {
+    importLine = isESM ? "import express from 'express';" : "const express = require('express');";
+  }
+
   tpl = tpl
-    .replace('__IMPORT_LINE__', isESM ? "import express from 'express';" : "const express = require('express');")
+    .replace('__IMPORT_LINE__', importLine)
     .replace('__ROUTER_DECL__', isESM
       ? 'export const spardaRouter = express.Router();'
       : 'const spardaRouter = express.Router();\nmodule.exports = { spardaRouter };')
     .replace('__JSON_MW__', 'express.json()')
     .replace('__TOOLS_JSON__', JSON.stringify(tools, null, 2))
     .replace('__LOCAL_KEY__', localKey)
-    .replace('__PORT__', String(port));
+    .replace('__PORT__', String(port))
+    .replace(/__REQ_TYPE__/g, reqType)
+    .replace(/__RES_TYPE__/g, resType)
+    .replace(/__NEXT_TYPE__/g, nextType)
+    .replace(/__STATS_TYPE__/g, isTS ? ': Record<string, any>' : '')
+    .replace(/__EVENTS_TYPE__/g, isTS ? ': any[]' : '')
+    .replace(/__ANY_TYPE__/g, isTS ? ': any' : '');
   atomicWrite(routerAbs, tpl);
 
   // --- inject into entry file (line-based via AST positions)
   const injection = injectIntoEntry({ entryAbs, moduleType, routerFileName, cwd });
 
+  // record what init did to .gitignore so `remove` can revert it exactly (hard rule #4, E-010)
+  const gitignore = ensureGitignore(cwd) ?? prev?.gitignore ?? null;
+
   // --- manifest
   const manifest = {
     version: 1,
@@ -62,10 +94,13 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
     injectedFiles: injection.injected ? [entryFile] : [],
     createdAt: new Date().toISOString(),
     tools: Object.fromEntries(Object.entries(tools).map(([k, v]) => [k, { method: v.method, path: v.path, enabled: v.enabled }])),
+    ...(gitignore ? { gitignore } : {}),
+    ...(prev?.semantic ? { semantic: prev.semantic } : {}),
+    ...(prev?.immune ? { immune: prev.immune } : {}),
+    ...(prev?.labs ? { labs: prev.labs } : {}),
   };
   atomicWrite(path.join(cwd, 'sparda.json'), JSON.stringify(manifest, null, 2) + '\n');
 
-  ensureGitignore(cwd);
   return { tools, manifest, routerFile: path.relative(cwd, routerAbs).split(path.sep).join('/'), injection };
 }
 
@@ -165,15 +200,19 @@ export function removeInjection(cwd, manifest) {
   return results;
 }
 
+// Returns what was done ('created' | 'appended' | null) so the manifest can
+// record it and `remove` can revert the exact edit (byte-for-byte promise).
 function ensureGitignore(cwd) {
   const gi = path.join(cwd, '.gitignore');
   const line = '.sparda/';
   if (fs.existsSync(gi)) {
     const content = fs.readFileSync(gi, 'utf8');
-    if (!content.split(/\r?\n/).includes(line)) fs.appendFileSync(gi, `\n${line}\n`);
-  } else {
-    fs.writeFileSync(gi, `${line}\n`);
+    if (content.split(/\r?\n/).includes(line)) return null;
+    fs.appendFileSync(gi, `\n${line}\n`);
+    return 'appended';
   }
+  fs.writeFileSync(gi, `${line}\n`);
+  return 'created';
 }
 
 function atomicWrite(file, content) {

package/src/generator/fastapi.js

@@ -0,0 +1,212 @@
+// generator/fastapi.js — router generation + python injection (spec: blueprint 04-GENERATION §A)
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { toolNameFor } from '../parser/express.js';
+import { carryOverManifest } from './manifest.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const MARK_START = '# >>> sparda-injection (do not edit this block) >>>';
+const MARK_END = '# <<< sparda-injection <<<';
+
+export function generateFastAPI({ cwd, entryFile, port, routes, entryAppVars, pythonCmd = 'python' }) {
+  const taken = new Set(['sparda_info', 'sparda_list_disabled_tools', 'sparda_get_context']);
+  const tools = {};
+  for (const r of routes) {
+    const name = toolNameFor(r, taken);
+    tools[name] = {
+      method: r.method.toUpperCase(),
+      path: r.path,
+      enabled: !r.mutating,             // write-safety: mutating tools off by default
+      pathParams: r.params.filter((p) => p.in === 'path').map((p) => p.name),
+      description: r.description,
+      params: r.params,
+      confidence: r.confidence,
+    };
+  }
+  const prev = carryOverManifest(cwd, tools);
+
+  // stable across re-runs so a running bridge/host pair never desyncs
+  const localKey = prev?.localKey ?? crypto.randomUUID();
+  const entryAbs = path.resolve(cwd, entryFile);
+  const entryDir = path.dirname(entryAbs);
+  const routerFileName = 'sparda_router.py';
+  const routerAbs = path.join(entryDir, routerFileName);
+
+  // --- render router from template
+  let tpl = fs.readFileSync(path.join(__dirname, '..', '..', 'templates', 'fastapi-router.txt'), 'utf8');
+  tpl = tpl
+    // double-stringify: a JSON string literal is also a valid Python string literal,
+    // and json.loads() in the template turns it into real Python values (E-009)
+    .replace('__TOOLS_JSON__', JSON.stringify(JSON.stringify(tools)))
+    .replace('__LOCAL_KEY__', localKey)
+    .replace('__PORT__', String(port));
+
+  atomicWrite(routerAbs, tpl);
+
+  // --- inject into entry file (regex-based with compilation safety check)
+  const injection = injectIntoEntry({ entryAbs, routerFileName, cwd, entryAppVars, pythonCmd });
+
+  // record what init did to .gitignore so `remove` can revert it exactly (hard rule #4, E-010)
+  const gitignore = ensureGitignore(cwd) ?? prev?.gitignore ?? null;
+
+  // --- manifest
+  const manifest = {
+    version: 1,
+    framework: 'fastapi',
+    entryFile,
+    port,
+    localKey,
+    generatedFiles: [path.relative(cwd, routerAbs).split(path.sep).join('/')],
+    injectedFiles: injection.injected ? [entryFile] : [],
+    createdAt: new Date().toISOString(),
+    tools: Object.fromEntries(Object.entries(tools).map(([k, v]) => [k, { method: v.method, path: v.path, enabled: v.enabled }])),
+    ...(gitignore ? { gitignore } : {}),
+    ...(prev?.semantic ? { semantic: prev.semantic } : {}),
+    ...(prev?.immune ? { immune: prev.immune } : {}),
+    ...(prev?.labs ? { labs: prev.labs } : {}),
+  };
+
+  atomicWrite(path.join(cwd, 'sparda.json'), JSON.stringify(manifest, null, 2) + '\n');
+
+  return { tools, manifest, routerFile: path.relative(cwd, routerAbs).split(path.sep).join('/'), injection };
+}
+
+function injectIntoEntry({ entryAbs, routerFileName, cwd, entryAppVars, pythonCmd }) {
+  const src = fs.readFileSync(entryAbs, 'utf8');
+  
+  // backup first
+  const backupDir = path.join(cwd, '.sparda', 'backup');
+  fs.mkdirSync(backupDir, { recursive: true });
+  fs.writeFileSync(path.join(backupDir, `${path.basename(entryAbs)}.${Date.now()}`), src);
+
+  // Determine if directory has __init__.py (relative vs absolute import)
+  const entryDir = path.dirname(entryAbs);
+  const hasInit = fs.existsSync(path.join(entryDir, '__init__.py'));
+  const importLine = hasInit
+    ? 'from .sparda_router import sparda_router'
+    : 'from sparda_router import sparda_router';
+
+  // preserve the file's own line endings (Windows checkouts are CRLF)
+  const eol = src.includes('\r\n') ? '\r\n' : '\n';
+
+  // strip previous injection blocks (idempotence)
+  let body = src;
+  const blockRx = new RegExp(`\\r?\\n?${escapeRx(MARK_START)}[\\s\\S]*?${escapeRx(MARK_END)}\\r?\\n?`, 'g');
+  body = body.replace(blockRx, eol);
+
+  // Let's find the FastAPI() call assignment to inject right after it
+  // ([ \t]*) — NOT (\s*): \s matches newlines and would swallow blank lines/CR into the "indent" (E-007)
+  const match = body.match(/^([ \t]*)(\w+)\s*=\s*(?:\w+\.)?FastAPI\(/m);
+  if (!match) {
+    return {
+      injected: false,
+      manual: [importLine, 'app.include_router(sparda_router, prefix="/mcp")']
+    };
+  }
+
+  const indent = match[1];
+  const appName = match[2];
+
+  // Prepare injection block
+  const useBlock = [
+    MARK_START,
+    `${indent}${importLine}`,
+    `${indent}${appName}.include_router(sparda_router, prefix="/mcp")`,
+    MARK_END
+  ];
+
+  // We find where the matching line starts and ends in order to insert right after it.
+  const lines = body.split(/\r?\n/);
+  let insertAt = -1;
+  const linePattern = new RegExp(`^[ \\t]*${appName}\\s*=\\s*(?:\\w+\\.)?FastAPI\\(`);
+  for (let i = 0; i < lines.length; i++) {
+    if (linePattern.test(lines[i])) {
+      insertAt = i + 1; // Insert AFTER this line
+      break;
+    }
+  }
+
+  if (insertAt === -1) {
+    return {
+      injected: false,
+      manual: [importLine, `${appName}.include_router(sparda_router, prefix="/mcp")`]
+    };
+  }
+
+  lines.splice(insertAt, 0, ...useBlock);
+  const out = lines.join(eol);
+
+  // Post-injection compilation check to avoid syntax errors
+  if (!verifyPythonSyntax(entryAbs, out, pythonCmd)) {
+    return {
+      injected: false,
+      manual: [importLine, `${appName}.include_router(sparda_router, prefix="/mcp")`]
+    };
+  }
+
+  atomicWrite(entryAbs, out);
+  return { injected: true, manual: null };
+}
+
+export function removeInjection(cwd, manifest, pythonCmd = 'python') {
+  const results = [];
+  for (const relFile of manifest.injectedFiles ?? []) {
+    const abs = path.resolve(cwd, relFile);
+    if (!fs.existsSync(abs)) continue;
+    const src = fs.readFileSync(abs, 'utf8');
+    const blockRx = new RegExp(`\\r?\\n?${escapeRx(MARK_START)}[\\s\\S]*?${escapeRx(MARK_END)}`, 'g');
+    const out = src.replace(blockRx, '');
+    
+    if (verifyPythonSyntax(abs, out, pythonCmd)) {
+      atomicWrite(abs, out);
+      results.push({ file: relFile, ok: true });
+    } else {
+      results.push({ file: relFile, ok: false });
+    }
+  }
+  return results;
+}
+
+function verifyPythonSyntax(filePath, content, pythonCmd) {
+  const tmpFile = `${filePath}.syntax-check.py`;
+  try {
+    fs.writeFileSync(tmpFile, content);
+    const args = pythonCmd === 'py' ? ['-3', '-m', 'py_compile', tmpFile] : ['-m', 'py_compile', tmpFile];
+    const res = spawnSync(pythonCmd, args, { timeout: 2000 });
+    return res.status === 0;
+  } catch {
+    return false;
+  } finally {
+    try {
+      if (fs.existsSync(tmpFile)) fs.unlinkSync(tmpFile);
+    } catch {
+      // ignore
+    }
+  }
+}
+
+// Returns what was done ('created' | 'appended' | null) so the manifest can
+// record it and `remove` can revert the exact edit (byte-for-byte promise).
+function ensureGitignore(cwd) {
+  const gi = path.join(cwd, '.gitignore');
+  const line = '.sparda/';
+  if (fs.existsSync(gi)) {
+    const content = fs.readFileSync(gi, 'utf8');
+    if (content.split(/\r?\n/).includes(line)) return null;
+    fs.appendFileSync(gi, `\n${line}\n`);
+    return 'appended';
+  }
+  fs.writeFileSync(gi, `${line}\n`);
+  return 'created';
+}
+
+function atomicWrite(file, content) {
+  const tmp = `${file}.sparda-tmp`;
+  fs.writeFileSync(tmp, content);
+  fs.renameSync(tmp, file);
+}
+
+function escapeRx(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }

package/src/generator/manifest.js

@@ -0,0 +1,24 @@
+// generator/manifest.js — carry user state across re-runs of `sparda init`
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Re-running init must not wipe what the user (or the semantic/immune/Labs
+// passes) wrote into sparda.json: per-tool `enabled` overrides, the cached
+// `semantic` enrichment, the `immune` memory (antibodies) and the `labs`
+// state (opt-in flags + observed circuits) survive as long as the tool's
+// method+path are unchanged.
+export function carryOverManifest(cwd, tools) {
+  let prev = null;
+  try {
+    prev = JSON.parse(fs.readFileSync(path.join(cwd, 'sparda.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+  for (const [name, t] of Object.entries(tools)) {
+    const old = prev?.tools?.[name];
+    if (old && typeof old.enabled === 'boolean' && old.method === t.method && old.path === t.path) {
+      t.enabled = old.enabled;
+    }
+  }
+  return prev;
+}

package/src/index.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 // SPARDA — Turn any codebase into an MCP server. Residual Labs.
+import { readFileSync } from 'node:fs';
+
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 const [, , cmd, ...rest] = process.argv;
 
 const flags = new Set(rest.filter((a) => a.startsWith('--')));
@@ -11,6 +14,7 @@ const getOpt = (name, dflt) => {
 const opts = {
   yes: flags.has('--yes') || flags.has('-y'),
   verbose: flags.has('--verbose'),
+  quiet: flags.has('--quiet'),
   port: getOpt('port', null),
   cwd: process.cwd(),
 };
@@ -34,19 +38,34 @@ try {
     }
     case 'doctor': {
       const { runDoctor } = await import('./commands/doctor.js');
-      await runDoctor(opts);
+      const { healthy } = await runDoctor(opts);
+      if (!healthy) process.exitCode = 1; // let scripts/CI gate on doctor
+      break;
+    }
+    case 'sync': {
+      const { runSync } = await import('./commands/sync.js');
+      await runSync(opts);
+      break;
+    }
+    case 'hook': {
+      const { runHook } = await import('./commands/hook.js');
+      await runHook(opts);
       break;
     }
     default:
-      console.log(`SPARDA v0.1.0 — Turn any codebase into an MCP server.
+      console.log(`SPARDA v${VERSION} — Turn any codebase into an MCP server.
 
 Usage:
   npx sparda-mcp init      Scan project, generate & inject the MCP router
   npx sparda-mcp dev       Run the MCP stdio bridge (connect Claude Desktop)
+  npx sparda-mcp sync      Re-sync the router after route changes (no prompts)
+  npx sparda-mcp hook      Install the git sentinel (auto-sync after commits)
   npx sparda-mcp remove    Remove SPARDA from this project (clean git diff)
   npx sparda-mcp doctor    Diagnose your setup
 
-Flags: --yes (skip prompts)  --port <n>  --verbose`);
+Flags: --yes (skip prompts)  --port <n>  --quiet  --verbose
+
+By Residual Labs — residual-labs.fr`);
       process.exit(cmd ? 1 : 0);
   }
 } catch (err) {

package/src/parser/express.js

@@ -50,16 +50,29 @@ export function parseExpressProject(cwd, entryFile) {
     traverse(ast, {
       VariableDeclarator(p) {
         const init = p.node.init;
-        const name = p.node.id?.name;
-        if (!name || !init) return;
+        if (!init) return;
         if (init.type === 'CallExpression') {
           const callee = init.callee;
-          if (callee.type === 'Identifier' && callee.name === 'express') { appVars.add(name); exprStarts.add(p.node.loc.end.line); }
-          if (callee.type === 'Identifier' && callee.name === 'Router') routerVars.add(name);
-          if (callee.type === 'MemberExpression' && callee.property?.name === 'Router') routerVars.add(name);
           if (callee.type === 'Identifier' && callee.name === 'require' && init.arguments[0]?.type === 'StringLiteral') {
             const resolved = resolveRel(absFile, init.arguments[0].value);
-            if (resolved) importMap.set(name, resolved);
+            if (resolved) {
+              const id = p.node.id;
+              if (id.type === 'Identifier') {
+                importMap.set(id.name, resolved);
+              } else if (id.type === 'ObjectPattern') {
+                for (const prop of id.properties) {
+                  if (prop.type === 'ObjectProperty' && prop.value.type === 'Identifier') {
+                    importMap.set(prop.value.name, resolved);
+                  }
+                }
+              }
+            }
+          }
+          const name = p.node.id?.name;
+          if (name) {
+            if (callee.type === 'Identifier' && callee.name === 'express') { appVars.add(name); exprStarts.add(p.node.loc.end.line); }
+            if (callee.type === 'Identifier' && callee.name === 'Router') routerVars.add(name);
+            if (callee.type === 'MemberExpression' && callee.property?.name === 'Router') routerVars.add(name);
           }
         }
       },
@@ -97,6 +110,11 @@ export function parseExpressProject(cwd, entryFile) {
         }
 
         const fullPath = joinPath(prefix, pathArg.value);
+        if (fullPath.startsWith('/mcp')) {
+          skipped.push({ reason: `self-referential path ${fullPath} blocked`, file: rel(absFile), line: p.node.loc?.start.line });
+          return;
+        }
+
         const handler = args[args.length - 1];
         const handlerName = handler?.type === 'Identifier' ? handler.name
           : handler?.id?.name ?? `anonymous_${routes.length + 1}`;
@@ -111,6 +129,14 @@ export function parseExpressProject(cwd, entryFile) {
 
         const mutating = method !== 'get';
         const params = [...pathParams];
+        // query params: handlers reveal them as req.query.X / destructured req.query —
+        // without this the AI cannot discover ?limit=… filters at all (E2E P2 finding)
+        const taken = new Set(params.map((x) => x.name));
+        for (const q of queryParamsOf(p)) {
+          if (taken.has(q)) continue;
+          taken.add(q);
+          params.push({ name: q, in: 'query', type: 'string', required: false, description: 'query parameter' });
+        }
         let confidence = 'high';
         if (mutating) {
           params.push({ name: 'body', in: 'body', type: 'object', required: false, description: 'JSON body — schema not statically detected' });
@@ -141,7 +167,8 @@ export function parseExpressProject(cwd, entryFile) {
 
   function resolveRel(fromFile, spec) {
     if (!spec.startsWith('.')) return null;
-    const base = path.resolve(path.dirname(fromFile), spec);
+    const cleanSpec = spec.replace(/\.(m?[jt]s|cjs)$/, '');
+    const base = path.resolve(path.dirname(fromFile), cleanSpec);
     for (const cand of [base, `${base}.ts`, `${base}.js`, `${base}.mjs`, `${base}.cjs`,
       path.join(base, 'index.ts'), path.join(base, 'index.js')]) {
       if (fs.existsSync(cand) && fs.statSync(cand).isFile()) {
@@ -153,6 +180,40 @@ export function parseExpressProject(cwd, entryFile) {
   }
 }
 
+// Query params are invisible in a route's signature; only the handler body
+// reveals them. Covers the two canonical shapes — req.query.x / req.query['x']
+// and `const { x } = req.query` — on inline handlers only (an Identifier
+// handler lives elsewhere; guessing is worse than staying silent). Bounded.
+function queryParamsOf(callPath) {
+  const reqNames = new Set();
+  for (const a of callPath.node.arguments) {
+    if ((a.type === 'ArrowFunctionExpression' || a.type === 'FunctionExpression') && a.params[0]?.type === 'Identifier') {
+      reqNames.add(a.params[0].name);
+    }
+  }
+  const found = [];
+  if (!reqNames.size) return found;
+  const isReqQuery = (n) => n?.type === 'MemberExpression' && !n.computed &&
+    n.object?.type === 'Identifier' && reqNames.has(n.object.name) &&
+    n.property?.type === 'Identifier' && n.property.name === 'query';
+  callPath.traverse({
+    MemberExpression(q) {
+      const n = q.node;
+      if (!isReqQuery(n.object) || found.length >= 15) return;
+      if (!n.computed && n.property.type === 'Identifier') found.push(n.property.name);
+      else if (n.computed && n.property.type === 'StringLiteral') found.push(n.property.value);
+    },
+    VariableDeclarator(q) {
+      if (q.node.id.type !== 'ObjectPattern' || !isReqQuery(q.node.init)) return;
+      for (const prop of q.node.id.properties) {
+        if (found.length >= 15) break;
+        if (prop.type === 'ObjectProperty' && prop.key.type === 'Identifier') found.push(prop.key.name);
+      }
+    },
+  });
+  return [...new Set(found)];
+}
+
 function joinPath(prefix, p) {
   const joined = `${prefix ?? ''}${p === '/' && prefix ? '' : p}`.replace(/\/{2,}/g, '/');
   return joined.startsWith('/') ? joined : `/${joined}`;
@@ -172,6 +233,7 @@ export function toolNameFor(route, taken) {
   let name = `${route.method}_${route.path}`
     .toLowerCase()
     .replace(/:(\w+)/g, 'by_$1')
+    .replace(/\{(\w+)\}/g, 'by_$1')
     .replace(/[^a-z0-9]+/g, '_')
     .replace(/^_+|_+$/g, '')
     .slice(0, 60) || 'tool';

package/src/parser/fastapi.js

@@ -0,0 +1,26 @@
+// parser/fastapi.js — JS wrapper executing Python AST extractor (spec: blueprint 03-PARSING §C)
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export function parseFastAPIProject(cwd, entryFile, pythonCmd = 'python') {
+  const extractorScript = path.resolve(__dirname, 'fastapi_extract.py');
+  const res = spawnSync(pythonCmd, [extractorScript, entryFile, cwd], { cwd, encoding: 'utf8' });
+  
+  if (res.status !== 0) {
+    const errorMsg = (res.stderr || res.stdout || '').trim();
+    throw new Error(`FastAPI extraction process failed: ${errorMsg}`);
+  }
+
+  try {
+    const payload = JSON.parse(res.stdout.trim());
+    if (payload.error) {
+      throw new Error(payload.error);
+    }
+    return { routes: payload.routes || [], skipped: payload.skipped || [], entryAppVars: payload.entryAppVars || [] };
+  } catch (err) {
+    throw new Error(`Failed to parse Python extractor output: ${err.message}. Raw output: ${res.stdout}`);
+  }
+}