MCP Server Reference

The LumenFlow MCP server exposes Software Delivery Pack tools and kernel runtime tools to AI assistants via the Model Context Protocol. The majority of the 110 tools are Software Delivery Pack tools; 7 are kernel runtime task primitives for advanced use cases.

Package

The MCP server is provided by @lumenflow/mcp:

pnpm add @lumenflow/mcp

Running the Server

The MCP server runs over stdio and is typically configured in your AI client:

# Direct execution
npx @lumenflow/mcp

# Or via the CLI binary
lumenflow-mcp

Environment Variables

Variable	Description	Default
`LUMENFLOW_PROJECT_ROOT`	Project root directory	`process.cwd()`
`LUMENFLOW_MCP_LOG_LEVEL`	Log level (debug, info, warn, error)	`info`

Tools Overview

The MCP server exposes 110 tools organized into 13 categories (103 in the core allTools registry plus 7 runtime task tools):

Category	Count	Description
Core WU Operations	8	Basic WU lifecycle and context
Public Parity Operations (W1)	15	Ops/setup parity families from public CLI
Public Parity Operations (W2)	17	File/git/plan/signal/config parity families
Additional WU Operations	17	Extended WU management
Initiative Operations	8	Multi-phase project orchestration
Memory Operations	14	Session tracking and agent coordination
Agent Operations	4	Agent session management and issue logging
Orchestration Operations	3	Initiative execution and monitoring
Delegation Operations	1	Sub-agent delegation tree management
Flow/Metrics Operations	3	DORA metrics and flow analysis
Validation Operations	5	WU and configuration validation
Setup Operations	8	LumenFlow initialization and configuration
Runtime Task Tools	7	Kernel runtime task lifecycle

Tool inventory source of truth: packages/@lumenflow/mcp/src/tools.ts (allTools + runtimeTaskTools).

Public CLI parity target is 91 normalized public commands (: and - converted to _). The allTools array contains 103 tools because 12 tools are intentionally MCP-only extras. The runtimeTaskTools array adds 7 kernel-native task tools for a total of 110 registered tools.

Core WU Operations

context_get

Get current LumenFlow context including location, git state, and active WU.

Input: None

Output:

{
  "location": {
    "type": "worktree",
    "cwd": "/path/to/worktrees/lane-wu-xxx",
    "mainCheckout": "/path/to/repo"
  },
  "git": {
    "branch": "lane/operations/wu-123",
    "dirty": false
  },
  "wu": {
    "id": "WU-123",
    "status": "in_progress"
  }
}

wu_list

List all Work Units with optional filtering.

Input:

Parameter	Type	Description
`status`	string	Filter by status (ready, in_progress, blocked, waiting, done)
`lane`	string	Filter by lane name

Output: Array of WU objects matching filters.

wu_status

Get detailed status of a specific Work Unit.

Input:

Parameter	Type	Required	Description
`id`	string	Yes	WU ID (e.g., `WU-1234`)

Output: Full WU status including spec, location, and valid commands.

wu_create

Create a new Work Unit specification.

Input:

Parameter	Type	Required	Description
`id`	string	No	WU ID (auto-generated if omitted)
`lane`	string	Yes	Lane name (e.g., `Framework: CLI`)
`title`	string	Yes	WU title
`description`	string	No	Context/Problem/Solution description
`acceptance`	string[]	No	Acceptance criteria
`code_paths`	string[]	No	Code paths this WU will modify
`exposure`	string	No	Exposure level (ui, api, backend-only, documentation)

Output: Confirmation message with created WU ID.

wu_claim

Claim a Work Unit and create a worktree for implementation.

Input:

Parameter	Type	Required	Description
`id`	string	Yes	WU ID to claim
`lane`	string	Yes	Lane for the WU

Output: Confirmation with worktree path.

wu_done

Complete a Work Unit (merge, stamp, cleanup).

Input:

