Decision State MCP

Decision State is a small MCP server for keeping project decisions outside the chat context while still making them easy for Claude Code or Codex to retrieve.

It is intentionally not a planner or executor. It only stores compact, decision-relevant state: goals, constraints, facts, assumptions, risks, decisions, and reflections.

Tools

• get_state: return the current state summary and record counts.
• update_state: apply a JSON merge patch to .claude-state/state.json.
• record_evidence: save normalized evidence sources, findings, limitations, and confidence.
• record_decision: save a structured decision under .claude-state/decisions/.
• get_task_context: return compact state and matching prior records for a task.
• search_state: search prior decisions, evidence, reflections, and sessions.
• get_session: return the active decision session.
• reflect_outcome: record what happened after a decision or implementation.

Local Use

Install dependencies:

npm install

Run the server over stdio:

npm start -- --state-dir .claude-state

The default state directory is .claude-state relative to the process working directory. You can also set DECISION_STATE_DIR.

Claude Code MCP

From a project where you want the state to live:

claude mcp add --transport stdio decision-state -- node C:\Users\ZCX\Documents\mcp-state\server\index.js --state-dir .claude-state

State Layout

.claude-state/
  state.json
  decisions/
  evidence/
  sessions/
  briefs/
  reflections/
  updates/

Keep this state compact. Do not store raw conversation dumps, private secrets, or full source files.

Evidence Shape

Evidence is normalized into a compact structure inspired by Spice:

{
  "summary": "Why this evidence matters",
  "sources": [
    {
      "source_id": "file:src/auth.ts",
      "source_type": "file",
      "title": "auth module",
      "path": "src/auth.ts",
      "verification_status": "verified_by_agent"
    }
  ],
  "findings": [
    {
      "text": "Auth token validation is centralized in src/auth.ts.",
      "source_refs": ["file:src/auth.ts"],
      "confidence": "high"
    }
  ],
  "limitations": ["Only inspected auth files"],
  "confidence": "medium"
}

record_decision accepts either legacy evidence findings or an evidence_context object. When evidence is present, the server writes a separate evidence artifact, links it to the decision, updates the active session, and creates a markdown brief under .claude-state/briefs/.