sparda-mcp 0.1.0 → 0.3.0

package/src/server/stdio.js

@@ -4,7 +4,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import {
+  CallToolRequestSchema, ListToolsRequestSchema,
+  ListPromptsRequestSchema, GetPromptRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { sanitizeDescription } from '../security/sanitize.js';
+
+const EVENT_POLL_MS = Number(process.env.SPARDA_EVENT_POLL_MS ?? 5000);
 
 export async function startStdioBridge({ cwd, portOverride }) {
   // pitfall #1: neutralize any stray console.log from deps
@@ -16,30 +22,40 @@ export async function startStdioBridge({ cwd, portOverride }) {
   }
   const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
   const port = Number(portOverride ?? manifest.port);
+  const framework = manifest.framework;
   const key = manifest.localKey;
-  const base = await waitForHost(port, key);
+  if (!key) {
+    throw Object.assign(new Error('localKey missing from sparda.json.'), { code: 'USER', hint: 'Re-run `npx sparda-mcp init` to regenerate it.' });
+  }
+  const base = await waitForHost(port, key, framework);
 
   // full tool specs live in the generated router; fetch them (single source of truth)
   const toolSpecs = await (await fetch(`${base}/mcp/tools`, { headers: { 'x-sparda-key': key } })).json();
 
-  const enabled = Object.entries(toolSpecs).filter(([, t]) => t.enabled);
-  const disabled = Object.entries(toolSpecs).filter(([, t]) => !t.enabled);
+  const enabled = () => Object.entries(toolSpecs).filter(([, t]) => t.enabled);
+  const disabled = () => Object.entries(toolSpecs).filter(([, t]) => !t.enabled);
 
   const server = new Server(
-    { name: `sparda-${path.basename(cwd)}`, version: '0.1.0' },
-    { capabilities: { tools: {} } },
+    { name: `sparda-${path.basename(cwd)}`, version: '0.3.0' },
+    { capabilities: { tools: { listChanged: true }, prompts: { listChanged: true }, logging: {} } },
   );
 
+  const descFor = (name, t) => {
+    const semantic = manifest.semantic?.descriptions?.[name];
+    const text = semantic || t.description || `${t.method} ${t.path}`;
+    return `${t.confidence === 'low' ? '[partial schema] ' : ''}${text}`;
+  };
+
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
-      ...enabled.map(([name, t]) => ({
+      ...enabled().map(([name, t]) => ({
         name,
-        description: `${t.confidence === 'low' ? '[partial schema] ' : ''}${t.description || `${t.method} ${t.path}`}`,
+        description: descFor(name, t),
         inputSchema: schemaFor(t),
       })),
       {
         name: 'sparda_info',
-        description: 'Info about this MCP server. Generated by SPARDA (npx sparda-mcp init) — turn any codebase into an MCP server in 3 minutes. github.com/zyx77550/sparda',
+        description: 'Info about this MCP server. Generated by SPARDA (npx sparda-mcp init) — turn any codebase into an MCP server in 3 minutes. By Residual Labs (residual-labs.fr) — github.com/zyx77550/sparda',
         inputSchema: { type: 'object', properties: {} },
       },
       {
@@ -47,44 +63,267 @@ export async function startStdioBridge({ cwd, portOverride }) {
         description: 'Lists write tools (POST/PUT/DELETE) disabled by SPARDA write-safety, and how to enable them.',
         inputSchema: { type: 'object', properties: {} },
       },
+      {
+        name: 'sparda_get_context',
+        description: 'Call this FIRST. Returns the full living context of this app: every tool with its description, known workflows, runtime telemetry (per-tool calls/errors/latency), quarantined tools, and the immune memory of past diagnosed failures. Lets any AI session resume exactly where the previous one stopped.',
+        inputSchema: { type: 'object', properties: {} },
+      },
     ],
   }));
 
+  server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: (manifest.semantic?.workflows ?? []).map((w) => ({
+      name: w.name,
+      description: w.description,
+    })),
+  }));
+
+  server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+    const w = (manifest.semantic?.workflows ?? []).find((x) => x.name === req.params.name);
+    if (!w) throw new Error(`unknown prompt: ${req.params.name}`);
+    return {
+      description: w.description,
+      messages: [{
+        role: 'user',
+        content: {
+          type: 'text',
+          text: `Goal: ${w.description}\n\nUse the available SPARDA tools in this order, adapting arguments from each result:\n${w.steps.map((s, i) => `${i + 1}. ${s}`).join('\n')}`,
+        },
+      }],
+    };
+  });
+
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const { name, arguments: args = {} } = req.params;
 
     if (name === 'sparda_info') {
       return text(JSON.stringify({
         project: path.basename(cwd), framework: manifest.framework,
-        tools_enabled: enabled.length, tools_disabled_write_safety: disabled.length,
-        generated_by: 'SPARDA — npx sparda-mcp init — github.com/zyx77550/sparda',
+        tools_enabled: enabled().length, tools_disabled_write_safety: disabled().length,
+        workflows: (manifest.semantic?.workflows ?? []).length,
+        immune_antibodies: Object.keys(manifest.immune?.antibodies ?? {}).length,
+        generated_by: 'SPARDA by Residual Labs (residual-labs.fr) — npx sparda-mcp init — github.com/zyx77550/sparda',
+      }, null, 2));
+    }
+    if (name === 'sparda_get_context') {
+      const headers = { 'x-sparda-key': key };
+      const [stats, events] = await Promise.all([
+        fetch(`${base}/mcp/stats`, { headers, signal: AbortSignal.timeout(2000) }).then((r) => (r.ok ? r.json() : null)).catch(() => null),
+        fetch(`${base}/mcp/events?since=0`, { headers, signal: AbortSignal.timeout(2000) }).then((r) => (r.ok ? r.json() : null)).catch(() => null),
+      ]);
+      return text(JSON.stringify({
+        project: path.basename(cwd),
+        framework: manifest.framework,
+        port,
+        tools: Object.fromEntries(Object.entries(toolSpecs).map(([n, t]) => [n, { method: t.method, path: t.path, enabled: t.enabled, description: descFor(n, t) }])),
+        workflows: manifest.semantic?.workflows ?? [],
+        runtime: stats,
+        recentEvents: (events?.events ?? []).slice(-20),
+        immuneMemory: manifest.immune?.antibodies ?? {},
+        hint: 'runtime.quarantine lists tools temporarily blocked by the immune system (503 until cooldown). immuneMemory maps failure signatures (source|tool|status) to cached diagnoses — same failure later costs zero tokens.',
       }, null, 2));
     }
     if (name === 'sparda_list_disabled_tools') {
-      return text(disabled.length
-        ? `Disabled (write-safety):\n${disabled.map(([n, t]) => `- ${n} (${t.method} ${t.path})`).join('\n')}\n\nTo enable: set "enabled": true in sparda.json, then re-run \`npx sparda-mcp init\` and restart this bridge.`
+      return text(disabled().length
+        ? `Disabled (write-safety):\n${disabled().map(([n, t]) => `- ${n} (${t.method} ${t.path})`).join('\n')}\n\nTo enable: set "enabled": true in sparda.json, then re-run \`npx sparda-mcp init\` and restart this bridge.`
         : 'No disabled tools.');
     }
 
-    try {
-      const res = await fetch(`${base}/mcp/invoke`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json', 'x-sparda-key': key },
-        body: JSON.stringify({ tool: name, args }),
-        signal: AbortSignal.timeout(30_000),
-      });
-      const payload = await res.json().catch(() => ({ error: 'non-JSON response from host' }));
-      const pretty = JSON.stringify(payload, null, 2);
-      const truncated = pretty.length > 8000 ? `${pretty.slice(0, 8000)}\n[truncated — ${pretty.length} chars total]` : pretty;
-      return { content: [{ type: 'text', text: truncated }], isError: res.status >= 400 };
-    } catch (err) {
-      return { content: [{ type: 'text', text: `Host app error: ${err.message}. Check that your server is still running on :${port}.` }], isError: true };
+    const spec = toolSpecs[name];
+    const isWrite = spec && spec.method !== 'GET';
+
+    // human-in-the-loop: confirm writes natively in the client UI when supported
+    if (isWrite && server.getClientCapabilities()?.elicitation) {
+      const answer = await server.elicitInput({
+        message: `SPARDA: allow ${spec.method} ${spec.path}? This is a write operation on your live app.`,
+        requestedSchema: {
+          type: 'object',
+          properties: { confirm: { type: 'boolean', title: `Allow ${spec.method} ${spec.path}` } },
+          required: ['confirm'],
+        },
+      }).catch(() => null);
+      if (!answer || answer.action !== 'accept' || answer.content?.confirm !== true) {
+        return { content: [{ type: 'text', text: `Write declined by user: ${spec.method} ${spec.path} was NOT executed.` }], isError: true };
+      }
     }
+
+    const payload = await invoke(base, key, name, args);
+    if (payload === null) {
+      return { content: [{ type: 'text', text: `Host app error. Check that your server is still running on :${port}.` }], isError: true };
+    }
+
+    // proof-after-write: re-read the same path so the AI sees the effect of its write
+    let proof = null;
+    if (isWrite && payload.upstreamStatus < 400) {
+      const getter = Object.entries(toolSpecs).find(([, t]) => t.enabled && t.method === 'GET' && t.path === spec.path);
+      if (getter) {
+        const after = await invoke(base, key, getter[0], pickPathArgs(spec, args));
+        if (after && after.upstreamStatus < 400) proof = { readBack: getter[0], state: after.data };
+      }
+    }
+
+    const body = proof ? { ...payload, proof } : payload;
+    const pretty = JSON.stringify(body, null, 2);
+    const truncated = pretty.length > 8000 ? `${pretty.slice(0, 8000)}\n[truncated — ${pretty.length} chars total]` : pretty;
+    // router-level rejections (quarantine, disabled tool, bad params) carry `error` and no upstreamStatus
+    const isError = payload.upstreamStatus !== undefined ? payload.upstreamStatus >= 400 : Boolean(payload.error);
+    return { content: [{ type: 'text', text: truncated }], isError };
   });
 
