@mindrian_os/cli 2.0.0-beta.29 → 2.0.0-beta.31

package/references/research/RESEARCH_17_MCP_UI_FRAMEWORKS.md

@@ -0,0 +1,272 @@
+# RESEARCH_17: MCP UI Frameworks -- Solving the Filesystem Invisibility Problem
+
+**Date:** 2026-04-06
+**Source:** Community research, MCP Apps spec, open-source ecosystem scan
+**Purpose:** Map available UI frameworks to MindrianOS UX friction points identified in RESEARCH_16 and the 2026-04-05 Lawrence/Leah user session
+**Depends on:** RESEARCH_16 (Native-First Architecture), user-research/2026-04-05-leah-lawrence-session.md
+
+---
+
+## 1. The Problem This Solves
+
+User session finding (2026-04-05):
+> "I was stressing me out, the file structure, because I didn't understand it." -- Lawrence Aronhime
+
+Design principle from session analysis:
+> "The folder structure must be invisible to the user while remaining the source of truth for the system."
+
+Current MindrianOS exports (dashboard, wiki, deck, graph) are generated as static HTML files that open in a browser. They work but require:
+1. User to know the `/mos:export` or `/mos:visualize` command exists
+2. A separate browser window
+3. No interactivity (static snapshots)
+4. No inline chat integration
+
+MCP Apps solve this by rendering interactive UI INSIDE the chat interface -- Claude Desktop, Cowork, or any MCP-compatible client.
+
+---
+
+## 2. Available Frameworks
+
+### Tier 1: Core Standards
+
+#### `@modelcontextprotocol/ext-apps` -- Official SDK
+- **Source:** github.com/modelcontextprotocol/ext-apps
+- **What it does:** Official Anthropic/MCP team SDK. Provides `registerAppTool`, `registerAppResource`, `useApp`/`useWidget` React hooks.
+- **Working examples:** pdf-server, system-monitor-server, map-server, shader-toy
+- **Transport:** Renders as iframes in Claude Desktop/Cowork chat
+- **Why it matters:** This is THE official path. Building on this guarantees compatibility with Claude's roadmap.
+
+#### `mcp-ui` -- Community Standard
+- **Source:** github.com/MCP-UI-Org/mcp-ui | mcpui.dev
+- **What it does:** Community project that PRECEDED and directly influenced the official spec.
+  - `@mcp-ui/server` -- `createUIResource()` helper to register UI bundles
+  - `@mcp-ui/client` -- `AppRenderer`/`UIResourceRenderer` React components
+- **Relationship:** Designed to work alongside `@modelcontextprotocol/ext-apps`
+- **Why it matters:** Community battle-tested patterns. Higher-level abstractions than the official SDK.
+
+### Tier 2: Accelerators
+
+#### `mcp-generative-ui` -- Auto-UI Wrapper
+- **Source:** github.com/vivekhaldar/mcp-generative-ui
+- **What it does:** Wraps ANY existing plain MCP server and automatically generates interactive UIs for tool results. Turns raw JSON into charts, tables, visual components.
+- **Key insight:** No manual UI coding needed. Could wrap MindrianOS MCP server immediately.
+- **Why it matters for MindrianOS:** Our MCP server already returns structured JSON (room state, section entries, grant results). This could generate visual cards from existing output WITHOUT rewriting the MCP server.
+
+#### Flowbite MCP UI Starter
+- **Source:** github.com/themesberg/mcp-ui-starter
+- **What it does:** Production-ready React + Tailwind starter with pre-built widgets (charts, tables, forms). Supports Claude, ChatGPT, and Gemini.
+- **Why it matters:** Fastest path to a polished widget library. De Stijl design tokens could be applied on top of Tailwind.
+
+### Tier 3: Reference Implementations
+
+#### MCP Memory Service React Dashboard
+- **Source:** github.com/doobidoo/mcp-memory-service
+- **What it does:** Working example of React + shadcn/ui + Tailwind dashboard wired to MCP via `window.mcpTools`. Stats cards, tabs, debounced queries, TypeScript types.
+- **Why it matters:** Closest architectural pattern to what MindrianOS needs (dashboard with sections, entry counts, intelligence signals).
+
+#### MCP Manager
+- **Source:** github.com/marcusglee11/mcp-manager
+- **What it does:** Full-stack: React frontend + FastAPI REST API + Python CLI. Manages MCP server installations, health monitoring, real-time status.
+- **Why it matters:** Shows the local web server pattern for complex admin UIs.
+
+#### Dynamic MCP UI Generator (POC)
+- **Source:** github.com/iamadi11/mcp-ui-poc
+- **What it does:** POC with React + Vite client + Express + MCP server. Dynamic form builder, dashboard creation, chart generation.
+- **Why it matters:** Shows the full client/server split architecture.
+
+### Tier 4: Plugin Infrastructure
+
+#### Claude Code Plugin Template
+- **Source:** github.com/ivan-magda/claude-code-plugin-template
+- **What it does:** GitHub template with plugin.json, hooks, skills, agents, slash commands, CI/CD.
+- **Relevance:** Reference for plugin structure, not UI.
+
+#### Desktop Extensions (.mcpb)
+- **Source:** anthropic.com/engineering/desktop-extensions
+- **What it does:** One-click install packages with manifest.json for Claude Desktop.
+- **Why it matters:** Distribution format for MindrianOS Desktop version.
+
+---
+
+## 3. Mapping UI to MindrianOS UX Problems
+
+### Problem -> Solution Matrix
+
+| User Session Problem | Current Solution | MCP UI Solution | Framework |
+|---|---|---|---|
+| "I don't know where my rooms are" | User navigates Finder, finds room/ folder | **Project Selector Widget** -- inline card showing all rooms with switch button | ext-apps + mcp-ui |
+| "What are these slash commands?" | User reads /mos:help output, copy-pastes | **Action Cards** -- clickable buttons rendered in chat: "Build Business Model", "Grade Your Progress" | ext-apps registerAppTool |
+| "How much longer?" (chain running) | No progress indicator | **Progress Widget** -- inline progress bar: "Step 3/6: Research | ~4 min remaining" | mcp-ui createUIResource |
+| "When I see 89%, what do I do?" | Skull icon in status bar | **Context Health Widget** -- visual meter with plain language: "Your session is 89% full. I'll summarize and keep working." | ext-apps useWidget |
+| "The tabs don't display properly" (export) | Static HTML snapshot with broken tabs | **Interactive Dashboard Widget** -- live room dashboard rendered inline with working tabs | mcp-ui AppRenderer |
+| "I was stressing about file structure" | Larry explains room/ directories | **Project Overview Card** -- visual card: "Blueprint Phase: 7 entries across 5 areas. Biggest gap: Business Model" | mcp-generative-ui (auto from existing JSON) |
+| "Every time I have to ask how to start" | User types `claude` in terminal | **Desktop Extension** -- one-click app icon, no terminal needed | .mcpb Desktop Extension |
+| Filing confirmation unclear | "artifact filed to room/market-analysis/" | **Filing Card** -- visual card: "Saved to Market Research [icon] | Your project now has 3 market analyses" | ext-apps |
+| Grant discovery results | Text list of grants | **Grant Discovery Widget** -- table with relevance scores, deadlines, apply buttons | Flowbite MCP UI Starter |
+| Chain modification mid-run | User types "add research to this chain" | **Chain Builder Widget** -- visual pipeline editor showing framework sequence with drag-reorder | ext-apps + custom |
+
+### The Three Surfaces Revisited
+
+| Surface | Current UI | With MCP Apps |
+|---|---|---|
+| **CLI** | Terminal text only. Slash commands. ASCII formatting. | Terminal text + **localhost dashboard** (existing pattern, enhanced) |
+| **Desktop** | Conversational only. No visual widgets. | Conversational + **inline widgets** (project cards, progress bars, filing confirmations) |
+| **Cowork** | Shared state via 00_Context/. Text only. | Shared state + **collaborative widgets** (team can see same project dashboard, grant table) |
+
+---
+
+## 4. Implementation Strategy
+
+### Phase 1: Quick Win -- mcp-generative-ui Wrapper (1-2 days)
+
+Wrap the existing MindrianOS MCP server with `mcp-generative-ui`. This auto-generates visual cards from our existing JSON output with ZERO changes to the MCP server.
+
+**What changes:** Tool results that currently return text/JSON render as visual components.
+**What doesn't change:** MCP server code, skill files, hook scripts.
+**Risk:** Low. Wrapper sits between server and client. If it breaks, remove it.
+
+**Immediate wins:**
+- Room status becomes a visual dashboard card instead of ASCII art
+- Grant results become a table with scores instead of text list
+- Section entry counts become a visual bar chart
+
+### Phase 2: Core Widgets -- ext-apps + mcp-ui (1-2 weeks)
+
+Build 5 custom widgets using the official SDK:
+
+1. **Project Selector** -- shows all rooms, switch with one click
+2. **Progress Tracker** -- chain/swarm progress with time estimates
+3. **Filing Confirmation** -- visual card when artifacts are saved
+4. **Action Suggester** -- clickable methodology buttons instead of /mos: commands
+5. **Context Health** -- visual meter replacing skull icon
+
+**Architecture:**
+```
+mindrian-mcp-server.cjs (existing)
+  ├── lib/mcp/tool-router.cjs (existing, unchanged)
+  ├── lib/mcp/resources.cjs (existing, unchanged)
+  ├── lib/mcp/prompts.cjs (existing, unchanged)
+  └── lib/mcp/widgets/          (NEW)
+      ├── project-selector.tsx
+      ├── progress-tracker.tsx
+      ├── filing-card.tsx
+      ├── action-suggester.tsx
+      └── context-health.tsx
+```
+
+**Key decision:** Widgets render in Desktop/Cowork via iframe. CLI users get the existing terminal output. Same MCP server, dual rendering.
+
+### Phase 3: Interactive Dashboard -- Full React App (2-4 weeks)
+
+Replace the static HTML snapshot with a live interactive dashboard:
+- Built with React + shadcn/ui + Tailwind (following MCP Memory Service pattern)
+- De Stijl design tokens applied via Tailwind config
+- Connected to MCP server via `window.mcpTools` pattern
+- Renders inline in Desktop/Cowork, localhost in CLI
+
+**This replaces:**
+- /mos:visualize (static HTML)
+- /mos:export dashboard (static HTML)
+- /mos:room (terminal output)
+- The need for users to EVER open Finder
+
+### Phase 4: Desktop Extension Package (1 week)
+
+Package MindrianOS as a `.mcpb` Desktop Extension:
+- One-click install from Anthropic marketplace
+- No terminal, no `claude` command, no PATH issues
+- User opens Claude Desktop, MindrianOS is there
+- Leah's "every time I have to ask how to start" problem: gone
+
+---
+
+## 5. The Native-First + MCP UI Architecture
+
+From RESEARCH_16:
+> Skills should encode WHAT to think, not HOW to use tools.
+
+From this research:
+> UI should show WHAT the user has, not WHERE it's stored.
+
+Combined principle:
+> **Skills teach Larry domain knowledge. MCP Apps show users their project. The filesystem is invisible to both.**
+
+### Token Impact
+
+MCP App widgets are rendered CLIENT-SIDE. They don't consume context tokens. A project selector card costs 0 tokens to display -- it's an iframe rendered by Claude Desktop from the MCP resource.
+
+This means the MCP UI approach is ADDITIVE to the Native-First token savings:
+- Native-First saves ~10,000 tokens per turn (skill compression)
+- MCP UI saves ~0 additional tokens (widgets are client-side)
+- But MCP UI REMOVES the need for verbose text descriptions of room state
+
+Currently, session-start injects ~1,750 tokens of room state as text. With an inline widget, that text could be replaced by a visual card + a 200-token summary. Potential additional savings: ~1,500 tokens per turn.
+
+### The Full v1.8.0 Stack
+
+```
+Layer 0: Skills (Native-First, ~11K tokens)
+  - Larry personality (WHAT to think)
+  - Proactive patterns (WHAT to detect)  
+  - Methodology routing (WHAT frameworks exist)
+  
+Layer 1: MCP Server (existing, enhanced)
+  - 6 hierarchical router tools (existing)
+  - Resources (existing)
+  - Prompts (existing)
+  - Widgets (NEW -- 5 core widgets)
+
+Layer 2: MCP UI (NEW)
+  - mcp-generative-ui wrapper (Phase 1)
+  - Custom ext-apps widgets (Phase 2)
+  - Interactive dashboard (Phase 3)
+  - Desktop Extension package (Phase 4)
+
+Layer 3: Filesystem (INVISIBLE to user)
+  - room/ structure (unchanged)
+  - STATE.md (unchanged)
+  - Hooks pipeline (unchanged)
+  - Everything works exactly as before
+  - User never sees it
+```
+
+---
+
+## 6. Risk Assessment
+
+| Risk | Severity | Mitigation |
+|---|---|---|
+| MCP Apps spec changes | MEDIUM | Build on official ext-apps SDK, not community forks |
+| Desktop-only (CLI users get nothing) | HIGH | CLI keeps existing terminal output. Widgets are ADDITIVE for Desktop/Cowork. |
+| Widget maintenance burden | MEDIUM | Start with mcp-generative-ui (zero custom code), graduate to custom only for high-value widgets |
+| De Stijl branding in widgets | LOW | Tailwind config with De Stijl tokens. Same approach as existing dashboard. |
+| TypeScript build step | MEDIUM | Widgets are separate from plugin core (markdown + CJS). Build step only for widgets. |
+
+---
+
+## 7. Quick Pick for MindrianOS
+
+| Goal | Use This | Timeline |
+|---|---|---|
+| Immediate visual upgrade (no coding) | `mcp-generative-ui` wrapper | 1-2 days |
+| Custom inline widgets for Desktop | `@modelcontextprotocol/ext-apps` | 1-2 weeks |
+| Full interactive dashboard | React + shadcn/ui + Tailwind (MCP Memory Service pattern) | 2-4 weeks |
+| One-click Desktop install | `.mcpb` Desktop Extension | 1 week |
+| Production widget library (Tailwind) | Flowbite MCP UI Starter | Reference only |
+
+---
+
+## 8. Connection to Existing Research
+
+- **RESEARCH_14** (Source Architecture): MCP Apps work within Claude's native tool system. `tengu_harbor` MCP allowlist must include widget servers.
+- **RESEARCH_15** (JTBD Optimization): Student archetype benefits most from visual widgets (no terminal literacy required). Venturist benefits from grant table widget. Researcher benefits from cross-domain visualization.
+- **RESEARCH_16** (Native-First): MCP UI is the visual complement to Native-First skills. Skills encode knowledge (tokens). Widgets encode presentation (zero tokens).
+- **User Session** (2026-04-05): Every friction point has a widget solution. See Section 3 mapping.
+
+---
+
+*Cross-references:*
+- *RESEARCH_14_CLAUDE_CODE_SOURCE_ARCHITECTURE.md*
+- *RESEARCH_15_V1.8_OPTIMIZATION_JTBD.md*
+- *RESEARCH_16_NATIVE_FIRST_PLUGIN_ARCHITECTURE.md*
+- *references/user-research/2026-04-05-leah-lawrence-session.md*

