sparda-mcp 0.1.0

package/README.md

@@ -0,0 +1,26 @@
+# SPARDA
+
+**Turn any codebase into an MCP server with one command.**
+
+```bash
+npx sparda-mcp init   # scan your Express app, generate + inject the MCP router
+npx sparda-mcp dev    # MCP stdio bridge — connect Claude Desktop / Claude Code
+```
+
+Your software, AI-controlled, in under 3 minutes. No config. No OpenAPI spec. No infra.
+
+## How it works
+1. `npx sparda-mcp init` parses your codebase (AST), extracts every route, and injects a tiny marked router (`/mcp`) into your app — fully reversible with `npx sparda-mcp remove`.
+2. Tool calls run **inside your live app process** — warm DB pools, real auth chain, real data.
+3. Write tools (POST/PUT/DELETE) are **disabled by default** (write-safety). You opt in per tool in `sparda.json`.
+4. Suspicious docstrings are purged before they ever reach the AI (prompt-injection defense).
+
+## v0 supports
+Express 4/5 (JS/TS, ESM/CJS). FastAPI next. Vote for your framework in the pinned issue.
+
+## Security posture (v0, honest)
+- 4 runtime dependencies, exact-pinned.
+- Local key on every router call; loop protection; 30s timeouts; 8KB output truncation.
+- AST-positioned injection with backup + post-injection re-parse; `npx sparda-mcp remove` leaves a clean git diff.
+
+MIT — by [Residual Labs](https://residual-labs.fr)

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "sparda-mcp",
+  "version": "0.1.0",
+  "description": "Turn any codebase into an MCP server with one command. Express & FastAPI → Claude-ready in 3 minutes.",
+  "type": "module",
+  "bin": {
+    "sparda": "./src/index.js"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "files": [
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "ai",
+    "express",
+    "fastapi",
+    "codegen"
+  ],
+  "author": "Residual Labs (residual-labs.fr)",
+  "license": "MIT",
+  "dependencies": {
+    "@babel/parser": "7.26.5",
+    "@babel/traverse": "7.26.5",
+    "@clack/prompts": "0.9.1",
+    "@modelcontextprotocol/sdk": "1.12.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.6"
+  }
+}

package/src/commands/dev.js

@@ -0,0 +1,5 @@
+// commands/dev.js
+import { startStdioBridge } from '../server/stdio.js';
+export async function runDev(opts) {
+  await startStdioBridge({ cwd: opts.cwd, portOverride: opts.port });
+}

package/src/commands/doctor.js

@@ -0,0 +1,34 @@
+// commands/doctor.js
+import fs from 'node:fs';
+import path from 'node:path';
+import { detectStack } from '../detect.js';
+
+export async function runDoctor(opts) {
+  console.log('SPARDA doctor');
+  const node = process.versions.node;
+  console.log(`  ${Number(node.split('.')[0]) >= 18 ? '✓' : '✗'} Node ${node} (≥18 required)`);
+  let stack = null;
+  try {
+    stack = detectStack(opts.cwd);
+    console.log(`  ✓ Framework: ${stack.framework} — entry: ${stack.entryFile} — port: ${stack.port}`);
+  } catch (e) {
+    console.log(`  ✗ ${e.message}`);
+  }
+  const manifest = path.join(opts.cwd, 'sparda.json');
+  if (fs.existsSync(manifest)) {
+    try {
+      const m = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+      console.log(`  ✓ sparda.json valid (${Object.keys(m.tools ?? {}).length} tools)`);
+      if (stack) {
+        try {
+          const r = await fetch(`http://127.0.0.1:${m.port}/mcp/tools`, { headers: { 'x-sparda-key': m.localKey }, signal: AbortSignal.timeout(1500) });
+          console.log(r.ok ? `  ✓ Host app reachable on :${m.port}, router responding` : `  ✗ Host app on :${m.port} answered ${r.status}`);
+        } catch {
+          console.log(`  ✗ Host app on :${m.port} — NOT reachable\n      → start it with: npm run dev`);
+        }
+      }
+    } catch { console.log('  ✗ sparda.json invalid JSON'); }
+  } else {
+    console.log('  · sparda.json not found (run `npx sparda-mcp init`)');
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,79 @@
+// commands/init.js
+import path from 'node:path';
+import fs from 'node:fs';
+import * as p from '@clack/prompts';
+import { detectStack } from '../detect.js';
+import { parseExpressProject } from '../parser/express.js';
+import { sanitizeDescription } from '../security/sanitize.js';
+import { generateExpress } from '../generator/express.js';
+
+export async function runInit(opts) {
+  const t0 = Date.now();
+  p.intro('SPARDA v0.1.0');
+
+  const s = p.spinner();
+  s.start('Scanning project...');
+  const stack = detectStack(opts.cwd);
+  const { routes, skipped } = parseExpressProject(opts.cwd, stack.entryFile);
+  s.stop(`Stack detected: Express (${stack.moduleType.toUpperCase()}) — entry: ${stack.entryFile}, port: ${stack.port}`);
+
+  if (routes.length === 0) {
+    throw Object.assign(new Error('0 routes extracted.'), { code: 'USER', hint: 'SPARDA found Express but no literal-path routes. Dynamic routing is not supported in v0.' });
+  }
+
+  let flaggedCount = 0;
+  for (const r of routes) {
+    const { text, flagged } = sanitizeDescription(r.description, `${r.method.toUpperCase()} ${r.path}`);
+    r.description = text;
+    if (flagged) flaggedCount++;
+  }
+
+  const high = routes.filter((r) => r.confidence === 'high').length;
+  p.log.info(`${routes.length} routes found — ${high} high confidence, ${routes.length - high} partial`);
+
+  const preview = routes.slice(0, 8).map((r) =>
+    `${r.mutating ? '✗' : '✓'} ${r.method.toUpperCase().padEnd(6)} ${r.path}${r.mutating ? '   (disabled: write-safety)' : ''}`
+  ).join('\n');
+  p.note(preview + (routes.length > 8 ? `\n... (+${routes.length - 8} more)` : ''), 'TOOLS TO GENERATE');
+
+  if (flaggedCount) p.log.warn(`${flaggedCount} suspicious docstring(s) purged (prompt-injection defense)`);
+  if (skipped.length) p.log.warn(`${skipped.length} route(s) skipped — details in .sparda/scan-report.json`);
+
+  let inject = true;
+  if (!opts.yes) {
+    const answer = await p.select({
+      message: `Inject the MCP router into ${stack.entryFile}?`,
+      options: [
+        { value: true, label: 'Yes, inject (adds a marked block, reversible via `sparda remove`)' },
+        { value: false, label: 'No, generate files only (I will add 2 lines manually)' },
+      ],
+    });
+    if (p.isCancel(answer)) { p.cancel('Aborted.'); process.exit(1); }
+    inject = answer;
+  }
+
+  const result = generateExpress({ cwd: opts.cwd, entryFile: stack.entryFile, moduleType: stack.moduleType, port: stack.port, routes });
+
+  fs.mkdirSync(path.join(opts.cwd, '.sparda'), { recursive: true });
+  fs.writeFileSync(path.join(opts.cwd, '.sparda', 'scan-report.json'), JSON.stringify({ routes, skipped }, null, 2));
+
+  p.log.success(`Generated ${result.routerFile}`);
+  if (inject && result.injection.injected) p.log.success(`Injected into ${stack.entryFile} (backup: .sparda/backup/)`);
+  else if (result.injection.manual) {
+    p.note(result.injection.manual.join('\n'), `Add these 2 lines to ${stack.entryFile} (after app = express())`);
+  }
+  p.log.success('Wrote sparda.json');
+
+  const cfg = JSON.stringify({ [path.basename(opts.cwd)]: { command: 'npx', args: ['sparda-mcp', 'dev'], cwd: opts.cwd } }, null, 2);
+  p.outro(`Done in ${((Date.now() - t0) / 1000).toFixed(1)}s.
+
+   Next steps:
+   1. Start your app:        npm run dev
+   2. Start the MCP bridge:  npx sparda-mcp dev
+   3. Add to Claude Desktop config (claude_desktop_config.json):
+
+${cfg.split('\n').map((l) => '   ' + l).join('\n')}
+
+   Write tools (POST/PUT/DELETE) are disabled by default.
+   Enable them in sparda.json, then re-run \`npx sparda-mcp init --yes\`.`);
+}

package/src/commands/remove.js

@@ -0,0 +1,32 @@
+// commands/remove.js
+import fs from 'node:fs';
+import path from 'node:path';
+import * as p from '@clack/prompts';
+import { removeInjection } from '../generator/express.js';
+
+export async function runRemove(opts) {
+  const manifestPath = path.join(opts.cwd, 'sparda.json');
+  if (!fs.existsSync(manifestPath)) {
+    throw Object.assign(new Error('sparda.json not found — nothing to remove.'), { code: 'USER' });
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+
+  if (!opts.yes) {
+    const ok = await p.confirm({ message: 'Remove SPARDA from this project? (deletes generated files + injected block)' });
+    if (p.isCancel(ok) || !ok) { p.cancel('Aborted.'); process.exit(1); }
+  }
+
+  const results = removeInjection(opts.cwd, manifest);
+  for (const r of results) {
+    if (r.ok) console.log(`✓ Removed injection from ${r.file} (file still parses)`);
+    else console.log(`✗ Could not safely remove from ${r.file} — restore from .sparda/backup/`);
+  }
+  for (const f of manifest.generatedFiles ?? []) {
+    const abs = path.resolve(opts.cwd, f);
+    if (fs.existsSync(abs)) { fs.rmSync(abs); console.log(`✓ Deleted ${f}`); }
+  }
+  fs.rmSync(manifestPath);
+  fs.rmSync(path.join(opts.cwd, '.sparda'), { recursive: true, force: true });
+  console.log('✓ Deleted sparda.json and .sparda/');
+  console.log('\nSPARDA removed. `git diff` should be clean (minus a .gitignore line).');
+}

package/src/detect.js

@@ -0,0 +1,84 @@
+// detect.js — framework, entry file, port detection (spec: blueprint 03-PARSING §A)
+import fs from 'node:fs';
+import path from 'node:path';
+
+const err = (message, hint) => Object.assign(new Error(message), { code: 'USER', hint });
+
+export function detectStack(cwd) {
+  const pkgPath = path.join(cwd, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps.express) {
+      const entryFile = findExpressEntry(cwd, pkg);
+      const moduleType = detectModuleType(cwd, pkg, entryFile);
+      const port = detectExpressPort(cwd, entryFile);
+      return { framework: 'express', entryFile, moduleType, port, expressVersion: deps.express };
+    }
+    const known = ['@nestjs/core', 'next', 'fastify', 'koa'].find((d) => deps[d]);
+    if (known) throw err(`${known} detected — not supported yet. Express & FastAPI only in v0.`, '+1 the framework vote: github.com/zyx77550/sparda/issues/1');
+  }
+  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');
+    }
+  }
+  throw err('No supported framework found (Express, FastAPI).', 'Run sparda inside your project root, next to package.json.');
+}
+
+function findExpressEntry(cwd, pkg) {
+  const candidates = [];
+  if (pkg.main) candidates.push(pkg.main);
+  for (const script of [pkg.scripts?.dev, pkg.scripts?.start]) {
+    if (!script) continue;
+    const m = script.match(/(\S+\.(?:m?[tj]s|cjs))\s*$/);
+    if (m) candidates.push(m[1]);
+  }
+  candidates.push(
+    'src/app.ts', 'src/server.ts', 'src/index.ts', 'app.ts', 'server.ts', 'index.ts',
+    'src/app.js', 'src/server.js', 'src/index.js', 'app.js', 'server.js', 'index.js',
+    'src/app.mjs', 'app.mjs', 'index.mjs',
+  );
+  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 (/express\s*\(/.test(src)) return path.relative(cwd, abs).split(path.sep).join('/');
+    }
+  }
+  throw err('Could not locate your Express entry file (the one calling express()).', 'Re-run from the project root, or open an issue with your layout.');
+}
+
+function detectModuleType(cwd, pkg, entryFile) {
+  if (entryFile.endsWith('.mjs')) return 'esm';
+  if (entryFile.endsWith('.cjs')) return 'cjs';
+  if (pkg.type === 'module' || entryFile.endsWith('.ts')) {
+    const src = fs.readFileSync(path.join(cwd, entryFile), 'utf8');
+    if (/^\s*(const|let|var)\s+\w+\s*=\s*require\(/m.test(src) && !/^\s*import\s/m.test(src)) return 'cjs';
+    return 'esm';
+  }
+  const src = fs.readFileSync(path.join(cwd, entryFile), 'utf8');
+  return /^\s*import\s.+from\s/m.test(src) ? 'esm' : 'cjs';
+}
+
+function detectExpressPort(cwd, entryFile) {
+  const src = fs.readFileSync(path.join(cwd, entryFile), 'utf8');
+  let m = src.match(/\.listen\(\s*(\d{2,5})/);
+  if (m) return Number(m[1]);
+  m = src.match(/\.listen\(\s*(?:process\.env\.(\w+))/);
+  if (m) {
+    const envPath = path.join(cwd, '.env');
+    if (fs.existsSync(envPath)) {
+      const line = fs.readFileSync(envPath, 'utf8').split(/\r?\n/).find((l) => l.startsWith(`${m[1]}=`));
+      if (line) {
+        const v = Number(line.split('=')[1].trim());
+        if (v) return v;
+      }
+    }
+  }
+  // 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]);
+  return 3000; // default + warning emitted by caller
+}

package/src/generator/express.js

@@ -0,0 +1,185 @@
+// generator/express.js — router generation + marked injection (spec: blueprint 04-GENERATION §A)
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { parse } from '@babel/parser';
+import { toolNameFor } from '../parser/express.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 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 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';
+  const routerFileName = `sparda-router${ext}`;
+  const routerAbs = path.join(entryDir, routerFileName);
+
+  // --- render router from template
+  let tpl = fs.readFileSync(path.join(__dirname, '..', '..', 'templates', 'express-router.txt'), 'utf8');
+  const isESM = moduleType === 'esm';
+  tpl = tpl
+    .replace('__IMPORT_LINE__', isESM ? "import express from 'express';" : "const express = require('express');")
+    .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));
+  atomicWrite(routerAbs, tpl);
+
+  // --- inject into entry file (line-based via AST positions)
+  const injection = injectIntoEntry({ entryAbs, moduleType, routerFileName, cwd });
+
+  // --- manifest
+  const manifest = {
+    version: 1,
+    framework: 'express',
+    entryFile,
+    moduleType,
+    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 }])),
+  };
+  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 };
+}
+
+function injectIntoEntry({ entryAbs, moduleType, routerFileName, cwd }) {
+  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);
+
+  const importSpec = `./${routerFileName.replace(/\.(ts|js|mjs|cjs)$/, moduleType === 'esm' && routerFileName.endsWith('.js') ? '.js' : '')}`.replace(/\.$/, '');
+  const importLine = moduleType === 'esm'
+    ? `import { spardaRouter } from '${importSpec}';`
+    : `const { spardaRouter } = require('${importSpec}');`;
+
+  // strip previous injection blocks (idempotence)
+  let body = src;
+  const blockRx = new RegExp(`\\n?${escapeRx(MARK_START)}[\\s\\S]*?${escapeRx(MARK_END)}\\n?`, 'g');
+  body = body.replace(blockRx, '\n');
+
+  let ast;
+  try {
+    ast = parse(body, { sourceType: 'unambiguous', plugins: ['typescript', 'jsx'], attachComment: false });
+  } catch {
+    return manualFallback(importLine);
+  }
+
+  const lines = body.split('\n');
+  let lastImportLine = 0;
+  let appAssignLine = null;
+  let listenLine = null;
+  let appName = 'app';
+
+  for (const node of ast.program.body) {
+    if (node.type === 'ImportDeclaration') lastImportLine = Math.max(lastImportLine, node.loc.end.line);
+    if (node.type === 'VariableDeclaration') {
+      for (const d of node.declarations) {
+        if (d.init?.type === 'CallExpression' && d.init.callee?.name === 'express') {
+          appAssignLine = node.loc.end.line;
+          appName = d.id.name;
+        }
+        if (d.init?.type === 'CallExpression' && d.init.callee?.name === 'require') {
+          lastImportLine = Math.max(lastImportLine, node.loc.end.line);
+        }
+      }
+    }
+    if (node.type === 'ExpressionStatement' &&
+        node.expression.type === 'CallExpression' &&
+        node.expression.callee?.property?.name === 'listen') {
+      listenLine = node.loc.start.line;
+    }
+  }
+
+  const useBlock = [MARK_START, importLine, `${appName}.use('/mcp', spardaRouter);`, MARK_END];
+
+  let insertAt; // 0-based index AFTER which we DON'T insert; we splice before index
+  if (appAssignLine !== null) insertAt = appAssignLine;        // after app = express()
+  else if (listenLine !== null) insertAt = listenLine - 1;      // before app.listen
+  else return manualFallback(importLine);
+
+  lines.splice(insertAt, 0, ...useBlock);
+  const out = lines.join('\n');
+
+  // post-injection re-parse safety check (blueprint pitfall #6)
+  try {
+    parse(out, { sourceType: 'unambiguous', plugins: ['typescript', 'jsx'] });
+  } catch {
+    return manualFallback(importLine);
+  }
+  atomicWrite(entryAbs, out);
+  return { injected: true, manual: null };
+
+  function manualFallback(imp) {
+    return {
+      injected: false,
+      manual: [imp, `app.use('/mcp', spardaRouter);`],
+    };
+  }
+}
+
+export function removeInjection(cwd, manifest) {
+  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(`\\n?${escapeRx(MARK_START)}[\\s\\S]*?${escapeRx(MARK_END)}`, 'g');
+    const out = src.replace(blockRx, '');
+    try {
+      parse(out, { sourceType: 'unambiguous', plugins: ['typescript', 'jsx'] });
+      atomicWrite(abs, out);
+      results.push({ file: relFile, ok: true });
+    } catch {
+      results.push({ file: relFile, ok: false });
+    }
+  }
+  return results;
+}
+
+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`);
+  }
+}
+
+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/index.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// SPARDA — Turn any codebase into an MCP server. Residual Labs.
+const [, , cmd, ...rest] = process.argv;
+
+const flags = new Set(rest.filter((a) => a.startsWith('--')));
+const getOpt = (name, dflt) => {
+  const i = rest.indexOf(`--${name}`);
+  return i !== -1 && rest[i + 1] ? rest[i + 1] : dflt;
+};
+
+const opts = {
+  yes: flags.has('--yes') || flags.has('-y'),
+  verbose: flags.has('--verbose'),
+  port: getOpt('port', null),
+  cwd: process.cwd(),
+};
+
+try {
+  switch (cmd) {
+    case 'init': {
+      const { runInit } = await import('./commands/init.js');
+      await runInit(opts);
+      break;
+    }
+    case 'dev': {
+      const { runDev } = await import('./commands/dev.js');
+      await runDev(opts);
+      break;
+    }
+    case 'remove': {
+      const { runRemove } = await import('./commands/remove.js');
+      await runRemove(opts);
+      break;
+    }
+    case 'doctor': {
+      const { runDoctor } = await import('./commands/doctor.js');
+      await runDoctor(opts);
+      break;
+    }
+    default:
+      console.log(`SPARDA v0.1.0 — 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 remove    Remove SPARDA from this project (clean git diff)
+  npx sparda-mcp doctor    Diagnose your setup
+
+Flags: --yes (skip prompts)  --port <n>  --verbose`);
+      process.exit(cmd ? 1 : 0);
+  }
+} catch (err) {
+  console.error(`\n✗ ${err?.message ?? err}`);
+  if (err?.hint) console.error(`  → ${err.hint}`);
+  if (opts.verbose && err?.stack) console.error(err.stack);
+  else console.error('  (run with --verbose for details — or open an issue: github.com/zyx77550/sparda/issues)');
+  process.exit(err?.code === 'USER' ? 1 : 2);
+}

package/src/parser/express.js

@@ -0,0 +1,182 @@
+// parser/express.js — AST route extraction (spec: blueprint 03-PARSING §B)
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from '@babel/parser';
+import traverseModule from '@babel/traverse';
+const traverse = traverseModule.default ?? traverseModule;
+
+const HTTP = new Set(['get', 'post', 'put', 'patch', 'delete']);
+const EXCLUDE = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.sparda']);
+
+export function parseExpressProject(cwd, entryFile) {
+  const routes = [];
+  const skipped = [];
+  const visited = new Set();
+  const entryAbs = path.resolve(cwd, entryFile);
+
+  // routerName -> { file, prefix } discovered via app.use(prefix, ident)
+  const mounts = [];
+
+  parseFile(entryAbs, '', 0);
+  // second pass: parse mounted router files with their prefixes
+  for (const m of mounts) {
+    if (m.file && fs.existsSync(m.file)) parseFile(m.file, m.prefix, 1);
+  }
+
+  return { routes: dedupe(routes), skipped };
+
+  function parseFile(absFile, prefix, depth) {
+    if (depth > 2 || visited.has(absFile + '::' + prefix)) return;
+    visited.add(absFile + '::' + prefix);
+    let src;
+    try { src = fs.readFileSync(absFile, 'utf8'); } catch { return; }
+    let ast;
+    try {
+      ast = parse(src, {
+        sourceType: 'unambiguous',
+        plugins: ['typescript', 'jsx', ['decorators', { decoratorsBeforeExport: true }]],
+        attachComment: true,
+      });
+    } catch (e) {
+      skipped.push({ reason: `parse error in ${rel(absFile)}: ${e.message.slice(0, 80)}`, file: rel(absFile) });
+      return;
+    }
+
+    const appVars = new Set();    // vars = express()
+    const routerVars = new Set(); // vars = express.Router() / Router()
+    const importMap = new Map();  // localName -> absolute file path (relative imports only)
+    const exprStarts = new Set(); // line numbers where express() assigned (for injector)
+
+    traverse(ast, {
+      VariableDeclarator(p) {
+        const init = p.node.init;
+        const name = p.node.id?.name;
+        if (!name || !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);
+          }
+        }
+      },
+      ImportDeclaration(p) {
+        const resolved = resolveRel(absFile, p.node.source.value);
+        if (!resolved) return;
+        for (const spec of p.node.specifiers) importMap.set(spec.local.name, resolved);
+      },
+      CallExpression(p) {
+        const callee = p.node.callee;
+        if (callee.type !== 'MemberExpression' || callee.property.type !== 'Identifier') return;
+        const objName = callee.object.type === 'Identifier' ? callee.object.name : null;
+        const method = callee.property.name;
+        const args = p.node.arguments;
+
+        // app.use(prefix, routerIdent) -> mount
+        if (method === 'use' && objName && appVars.has(objName) && args.length >= 2) {
+          const [a0, a1] = args;
+          if (a0.type === 'StringLiteral' && a1.type === 'Identifier') {
+            mounts.push({ prefix: joinPath(prefix, a0.value), file: importMap.get(a1.name) ?? null, ident: a1.name });
+            if (!importMap.get(a1.name)) skipped.push({ reason: `router "${a1.name}" mounted at ${a0.value} — source file not resolved`, file: rel(absFile), line: p.node.loc.start.line });
+          }
+          return;
+        }
+
+        if (!HTTP.has(method)) return;
+        const isApp = objName && appVars.has(objName);
+        const isRouter = objName && routerVars.has(objName);
+        if (!isApp && !isRouter) return;
+
+        const pathArg = args[0];
+        if (!pathArg || pathArg.type !== 'StringLiteral') {
+          skipped.push({ reason: `dynamic path on ${method.toUpperCase()} (non-literal first arg)`, file: rel(absFile), line: p.node.loc?.start.line });
+          return;
+        }
+
+        const fullPath = joinPath(prefix, pathArg.value);
+        const handler = args[args.length - 1];
+        const handlerName = handler?.type === 'Identifier' ? handler.name
+          : handler?.id?.name ?? `anonymous_${routes.length + 1}`;
+
+        const leading = (p.parentPath.node.leadingComments ?? p.node.leadingComments ?? [])
+          .map((c) => c.value.replace(/^\*+/gm, '').replace(/^\s*\*\s?/gm, '').trim())
+          .filter(Boolean).join(' ');
+
+        const pathParams = [...fullPath.matchAll(/:(\w+)/g)].map((mm) => ({
+          name: mm[1], in: 'path', type: 'string', required: true, description: 'path parameter',
+        }));
+
+        const mutating = method !== 'get';
+        const params = [...pathParams];
+        let confidence = 'high';
+        if (mutating) {
+          params.push({ name: 'body', in: 'body', type: 'object', required: false, description: 'JSON body — schema not statically detected' });
+          confidence = 'low';
+        }
+
+        routes.push({
+          method, path: fullPath, handlerName,
+          sourceFile: rel(absFile), sourceLine: p.node.loc?.start.line ?? 0,
+          params, description: leading.slice(0, 400), mutating, confidence,
+        });
+      },
+    });
+
+    // depth-1 import follow for files that themselves declare app routes (rare but covered)
+    if (depth === 0) {
+      for (const [, file] of importMap) {
+        if (!visited.has(file + '::' + prefix) && fs.existsSync(file)) {
+          // only follow if the file references Router or app routes — cheap pre-check
+          const s = fs.readFileSync(file, 'utf8');
+          if (/\bRouter\s*\(/.test(s)) continue; // handled by mounts pass with proper prefix
+        }
+      }
+    }
+  }
+
+  function rel(abs) { return path.relative(cwd, abs).split(path.sep).join('/'); }
+
+  function resolveRel(fromFile, spec) {
+    if (!spec.startsWith('.')) return null;
+    const base = path.resolve(path.dirname(fromFile), spec);
+    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()) {
+        if ([...EXCLUDE].some((x) => cand.includes(`${path.sep}${x}${path.sep}`))) return null;
+        return cand;
+      }
+    }
+    return null;
+  }
+}
+
+function joinPath(prefix, p) {
+  const joined = `${prefix ?? ''}${p === '/' && prefix ? '' : p}`.replace(/\/{2,}/g, '/');
+  return joined.startsWith('/') ? joined : `/${joined}`;
+}
+
+function dedupe(routes) {
+  const seen = new Set();
+  return routes.filter((r) => {
+    const k = `${r.method} ${r.path}`;
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+}
+
+export function toolNameFor(route, taken) {
+  let name = `${route.method}_${route.path}`
+    .toLowerCase()
+    .replace(/:(\w+)/g, 'by_$1')
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 60) || 'tool';
+  let final = name; let i = 2;
+  while (taken.has(final)) final = `${name}_${i++}`;
+  taken.add(final);
+  return final;
+}

package/src/security/sanitize.js

@@ -0,0 +1,16 @@
+// security/sanitize.js — docstring poisoning defense (spec: blueprint 06-SECURITY §2)
+const DANGEROUS = [
+  /(^|\s)(ignore|forget|disregard|override)\s+(all\s+)?(previous|prior|above|earlier)/i,
+  /(you\s+are\s+(now|a)\b|act\s+as\b|pretend\s+(you\s+are|to\s+be)|from\s+now\s+on)/i,
+  /(system\s+prompt|env(ironment)?\s+var|api[\s_-]?key|credential|secret|exfiltrat|\.env\b)/i,
+  /(<\/?(system|assistant|human|tool|instructions?)\b|```)/i,
+  /(new\s+(role|instructions?)|your\s+(real|true)\s+(task|goal))/i,
+];
+
+export function sanitizeDescription(raw, fallback) {
+  let text = String(raw ?? '').replace(/[\r\n]+/g, ' ').replace(/\s{2,}/g, ' ').trim().slice(0, 300);
+  const flagged = DANGEROUS.some((rx) => rx.test(text));
+  if (flagged) text = '';
+  text = text.replace(/[<>{}]/g, '');
+  return { text: text || fallback, flagged };
+}

