# 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:

```bash
npm install
```

Run the server over stdio:

```bash
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:

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

## State Layout

```text
.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:

```json
{
  "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/`.