@nikheal/devstate-mcp

DevState MCP Server — gives Claude, Cursor, Windsurf, and any Model Context Protocol-capable AI assistant portable, persistent project context.

Every new AI chat starts from zero. This server lets an assistant read your project's compiled context and write decisions back as it works — so the next tool, or the next session, continues exactly where you left off.

Use via npx (recommended)

No installation needed. Configure your MCP client to run:

npx @nikheal/devstate-mcp

The server speaks JSON-RPC over stdio. It resolves the workspace from its working directory or the DEVSTATE_WORKSPACE environment variable.

Tools

| Tool | Purpose | |---|---| | resume_work | Recover everything needed to continue development in ONE call — project frame, active session + full progress trail, and active decisions. Call this first when resuming (after a usage limit, in a new chat, or when switching AI tools). | | get_context | Compiled briefing: how to run/test, current focus, working state, architecture, recent decisions. Call at the start of every task. | | get_active_session | The current session intent, if any. | | list_decisions | All recorded decisions and their rationale. | | record_decision | Record an architectural decision and WHY (author = ai). | | supersede_decision | Mark a decision obsolete and record its replacement. | | remove_decision | Soft-delete a decision (kept in history, never surfaced to AI). | | update_brief | Replace the project brief (architecture / conventions / constraints). | | log_progress | Checkpoint where work stopped — resume marker for the next session. | | sync_agent_files | Regenerate AGENTS.md / CLAUDE.md on demand. | | initialize_workspace | Bootstrap a DevState workspace in the project. |

get_context accepts:

• tokenBudget (number) — max tokens to include in the briefing
• format (markdown | compact | json) — output format

resume_work — one-call continuity

Purpose. resume_work is the flagship continuity tool. It aggregates the data that today requires several separate calls (get_context + get_active_session + list_decisions) into a single, resume-shaped briefing — so an assistant coming into a project cold (a fresh chat, a new tool, after a usage limit) recovers everything it needs to continue in one call. It takes no arguments and adds no new data — it is a read-only aggregation over existing DevState memory.

What it returns (concise, LLM-oriented markdown; empty sections are omitted, never fabricated):

• Project — name, stack, and architecture/conventions (from the project brief).
• Current Work — the active session and its intent, the full progress trail (every log_progress note, most recent first — get_context shows only the latest), and the current working state (branch, changed files).
• Recent Decisions — the active decisions and their rationale (the current "why" and constraints).

Fields DevState does not store — next step, blockers, open questions, suggested files — are intentionally omitted rather than invented.

Intended AI workflow. Call resume_work first whenever you begin or continue work on a project. Read the Current Work section to see where the previous session stopped and what was in flight; read Recent Decisions before changing behavior so you do not re-litigate a settled choice; use Project for the durable frame. For a deeper or token-budgeted briefing, follow up with get_context; to record where you stop, call log_progress.

Configure Your Client

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "devstate": {
      "command": "npx",
      "args": ["@nikheal/devstate-mcp"],
      "env": {
        "DEVSTATE_WORKSPACE": "/absolute/path/to/your/project"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project or the global Cursor MCP config:

{
  "mcpServers": {
    "devstate": {
      "command": "npx",
      "args": ["@nikheal/devstate-mcp"],
      "env": {
        "DEVSTATE_WORKSPACE": "/absolute/path/to/your/project"
      }
    }
  }
}

Claude Code (one-liner)

claude mcp add devstate -- npx @nikheal/devstate-mcp

Environment Variable

| Variable | Description | |---|---| | DEVSTATE_WORKSPACE | Absolute path to the project root containing your .devstate/ workspace. If omitted, the server uses its current working directory. |

Full Documentation

See the main README for the complete guide including CLI usage, decision management, session/checkpoint workflows, and team setup.

License

MIT © 2025 Nikhil Patel