# 🌌 devuniverse-mcp

**An autonomous virtual software agency, packaged as an MCP server.**

Point any MCP client (Claude Code, Claude Desktop, Cursor, …) at `devuniverse-mcp`,
describe a product, and a bench of **27 codified senior personas** debates the
stack for your brief (Supabase vs Firebase, Riverpod vs Bloc, offline layer, 3D
renderer, service layer…), records votes and dissents as ADRs, and scaffolds a
project wired to those rulings — then cross-examines the generated files before
writing them, with the full meeting transcript on disk.

```
init_dev_universe(
  project_type: "flutter_spatial_app",
  description:  "A meditation app with a 3D deep-scroll journey through calming
                 rooms, user accounts, offline mode, and Stripe subscriptions.
                 GDPR matters.",
  dry_run: true            # show the rulings + file list first; nothing written
)
→ Plan for "Meditation Journey": supabase + node service, riverpod, drift, 3D journey …

init_dev_universe(... same args, dry_run: false)   # optional: name: "Stillwater"
→ projects/meditation-journey/ + the exact commands to run next
```

## What you actually get

An honest capability statement — everything below is checked by
`npm run verify:generated` (see [Verification](#verification)):

- **A Flutter app that compiles and passes its own tests as generated**
  (`flutter analyze` clean, `flutter test` green, no `build_runner` step), on
  Flutter stable 3.44+ / Dart 3.12+. It is wired to the rulings:
  `bootstrap()` initializes Supabase from `--dart-define` values (or Firebase
  after `flutterfire configure`), Riverpod or Bloc for auth state, go_router
  with one route per wireframed screen (sign-in/up, home, 3D journey, explore,
  messages, checkout, settings), settings with sign-out and confirmed account
  deletion, a checkout screen behind a `SubscriptionService` stub (no keys, no
  SDK), a codegen-free drift offline layer (or Firestore persistence), and a
  Material 3 theme from the synthesized design tokens. Without backend
  configuration the app runs in **demo mode** with in-memory accounts.
- **Backend definitions**: Supabase migrations with RLS on every table,
  tenant-isolation policies, a profile-on-signup trigger and
  `delete_my_account()` (applied to real Postgres and smoke-tested for
  isolation in the matrix), or Firestore/Storage rules with `firebase.json`.
- **An optional Fastify service** (chosen when payments/integrations call for
  it) with raw-body HMAC webhook verification, `node:test` tests, and a
  multi-stage rootless Dockerfile.
- ADRs, a meeting transcript, SVG wireframes + a Figma import plugin, and
  **draft** Terms/Privacy/store checklists for counsel review.

What it is **not**: it does not generate platform folders (one
`flutter create . --platforms=android,ios` adds them, and the report tells you
so), it does not integrate a payment provider, it does not write your
product's domain features, and the personas are deterministic rules, not LLM
agents. `backend_api` projects get a backend + service and no Flutter app.

---

## Table of contents

- [How it works](#how-it-works)
- [The senior bench (27 personas)](#the-senior-bench)
- [Quick start](#quick-start)
- [Tool reference](#tool-reference)
- [The immersive 3D Flutter canvas](#the-immersive-3d-flutter-canvas)
- [Material verification & adaptation engine](#material-verification--adaptation-engine)
- [OmniCinema companion bridge (IPC)](#omnicinema-companion-bridge)
- [Design-to-Figma pipeline & reference ingestion](#design-to-figma-pipeline--reference-ingestion)
- [Legal & compliance framework](#legal--compliance-framework)
- [Extension marketplace (human-in-the-loop)](#extension-marketplace)
- [Storage guarantees](#storage-guarantees)
- [Development](#development)
- [Design honesty notes](#design-honesty-notes)

---

## How it works

```mermaid
flowchart LR
    A[init_dev_universe] --> B[Signal parsing<br/>3d · offline · payments · tenants · gdpr…]
    B --> C[Roundtable<br/>proposals → objections → mitigations → votes]
    C --> D[Rulings + ADRs<br/>dissents recorded]
    D --> E[Design synthesis<br/>aesthetic blend → tokens]
    E --> F[Scaffold assembly<br/>app · backend · RLS · Docker · CI · legal docs]
    F --> G[Cross-examination<br/>RLS/FK/a11y/secrets/legal checks,<br/>auto-fixes recorded]
    G --> H[Write to projects/&lt;slug&gt;<br/>+ MEETING_TRANSCRIPT.md]
    H --> I[Wireframes + Figma plugin]
    H --> J[Compliance audit report]
    H --> K[Asset watcher armed]
```

Every phase is **deterministic**: the debate is driven by a stance table
(who champions what, when, how strongly, and who objects with which argument),
scored against the parsed requirement signals. Same brief in, same rulings out —
reproducible, diffable, and covered by tests.

What lands in `projects/<slug>/`:

| Artifact | Contents |
|---|---|
| `MEETING_TRANSCRIPT.md` | Full debate: proposals, objections, responses, votes, rulings, dissents, artifact review table |
| `docs/adr/*.md` | One ADR per decision with options, scores, champions, and recorded dissent |
| `app/` | Flutter app wired to the rulings (see above) + widget tests + `app/README.md` + `.env.example` |
| `backend/` | Supabase migrations (RLS, storage policies, account deletion), or Firebase rules + `firebase.json`; optional Fastify service with tests and a multi-stage Dockerfile |
| `design/` | `DESIGN_LANGUAGE.md`, `design-tokens.json`, SVG wireframes, generated Figma plugin |
| `compliance/` | Privacy Policy, Terms of Service, store checklist, audit report |
| `.github/workflows/ci.yml`, `docs/ENV_ROUTING.md`, `.env.example` | Delivery + secret-routing discipline |

## The senior bench

27 codified senior personas across six practices — run `get_agency_roster` for the full table.

| Practice | Personas |
|---|---|
| **Multi-framework specialists** | Principal Systems Architect · Principal Flutter Architect · Flutter Platform Engineer · Supabase/Postgres Architect · Firebase Specialist · Node.js Backend Architect · API Contract Engineer |
| **UI/UX synthesis** | Principal UX Engineer · Design Synthesis Director · Spatial Canvas UI Engineer · 3D Navigation Designer · Accessibility Lead |
| **Legal & compliance** | Privacy & Data Protection Counsel (GDPR/CCPA) · App Store & Licensing Compliance Officer |
| **3D & animation** | 3D Modeler / glTF Pipeline Engineer · Technical Animator (Rive) |
| **Database** | Principal Data Modeler · RLS & Data Security Engineer |
| **DevSecOps & delivery** | Principal DevSecOps Engineer · Container & Isolation Specialist · CI/CD Release Engineer · SRE · QA Architect · Performance Engineer · Red-Team Reviewer · DX Engineer · Delivery Lead (chair) |

They genuinely disagree. A payments brief makes the Node architect win a service
layer over the SRE's objection; the Flutter platform engineer kills `three_dart`
on maintenance grounds every time; the accessibility lead's sign-off condition
(reduced-motion flat fallback) is enforced by a cross-exam check against the
actual generated Dart.

## Quick start

```bash
# The canonical home for this tool and everything it generates:
git clone https://github.com/joeshwoa/devuniverse-mcp.git /Volumes/PortableSSD/devuniverse-mcp
cd /Volumes/PortableSSD/devuniverse-mcp
npm install
npm run build
npm test && npm run smoke   # unit tests + a real stdio round-trip
```

> Running from a different path? Set `DEVUNIVERSE_ROOT` — every read and write
> stays inside that root.

**Claude Code**

```bash
claude mcp add devuniverse -- node /Volumes/PortableSSD/devuniverse-mcp/dist/index.js
```

**Claude Desktop / Cursor** (`claude_desktop_config.json` / `mcp.json`)

```json
{
  "mcpServers": {
    "devuniverse": {
      "command": "node",
      "args": ["/Volumes/PortableSSD/devuniverse-mcp/dist/index.js"],
      "env": { "OMNICINEMA_REPO_URL": "https://github.com/<owner>/omnicinema-mcp" }
    }
  }
}
```

Then, in your client: *"Use init_dev_universe to build a 3D portfolio universe
with offline mode and a contact form, dark editorial style."*

## Tool reference

| Tool | What it does |
|---|---|
| `init_dev_universe` | **Start here.** `project_type` (`flutter_app` · `flutter_spatial_app` · `full_stack` · `backend_api` (no app) · `three_d_experience` (3D, no accounts) · `custom`), `description`, optional `name` (else derived from the brief), `dry_run` (plan only, writes nothing), `use_omnicinema`, `style_preferences[]`. Ends with the exact next commands. |
| `get_agency_roster` | The 27 seniors: names, titles, focus, principles. |
| `generate_spatial_module` | Add the 3D journey to an existing project (patches `app/pubspec.yaml`) or emit it standalone (`mesh_renderer`: `model_viewer_plus` \| `flutter_scene`, `rive`, `depth_layers`). |
| `verify_assets` | Analyze art in the drop zones and re-derive the theme (report + WCAG checks). |
| `watch_assets` | Start/stop the drop-zone watcher; omit `project_dir` to list watchers. |
| `omnicinema_status` | Detect the companion, check loopback IPC health, report CASE A/B/C. |
| `provision_omnicinema` | CASE C: consent-gated clone → install → build → start IPC → token sync. |
| `generate_media_asset` | CASE A: request image/texture/audio/video from the companion; provenance manifest + auto-adaptation. |
| `sync_figma` | Compile wireframes (SVG), generate the Figma import plugin, optional REST handoff comment (`figma_file_key`, `FIGMA_TOKEN`). |
| `ingest_reference` | Pattern-analyze a URL or local video you provide; optional `apply_theme` blends its palette into the tokens. |
| `scan_extension_marketplace` | Crawl GitHub/Hugging Face for new MCP servers → `data/dev-review-queue.json` (pending human review, risk-flagged). |
| `generate_compliance_docs` | (Re)generate Terms/Privacy/store checklist for a project, with overrides (`company_name`, `contact_email`, `governing_law`). |
| `audit_compliance` | Static liability scan → `compliance/AUDIT_REPORT.md` (fails on high severity). |

## The immersive 3D Flutter canvas

`src/spatial/` is a code-generation skill producing a hand-owned deep-scroll
core — **scrolling dollies a camera along the Z axis**:

- `DeepScrollController` — maps scroll offset → camera depth with capped travel
  velocity and snap-point rooms ("seatbelts for spatial scrolling").
- `SpatialCamera` + `ParallaxLayer` — `Matrix4` perspective transforms
  (`setEntry(3,2,…)`), per-layer parallax factors, depth-fade curves.
- `StarfieldPainter` — seeded `CustomPainter` behind a `RepaintBoundary`,
  `shouldRepaint` keyed on camera depth (the performance engineer's 16 ms budget).
- `SpatialRoom`s — content stations strung through Z with wayfinding rail.
- **Accessibility contract:** when `MediaQuery.disableAnimations` is set the
  entire Z-axis experience collapses to a flat, semantic, screen-reader-navigable
  list. This is checked against the generated Dart, not just promised.
- Optional glTF model stage, opened on demand from the journey:
  `model_viewer_plus` (Google's `<model-viewer>`, works on stable Flutter) wins
  the debate by default; `flutter_scene` is debated and loses because it needs
  Flutter GPU (master channel) — it remains available via
  `generate_spatial_module` and is compile-checked in the matrix.
  `three_dart` is rejected on maintenance grounds.
- Optional `rive` (0.14) HUD overlay; it enables itself only once
  `assets/rive/hud.riv` exists, so a fresh scaffold stays bootable.

## Material verification & adaptation engine

Drop any image into `app/assets/incoming/` (watched) or call `verify_assets`:

1. **Verify** — format sniffing (PNG/JPEG/GIF/WebP/BMP/SVG), header dimensions,
   and for PNGs a full dependency-free decode (zlib inflate + unfilter) with
   palette clustering.
2. **Adapt** — deterministic rules re-derive the design tokens: theme brightness
   from hero luminance, primary from the most saturated dominant cluster
   (contrast-nudged to ≥3:1), secondary from the next distinct hue, padding grid
   from hero aspect, radius from saturation. Every rule is written into
   `docs/ADAPTATION_REPORT.md` with WCAG verification.
3. **Apply** — `design-tokens.json` and the marker-delimited block in
   `app/lib/theme/design_tokens.dart` are patched atomically.

## OmniCinema companion bridge

`src/bridge/omnicinema-connector.ts` links the optional local media generator
for cinematic assets. Detection looks at `/Volumes/PortableSSD/autonomous-cinema-mcp`,
`/Volumes/PortableSSD/omnicinema-mcp` (override: `OMNICINEMA_PATHS`).

| Case | State | Behavior |
|---|---|---|
| **A** | Installed & IPC healthy | `generate_media_asset` talks to `http://127.0.0.1:8787` (bearer token from the companion's `data/ipc-token.txt`), saves into `app/assets/generated/` with a provenance manifest, re-adapts the theme. |
| **B** | Not found | You get: `⚠️ OmniCinema asset generator not detected. The asset maker repository can be found here: <OMNICINEMA_REPO_URL>` |
| **C** | Not found + your consent | `Would you like devuniverse-mcp to automatically clone, install dependencies, and link OmniCinema-MCP for 100% free cinematic assets? [y/N]` — answered interactively (MCP elicitation) or via `provision_omnicinema confirm:true`. Then: `git clone` → `npm install` → `npm run build` → start the IPC service (detached, logged to `data/logs/`) → sync the token. |

Security model (see `SECURITY.md`): provisioning **refuses unpinned URLs**
(`OMNICINEMA_REPO_URL` must be a concrete `https://github.com/<owner>/<repo>`),
consent is explicit and recorded, the bridge follows only same-origin asset
URLs, and every IPC request is logged — a public tool that talks to another
local process should never do so silently.

## Design-to-Figma pipeline & reference ingestion

**To Figma.** The Figma REST API cannot create or edit design content (it reads
files, writes comments/webhooks). So `sync_figma` produces what actually lands
an editable draft:

1. **SVG wireframes** per screen (screen plan derived from your signals: spatial
   journey, auth, explore, messages, checkout, settings…) — drag into any file;
2. a **generated Figma development plugin** (`design/figma-plugin/`) that
   rebuilds every screen as native auto-layout frames using your tokens — import
   via *Plugins → Development → Import plugin from manifest*, edit freely, then
   hand changes back through tokens or the asset drop zone;
3. an optional **REST handoff**: token-validated comment on your Figma file
   linking the draft materials (`FIGMA_TOKEN`).

**From references.** `ingest_reference` accepts a URL or a local video that
demonstrates an interaction you want:

- URLs: single-page read (+ same-origin CSS, size-capped, honest User-Agent) →
  palette, typography, framework fingerprint (three.js, GSAP/ScrollTrigger,
  React/Vue/Next, WebGL, Rive/Lottie…), interaction mechanics (scroll-snap,
  IntersectionObserver, 3D transforms, reduced-motion handling), structure and
  a11y signals — plus a **rebuild plan mapped onto devuniverse modules**.
- Videos: `ffprobe`/`ffmpeg` (when installed) extract metadata + keyframes with
  per-scene palettes into `references/<slug>/frames/`.
- `apply_theme: true` blends the extracted palette into your tokens via the
  synthesis engine.

**IP stance, stated plainly:** reconstruction is *pattern-level* — interaction
mechanics and structure are re-derived natively; protected artwork, copy, and
trade dress are never copied, and the note ships inside every analysis report.
Likewise, the aesthetic library is curated and license-clean: devuniverse does
**not** crawl Dribbble/Behance (their ToS prohibit scraping); you steer the
blend with `style_preferences` and references you have the right to study.

## Legal & compliance framework

The legal bench generates, per project:

- **Privacy Policy** — GDPR (lawful-basis + retention table per actual data
  category, Arts. 15–22 rights, 72-hour breach window, transfers/SCCs) and
  CCPA/CPRA (know/delete/correct/opt-out, "we do not sell or share"), COPPA
  section when the brief targets children, in-app account deletion per Apple
  5.1.1(v) / Play policy.
- **Terms of Service** — license, acceptable use, UGC, IP, subscriptions/IAP
  language matched to the detected monetization, liability caps, governing law.
- **Store compliance checklist** — Apple privacy labels & IAP rules, Play data
  safety & billing, web consent banners — only the rows your build triggers.
- **Active code audit** (`audit_compliance`, also run at init) — committed
  credentials, plaintext endpoints, undisclosed tracker SDKs, sensitive
  permissions, missing policies → severity-ranked report with remediations.
- Cross-exam gates: privacy counsel verifies the docs cover what the signals
  imply; the RLS engineer auto-fixes any table created without
  `enable row level security` and records the fix in the transcript.

> **The honest version of "zero compliance liabilities":** generated documents
> are structured drafts with a mandatory review-by-counsel banner, and the audit
> reports residual risk. No tool can guarantee legal outcomes — this one refuses
> to pretend otherwise.

## Extension marketplace

`scan_extension_marketplace` discovers newly published MCP servers and dev
packages (GitHub search + Hugging Face spaces/models) and logs them to
`data/dev-review-queue.json` as `pending_human_review`, with risk flags
(`missing-license`, `low-adoption`, `suspicious-description`,
`pipe-to-shell-install`, `archived`). **Nothing is ever auto-installed**; flip
entries to `approved`/`rejected` and your decisions survive re-scans.

## Storage guarantees

Everything lives under one portable root (default
`/Volumes/PortableSSD/devuniverse-mcp`, override `DEVUNIVERSE_ROOT`):

```
devuniverse-mcp/
├── src/            server source (agency · spatial · bridge · compliance · design · marketplace)
├── dist/           build output (gitignored)
├── projects/       generated project environments (gitignored — each becomes its own repo)
├── data/
│   ├── dev-review-queue.json   marketplace review queue (committed)
│   ├── omnicinema-link.json    companion link record (chmod 600, gitignored)
│   └── logs/                   detached-process logs (gitignored)
└── test/ scripts/ docs
```

A storage guard wraps every write: paths must resolve inside the managed root,
or the call throws. The only sanctioned writes outside it are the OmniCinema
install directory you explicitly consent to.

## Development

```bash
npm run typecheck        # strict TS across src/test/scripts
npm run build            # tsc → dist/
npm test                 # fast node:test suite (no toolchains needed)
npm run smoke            # boots dist/index.js over real stdio and calls tools
npm run test:generated   # slow: compiles every generated project (skips without flutter/npm)
npm run verify:generated # same matrix as a CLI (--only=<id>, --platforms)
npm run dev              # tsx src/index.ts
```

### Verification

`scripts/verify-generated.ts` scaffolds nine briefs covering every
`project_type` and the main branches (Supabase/Firebase, Riverpod/Bloc,
drift/Firestore offline, with/without service, 3D with either renderer, no-auth
3D, `backend_api`) and runs, per project: `flutter pub get`, `flutter analyze`,
`flutter test` (optionally after `flutter create --platforms`), `npm install` +
`tsc --noEmit` + `npm test` for the service, and — when `DEVUNIVERSE_VERIFY_PG`
points at a Postgres server — applies the migrations against a stubbed
Supabase `auth`/`storage` schema and runs an RLS smoke test (tenant isolation,
owner bootstrap, `delete_my_account`). Missing toolchains are reported as
skipped, never as passed. The `flutter_scene` case compiles and passes its
tests on stable, but its model stage only renders on a master-channel Flutter
(Flutter GPU), which the tests do not open.

Not covered by the matrix: building APK/IPA binaries, running on devices,
Docker image builds, and Firebase rules (test those with the Firebase emulator
suite — `backend/firebase/firebase.json` is set up for it).

PRs welcome — new personas need a stance (when do they speak, what do they
champion or object to, with what score) plus a test proving the debate stays
deterministic.

## Design honesty notes

- **Personas are codified expert heuristics**, not 27 live LLMs: stance tables,
  scoring rules, and critique conditions driven by your requirement signals.
  That's what makes the debates reproducible, testable, and free to run. The
  transcript says so in its footer.
- **The bridge is transparent by design.** The original brief for CASE A said
  "silently query" — this implementation logs every companion request instead,
  because a published tool talking to another local process must be auditable.
- **Figma REST can't author designs**, so the pipeline generates a plugin +
  SVGs rather than pretending otherwise.

## License

[MIT](LICENSE) — see also [SECURITY.md](SECURITY.md).