Parameter	Type	Required	Description
`id`	string	Yes	WU ID to complete
`skip_gates`	boolean	No	Skip gates (requires reason)
`reason`	string	No	Reason for skipping gates
`fix_wu`	string	No	WU ID that will fix the skipped issue

Output: Confirmation message or error if called from worktree.

gates_run

Run LumenFlow quality gates (lint, typecheck, tests).

Input:

Parameter	Type	Required	Description
`docs_only`	boolean	No	Run docs-only gates (skip lint/typecheck/tests)

Output: Gate results or error details.

Public CLI Parity Operations (Wave 1)

These tools were added to close ops/setup parity gaps against the public CLI manifest.

MCP Tool	CLI Command	Purpose
`backlog_prune`	`backlog:prune`	Prune stale backlog entries
`docs_sync`	`docs:sync`	Sync onboarding docs/templates
`gates`	`gates`	Run quality gates
`gates_docs`	`gates --docs-only`	Run docs-only gates
`lane_health`	`lane:health`	Report lane overlap/health
`lane_suggest`	`lane:suggest`	Suggest lane from scope/context
`lumenflow`	`lumenflow`	Main CLI entrypoint
`lumenflow_gates`	`gates`	Framework gates wrapper
`lumenflow_validate`	`validate`	Framework validation wrapper
`lumenflow_metrics`	`lumenflow:metrics`	Framework metrics wrapper
`metrics`	`metrics`	Metrics CLI
`state_bootstrap`	`state:bootstrap`	Bootstrap state store
`state_cleanup`	`state:cleanup`	Cleanup state artifacts
`state_doctor`	`state:doctor`	Diagnose/repair state issues
`sync_templates`	`sync:templates`	Sync framework templates

Public CLI Parity Operations (Wave 2)

These tools were added to close file/git/plan/signal/proto parity gaps.

MCP Tool	CLI Command	Purpose
`file_read`	`file:read`	Read files with line/size controls
`file_write`	`file:write`	Write files with optional safety flags
`file_edit`	`file:edit`	Exact string replacement editing
`file_delete`	`file:delete`	Delete files/directories
`git_status`	`git:status`	Git status reporting
`git_diff`	`git:diff`	Git diff inspection
`git_log`	`git:log`	Commit history inspection
`git_branch`	`git:branch`	Branch listing/inspection
`init_plan`	`init:plan`	Initiative plan linking/creation
`plan_create`	`plan:create`	Create plan files
`plan_edit`	`plan:edit`	Edit plan sections
`plan_link`	`plan:link`	Link plan URIs to WUs/initiatives
`plan_promote`	`plan:promote`	Promote plan status
`signal_cleanup`	`signal:cleanup`	Cleanup stale coordination signals
`wu_proto`	`wu:proto`	Create+claim relaxed prototype WUs

Additional WU Operations

wu_block

Block a Work Unit and move it from in_progress to blocked status.

Input:

Parameter	Type	Required	Description
`id`	string	Yes	WU ID to block
`reason`	string	Yes	Reason for blocking
`remove_worktree`	boolean	No	Remove worktree when blocking

wu_unblock

Unblock a Work Unit and move it from blocked to in_progress status.

Input:

Parameter	Type	Required	Description
`id`	string	Yes	WU ID to unblock
`reason`	string	No	Reason for unblocking
`create_worktree`	boolean	No	Create worktree when unblocking

wu_edit

Edit Work Unit spec fields with micro-worktree isolation.

Input:

Parameter	Type	Required	Description
`id`	string	Yes	WU ID to edit
`description`	string	No	New description text
`acceptance`	string[]	No	Acceptance criteria to add
`notes`	string	No	Notes text to add
`code_paths`	string[]	No	Code paths to add
`lane`	string	No	New lane assignment
`priority`	string	No	New priority (P0, P1, P2, P3)
`initiative`	string	No	Initiative ID
`phase`	number	No	Phase number within initiative
`no_strict`	boolean	No	Bypass strict validation

wu_release