package/src/server/stdio.js

@@ -0,0 +1,115 @@
+// server/stdio.js — MCP stdio bridge (spec: blueprint 05-MCP-SERVER)
+// CRITICAL: stdout is the MCP protocol. All human logs -> stderr. (pitfall #1)
+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';
+
+export async function startStdioBridge({ cwd, portOverride }) {
+  // pitfall #1: neutralize any stray console.log from deps
+  console.log = (...a) => console.error(...a);
+
+  const manifestPath = path.join(cwd, 'sparda.json');
+  if (!fs.existsSync(manifestPath)) {
+    throw Object.assign(new Error('sparda.json not found.'), { code: 'USER', hint: 'Run `npx sparda-mcp init` first.' });
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const port = Number(portOverride ?? manifest.port);
+  const key = manifest.localKey;
+  const base = await waitForHost(port, key);
+
+  // 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 server = new Server(
+    { name: `sparda-${path.basename(cwd)}`, version: '0.1.0' },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      ...enabled.map(([name, t]) => ({
+        name,
+        description: `${t.confidence === 'low' ? '[partial schema] ' : ''}${t.description || `${t.method} ${t.path}`}`,
+        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',
+        inputSchema: { type: 'object', properties: {} },
+      },
+      {
+        name: 'sparda_list_disabled_tools',
+        description: 'Lists write tools (POST/PUT/DELETE) disabled by SPARDA write-safety, and how to enable them.',
+        inputSchema: { type: 'object', properties: {} },
+      },
+    ],
+  }));
+
+  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',
+      }, 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.`
+        : '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 transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`[sparda] MCP bridge running. ${enabled.length} tools enabled, ${disabled.length} disabled (write-safety). Host: ${base}`);
+}
+
+function schemaFor(t) {
+  const properties = {}; const required = [];
+  for (const p of t.params ?? []) {
+    properties[p.name] = { type: p.type === 'unknown' ? 'string' : p.type, description: p.description ?? p.in };
+    if (p.required) required.push(p.name);
+  }
+  return { type: 'object', properties, ...(required.length ? { required } : {}) };
+}
+
+function text(t) { return { content: [{ type: 'text', text: t }] }; }
+
+async function waitForHost(port, key) {
+  const hosts = ['127.0.0.1', 'localhost'];
+  for (let attempt = 0; attempt < 40; attempt++) {
+    for (const h of hosts) {
+      try {
+        const r = await fetch(`http://${h}:${port}/mcp/tools`, { headers: { 'x-sparda-key': key }, signal: AbortSignal.timeout(1500) });
+        if (r.ok) return `http://${h}:${port}`;
+        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)`);
+    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

@@ -0,0 +1,58 @@
+// ============================================================
+// SPARDA ROUTER — Auto-generated. DO NOT EDIT.
+// Regenerate: npx sparda-mcp init   •   Remove: npx sparda-mcp remove
+// ============================================================
+__IMPORT_LINE__
+
+const SPARDA_TOOLS = __TOOLS_JSON__;
+
+const SPARDA_LOCAL_KEY = "__LOCAL_KEY__";
+const SPARDA_PORT = __PORT__;
+
+__ROUTER_DECL__
+
+spardaRouter.use((req, res, next) => {
+  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.post('/invoke', __JSON_MW__, async (req, res) => {
+  const { tool, args = {} } = req.body ?? {};
+  const spec = SPARDA_TOOLS[tool];
+  if (!spec) return res.status(404).json({ error: `unknown tool: ${tool}` });
+  if (!spec.enabled) {
+    return res.status(403).json({ error: `tool disabled (write-safety): ${tool}`, hint: 'Enable it in sparda.json, then re-run: npx sparda-mcp init' });
+  }
+  if (spec.path.startsWith('/mcp')) {
+    return res.status(400).json({ error: 'self-referential tool blocked (loop protection)' });
+  }
+  try {
+    let url = spec.path.replace(/:(\w+)/g, (_, name) => {
+      const v = args[name];
+      if (v === undefined) throw Object.assign(new Error(`missing path param: ${name}`), { status: 400 });
+      return encodeURIComponent(String(v));
+    });
+    const query = [];
+    for (const [k, v] of Object.entries(args)) {
+      if (k === 'body' || spec.pathParams.includes(k) || v === undefined) continue;
+      query.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+    }
+    if (query.length) url += `?${query.join('&')}`;
+
+    const init = { method: spec.method, headers: {} };
+    if (spec.method !== 'GET' && args.body !== undefined) {
+      init.headers['content-type'] = 'application/json';
+      init.body = JSON.stringify(args.body);
+    }
+    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; }
+    return res.status(200).json({ upstreamStatus: upstream.status, data });
+  } catch (err) {
+    return res.status(err.status ?? 502).json({ error: err.message });
+  }
+});