+  let pollTimer = null;
+  server.oninitialized = () => {
+    pollTimer = startEventPolling(server, base, key, manifest, manifestPath);
+    runSemanticEnrichment({ server, manifest, manifestPath, toolSpecs }).catch((e) => console.error(`[sparda] semantic pass skipped: ${e.message}`));
+  };
+  server.onclose = () => { if (pollTimer) clearInterval(pollTimer); };
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error(`[sparda] MCP bridge running. ${enabled.length} tools enabled, ${disabled.length} disabled (write-safety). Host: ${base}`);
+  console.error(`[sparda] MCP bridge running. ${enabled().length} tools enabled, ${disabled().length} disabled (write-safety). Host: ${base}`);
+}
+
+async function invoke(base, key, tool, args) {
+  try {
+    const res = await fetch(`${base}/mcp/invoke`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-sparda-key': key },
+      body: JSON.stringify({ tool, args }),
+      signal: AbortSignal.timeout(30_000),
+    });
+    return await res.json().catch(() => ({ upstreamStatus: res.status, error: 'non-JSON response from host' }));
+  } catch {
+    return null;
+  }
+}
+
+// keep only the path params of the original call so the read-back targets the same resource
+function pickPathArgs(spec, args) {
+  const out = {};
+  for (const p of spec.pathParams ?? []) if (args[p] !== undefined) out[p] = args[p];
+  return out;
+}
+
+// live error feed: host app errors reach the AI as MCP logging notifications.
+// immune memory: known failure signatures carry their cached diagnosis (zero tokens);
+// new signatures wake the client's LLM once, and the antibody is stored in sparda.json.
+function startEventPolling(server, base, key, manifest, manifestPath) {
+  let lastSeq = null; // first poll sets the baseline; only NEW errors are reported
+  const timer = setInterval(async () => {
+    try {
+      const r = await fetch(`${base}/mcp/events?since=${lastSeq ?? 0}`, { headers: { 'x-sparda-key': key }, signal: AbortSignal.timeout(2000) });
+      if (!r.ok) return;
+      const { seq, events } = await r.json();
+      if (lastSeq === null) { lastSeq = seq; return; }
+      lastSeq = Math.max(lastSeq, seq);
+      for (const ev of events) {
+        const sig = `${ev.source}|${ev.tool ?? ''}|${ev.status ?? ''}`;
+        const antibody = manifest.immune?.antibodies?.[sig];
+        if (antibody) {
+          antibody.hits = (antibody.hits ?? 0) + 1;
+          antibody.lastSeen = ev.ts;
+          persistImmune(manifestPath, manifest);
+          await server.sendLoggingMessage({ level: 'error', logger: 'sparda', data: { ...ev, diagnosis: antibody.diagnosis } }).catch(() => {});
+        } else {
+          await server.sendLoggingMessage({ level: 'error', logger: 'sparda', data: ev }).catch(() => {});
+          diagnoseAndRemember({ server, manifest, manifestPath, ev, sig }).catch(() => {});
+        }
+      }
+    } catch { /* host briefly unreachable — next tick */ }
+  }, EVENT_POLL_MS);
+  timer.unref?.();
+  return timer;
+}
+
+// adaptive immunity: costly intelligence is summoned only when the body has a fever,
+// and the diagnosis is remembered so the same fever never costs tokens again.
+const diagnosing = new Set();
+async function diagnoseAndRemember({ server, manifest, manifestPath, ev, sig }) {
+  if (!server.getClientCapabilities()?.sampling) return;
+  if (diagnosing.has(sig)) return;
+  manifest.immune ??= {};
+  manifest.immune.antibodies ??= {};
+  const antibodies = manifest.immune.antibodies;
+  if (antibodies[sig] || Object.keys(antibodies).length >= 50) return; // bounded memory
+  diagnosing.add(sig);
+  try {
+    const res = await server.createMessage({
+      messages: [{
+        role: 'user',
+        content: {
+          type: 'text',
+          text: `A tool of a live ${manifest.framework} app just failed.\nTool: ${ev.tool ?? 'n/a'}\nSource: ${ev.source}\nStatus: ${ev.status ?? 'n/a'}\nError message: ${ev.message}\n\nReply with ONE short sentence (max 140 chars): most likely root cause and fix direction. No preamble.`,
+        },
+      }],
+      maxTokens: 120,
+    });
+    const raw = res?.content?.type === 'text' ? res.content.text.trim() : '';
+    const { text: clean, flagged } = sanitizeDescription(raw, '');
+    if (!clean || flagged) return;
+    antibodies[sig] = { diagnosis: clean, firstSeen: ev.ts, lastSeen: ev.ts, hits: 1 };
+    persistImmune(manifestPath, manifest);
+    await server.sendLoggingMessage({
+      level: 'info', logger: 'sparda',
+      data: { source: 'immune', signature: sig, diagnosis: clean, note: 'antibody stored in sparda.json — the same failure will be diagnosed instantly, zero tokens' },
+    }).catch(() => {});
+    console.error(`[sparda] immune: antibody stored for ${sig}`);
+  } finally {
+    diagnosing.delete(sig);
+  }
+}
+
+function persistImmune(manifestPath, manifest) {
+  try {
+    const onDisk = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    onDisk.immune = manifest.immune;
+    fs.writeFileSync(manifestPath, JSON.stringify(onDisk, null, 2) + '\n');
+  } catch { /* disk briefly unavailable — the antibody stays in memory */ }
+}
+
+// semantic pass: uses the CLIENT's own model via MCP sampling — zero key, zero cost.
+// Runs once, result cached in sparda.json (and preserved across re-init).
+async function runSemanticEnrichment({ server, manifest, manifestPath, toolSpecs }) {
+  if (manifest.semantic || !server.getClientCapabilities()?.sampling) return;
+
+  const inventory = Object.entries(toolSpecs).map(([n, t]) =>
+    `- ${n}: ${t.method} ${t.path}${t.description ? ` — ${t.description}` : ''}`).join('\n');
+  const res = await server.createMessage({
+    messages: [{
+      role: 'user',
+      content: {
+        type: 'text',
+        text: `These are API tools extracted from a ${manifest.framework} codebase:\n${inventory}\n\nReply with ONLY a JSON object, no prose, shaped as {"descriptions": {"<tool>": "<one clear sentence of what it does in business terms>"}, "workflows": [{"name": "<snake_case>", "description": "<goal>", "steps": ["<tool>", ...]}]}. Include 1-3 workflows that chain tools toward a realistic business goal. Use only the tool names listed above.`,
+      },
+    }],
+    maxTokens: 1500,
+  });
+
+  const raw = res?.content?.type === 'text' ? res.content.text : '';
+  const parsed = JSON.parse(raw.replace(/^```(json)?\s*/i, '').replace(/```\s*$/, ''));
+
+  const descriptions = {};
+  for (const [n, d] of Object.entries(parsed.descriptions ?? {})) {
+    if (!toolSpecs[n] || typeof d !== 'string') continue;
+    const { text: clean, flagged } = sanitizeDescription(d, '');
+    if (clean && !flagged) descriptions[n] = clean;
+  }
+  const workflows = (Array.isArray(parsed.workflows) ? parsed.workflows : [])
+    .filter((w) => w && typeof w.name === 'string' && typeof w.description === 'string' && Array.isArray(w.steps))
+    .slice(0, 5)
+    .map((w) => ({
+      name: w.name.toLowerCase().replace(/[^a-z0-9_]/g, '_').slice(0, 60),
+      description: sanitizeDescription(w.description, 'workflow').text,
+      steps: w.steps.filter((s) => typeof s === 'string' && toolSpecs[s]),
+    }))
+    .filter((w) => w.steps.length > 0);
+
+  manifest.semantic = { enrichedAt: new Date().toISOString(), source: 'mcp-sampling', descriptions, workflows };
+  const onDisk = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  onDisk.semantic = manifest.semantic;
+  fs.writeFileSync(manifestPath, JSON.stringify(onDisk, null, 2) + '\n');
+
+  await server.sendToolListChanged().catch(() => {});
+  await server.sendPromptListChanged().catch(() => {});
+  console.error(`[sparda] semantic pass done: ${Object.keys(descriptions).length} descriptions, ${workflows.length} workflows (cached in sparda.json)`);
 }
 
 function schemaFor(t) {
@@ -98,7 +337,7 @@ function schemaFor(t) {
 
 function text(t) { return { content: [{ type: 'text', text: t }] }; }
 
-async function waitForHost(port, key) {
+async function waitForHost(port, key, framework) {
   const hosts = ['127.0.0.1', 'localhost'];
   for (let attempt = 0; attempt < 40; attempt++) {
     for (const h of hosts) {
@@ -108,7 +347,10 @@ async function waitForHost(port, key) {
         if (r.status === 401) throw Object.assign(new Error('Host app reachable but key mismatch — re-run `npx sparda-mcp init`.'), { code: 'USER' });
       } catch (e) { if (e.code === 'USER') throw e; }
     }
-    if (attempt === 0) console.error(`[sparda] Waiting for host app on :${port} ... (start it with npm run dev — Ctrl+C to abort)`);
+    if (attempt === 0) {
+      const startCmd = framework === 'express' ? 'npm run dev' : 'fastapi dev';
+      console.error(`[sparda] Waiting for host app on :${port} ... (start it with ${startCmd} — Ctrl+C to abort)`);
+    }
     await new Promise((r) => setTimeout(r, 3000));
   }
   throw Object.assign(new Error(`Host app unreachable on :${port} after 2 minutes.`), { code: 'USER', hint: 'Start your server first, then run `npx sparda-mcp dev`.' });

package/templates/express-router.txt

@@ -9,19 +9,40 @@ const SPARDA_TOOLS = __TOOLS_JSON__;
 const SPARDA_LOCAL_KEY = "__LOCAL_KEY__";
 const SPARDA_PORT = __PORT__;
 
+const SPARDA_STATS__STATS_TYPE__ = {};
+const SPARDA_EVENTS__EVENTS_TYPE__ = [];
+let SPARDA_SEQ = 0;
+// immune system: tools that keep failing are quarantined so the AI can't hammer a broken route
+const SPARDA_QUARANTINE__STATS_TYPE__ = {};
+const SPARDA_QUARANTINE_MS = Number(process.env.SPARDA_QUARANTINE_MS ?? 60000);
+function spardaEvent(source__ANY_TYPE__, tool__ANY_TYPE__, status__ANY_TYPE__, message__ANY_TYPE__) {
+  SPARDA_EVENTS.push({ seq: ++SPARDA_SEQ, ts: new Date().toISOString(), source, tool, status, message: String(message ?? '').slice(0, 500) });
+  if (SPARDA_EVENTS.length > 100) SPARDA_EVENTS.shift();
+}
+// observe-only: uncaughtExceptionMonitor never changes the host app's crash behavior
+process.on('uncaughtExceptionMonitor', (err__ANY_TYPE__) => spardaEvent('process', null, null, err && err.message ? err.message : err));
+
 __ROUTER_DECL__
 
-spardaRouter.use((req, res, next) => {
+spardaRouter.use((req__REQ_TYPE__, res__RES_TYPE__, next__NEXT_TYPE__) => {
   if (req.headers['x-sparda-key'] !== SPARDA_LOCAL_KEY) {
     return res.status(401).json({ error: 'unauthorized' });
   }
   next();
 });
 
-spardaRouter.get('/tools', (_req, res) => res.json(SPARDA_TOOLS));
+spardaRouter.get('/tools', (_req__REQ_TYPE__, res__RES_TYPE__) => res.json(SPARDA_TOOLS));
+
+spardaRouter.get('/stats', (_req__REQ_TYPE__, res__RES_TYPE__) => res.json({ uptimeSec: Math.round(process.uptime()), stats: SPARDA_STATS, quarantine: SPARDA_QUARANTINE }));
 
-spardaRouter.post('/invoke', __JSON_MW__, async (req, res) => {
+spardaRouter.get('/events', (req__REQ_TYPE__, res__RES_TYPE__) => {
+  const since = Number(req.query.since ?? 0) || 0;
+  res.json({ seq: SPARDA_SEQ, events: SPARDA_EVENTS.filter((e__ANY_TYPE__) => e.seq > since) });
+});
+
+spardaRouter.post('/invoke', __JSON_MW__, async (req__REQ_TYPE__, res__RES_TYPE__) => {
   const { tool, args = {} } = req.body ?? {};
+  const t0 = Date.now();
   const spec = SPARDA_TOOLS[tool];
   if (!spec) return res.status(404).json({ error: `unknown tool: ${tool}` });
   if (!spec.enabled) {
@@ -30,6 +51,15 @@ spardaRouter.post('/invoke', __JSON_MW__, async (req, res) => {
   if (spec.path.startsWith('/mcp')) {
     return res.status(400).json({ error: 'self-referential tool blocked (loop protection)' });
   }
+  const quarantined = SPARDA_QUARANTINE[tool];
+  if (quarantined) {
+    if (Date.now() < quarantined.until) {
+      return res.status(503).json({ error: `tool quarantined (immune system): ${tool}`, reason: quarantined.reason, retryInMs: quarantined.until - Date.now() });
+    }
+    // half-open: cooldown elapsed — allow one probe; a single new 5xx re-quarantines
+    delete SPARDA_QUARANTINE[tool];
+    if (SPARDA_STATS[tool]) SPARDA_STATS[tool].consecutive5xx = 2;
+  }
   try {
     let url = spec.path.replace(/:(\w+)/g, (_, name) => {
       const v = args[name];
@@ -51,8 +81,31 @@ spardaRouter.post('/invoke', __JSON_MW__, async (req, res) => {
     const upstream = await fetch(`http://127.0.0.1:${SPARDA_PORT}${url}`, { ...init, signal: AbortSignal.timeout(30_000) });
     const text = await upstream.text();
     let data; try { data = JSON.parse(text); } catch { data = text; }
+    spardaRecord(tool, upstream.status, Date.now() - t0);
+    if (upstream.status >= 500) spardaEvent('invoke', tool, upstream.status, text.slice(0, 200));
     return res.status(200).json({ upstreamStatus: upstream.status, data });
-  } catch (err) {
+  } catch (err__ANY_TYPE__) {
+    spardaRecord(tool, err.status ?? 502, Date.now() - t0);
+    spardaEvent('invoke', tool, err.status ?? 502, err.message);
     return res.status(err.status ?? 502).json({ error: err.message });
   }
 });
+
+function spardaRecord(tool__ANY_TYPE__, status__ANY_TYPE__, ms__ANY_TYPE__) {
+  const st = SPARDA_STATS[tool] ?? (SPARDA_STATS[tool] = { calls: 0, errors: 0, totalMs: 0, lastStatus: null, lastTs: null, consecutive5xx: 0 });
+  // innate immunity: latency far beyond the learned baseline is an antigen
+  if (st.calls >= 5 && ms > Math.max((st.totalMs / st.calls) * 10, 200)) {
+    spardaEvent('immune', tool, status, `latency anomaly: ${ms}ms vs ~${Math.round(st.totalMs / st.calls)}ms baseline`);
+  }
+  st.calls += 1;
+  st.totalMs += ms;
+  if (status >= 400) st.errors += 1;
+  st.lastStatus = status;
+  st.lastTs = new Date().toISOString();
+  if (status >= 500) st.consecutive5xx += 1;
+  else if (status < 400) st.consecutive5xx = 0;
+  if (st.consecutive5xx >= 3 && !SPARDA_QUARANTINE[tool]) {
+    SPARDA_QUARANTINE[tool] = { since: new Date().toISOString(), until: Date.now() + SPARDA_QUARANTINE_MS, reason: `${st.consecutive5xx} consecutive 5xx` };
+    spardaEvent('immune', tool, 503, `quarantined after ${st.consecutive5xx} consecutive 5xx (cooldown ${SPARDA_QUARANTINE_MS}ms)`);
+  }
+}

package/templates/fastapi-router.txt

@@ -0,0 +1,198 @@
+# ============================================================
+# SPARDA ROUTER — Auto-generated. DO NOT EDIT.
+# Regenerate: npx sparda-mcp init   •   Remove: npx sparda-mcp remove
+# ============================================================
+from fastapi import APIRouter, Request, Response, HTTPException
+from fastapi.responses import JSONResponse
+import json
+import urllib.request
+import urllib.parse
+import concurrent.futures
+import re
+import asyncio
+import time
+import datetime
+import os
+
+# json.loads, not a Python literal: JSON true/false/null are not valid Python (E-009)
+SPARDA_TOOLS = json.loads(__TOOLS_JSON__)
+SPARDA_LOCAL_KEY = "__LOCAL_KEY__"
+SPARDA_PORT = __PORT__
+
+SPARDA_STATS = {}
+SPARDA_EVENTS = []
+SPARDA_SEQ = 0
+SPARDA_START = time.time()
+# immune system: tools that keep failing are quarantined so the AI can't hammer a broken route
+SPARDA_QUARANTINE = {}
+SPARDA_QUARANTINE_MS = int(os.environ.get("SPARDA_QUARANTINE_MS", "60000"))
+
+def sparda_event(source, tool, status, message):
+    global SPARDA_SEQ
+    SPARDA_SEQ += 1
+    SPARDA_EVENTS.append({
+        "seq": SPARDA_SEQ,
+        "ts": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+        "source": source, "tool": tool, "status": status,
+        "message": str(message or "")[:500],
+    })
+    if len(SPARDA_EVENTS) > 100:
+        SPARDA_EVENTS.pop(0)
+
+def sparda_record(tool, status, ms):
+    st = SPARDA_STATS.setdefault(tool, {"calls": 0, "errors": 0, "totalMs": 0, "lastStatus": None, "lastTs": None, "consecutive5xx": 0})
+    # innate immunity: latency far beyond the learned baseline is an antigen
+    if st["calls"] >= 5 and ms > max((st["totalMs"] / st["calls"]) * 10, 200):
+        sparda_event("immune", tool, status, f"latency anomaly: {ms}ms vs ~{round(st['totalMs'] / st['calls'])}ms baseline")
+    st["calls"] += 1
+    st["totalMs"] += ms
+    if status >= 400:
+        st["errors"] += 1
+    st["lastStatus"] = status
+    st["lastTs"] = datetime.datetime.now(datetime.timezone.utc).isoformat()
+    if status >= 500:
+        st["consecutive5xx"] = st.get("consecutive5xx", 0) + 1
+    elif status < 400:
+        st["consecutive5xx"] = 0
+    if st.get("consecutive5xx", 0) >= 3 and tool not in SPARDA_QUARANTINE:
+        SPARDA_QUARANTINE[tool] = {
+            "since": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+            "until": time.time() * 1000 + SPARDA_QUARANTINE_MS,
+            "reason": f"{st['consecutive5xx']} consecutive 5xx",
+        }
+        sparda_event("immune", tool, 503, f"quarantined after {st['consecutive5xx']} consecutive 5xx (cooldown {SPARDA_QUARANTINE_MS}ms)")
+
+sparda_router = APIRouter()
+executor = concurrent.futures.ThreadPoolExecutor(max_workers=10)
+
+def sync_fetch(url, method, headers, body_bytes):
+    req = urllib.request.Request(url, data=body_bytes, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=30) as response:
+            status = response.status
+            content_type = response.headers.get("content-type", "")
+            data = response.read()
+            return status, content_type, data
+    except urllib.error.HTTPError as e:
+        return e.code, e.headers.get("content-type", ""), e.read()
+    except Exception as e:
+        raise e
+
+@sparda_router.get("/tools")
+async def get_tools(request: Request):
+    if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=401, content={"error": "unauthorized"})
+    return SPARDA_TOOLS
+
+@sparda_router.get("/stats")
+async def get_stats(request: Request):
+    if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=401, content={"error": "unauthorized"})
+    return {"uptimeSec": round(time.time() - SPARDA_START), "stats": SPARDA_STATS, "quarantine": SPARDA_QUARANTINE}
+
+@sparda_router.get("/events")
+async def get_events(request: Request):
+    if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=401, content={"error": "unauthorized"})
+    try:
+        since = int(request.query_params.get("since", "0"))
+    except ValueError:
+        since = 0
+    return {"seq": SPARDA_SEQ, "events": [e for e in SPARDA_EVENTS if e["seq"] > since]}
+
+@sparda_router.post("/invoke")
+async def invoke_tool(request: Request):
+    if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=401, content={"error": "unauthorized"})
+
+    try:
+        body = await request.json()
+    except Exception:
+        body = {}
+
+    tool = body.get("tool")
+    args = body.get("args", {})
+    
+    spec = SPARDA_TOOLS.get(tool)
+    if not spec:
+        return JSONResponse(status_code=404, content={"error": f"unknown tool: {tool}"})
+
+    if not spec.get("enabled"):
+        return JSONResponse(status_code=403, content={
+            "error": f"tool disabled (write-safety): {tool}",
+            "hint": "Enable it in sparda.json, then re-run: npx sparda-mcp init"
+        })
+
+    path = spec.get("path")
+    if path.startswith("/mcp"):
+        return JSONResponse(status_code=400, content={"error": "self-referential tool blocked (loop protection)"})
+
+    quarantined = SPARDA_QUARANTINE.get(tool)
+    if quarantined:
+        now_ms = time.time() * 1000
+        if now_ms < quarantined["until"]:
+            return JSONResponse(status_code=503, content={
+                "error": f"tool quarantined (immune system): {tool}",
+                "reason": quarantined["reason"],
+                "retryInMs": round(quarantined["until"] - now_ms),
+            })
+        # half-open: cooldown elapsed — allow one probe; a single new 5xx re-quarantines
+        del SPARDA_QUARANTINE[tool]
+        if tool in SPARDA_STATS:
+            SPARDA_STATS[tool]["consecutive5xx"] = 2
+
+    t0 = time.time()
+    try:
+        path_params = spec.get("pathParams", [])
+
+        def repl(match):
+            name = match.group(1)
+            val = args.get(name)
+            if val is None:
+                raise HTTPException(status_code=400, detail=f"missing path param: {name}")
+            return urllib.parse.quote(str(val))
+
+        resolved_path = re.sub(r'\{(\w+)\}', repl, path)
+
+        query_params = []
+        for k, v in args.items():
+            if k == 'body' or k in path_params or v is None:
+                continue
+            query_params.append(f"{urllib.parse.quote(k)}={urllib.parse.quote(str(v))}")
+        
+        if query_params:
+            resolved_path += "?" + "&".join(query_params)
+
+        url = f"http://127.0.0.1:{SPARDA_PORT}{resolved_path}"
+        method = spec.get("method", "GET")
+        
+        headers = {}
+        body_bytes = None
+        
+        if method != "GET" and args.get("body") is not None:
+            headers["content-type"] = "application/json"
+            body_bytes = json.dumps(args["body"]).encode("utf-8")
+
+        loop = asyncio.get_running_loop()
+        status, content_type, data_bytes = await loop.run_in_executor(
+            executor, sync_fetch, url, method, headers, body_bytes
+        )
+        
+        text_data = data_bytes.decode("utf-8", errors="ignore")
+        try:
+            data = json.loads(text_data)
+        except Exception:
+            data = text_data
+
+        sparda_record(tool, status, round((time.time() - t0) * 1000))
+        if status >= 500:
+            sparda_event("invoke", tool, status, text_data[:200])
+        return {"upstreamStatus": status, "data": data}
+    except HTTPException as e:
+        sparda_record(tool, e.status_code, round((time.time() - t0) * 1000))
+        sparda_event("invoke", tool, e.status_code, e.detail)
+        return JSONResponse(status_code=e.status_code, content={"error": e.detail})
+    except Exception as e:
+        sparda_record(tool, 502, round((time.time() - t0) * 1000))
+        sparda_event("invoke", tool, 502, str(e))
+        return JSONResponse(status_code=502, content={"error": str(e)})