Release an orphaned WU from in_progress back to ready state for reclaiming.

Input:

Parameter	Type	Required	Description
`id`	string	Yes	WU ID to release
`reason`	string	No	Reason for releasing

wu_recover

Analyze and fix WU state inconsistencies.

Input:

Parameter	Type	Required	Description
`id`	string	Yes	WU ID to recover
`action`	string	No	Recovery action (resume, reset, nuke, cleanup)
`force`	boolean	No	Required for destructive actions
`json`	boolean	No	Output as JSON

wu_repair

Unified WU repair tool - detect and fix WU state issues.

Input:

Parameter	Type	Required	Description
`id`	string	No	WU ID to check/repair
`check`	boolean	No	Audit only, no changes
`all`	boolean	No	Check/repair all WUs
`claim`	boolean	No	Claim repair mode
`admin`	boolean	No	Admin repair mode
`repair_state`	boolean	No	State repair mode

wu_deps

Visualize WU dependency graph.

Input:

Parameter	Type	Required	Description
`id`	string	Yes	WU ID to analyze
`format`	string	No	Output format (table, json, ascii, mermaid)
`depth`	number	No	Maximum traversal depth
`direction`	string	No	Graph direction (up, down, both)

wu_prep

Prepare WU for completion by running gates in worktree.

Input:

Parameter	Type	Required	Description
`id`	string	Yes	WU ID to prepare
`docs_only`	boolean	No	Run docs-only gates

wu_preflight

Fast validation of code_paths and test paths before gates run (under 5 seconds vs 2+ minutes).

Input:

Parameter	Type	Required	Description
`id`	string	Yes	WU ID to preflight
`worktree`	string	No	Override worktree path

wu_prune

Clean stale worktrees (dry-run by default).

Input:

Parameter	Type	Required	Description
`execute`	boolean	No	Execute cleanup (default is dry-run)

wu_delete

Safely delete WU YAML files with micro-worktree isolation.

Input:

Parameter	Type	Required	Description
`id`	string	No	WU ID to delete
`dry_run`	boolean	No	Show what would be deleted without changes
`batch`	string	No	Delete multiple WUs (comma-separated)

wu_cleanup

Clean up worktree and branch after PR merge (PR-based completion workflow).

Input:

Parameter	Type	Required	Description
`id`	string	Yes	WU ID to cleanup
`artifacts`	boolean	No	Remove build artifacts

wu_brief

Generate handoff prompt for sub-agent WU execution.

Input:

Parameter	Type	Required	Description
`id`	string	Yes	WU ID to brief
`client`	string	No	Target client (e.g. claude-code, codex-cli, gemini-cli)
`thinking`	boolean	No	Enable extended thinking
`budget`	number	No	Token budget for extended thinking
`no_context`	boolean	No	Skip memory context injection

wu_delegate

Generate delegation prompt and record explicit lineage intent.

Input:

Parameter	Type	Required	Description
`id`	string	Yes	WU ID to delegate
`parent_wu`	string	Yes	Parent WU ID for delegation lineage
`client`	string	No	Target client (e.g. claude-code, codex-cli, gemini-cli)
`thinking`	boolean	No	Enable extended thinking
`budget`	number	No	Token budget for extended thinking
`no_context`	boolean	No	Skip memory context injection

wu_validate

Validate WU YAML files against schema (strict mode by default).

Input:

Parameter	Type	Required	Description
`id`	string	Yes	WU ID to validate
`no_strict`	boolean	No	Bypass strict validation

wu_infer_lane

Suggest lane for a WU based on code paths and description.

Input:

Parameter	Type	Required	Description
`id`	string	No	WU ID to analyze (reads YAML)
`paths`	string[]	No	Code paths to analyze
`desc`	string	No	WU description/title text

wu_unlock_lane

Safely unlock a lane lock with audit logging.

Input:

Parameter	Type	Required	Description
`lane`	string	No	Lane name to unlock
`reason`	string	No	Reason for unlocking
`force`	boolean	No	Force operation
`list`	boolean	No	List all current lane locks
`status`	boolean	No	Show detailed status for the lane

Initiative Operations

initiative_list

List all initiatives with optional status filter.

Input:

Parameter	Type	Required	Description
`status`	string	No	Filter by status (active, completed, paused)
`json`	boolean	No	Output as JSON

initiative_status

Get detailed status of a specific initiative including WUs and progress.

Input:

Parameter	Type	Required	Description
`id`	string	Yes	Initiative ID (e.g., INIT-001)
`json`	boolean	No	Output as JSON

initiative_create

Create a new initiative for multi-phase project orchestration.

Input:

Parameter	Type	Required	Description
`id`	string	Yes	Initiative ID (e.g., INIT-001)
`title`	string	Yes	Initiative title
`description`	string	No	Initiative description
`phases`	string[]	No	Phase names (e.g., “Phase 1: MVP”)

initiative_edit

Edit initiative fields.

Input:

Parameter	Type	Required	Description
`id`	string	Yes	Initiative ID to edit
`title`	string	No	New title
`description`	string	No	New description
`status`	string	No	New status (active, completed, paused)

initiative_add_wu

Add a Work Unit to an initiative, optionally assigning to a phase.

Input:

Parameter	Type	Required	Description
`initiative`	string	Yes	Initiative ID
`wu`	string	Yes	WU ID to add
`phase`	number	No	Phase number to assign (1-based)

initiative_remove_wu

Remove a Work Unit from an initiative.

Input:

Parameter	Type	Required	Description
`initiative`	string	Yes	Initiative ID
`wu`	string	Yes	WU ID to remove

initiative_bulk_assign

Bulk assign WUs to an initiative based on pattern matching.

Input:

Parameter	Type	Required	Description
`id`	string	Yes	Initiative ID
`pattern`	string	No	Pattern to match WU titles (e.g., “MCP:*“)
`phase`	number	No	Phase to assign matched WUs

initiative_plan

Link an existing plan or create a new plan template for an initiative.

Input:

Parameter	Type	Required	Description
`initiative`	string	Yes	Initiative ID
`plan`	string	No	Path to existing plan file
`create`	boolean	No	Create a new plan template

Memory Operations

mem_init

Initialize memory layer for a Work Unit.

Input:

Parameter	Type	Required	Description
`wu`	string	Yes	WU ID to initialize memory for

mem_start

Start a memory session for a Work Unit.

Input:

Parameter	Type	Required	Description
`wu`	string	Yes	WU ID to start session for
`lane`	string	No	Lane name

mem_ready

Check pending memory nodes for a Work Unit.

Input:

Parameter	Type	Required	Description
`wu`	string	Yes	WU ID to check

mem_checkpoint

Save a progress checkpoint for a Work Unit.

Input:

Parameter	Type	Required	Description
`wu`	string	Yes	WU ID to checkpoint
`message`	string	No	Checkpoint message

mem_cleanup

Clean up stale memory data.

Input:

Parameter	Type	Required	Description
`dry_run`	boolean	No	Preview cleanup without making changes

mem_context

Get memory context for a Work Unit, optionally filtered by lane.

Input:

Parameter	Type	Required	Description
`wu`	string	Yes	WU ID to get context for
`lane`	string	No	Filter by lane

mem_create

Create a memory node (e.g., for bug discovery).

Input:

Parameter	Type	Required	Description
`message`	string	Yes	Memory node message
`wu`	string	Yes	WU ID to associate with
`type`	string	No	Node type (e.g., “discovery”)
`tags`	string[]	No	Tags for the node

mem_delete

Delete or archive a memory node.

Input:

Parameter	Type	Required	Description
`id`	string	Yes	Memory node ID to delete

mem_export

Export memory for a Work Unit as markdown or JSON.

Input:

Parameter	Type	Required	Description
`wu`	string	Yes	WU ID to export
`format`	string	No	Export format (markdown, json)

