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

Related MCP server: Antigravity Mobile Command MCP Server

Architecture

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

1. Create the Supabase backend

1. Create a Supabase project.

2. In SQL Editor, run 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+:

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:

npm install
npm run build
npm test

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

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 into ~/.codex/config.toml and replace the server path, or run:

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 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 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:

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