# 🌌 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 senior engineering personas** convenes:
they parse your requirements, propose stacks, debate each other, vote, record
dissents, generate a production-grade scaffold — Flutter app with an immersive
3D deep-scroll canvas, Supabase/Firebase/Node backend with Row Level Security,
multi-stage Dockerfiles, CI, Terms of Service and a GDPR/CCPA Privacy Policy —
then **cross-examine every generated artifact** before presenting it, with the
full meeting transcript on disk.

```
init_dev_universe(
  project_type: "flutter_spatial_app",
  description:  "A 3D deep-scroll galaxy shop called 'Aurora Atelier' with
                 glTF product meshes, accounts, offline mode, and Stripe
                 subscriptions — GDPR matters. Glassmorphism, dark.",
  use_omnicinema: true
)
→ projects/aurora-atelier/  (50+ files, 10 debated decisions, transcript, audit)
```

---

## 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: theme tokens, spatial module (if 3D), widget tests, analysis options |
| `backend/` | Supabase migrations + RLS policies + storage policies, or Firebase rules; optional Fastify service with 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/<you>/devuniverse-mcp.git /Volumes/PortableSSD/devuniverse-mcp
cd /Volumes/PortableSSD/devuniverse-mcp
npm install
npm run build
npm test && npm run smoke   # 22 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` | **The unified entry point.** `project_type` (`flutter_app` · `flutter_spatial_app` · `full_stack` · `backend_api` · `three_d_experience` · `custom`), `description`, `use_omnicinema`, optional `style_preferences[]`. Runs the whole pipeline above. |
| `get_agency_roster` | The 27 seniors: names, titles, focus, principles. |
| `generate_spatial_module` | Emit the deep-scroll 3D Flutter module standalone or into an existing project (`mesh_renderer`, `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 mesh stage: `flutter_scene` (glTF/Impeller, wrapped behind a
  `GltfStage` seam) or `flutter_cube` (lightweight OBJ). `three_dart` is debated
  and rejected on maintenance grounds — you'll find the argument in the ADR.
- Optional `rive` HUD overlay driven by a state machine.

## 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            # node:test suite (roundtable, scaffold, PNG decode, bridges, crawler, legal)
npm run smoke       # boots dist/index.js over real stdio and calls tools
npm run dev         # tsx src/index.ts
```

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).