mem_inbox

Check coordination signals from other agents.

Input:

Parameter	Type	Required	Description
`since`	string	No	Time filter (e.g., “30m”, “1h”)
`wu`	string	No	Filter by WU ID
`lane`	string	No	Filter by lane

mem_signal

Broadcast a coordination signal to other agents.

Input:

Parameter	Type	Required	Description
`message`	string	Yes	Signal message
`wu`	string	Yes	WU ID to associate with

mem_summarize

Summarize memory context for a Work Unit.

Input:

Parameter	Type	Required	Description
`wu`	string	Yes	WU ID to summarize

mem_triage

Triage discovered issues and bugs for a Work Unit.

Input:

Parameter	Type	Required	Description
`wu`	string	Yes	WU ID to triage

mem_recover

Generate post-compaction recovery context for a Work Unit.

Input:

Parameter	Type	Required	Description
`wu`	string	Yes	WU ID to recover context for
`max_size`	number	No	Maximum output size in bytes
`format`	string	No	Output format (`json` or `human`)
`quiet`	boolean	No	Suppress header/footer output
`base_dir`	string	No	Base directory override

Agent Operations

agent_session

Start an agent session for tracking WU execution.

Input:

Parameter	Type	Required	Description
`wu`	string	Yes	WU ID to work on (e.g., WU-1234)
`tier`	number	Yes	Context tier (1, 2, or 3)
`agent_type`	string	No	Agent type (e.g. claude-code, codex-cli, gemini-cli)

agent_session_end

End the current agent session and return summary.

Input: None

agent_log_issue

Log a workflow issue or incident during agent execution.

Input:

Parameter	Type	Required	Description
`category`	string	Yes	Issue category (workflow, tooling, confusion, violation, error)
`severity`	string	Yes	Severity level (blocker, major, minor, info)
`title`	string	Yes	Short description (5-100 chars)
`description`	string	Yes	Detailed context (10-2000 chars)
`resolution`	string	No	How the issue was resolved
`tags`	string[]	No	Tags for categorization
`step`	string	No	Current workflow step (e.g., wu:done, gates)
`files`	string[]	No	Related file paths

agent_issues_query

Query and display logged agent incidents/issues summary.

Input:

Parameter	Type	Required	Description
`since`	number	No	Days to include (default: 7)
`category`	string	No	Filter by category
`severity`	string	No	Filter by severity (blocker, major, minor, trivial)

Orchestration Operations

orchestrate_initiative

Orchestrate initiative execution with parallel agent spawning.

Input:

Parameter	Type	Required	Description
`initiative`	string	Yes	Initiative ID to orchestrate (e.g., INIT-001)
`dry_run`	boolean	No	Show execution plan without spawning agents
`progress`	boolean	No	Show current progress only
`checkpoint_per_wave`	boolean	No	Spawn next wave then exit (no polling)

orchestrate_init_status

Show compact initiative progress status including WUs and lane availability.

Input:

Parameter	Type	Required	Description
`initiative`	string	Yes	Initiative ID (e.g., INIT-001)

orchestrate_monitor

Monitor delegated agent progress and delegation health (stuck detection, zombie locks).

Input:

Parameter	Type	Required	Description
`threshold`	number	No	Stuck detection threshold in minutes (default: 30)
`recover`	boolean	No	Run recovery actions for stuck spawns
`dry_run`	boolean	No	Show what would be done without action
`since`	string	No	Show signals since (e.g., 30m, 1h)
`wu`	string	No	Filter by WU ID
`signals_only`	boolean	No	Only show signals (skip spawn analysis)

Delegation Operations

delegation_list

Display delegation trees for WUs or initiatives.

Input:

Parameter	Type	Required	Description
`wu`	string	No	WU ID to show delegations for (e.g., WU-1234)
`initiative`	string	No	Initiative ID to show all delegations for
`json`	boolean	No	Output as JSON

