@isdlc/mcp

Model Context Protocol server for the Shefing iSDLC methodology. It exposes the iSDLC project state — stage, entry door, quirks, active plan, doctor results — and a small set of guarded write helpers (ADRs, tech-debt rows, STATE.md sync, legacy graduation) so AI agents like Claude Code, Junie, and Cursor can query and update an iSDLC repo natively, without hand-rolled file parsing.

The MCP server is a thin transport over @isdlc/cli — the CLI is the real API, MCP is just JSON-RPC stdio on top of it.

See the top-level USER_GUIDE.md and TOOLING.md for context.

Install

npm i -g @isdlc/mcp
# or run on demand:
npx -y @isdlc/mcp

The binary is isdlc-mcp. It speaks newline-delimited JSON-RPC 2.0 on stdin/stdout and implements MCP protocol version 2024-11-05.

Wire it into your AI client

Claude Code / Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your OS:

{
  "mcpServers": {
    "isdlc": {
      "command": "npx",
      "args": ["-y", "@isdlc/mcp"]
    }
  }
}

Cursor / generic MCP client

Point any MCP-aware client at the isdlc-mcp command. No flags, no env vars required — the server uses the current working directory as the project root by default, and every tool accepts an explicit path argument to override it.

Tools

All tools accept an optional path (project root; defaults to the server CWD).

Read-only

| Tool | Purpose | |---|---| | isdlc_getStage | Current iSDLC stage, entry door, active plan, and Session Continuity summary parsed from STATE.md. | | isdlc_getEntryDoor | Whether the project entered via the New (greenfield) or Existing (Legacy Onboarding) door, and — if existing — which Legacy step is current. | | isdlc_getQuirks | Entries from QUIRKS.md (the Bug-as-Feature register). Agents must consult this before modifying legacy code. | | isdlc_getPlan | The active plan under plans/ (or all plans when which: "all"). | | isdlc_runDoctor | Runs isdlc doctor --json and returns the structured check results. |

Write (delegates to @isdlc/cli)

| Tool | Purpose | |---|---| | isdlc_recordADR | Create a new ADR (isdlc adr new <title>). Returns the created path under docs/adr/. | | isdlc_logTechDebt | Append a TD-NNN row to TECH_DEBT.md (isdlc debt add). Fails loudly if TECH_DEBT.md is missing (AGENTS.md Rule 6). | | isdlc_updateState | Prefill STATE.md from git log + ADRs + active plan (isdlc state sync). Leaves Human confirmation required? Yes unless confirm: true is explicitly passed. | | isdlc_graduate | Run Legacy Onboarding Step 7 graduation (isdlc graduate). Refuses unless every Legacy step is confirmed/skipped; pass force: true to emit a DRAFT. |

Failed writes are returned as structured MCP tool errors (isError: true) — agents cannot silently succeed on a failed mutation.

Deliberation-preserving guardrails

The MCP server inherits the iSDLC methodology's human-in-the-loop invariants:

• isdlc_updateState will never flip the Session Continuity confirmation flag unless an explicit confirm: true arrives in the call. Agents must not set that on behalf of the human.
• isdlc_graduate will never bypass missing Legacy confirmations unless force: true is passed — and even then it produces a DRAFT, not a final report.
• All write tools shell out to @isdlc/cli, which enforces the same invariants the human-driven CLI does.

Dev

npm install                        # from monorepo root
npm -w @isdlc/mcp run build
node packages/mcp/bin/isdlc-mcp.js  # speaks JSON-RPC on stdio
npm -w @isdlc/mcp test

License

Apache-2.0