# Project Node MCP

Project Node turns an agent's implementation plan into a live recursive execution graph. Codex or Claude Code publishes project nodes through a local MCP server; Supabase persists and broadcasts changes; a Flutter app renders the plan and activity on Android or iOS.

## What the MVP includes

- One MCP server for both Codex and Claude Code
- Recursive phases, tasks, subtasks, and milestones
- `not started`, `in progress`, `blocked`, `completed`, and `cancelled` states
- Percentage progress with automatic project roll-up from leaf nodes
- Idempotent plan sync through stable `external_key` values
- Realtime Flutter project list, expandable tree, and activity timeline
- Supabase Auth, row-level security, and read-only mobile policies
- In-memory mode and unit tests for local MCP development

## Architecture

```mermaid
flowchart LR
  A["Codex / Claude Code"] -->|STDIO MCP tools| B["Project Node MCP"]
  B -->|Service-role writes| C["Supabase Postgres"]
  C -->|Realtime + RLS| D["Flutter mobile app"]
```

The MCP server does not inspect private model thoughts. The coding agent explicitly reports plan and status events using the included `AGENTS.md` or `CLAUDE.md` instructions.

## MCP tools

| Tool | Purpose |
| --- | --- |
| `project_create` | Create a project graph |
| `project_list` | Find projects for the configured owner |
| `project_tree_get` | Read the complete recursive tree |
| `project_plan_sync` | Idempotently publish a nested plan |
| `project_node_upsert` | Create or update one node |
| `project_node_status` | Report start, progress, blocker, or completion |

## 1. Create the Supabase backend

1. Create a Supabase project.
2. In **SQL Editor**, run [`supabase/migrations/001_project_node.sql`](supabase/migrations/001_project_node.sql).
3. In **Authentication → Providers → Email**, enable email/password authentication.
4. Copy the project URL, publishable key, and service-role key from the project settings.

The service-role key bypasses row-level security. Keep it only in the local MCP process—never commit it or put it in the mobile app.

## 2. Start the mobile app

The repository contains the Flutter source. Generate the standard platform wrappers once on a machine with Flutter 3.32+:

```bash
cd apps/mobile
flutter create . --project-name project_node_mobile --platforms android,ios
flutter pub get
flutter run \
  --dart-define=SUPABASE_URL=https://YOUR_PROJECT.supabase.co \
  --dart-define=SUPABASE_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
```

Create an account in the app. From the Projects screen menu choose **Copy MCP owner ID**. This is the Supabase Auth user UUID used below.

## 3. Build the MCP server

From the repository root:

```bash
npm install
npm run build
npm test
```

Export the server-only environment variables in your shell or secret manager:

```bash
export SUPABASE_URL=https://YOUR_PROJECT.supabase.co
export SUPABASE_SERVICE_ROLE_KEY=YOUR_SERVICE_ROLE_KEY
export PROJECT_NODE_OWNER_ID=UUID_COPIED_FROM_THE_APP
```

For an offline smoke test, set `STORAGE_DRIVER=memory`. Memory data disappears when the MCP process exits.

## 4. Connect Codex

Either copy [`integrations/codex-config.toml.example`](integrations/codex-config.toml.example) into `~/.codex/config.toml` and replace the server path, or run:

```bash
codex mcp add project-node \
  --env SUPABASE_URL="$SUPABASE_URL" \
  --env SUPABASE_SERVICE_ROLE_KEY="$SUPABASE_SERVICE_ROLE_KEY" \
  --env PROJECT_NODE_OWNER_ID="$PROJECT_NODE_OWNER_ID" \
  -- node /ABSOLUTE/PATH/project-node-mcp/apps/mcp-server/dist/index.js
```

Run `codex mcp list`, then use `/mcp` inside Codex to confirm the six tools are connected.

Append [`integrations/AGENTS.snippet.md`](integrations/AGENTS.snippet.md) to the target repository's `AGENTS.md`. This tells Codex when progress must be reported.

## 5. Connect Claude Code

Copy [`integrations/claude-mcp.json.example`](integrations/claude-mcp.json.example) to `.mcp.json` in the target project and replace the absolute server path. Then run Claude Code and approve the project-scoped MCP server when prompted.

Alternatively:

```bash
claude mcp add --scope project --transport stdio project-node \
  --env SUPABASE_URL="$SUPABASE_URL" \
  --env SUPABASE_SERVICE_ROLE_KEY="$SUPABASE_SERVICE_ROLE_KEY" \
  --env PROJECT_NODE_OWNER_ID="$PROJECT_NODE_OWNER_ID" \
  -- node /ABSOLUTE/PATH/project-node-mcp/apps/mcp-server/dist/index.js
```

Append [`integrations/CLAUDE.snippet.md`](integrations/CLAUDE.snippet.md) to the target repository's `CLAUDE.md`.

## Example request

After configuration, ask the coding agent:

> Build this feature and use Project Node to publish the recursive plan and keep every task status synchronized until verification is complete.

Open the mobile app. The project, nested nodes, progress, blockers, and activity should update without refreshing.

## Security notes

- The Flutter app receives only the publishable key and is limited by RLS to the signed-in user's rows.
- The service-role key stays on the developer machine. For a public SaaS release, replace it with a remote authenticated MCP server and scoped per-user tokens.
- Tracking metadata must not contain secrets, raw prompts, source code, or personal data.
- Mobile policies are intentionally read-only; agents remain the only writers in this MVP.

## Next production steps

- Remote Streamable HTTP MCP with OAuth instead of distributing a service-role key
- Organization/workspace support and device pairing codes
- Push notifications for blockers and completion
- Offline mobile cache, pagination, and project archive controls
- Client hooks and filesystem signals for richer automatic progress detection
- Web dashboard and shareable read-only project views