Orchestro MCP

TL;DR

- MCP Server (TypeScript): executes the flow goal → tasks → deps → code → learning, exposing ~60 tools to Claude Code.

- Web Dashboard (Next.js + React Flow): Kanban board, dependency graphs, event timeline, real-time via Socket.io.

- Claude Code: consumes MCP tools for analysis/implementation; agents move cards across columns as work happens.

- Supabase (PostgreSQL + RLS): the single source of truth with a complete audit trail and row-level security.

---

## Block view

[User/PM] ──(story)──▶ Dashboard

│

▼

MCP Server (Conductor)

┌──────── tasking / deps / analysis / history ───────┐

│ │

Claude Code ◀── MCP tools & prompts ──▶ Supabase (data & events)

│ │

└──── agents / “scrum master” ⇒ move cards (Socket) ──┘

---

## Components

1) MCP Server (TypeScript)

- Tools for: decompose_story, create/list/update_task, save_dependencies, prepare_task_for_execution, get_execution_prompt, add_feedback, detect_failure_patterns, get_task_history, and more.

- Scrum Master (auto): guardrails for states, dependencies, execution order, and consistency.

- Suggestions: proposes relevant agents/tools; syncs .claude/agents/.

- Safety & idempotency: validations, conflict checks, every mutation audited.

2) Web Dashboard (Next.js)

- Kanban + dependency graphs (React Flow); filters by story/task/status.

- Real-time via Socket.io: each server event updates the UI (card movement, risk flags, decision history).

- Timeline: decisions, status changes, analyses, code changes.

3) Claude Code (MCP client)

- Consumes Orchestro tools; gets context-rich prompts per task/feature.

- Agents (guardians/sub-agents) analyze, implement, and move cards via MCP calls.

4) Supabase (data layer)

- PostgreSQL with RLS; stores tasks, deps, resources, events, patterns, learnings.

- Triggers for pattern frequency, task history, and audit exports.

---

## End-to-end flow

1. Create Story (PM/Dev from the dashboard): “User logs in with email/password.”

2. decompose_story (MCP): generates technical tasks + initial dependencies (optional autoAnalyze).

3. save_dependencies: consolidates the graph + get_execution_order (topological sort).

4. prepare_task_for_execution: produces analysis prompts (files/impact areas, risks, helpful patterns).

5. get_execution_prompt: execution prompt for Claude (context, constraints, checklist).

6. Implementation (Claude/Dev): code & tests; record_code_change and record_decision.

7. Status & Board: record_status_transition → card moves (Socket.io), risks/indicators refresh.

8. Learning: add_feedback and detect_failure_patterns → future suggestions + mitigations.

---

## Data model (excerpt)

- projects, user_stories, tasks (JSONB metadata: assignee, priority, tags, category)

- task_dependencies (graph), resource_nodes / resource_edges (files, APIs, tables, etc.)

- events / history: task_history, status_transitions, decisions, code_changes, guardian_interventions

- knowledge: patterns, learnings, templates, pattern_frequency

- config: tech_stack, agents, mcp_tools

> Every action emits an auditable event.

---

## Security & trust

- Local-first: data lives in your Supabase project.

- RLS on + least-privilege access.

- Secrets via ENV only (no secrets in code).

- Full audit trail, exportable (compliance/GDPR friendly).

---

## Extensibility

- Add MCP tools: define schema + validation, register in mcp_tools.

- Custom agents: drop files in .claude/agents/ → sync_claude_code_agents.

- Patterns/Templates: enrich patterns, templates, learnings to cut friction.

- Hooks: wire Slack/Teams via event stream for notifications.

---

## Operations & performance

- Socket.io for live updates; light polling where needed.

- Indexes (GIN on JSONB) for sub-10ms queries on common task/event filters.

- Migrations via scripts; manual fallback for locked-down envs.

- Quick troubleshooting: dashboard health, Claude config checks, ENV sanity.

---

## Deploy

- Local dev

npx @orchestro/init

npm run dashboard (opens http://localhost:3000)

restart Claude Code and ask: “Show me orchestro tools”

- Self-host

Container with ENV: DATABASE_URL, SUPABASE_URL, SUPABASE_SERVICE_KEY, PORT.

- Multi-user/team

RLS + event stream per workspace; project/permission separation.

---

## Why this architecture

- Visibility (board + graphs) and executability (MCP) in the same loop.

- Claude-first: robust prompts, persistent context, agent/tool suggestions.

- Shared state (Supabase) with full history for retros and quality gates.

---

## Next steps (short)

- PM-friendly exports & stakeholder notifications

- Lightweight metrics (velocity, aging, blockers)

- Slack/Teams integrations

- Advanced auto-orchestration (path suggestions, conflict resolution)

---

## Links

- Website: orchestro.org

- Repo: github.com/khaoss85/mcp-orchestro

If you want a deeper dive (schema diagrams, event examples), tell me and I’ll add them here.