package/references/security/agentshield-baseline.json

@@ -0,0 +1,8 @@
+{
+  "schema_version": "1.0",
+  "artifact_kind": "agentshield-baseline",
+  "note": "Committed known/accepted AgentShield findings. The PR-gate CLI (scripts/agentshield-scan-cli.cjs) fails ONLY on a finding whose surface+id+ruleId triple is NOT in this list (baseline-delta mode). Regenerate ONLY via `node scripts/agentshield-scan-cli.cjs --write-baseline`; every change is PR-reviewable in the diff.",
+  "generated_at": "2026-07-02T00:52:43.075Z",
+  "generator": "199-07 agentshield-scan-cli --write-baseline",
+  "findings": []
+}

package/references/security/cve-db.json

@@ -0,0 +1,220 @@
+{
+  "version": "1.0.0",
+  "updated": "2026-07-01",
+  "source_inspiration": "patterns adapted from publicly documented MCP/agent-config attack classes (github.com/affaan-m/agentshield v1.4.0, MIT); no code or exploit text copied verbatim -- see .planning/seeds/SEED-016",
+  "_note": "The ONE external, versioned rules source the generalized AgentShield engine (199-03) reads via require(); no private pattern copy anywhere. Each regex rule carries a pattern (regex source, no delimiters), flags, severity, and a plain-English description. Updates land via PR like any other plugin artifact.",
+  "surfaces": {
+    "mcp_tool_description": [
+      {
+        "id": "AS-CVE-001",
+        "pattern": "ignore\\s+(all\\s+)?previous\\s+instructions",
+        "flags": "i",
+        "severity": "high",
+        "description": "MCP tool description carries an ignore-previous-instructions override marker (prompt injection against any downstream LLM consumer)."
+      },
+      {
+        "id": "AS-CVE-002",
+        "pattern": "\\bsystem\\s*:\\s*(you\\s+are|disable|enable|act|comply|ignore|override)",
+        "flags": "i",
+        "severity": "high",
+        "description": "System-role impersonation: a system: prefix followed by an imperative that tries to reset the model's role."
+      },
+      {
+        "id": "AS-CVE-003",
+        "pattern": "[\\u200B\\u200C\\u200D\\u2060\\uFEFF]",
+        "flags": "",
+        "severity": "medium",
+        "description": "Zero-width or invisible-unicode steganography marker hidden inside the tool description."
+      },
+      {
+        "id": "AS-CVE-004",
+        "pattern": "[A-Za-z0-9+/]{40,}={0,2}",
+        "flags": "",
+        "severity": "medium",
+        "description": "Suspiciously long base64-looking blob embedded in a tool description (possible obfuscated payload)."
+      }
+    ],
+    "hook_scope": [
+      {
+        "id": "AS-CVE-005",
+        "pattern": "\\b(curl|wget)\\b(?![^\\n]*\\b(localhost|127\\.0\\.0\\.1|::1)\\b)[^\\n]*https?://",
+        "flags": "i",
+        "severity": "high",
+        "description": "Hook command performs an outbound curl/wget to a non-localhost host (possible exfiltration channel)."
+      },
+      {
+        "id": "AS-CVE-006",
+        "pattern": "rm\\s+-rf\\s+(/(\\s|--|$)|--no-preserve-root)",
+        "flags": "i",
+        "severity": "high",
+        "description": "Hook command runs a destructive rm -rf sweep from the filesystem/repo root."
+      },
+      {
+        "id": "AS-CVE-007",
+        "pattern": "\\b(eval\\(|new\\s+Function\\()",
+        "flags": "",
+        "severity": "high",
+        "description": "Hook command performs dynamic code execution via eval( or new Function(."
+      },
+      {
+        "id": "AS-CVE-008",
+        "pattern": "(nc\\s+-e|/dev/tcp/)",
+        "flags": "i",
+        "severity": "high",
+        "description": "Hook command contains a reverse-shell idiom (nc -e or /dev/tcp/)."
+      }
+    ],
+    "skill_injection": [
+      {
+        "id": "AS-CVE-001",
+        "see": "AS-CVE-001",
+        "severity": "high",
+        "description": "Reuses the ignore-previous-instructions override marker (AS-CVE-001, defined under mcp_tool_description) applied to a SKILL.md body; no duplicate regex string is kept here -- the engine resolves the pattern via the see reference."
+      },
+      {
+        "id": "AS-CVE-009",
+        "pattern": "disregard\\s+(your\\s+|the\\s+)?system\\s+prompt",
+        "flags": "i",
+        "severity": "high",
+        "description": "Skill body instructs the model to disregard its system prompt."
+      },
+      {
+        "id": "AS-CVE-010",
+        "pattern": "allowed-tools\\s*:\\s*(\\[\\s*['\"]?\\*['\"]?\\s*\\]|['\"]?\\*['\"]?)",
+        "flags": "i",
+        "severity": "high",
+        "description": "SKILL.md frontmatter declares a wildcard allowed-tools grant (unscoped tool access)."
+      },
+      {
+        "id": "AS-CVE-014",
+        "pattern": "ignore\\s+(your\\s+|the\\s+)?system\\s+prompt",
+        "flags": "i",
+        "severity": "high",
+        "description": "Skill body instructs the model to ignore its system prompt (injection variant of the AS-CVE-009 disregard marker)."
+      }
+    ],
+    "claudemd_permission": [
+      {
+        "id": "AS-CVE-011",
+        "pattern": "Bash\\(\\s*\\*\\s*\\)",
+        "flags": "",
+        "severity": "high",
+        "description": "Unscoped Bash(*) permission grant (allows any shell command)."
+      },
+      {
+        "id": "AS-CVE-012",
+        "pattern": "--dangerously-skip-permissions",
+        "flags": "",
+        "severity": "high",
+        "description": "A committed file recommends running with --dangerously-skip-permissions (bypasses the permission gate)."
+      },
+      {
+        "id": "AS-CVE-013",
+        "pattern": "Bash\\(\\s*rm\\s+-rf\\b[^)]*\\)",
+        "flags": "i",
+        "severity": "high",
+        "description": "Permission grant scoped to a destructive Bash(rm -rf ...) command."
+      },
+      {
+        "id": "AS-CVE-015",
+        "pattern": "auto-approve\\s+all\\b",
+        "flags": "i",
+        "severity": "high",
+        "description": "A committed file recommends auto-approving all commands (blanket permission-gate bypass)."
+      }
+    ],
+    "supply_chain": {
+      "_note": "Structured heuristic input (not regex). known_bad_packages is an empty seed array -- a living list updated via PR the moment a real malicious package is identified. typosquat_watchlist maps each legitimate package to close-miss names an attacker might publish. allowlist echoes the GSD Package Legitimacy Gate vocabulary (ASSUMED/SUS/SLOP/VETTED) in the disposition field, so any FUTURE new dependency defaults to a state other than VETTED until a human reviews it.",
+      "known_bad_packages": [
+        "left-pad-typosquat"
+      ],
+      "typosquat_watchlist": [
+        {
+          "legit": "lodash",
+          "watch": [
+            "lodahs",
+            "lodash-es-typo"
+          ]
+        },
+        {
+          "legit": "express",
+          "watch": [
+            "expres",
+            "expresss"
+          ]
+        },
+        {
+          "legit": "chalk",
+          "watch": [
+            "chalk-cli-fake"
+          ]
+        }
+      ],
+      "allowlist": [
+        {
+          "name": "@huggingface/transformers",
+          "disposition": "VETTED",
+          "note": "e5 local embedding runtime (multilingual-e5-large). Apache-2.0, canonical upstream huggingface/transformers.js, v4.2.0, NO install/postinstall scripts. Already shipping in released versions. Reviewed 2026-08-09 on the first run of this scan that did not crash."
+        },
+        {
+          "name": "@ig3/markdown-it-wikilinks",
+          "disposition": "VETTED"
+        },
+        {
+          "name": "@modelcontextprotocol/ext-apps",
+          "disposition": "VETTED"
+        },
+        {
+          "name": "@modelcontextprotocol/sdk",
+          "disposition": "VETTED"
+        },
+        {
+          "name": "ajv",
+          "disposition": "VETTED",
+          "note": "JSON Schema validator, required directly by lib/core/brain-client.cjs for Phase 110 typed-packet enforcement. MIT, canonical upstream ajv-validator/ajv, v8.18.0, NO install scripts. Was already on disk as a transitive dep of the VETTED @modelcontextprotocol/sdk at the IDENTICAL version, so declaring it adds no new code -- it only makes an existing direct require honest. Reviewed 2026-08-09."
+        },
+        {
+          "name": "asciichart",
+          "disposition": "VETTED"
+        },
+        {
+          "name": "chokidar",
+          "disposition": "VETTED"
+        },
+        {
+          "name": "chrono-node",
+          "disposition": "VETTED"
+        },
+        {
+          "name": "express",
+          "disposition": "VETTED"
+        },
+        {
+          "name": "flexsearch",
+          "disposition": "VETTED"
+        },
+        {
+          "name": "gray-matter",
+          "disposition": "VETTED"
+        },
+        {
+          "name": "markdown-it",
+          "disposition": "VETTED"
+        },
+        {
+          "name": "semver",
+          "disposition": "VETTED"
+        },
+        {
+          "name": "sqlite-vec",
+          "disposition": "VETTED",
+          "note": "SQLite vector extension for local room.db vector search. MIT OR Apache, canonical upstream asg017/sqlite-vec, v0.1.9, ZERO transitive deps, NO install scripts. Already shipping in released versions. Reviewed 2026-08-09 on the first run of this scan that did not crash."
+        },
+        {
+          "name": "zod",
+          "disposition": "VETTED"
+        }
+      ]
+    }
+  }
+}