Flow/Metrics Operations

flow_bottlenecks

Identify flow bottlenecks in the workflow (WIP violations, stuck WUs, etc.).

Input:

Parameter	Type	Required	Description
`json`	boolean	No	Output as JSON

flow_report

Generate flow metrics report with cycle time, throughput, and other DORA metrics.

Input:

Parameter	Type	Required	Description
`since`	string	No	Start date or duration (e.g., “7d”, “2025-01-01”)
`until`	string	No	End date (e.g., “now”, “2025-01-31”)
`json`	boolean	No	Output as JSON

metrics_snapshot

Capture a snapshot of current LumenFlow metrics.

Input:

Parameter	Type	Required	Description
`json`	boolean	No	Output as JSON

Validation Operations

validate

Validate WU YAML files and status consistency.

Input:

Parameter	Type	Required	Description
`id`	string	No	Specific WU ID to validate
`strict`	boolean	No	Fail on warnings too
`done_only`	boolean	No	Only validate done WUs

validate_agent_skills

Validate agent skill definitions in .claude/skills/.

Input:

Parameter	Type	Required	Description
`skill`	string	No	Specific skill to validate (e.g., “wu-lifecycle”)

validate_agent_sync

Validate agent synchronization state.

Input: None

validate_backlog_sync

Validate backlog synchronization between WU YAMLs and backlog.md.

Input: None

validate_skills_spec

Validate skills specification files.

Input: None

Setup Operations

lumenflow_init

Initialize LumenFlow workflow framework in a project.

Input:

Parameter	Type	Required	Description
`client`	string	No	Client type (claude, cursor, windsurf, all)
`merge`	boolean	No	Merge into existing files using bounded markers

lumenflow_doctor

Diagnose LumenFlow configuration and safety components.

Input: None

lumenflow_integrate

Generate enforcement hooks for a specific client.

Input:

Parameter	Type	Required	Description
`client`	string	Yes	Target client (e.g. claude-code, codex-cli, cursor, gemini-cli)

lumenflow_upgrade

Upgrade LumenFlow packages to latest versions.

Input: None

lumenflow_commands

List all available LumenFlow CLI commands.

Input: None

lumenflow_docs_sync

Sync agent documentation after upgrading LumenFlow packages.

Input: None

lumenflow_release

Run LumenFlow release workflow (versioning, npm publish).

Input:

Parameter	Type	Required	Description
`dry_run`	boolean	No	Preview release without publishing

lumenflow_sync_templates

Sync LumenFlow templates to the project.

Input: None

Runtime Task Tools

These 7 tools are available when the kernel runtime is active. They are part of the runtimeTaskTools registry and are additive to the core allTools set.

Tool	Description
`task_claim`	Claim a task for execution
`task_create`	Create a new task
`task_complete`	Mark a task as completed
`task_block`	Block a task
`task_unblock`	Unblock a task
`task_inspect`	Inspect task state
`task_tool_execute`	Execute a tool within a task context

Resources

The MCP server exposes 3 resources for reading LumenFlow data:

lumenflow://context

Type: Static resource

Current LumenFlow context including location, git state, and active WU.

{
  "uri": "lumenflow://context",
  "mimeType": "application/json"
}

`lumenflow://wu/{id}`

Type: Resource template

Work Unit specification by ID. Replace {id} with the WU ID.

{
  "uriTemplate": "lumenflow://wu/{id}",
  "mimeType": "application/json"
}

Example: lumenflow://wu/WU-1427

lumenflow://backlog

Type: Static resource

Current LumenFlow backlog with all WUs grouped by status.

{
  "uri": "lumenflow://backlog",
  "mimeType": "text/markdown"
}

Client Configuration

Claude Code

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "lumenflow": {
      "command": "npx",
      "args": ["@lumenflow/mcp"],
      "env": {
        "LUMENFLOW_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "lumenflow": {
      "command": "npx",
      "args": ["@lumenflow/mcp"]
    }
  }
}

