{"id":51551321,"url":"https://github.com/zyx77550/sparda","last_synced_at":"2026-07-12T14:01:17.564Z","repository":{"id":365113341,"uuid":"1270615052","full_name":"zyx77550/sparda","owner":"zyx77550","description":"Turn any Express/FastAPI app into an MCP server, in one command.","archived":false,"fork":false,"pushed_at":"2026-07-11T05:38:37.000Z","size":7607,"stargazers_count":3,"open_issues_count":10,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-11T07:12:10.853Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zyx77550.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-15T22:19:32.000Z","updated_at":"2026-07-11T05:34:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zyx77550/sparda","commit_stats":null,"previous_names":["zyx77550/sparda"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/zyx77550/sparda","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyx77550%2Fsparda","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyx77550%2Fsparda/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyx77550%2Fsparda/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyx77550%2Fsparda/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zyx77550","download_url":"https://codeload.github.com/zyx77550/sparda/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyx77550%2Fsparda/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35393398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-10T00:00:52.211Z","updated_at":"2026-07-12T14:01:17.557Z","avatar_url":"https://github.com/zyx77550.png","language":"JavaScript","funding_links":[],"categories":["Providers, Runtime \u0026 Integration Infrastructure"],"sub_categories":[],"readme":"# SPARDA\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/logo-presentation.png\" alt=\"SPARDA Banner\" width=\"800\" /\u003e\n\u003c/div\u003e\n\n\u003cbr/\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n## **AI writes. SPARDA proves.**\n\n\u003c/div\u003e\n\nAI made writing code free. It made *trusting* code the bottleneck. Your agents open\npull requests faster than any human can truly review them, and the industry's answer\nis to have another LLM skim the diff — an opinion grading an opinion.\n\nSPARDA is not an opinion. It's a **behavior compiler**: it compiles your backend\n(code + schema) into a deterministic behavior graph, and *proves* things against it —\nwhich guard a PR removed, which invariant a deploy dropped, whether a fix broke\nnothing else. Every finding is a **counterexample**, never a vibe. Zero spec to\nwrite, zero config, zero API key, nothing leaves your machine.\n\nOne engine, four moves:\n\n| | Command | What it proves |\n|---|---|---|\n| 🔍 | `sparda review` | the **behavior diff** of a PR — guards dropped, blast radius grown, new endpoints |\n| 🛡️ | `sparda apocalypse` | a deploy can't break any declared guard, invariant, transaction or aggregate |\n| 🪞 | `sparda mirror` | a live mock **derived from the code** — enforces the real state machine, can never drift |\n| ⏪ | `sparda timeless` / `heal` | replay a production bug deterministically; gate the fix with proof, not hope |\n\nAnd because trust must extend to *runtime*, the same engine turns your app into a\nsafe set of MCP tools for Claude \u0026 friends — writes gated, failures quarantined\n(see [Give your AI safe hands](#give-your-ai-safe-hands-the-mcp-layer)).\n\n## Review every PR's *behavior* — one file, zero config\n\nEvery code-review tool diffs your **text**. None diff your **behavior**. SPARDA\ncompiles the PR's base branch and your changes to the behavior graph and comments the\ndifference — as one sticky comment that updates on every push:\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/pr-review-demo.svg\" alt=\"SPARDA review bot commenting the behavior diff on a pull request: NOT PROVEN — GUARD_REMOVED on POST /pay, BLAST_RADIUS_GREW on POST /transfer, new endpoint POST /refund\" width=\"740\" /\u003e\n\u003c/div\u003e\n\n\u003cbr/\u003e\n\nDrop this one file into `.github/workflows/sparda-review.yml` — no key, no account,\nno spec to write:\n\n```yaml\nname: SPARDA behavior review\non: pull_request\npermissions:\n  contents: read\n  pull-requests: write\njobs:\n  review:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n        with: { fetch-depth: 0 }\n      - uses: zyx77550/sparda@main\n        with:\n          mode: review          # comment-only by default — never blocks a merge\n          # fail-on-severity: high   # uncomment to also gate the check\n```\n\nEvery finding is a **counterexample from the code + schema**, not a pattern-match — so\nno false-positive noise to train your team to ignore. Same engine, as a hard CI gate:\n`mode: apocalypse` (the default) fails the job on any critical/high and can upload\nSARIF to the Security tab.\n\n## Prove the deploy\n\n```bash\nnpx sparda-mcp apocalypse            # PROVEN, RISKY, or NOT PROVEN — with counterexamples\nnpx sparda-mcp apocalypse --sarif    # findings land in GitHub's Security tab\n```\n\nFive proof obligations discharged over the compiled graph — unguarded mutations,\nunvalidated constrained writes, non-atomic aggregate writes, irreversible external\ncalls, aggregate bypasses — plus a diff against your saved baseline: no entrypoint\nsilently removed, no guard dropped, no blast radius grown. Exit 1 gates the pipeline.\n\n## A mock that can never lie\n\n```bash\nnpx sparda-mcp mirror                # the graph IS the server — no framework, no source\n```\n\nThe mirror serves your compiled behavior over HTTP: guards actually deny (401),\nresponses come out typed, and the **inferred state machine is enforced** — `POST\n/orders` seeds `pending`, paying it moves it to `paid`, paying it *again* is refused\n`409`. Hand-written mocks drift; this one is derived from your code + schema, so it's\nsynchronized by construction. Front-ends develop against backends that aren't\ndeployed — or written — yet.\n\n## Give your AI safe hands (the MCP layer)\n\nYour AI can write code. It still can't *operate* your app — and giving it raw access\nusually means days of glue code and one prayer per `DELETE`. SPARDA deletes that work:\n\n```bash\nnpx sparda-mcp init   # scan your Express/FastAPI/Next.js app, inject the MCP router — 3 minutes\nnpx sparda-mcp dev    # connect Claude Desktop / Claude Code. Done.\n```\n\nNo OpenAPI spec. No account. No API key. No server to host. And the same trust rules\napply at runtime: **writes are disabled by default**, an enabled write needs an\nexplicit human confirmation (two-phase, single-use token), and every write is followed\nby a proof-after-write read-back.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eQuickstart — three steps\u003c/b\u003e\u003c/summary\u003e\n\n1. **Scan + inject** — run once, from your app's directory:\n   ```bash\n   npx sparda-mcp init\n   ```\n   SPARDA parses your routes (AST), generates a marked `/mcp` router, injects it into\n   your app (with a backup), and writes `sparda.json`. Every step is reversible.\n\n2. **Start your app, then start the bridge:**\n   ```bash\n   npx sparda-mcp dev\n   ```\n\n3. **Connect your client.** `init` prints a ready-to-paste block for\n   `claude_desktop_config.json`, pre-filled with your app's name and path:\n   ```json\n   {\n     \"mcpServers\": {\n       \"your-app\": {\n         \"command\": \"npx\",\n         \"args\": [\"sparda-mcp\", \"dev\"],\n         \"cwd\": \"/absolute/path/to/your-app\"\n       }\n     }\n   }\n   ```\n   Claude Code connects to the same bridge. That's it — your running app is now a set\n   of MCP tools your AI can call.\n\n\u003c/details\u003e\n\n## Try the Standalone Demo\n\nTo see SPARDA in action instantly without modifying your codebase:\n```bash\nnpx sparda-mcp demo\n```\nThis runs the entire lifecycle (detect → parse → generate → inject → remove) on a bundled demo app in a temporary folder, illustrating all six guarantees in 10 seconds.\n\n## Black Box Report\n\nSPARDA is designed as a local organism. To see what it remembers and how much compute it has recycled:\n```bash\nnpx sparda-mcp report          # terminal dashboard\nnpx sparda-mcp report --html   # self-contained offline dashboard at .sparda/report.html\nnpx sparda-mcp report --json   # raw JSON for integration\n```\n\nTo undo everything: **`npx sparda-mcp remove`** restores your code byte-for-byte.\n\n## The promise — every word is backed by a test in CI\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/features-presentation.png\" alt=\"SPARDA Features\" width=\"800\" /\u003e\n\u003c/div\u003e\n\n\u003cbr/\u003e\n\n1. **Proof, not opinion.** Every review/apocalypse finding is a counterexample derived from your code + schema — deterministic, byte-identical run after run, machine after machine.\n2. **Three minutes, one command.** AST scan, router generation, reversible injection — no config.\n3. **Try it for free, leave for free.** `npx sparda-mcp remove` restores your code **byte-for-byte** (tested on JS, TS, Python, even Windows CRLF files). No trace, no lock-in.\n4. **The AI cannot write until you say so.** Every POST/PUT/DELETE is disabled by default; you enable per tool, and your choice survives every re-run.\n5. **Nothing leaves your machine.** No telemetry to us, no cloud, local key auth, 4 exact-pinned dependencies.\n6. **What it learns is never lost.** Diagnoses, descriptions, settings — versioned with your git, surviving every re-init.\n\nWhat we *don't* promise: the honest limits in [docs/SECURITY.md](./docs/SECURITY.md).\n\n## How it works\n\n1. **The compiler.** `sparda ubg` (run implicitly by `review`/`apocalypse`/`mirror`) parses your codebase and SQL/Prisma schema (AST — 100% local, zero LLM) into a deterministic behavior graph: entrypoints, guards, effects, state, invariants, state machines. `sparda verify` proves the compiler's own laws (determinism, soundness, round-trip) on your input.\n2. **The proofs.** `review` and `apocalypse` discharge proof obligations over that graph; `mirror` executes it; `timeless` records/replays real requests against it.\n3. **The MCP layer.** `init` injects a tiny marked router (`/mcp`) into your app — fully reversible with `remove`. Tool calls run **inside your live app process** — warm DB pools, real auth chain, real data. Zero infrastructure: compute from your host process, intelligence from your AI client's own model (MCP sampling), storage from `sparda.json` + git.\n4. Suspicious docstrings are sanitized before they ever reach the AI (prompt-injection defense).\n\n## The living organism — what runtime trust looks like\n\nThe proof gate covers what AI *writes*. These organs cover what AI *does*, live:\n\n### Write-safety: the AI can't write until you say so\n- Writes (POST/PUT/DELETE) ship **disabled**. Enable them per tool in `sparda.json`; your choice survives every re-init.\n- An enabled write is **never executed on the first call**. SPARDA returns an `awaiting_confirmation` envelope — a single-use token plus a preview of the action — and commits only after an explicit confirm step.\n- When your client supports MCP elicitation, that confirmation prompt appears **in the AI's own UI**.\n- **Proof-after-write**: every successful write is followed by a read-back of the same resource, so the AI — and you — see the real effect, not a hopeful guess.\n\n### Your app defends itself — zero LLM on the hot path\n- **Quarantine.** A tool that returns 3 consecutive 5xx is quarantined: further calls get a `503` with a reason and a retry delay instead of hammering your broken route. After a cooldown it half-opens for a single probe.\n- **Latency \u0026 anomaly flags.** The router learns each route's baseline and flags deviations locally, in a few lines of math.\n- **Adaptive diagnosis, only on surprise.** A genuinely new failure wakes your AI client's own model to diagnose it once; the diagnosis is cached as an \"antibody\" in `sparda.json`, so the same failure later costs zero tokens. Cloning your code doesn't clone its immune memory.\n\n### A free intelligence layer, zero API key\nOn first connection your AI client's own model (via MCP sampling) rewrites raw routes\ninto business-language tool descriptions and proposes multi-step workflows — cached in\n`sparda.json` and exposed as MCP prompts. Nothing to configure, nothing to pay.\n\n### It gets cheaper the more you use it\n- **Response recycling.** When a read keeps returning the same answer, SPARDA serves the next identical call straight from memory — without touching your host app. Reads only; writes always hit the host.\n- **A recycling gauge.** `GET /mcp/stats` counts how many calls were answered from SPARDA's own knowledge vs. how many paid the host route. It reads 0% on day one and fills with usage — a measure, never a promise.\n\n### Tools nobody wrote — Labs, opt-in, default OFF\nTurn it on with `\"labs\": { \"recordSequences\": true }` in `sparda.json`. SPARDA then\nnotices when one tool's output feeds the next tool's input and records the *circuit* —\nstructure only (tool names, argument names, counts), never your data. A read-only\ncircuit seen enough times **crystallizes into a composite tool**, announced\nmid-session: one call runs the whole chain, auto-feeding each step from the previous\nstep's real response. Write routes are never absorbed — their per-call confirmation\nalways stands.\n\n### Living context \u0026 telemetry\nOne call to **`sparda_get_context`** hands the AI the whole living picture: enabled\ntools, suggested workflows, runtime telemetry, quarantine state, and immune memory —\nso every session resumes where the last one stopped. `GET /mcp/stats` and\n`GET /mcp/events` expose the same live picture over HTTP.\n\n## Built for AI clients: the bundled Skill\nSPARDA ships with an Agent Skill ([`SKILL.md`](./SKILL.md)) that teaches any compatible\nAI client how to drive a SPARDA server to its **full potential** — call\n`sparda_get_context` first, exploit response recycling, honor quarantine, prefer\ncrystallized circuits over re-walking a chain, and follow the two-phase write-confirm\nprotocol. The live, per-project tool list always comes from `sparda_get_context` at\nruntime, so the guidance never goes stale.\n\n## Supported frameworks\n\n- **Next.js App Router (13/14/15)** — file-based injection. Since Next.js uses file-system routing, SPARDA simply creates a catch-all route handler under `app/mcp/[...sparda]/route.js`. **Nothing in your existing codebase's code is touched**; running `remove` simply deletes the generated file.\n- **Express 4/5** (JS/TS, ESM/CJS) — AST-based router injection.\n- **FastAPI** (Python \u003e= 3.9) — AST-based router injection.\n- **Any backend with an OpenAPI spec** — `--openapi api.json` lowers the spec into the same behavior graph, so `review`, `apocalypse`, `mirror` and `openapi` work on Go, Rails, Java, .NET… without a parser.\n\n## Security posture (honest)\n- 4 runtime dependencies, exact-pinned.\n- Local key on every router call; self-reference loop protection; 30s timeouts; 8 KB output truncation.\n- AST-positioned injection with backup and post-injection re-parse; `npx sparda-mcp remove` leaves a clean git diff.\n- Persistence is **value-free**: SPARDA records structure (tool names, field names, fingerprints), never your payloads.\n\nFull threat model and known gaps: [docs/SECURITY.md](./docs/SECURITY.md).\n\n## Documentation\n- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) — how `init`, the injected router, and the bridge fit together, plus the `sparda.json` schema.\n- [docs/SECURITY.md](./docs/SECURITY.md) — threat model, defenses, and honest known gaps.\n- [docs/TESTING.md](./docs/TESTING.md) — how the promises above are kept honest in CI.\n- [docs/ERRORS.md](./docs/ERRORS.md) — the error knowledge base.\n\n## Beyond the open core\nSPARDA is free, including in production (see License). Team-scale capabilities —\nfine-grained per-person access policies and a signed, tamper-evident audit log — are\nplanned for a future paid tier. The open core stands on its own; nothing here is\ncrippled to upsell you.\n\n## License\n[Business Source License 1.1](./LICENSE) — free to use, including in production.\nYou may not resell SPARDA or offer it as a competing commercial service.\nEach version converts to Apache 2.0 four years after its release.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/github-star.png\" alt=\"Leave a Star\" width=\"600\" /\u003e\n\u003c/div\u003e\n\n\u003cbr/\u003e\n\nBy [Residual Labs](https://residual-labs.fr)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzyx77550%2Fsparda","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzyx77550%2Fsparda","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzyx77550%2Fsparda/lists"}