@thecfguy/flowforge-mcp-server

Global MCP (Model Context Protocol) server for FlowForge SDLC agent orchestration.

Agents running inside Claude Code, OpenCode, or any MCP-compatible IDE call this server's tools to resolve skill files, report pipeline progress, check quality gates, and query run state — all persisted to disk so any agent in any phase can read what previous phases produced.

Installation

# Global install (recommended for shared use)
npm install -g @thecfguy/flowforge-mcp-server

# Or run directly with npx
npx @thecfguy/flowforge-mcp-server

Adding to your AI IDE

Claude Code

flowforge init writes this automatically to .claude/settings.json:

{
  "mcpServers": {
    "flowforge": {
      "command": "npx",
      "args": ["-y", "@thecfguy/flowforge-mcp-server"],
      "env": {}
    }
  }
}

Or add it from the CLI:

claude mcp add flowforge -- npx -y @thecfguy/flowforge-mcp-server

OpenCode

opencode mcp add flowforge -- npx -y @thecfguy/flowforge-mcp-server

Manual (stdio transport)

flowforge-mcp

The server reads from stdin and writes to stdout using the MCP JSON-RPC protocol.

Tools

list_skills

Resolve skill files for all phases in the project. Call this at the start of every /orchestrator invocation — before initialize_project — to get the per-phase skill map.

Resolution order per phase:

1. Explicit — skillFile field set in .agent.yaml → returns that path
2. Convention — ./skills/{phase}/SKILL.md exists in project → returns that path
3. Built-in — no file found → returns null (orchestrator uses embedded fallback instructions)

If an explicit skillFile is configured but the file does not exist, this tool returns an error. Silent fallthrough is not allowed for explicit paths.

Input:

| Field | Type | Required | Description | |---|---|---|---| | projectDir | string | ✓ | Absolute path to the project root (directory containing .agent.yaml) |

Output:

{
  "phases": [
    { "phase": "plan",    "resolution": "built-in",  "skillFile": null },
    { "phase": "develop", "resolution": "convention", "skillFile": "/abs/path/skills/develop/SKILL.md" },
    { "phase": "review",  "resolution": "explicit",   "skillFile": "/abs/path/.claude/commands/review.md" }
  ],
  "projectDir": "/abs/path/to/project"
}

resolution values: "explicit" | "convention" | "built-in"

initialize_project

Register a project and start a new pipeline run. Call this once at the start of every /orchestrator invocation. Returns the runId used by all subsequent tools.

Input:

| Field | Type | Required | Description | |---|---|---|---| | projectId | string | ✓ | Unique project identifier (e.g. repo name) | | name | string | ✓ | Human-readable project name | | taskDescription | string | ✓ | The task being implemented | | stack | string[] | — | Tech stack tags | | skills | string[] | — | SDLC phases to run (default: all 5) |

Output: { runId: string, projectId: string, message: string }

report_stage

Report a stage status update. Call with "running" when a phase agent starts, then "complete" or "failed" when it finishes.

Input:

| Field | Type | Required | Description | |---|---|---|---| | runId | string | ✓ | From initialize_project | | stage | SdlcPhase | ✓ | plan, develop, test, review, docs, etc. | | status | StageStatus | ✓ | running, complete, or failed | | output | object | — | Stage output data (see required fields below) | | error | string | — | Error message if status is "failed" |

Required output fields per phase (checked by gate_check):

| Phase | Required fields | |---|---| | plan | impact_score (0–10), plan (string), affected_files (string[]) | | develop | files_changed (string[]) | | test | all_tests_passed (boolean), tests_passed (number), tests_failed (number) | | review | quality_score (0–10), issues (string[]), approved (boolean) | | docs | changelog_updated (boolean), docs_updated (string[]) |

Output: { ok: true, runId, stage, status }

gate_check

Check whether a gate condition is satisfied based on the stage's stored output. The orchestrator calls this after plan (impact gate) and after review (quality gate).

Input:

| Field | Type | Required | Description | |---|---|---|---| | runId | string | ✓ | From initialize_project | | stage | SdlcPhase | ✓ | Stage to check gate for | | criteria | object | ✓ | Gate conditions (see below) |

Criteria fields:

| Field | Applies to | Description | |---|---|---| | impact_score_max | plan | Gate fails if impact_score > this value | | quality_score_min | review | Gate fails if quality_score < this value | | tests_pass | test | Gate fails if all_tests_passed !== true |

Output: { pass: boolean, reason: string }

get_progress

Retrieve the complete state of a pipeline run, including all stage entries and their outputs.

Input: { runId: string }

Output: Full PipelineRun object:

{
  "runId": "abc-123",
  "projectId": "my-project",
  "taskDescription": "add JWT auth",
  "createdAt": "2026-05-14T12:00:00Z",
  "updatedAt": "2026-05-14T12:05:00Z",
  "stages": [
    {
      "stage": "plan",
      "status": "complete",
      "startedAt": "2026-05-14T12:00:05Z",
      "completedAt": "2026-05-14T12:01:00Z",
      "retryCount": 0,
      "output": { "impact_score": 4, "plan": "...", "affected_files": ["src/auth.ts"] }
    }
  ]
}

update_project

Merge metadata into a project's registry entry. Used by the Docs Agent to record the last completed run.

Input:

| Field | Type | Required | Description | |---|---|---|---| | projectId | string | ✓ | Project identifier | | metadata | object | ✓ | Key-value pairs to merge |

Output: { ok: true, projectId }

Orchestrator startup sequence

The orchestrator calls tools in this order at the start of every pipeline run:

1. list_skills({ projectDir: "<absolute cwd>" })
   → stores per-phase skill map (skillFile path or null for built-in)

2. initialize_project({ projectId, name, taskDescription, skills })
   → stores runId

3. For each phase:
   a. Read skill file if non-null (or use built-in instructions)
   b. Spawn subagent with wrapped prompt (runId + contract + instructions)
   c. report_stage(runId, phase, "running") at phase start
   d. report_stage(runId, phase, "complete", output) at phase end
   e. gate_check(...) if applicable

4. get_progress({ runId }) → final summary

Data persistence

The server writes JSON files to .flowforge/ in the current working directory:

.flowforge/
├── runs.json       ← all pipeline runs keyed by runId
└── projects.json   ← all registered projects keyed by projectId

These files are created automatically on first write. Add .flowforge/ to .gitignore if you don't want run history committed.

License

MIT