Generic MCP Client

import { createMcpServer } from '@lumenflow/mcp';

const server = createMcpServer({
  projectRoot: '/path/to/project',
  logLevel: 'info',
});

await server.start();

Programmatic Usage

The MCP package exports tools and resources for direct use:

import {
  createMcpServer,
  allTools,
  allResources,
  contextGetTool,
  wuListTool,
} from '@lumenflow/mcp';

// List available tools
const tools = allTools.map((t) => ({ name: t.name, description: t.description }));

// Execute a tool directly
const result = await contextGetTool.execute({}, { projectRoot: process.cwd() });

Error Handling

All tools return a consistent result structure:

interface ToolResult {
  success: boolean;
  data?: unknown;
  error?: {
    message: string;
    code?: string;
  };
}

Error Codes

Code	Description
`MISSING_PARAMETER`	Required parameter not provided
`CONTEXT_ERROR`	Failed to compute LumenFlow context
`WU_LIST_ERROR`	Failed to list WUs
`WU_STATUS_ERROR`	Failed to get WU status
`WU_CREATE_ERROR`	Failed to create WU
`WU_CLAIM_ERROR`	Failed to claim WU
`WU_DONE_ERROR`	Failed to complete WU
`WRONG_LOCATION`	Operation called from wrong location
`GATES_ERROR`	Gates failed
`WU_BLOCK_ERROR`	Failed to block WU
`WU_UNBLOCK_ERROR`	Failed to unblock WU
`WU_EDIT_ERROR`	Failed to edit WU
`WU_RELEASE_ERROR`	Failed to release WU
`WU_RECOVER_ERROR`	Failed to recover WU
`WU_REPAIR_ERROR`	Failed to repair WU
`WU_DEPS_ERROR`	Failed to get WU dependencies
`WU_PREP_ERROR`	Failed to prep WU
`WU_PREFLIGHT_ERROR`	Failed to preflight WU
`WU_PRUNE_ERROR`	Failed to prune worktrees
`WU_DELETE_ERROR`	Failed to delete WU
`WU_CLEANUP_ERROR`	Failed to cleanup WU
`WU_DELEGATE_ERROR`	Failed to delegate WU
`WU_VALIDATE_ERROR`	Failed to validate WU
`WU_INFER_LANE_ERROR`	Failed to infer lane
`WU_UNLOCK_LANE_ERROR`	Failed to unlock lane
`INITIATIVE_LIST_ERROR`	Failed to list initiatives
`INITIATIVE_STATUS_ERROR`	Failed to get initiative status
`INITIATIVE_CREATE_ERROR`	Failed to create initiative
`INITIATIVE_EDIT_ERROR`	Failed to edit initiative
`INITIATIVE_ADD_WU_ERROR`	Failed to add WU to initiative
`INITIATIVE_REMOVE_WU_ERROR`	Failed to remove WU from initiative
`INITIATIVE_BULK_ASSIGN_ERROR`	Failed to bulk assign WUs
`INITIATIVE_PLAN_ERROR`	Failed to link plan
`MEM_INIT_ERROR`	Failed to initialize memory
`MEM_START_ERROR`	Failed to start session
`MEM_READY_ERROR`	Failed to check ready nodes
`MEM_CHECKPOINT_ERROR`	Failed to save checkpoint
`MEM_CLEANUP_ERROR`	Failed to cleanup memory
`MEM_CONTEXT_ERROR`	Failed to get memory context
`MEM_CREATE_ERROR`	Failed to create memory node
`MEM_DELETE_ERROR`	Failed to delete memory node
`MEM_EXPORT_ERROR`	Failed to export memory
`MEM_INBOX_ERROR`	Failed to check inbox
`MEM_SIGNAL_ERROR`	Failed to send signal
`MEM_SUMMARIZE_ERROR`	Failed to summarize memory
`MEM_TRIAGE_ERROR`	Failed to triage issues
`MEM_RECOVER_ERROR`	Failed to recover memory context
`AGENT_SESSION_ERROR`	Failed to start agent session
`AGENT_SESSION_END_ERROR`	Failed to end agent session
`AGENT_LOG_ISSUE_ERROR`	Failed to log issue
`AGENT_ISSUES_QUERY_ERROR`	Failed to query issues
`ORCHESTRATE_INITIATIVE_ERROR`	Failed to orchestrate initiative
`ORCHESTRATE_INIT_STATUS_ERROR`	Failed to get initiative status
`ORCHESTRATE_MONITOR_ERROR`	Failed to monitor delegations
`DELEGATION_LIST_ERROR`	Failed to list delegations
`FLOW_BOTTLENECKS_ERROR`	Failed to analyze bottlenecks
`FLOW_REPORT_ERROR`	Failed to generate flow report
`METRICS_SNAPSHOT_ERROR`	Failed to capture metrics
`VALIDATE_ERROR`	Validation failed
`VALIDATE_AGENT_SKILLS_ERROR`	Failed to validate skills
`VALIDATE_AGENT_SYNC_ERROR`	Failed to validate agent sync
`VALIDATE_BACKLOG_SYNC_ERROR`	Failed to validate backlog sync
`VALIDATE_SKILLS_SPEC_ERROR`	Failed to validate skills spec
`LUMENFLOW_INIT_ERROR`	Failed to initialize LumenFlow
`LUMENFLOW_DOCTOR_ERROR`	Doctor found issues
`LUMENFLOW_INTEGRATE_ERROR`	Failed to integrate hooks
`LUMENFLOW_UPGRADE_ERROR`	Failed to upgrade
`LUMENFLOW_COMMANDS_ERROR`	Failed to list commands
`LUMENFLOW_DOCS_SYNC_ERROR`	Failed to sync docs
`LUMENFLOW_RELEASE_ERROR`	Failed to run release
`LUMENFLOW_SYNC_TEMPLATES_ERROR`	Failed to sync templates

