mcp-flow

A safe, local MCP server that lets Claude (or any MCP client) drive a controlled software-development loop on a project on your machine:

inspect → read → plan → patch → apply → check → analyze → fix-loop → summarize

The goal is simple: after every model turn, the code stays understandable, tested, reviewed, and corrected — through real diffs, real test/lint/typecheck runs, and an iterative fix loop, all behind hard safety rails.

• SDK: @modelcontextprotocol/sdk ^1.29.0

• Runtime: Node.js ≥ 18 (developed and tested on Node 22)

• Language: TypeScript (strict), ESM

• Transport: stdio (works with Claude Desktop, Cursor, and any standard MCP client)

1. What it does

mcp-flow exposes 10 tools:

How the "thinking" tools work (important)

An MCP server is not a language model. So mcp-flow is deliberately honest about the split of work:

• Deterministic tools do real work locally: scan the filesystem, build and apply diffs, run checks, parse errors, read git. These never need an LLM.

• create_change_plan, generate_patch (brief mode), analyze_check_failures, summarize_changes assemble precise, structured context and hand the reasoning back to the calling model (Claude). They never fabricate code from a non-existent embedded model.

• generate_patch becomes fully deterministic the moment you give it edits: it converts your intended changes into a clean unified diff that apply_patch is guaranteed to accept.

• fix_loop runs the deterministic verify/analyze cycle. If the connected client supports the optional MCP sampling capability (sampling/createMessage), it asks the client's own model for corrective edits and applies them automatically. If the client does not support sampling (some desktop clients don't), fix_loop returns a precise advisory with the next actions, and the orchestrating assistant drives the loop by calling the other tools — which Claude does naturally.

This design means the server is safe, deterministic where it matters, and never lies about having capabilities it doesn't.

Related MCP server: SafeFlo

2. What it does not do

• It does not run arbitrary shell commands. Only an allowlist of base executables (npm/pnpm/yarn/bun/npx/node, tsc/vitest/jest/eslint/biome/prettier, python/pytest/ruff/mypy, git) can ever be spawned, with shell: false.

• It does not touch anything outside the projectPath you give it.

• It does not run destructive commands (rm -rf, sudo, chmod -R, curl | bash, git push --force, git reset --hard, fork bombs, …).

• It does not read .env and other sensitive files unless you explicitly pass allowSensitive: true.

• It does not apply patches by default — apply_patch is dry-run unless you set dryRun: false.

• It does not embed or call any external LLM on its own.

3. Install

git clone <your-fork-or-path> "mcp flow"
cd "mcp flow"
npm install

4. Build

npm run build       # compiles src/ -> dist/ with tsc
npm run typecheck   # tsc --noEmit (strict)
npm test            # vitest run (unit tests)

Quick manual run (it speaks MCP over stdio and waits for a client):

npm start           # node dist/index.js
# or, without building, for development:
npm run dev         # tsx src/index.ts

5. Add it to Claude Desktop

Build first (npm run build), then edit your Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add an entry (see claude_desktop_config.example.json):

{
  "mcpServers": {
    "mcp-flow": {
      "command": "node",
      "args": ["/absolute/path/to/mcp flow/dist/index.js"]
    }
  }
}

Restart Claude Desktop. You should see the mcp-flow tools appear.

Cursor / other MCP clients

Any client that supports stdio MCP servers works. Point it at node /absolute/path/to/mcp flow/dist/index.js. Clients that implement the sampling capability unlock fully-autonomous fix_loop; others use it in advisory mode.

6. Example prompts

Once connected, talk to Claude normally — it will pick the right tools:

• “Analyse ce projet et dis-moi comment il est structuré.” → inspect_project

• “Ajoute une route API pour créer un utilisateur, puis lance les tests.” → create_change_plan → read_relevant_files → generate_patch → apply_patch → run_project_checks

• “Corrige les erreurs TypeScript jusqu’à ce que le typecheck passe.” → run_project_checks (typecheck) → analyze_check_failures → fix_loop

• “Implémente cette fonctionnalité, applique le patch, lance lint et tests, puis résume les changements.” → full chain ending in summarize_changes