Architecture

The MCP server uses a pack dispatch architecture: tools are executed through the kernel runtime, not by shelling out to CLI commands.

AI Client (Claude, Cursor, etc.)
    │
    ▼
MCP Server (@lumenflow/mcp)
    │
    ├─ runtimeFactory() → initializes KernelRuntime
    │   └─ loads workspace.yaml → resolves pack pins → loads pack manifests
    │
    └─ executeViaPack(toolName, input, context)
        │
        ▼
    KernelRuntime.executeTool()
        │
        ├─ 1. Tool lookup (pack manifest)
        ├─ 2. Scope intersection (workspace ∩ lane ∩ task ∩ tool)
        ├─ 3. Reserved path check (.lumenflow/**)
        ├─ 4. Input persistence (SHA-256 content-addressed)
        ├─ 5. Policy evaluation (deny-wins cascade)
        ├─ 6. Input validation (Zod schema)
        ├─ 7. Tool dispatch (in-process or subprocess/bwrap)
        └─ 8. Evidence recording (append-only JSONL)

Every MCP tool call passes through the kernel’s full execution pipeline, including scope intersection, policy evaluation, and evidence recording. This means MCP tools receive the same security guarantees as direct kernel API calls.

Execution Flow

runtimeFactory() — Creates a KernelRuntime instance for the workspace, loading the workspace spec and resolving all pack pins
executeViaPack() — Routes the MCP tool call to the kernel’s executeTool() method with the appropriate execution context
Kernel pipeline — The tool passes through scope, policy, validation, and dispatch stages (see Kernel Runtime for details)
Evidence — Success or denial is recorded in the evidence store — the audit trail has no gaps

Next Steps

CLI Commands — Full CLI command reference
Workspace Spec — Kernel-level workspace.yaml reference
Kernel Runtime — How tool calls are authorized and executed
Packs — Domain pack architecture (the Software Delivery Pack)
Evidence Store — How tool call evidence is recorded