• “Fais une revue du diff actuel et propose un patch correctif.” → git_status → analyze_check_failures → generate_patch

A typical safe sequence Claude follows:

inspect_project(projectPath)
read_relevant_files(projectPath, taskDescription)
create_change_plan(projectPath, taskDescription)
generate_patch(projectPath, taskDescription, edits=[…])   # real unified diff
apply_patch(projectPath, patch, dryRun=true)               # validate
apply_patch(projectPath, patch, dryRun=false)              # apply + backup
run_project_checks(projectPath, checks=["test","lint","typecheck"])
analyze_check_failures(projectPath, checkResults=…)        # if anything failed
# …iterate generate_patch/apply_patch until green…
summarize_changes(projectPath, checkResults=…)

7. Security rules (enforced in code)

All of these live in src/core/security.ts and are covered by tests in tests/security.test.ts:

• Path confinement: every path is normalized and must resolve inside projectPath. Traversal (../…), absolute escapes, and symlink escapes are rejected with a clear error.

• Command allowlist: only known base executables run; everything else is refused. Commands run with shell: false (no interpolation), and arguments containing shell metacharacters (; & | \ $ > <` …) are rejected.

• Dangerous-command blocklist: rm -rf, sudo, recursive chmod/chown, mkfs, dd if=, curl|bash, force-push, hard-reset, fork bombs, etc.

• Mass-deletion guard: a patch that removes a huge number of lines while adding none, or deletes many files at once, is refused.

• Backups: apply_patch copies every touched file into .mcp-flow-backups/<timestamp>/ before writing (unless createBackup:false).

• Sensitive files: .env, keys, credentials, secrets.* are skipped unless allowSensitive:true. .env.example/.sample/.template are allowed.

• Secret masking: output is scrubbed for KEY=… secrets, provider tokens (sk-…, ghp_…, AWS AKIA…, Google AIza…), JWTs, and PEM private keys.

• Bounded everything: per-file read size, aggregate read budget, per-stream output size, and per-command timeout are all capped.

• No crashes: every tool catches its errors and returns a clean error result instead of taking the server down.

8. Known limitations

• Reasoning lives in the client. mcp-flow structures and validates work; it does not invent code by itself. Patch quality depends on the model driving it.

• Autonomous fix_loop requires client sampling support. Without it, the loop runs deterministically and returns precise next actions for the assistant to execute. (Claude follows these naturally.)

• Check detection is heuristic. It covers common Node and Python setups well; Rust/Go/PHP are detected but only get a build/test mapping where obvious. You can always pass an explicit packageManager or checks list.

• apply_patch uses exact-context matching. If a file changed since the diff was generated, application fails with a clear message rather than guessing.

• Patches are content-based, not git-blob-based: renames are modeled as delete + create.

9. Roadmap

• Optional outputSchema / structuredContent for clients that prefer it.

• Resource endpoints (expose the scan / last diff as MCP resources).

• Smarter relevance ranking (symbol/import graph instead of lexical only).

• Configurable allowlist and limits via env vars.

• Rename/move detection in generate_patch.

• Pluggable check adapters for more ecosystems (Rust cargo, Go go test, etc.).

Project layout

src/
  index.ts                 # MCP entrypoint: registers all 11 tools over stdio
  types.ts                 # shared result/structure types
  core/
    security.ts            # path confinement, allowlist, masking, limits
    walk.ts                # bounded, ignore-aware directory walking
    projectScanner.ts      # stack / pm / scripts / tests / config detection
    fileReader.ts          # task-aware, bounded, masked file reading
    patchManager.ts        # unified-diff build + safe apply (backups, guards)
    commandRunner.ts       # safe spawn (no shell, timeout, bounded output)
    checkDetector.ts       # map test/lint/typecheck/build -> concrete commands
    failureAnalyzer.ts     # parse tsc/eslint/ruff/mypy/pytest output
    git.ts                 # read-only git status & diff
    sampling.ts            # optional MCP sampling for autonomous fix_loop
    toolResult.ts          # uniform ok()/fail() result helpers
  tools/                   # one file per tool, each exports register<Tool>()
tests/                     # vitest unit tests (+ helpers)

License

MIT