# ctx-mcp

[![npm version](https://img.shields.io/npm/v/ctx-mcp.svg)](https://www.npmjs.com/package/ctx-mcp)

Local MCP server for decision trace capture and deterministic explanations.

## Requirements

- Node.js 18+

## Install

```bash
npm install
```

## Run (stdio MCP server)

```bash
npm run dev
```

## Architecture (high level)

```mermaid
flowchart LR
  Client[MCP client] -->|stdio| Server[ctx MCP server]
  Server --> Tools[Trace tools]
  Tools --> Store[(Trace store)]
  Server --> Resources[trace:// resources]
  Store --> Resources
```

## Usage contract (agents)

- You MUST call `trace.start` when a user-requested task begins (once intent is clear).
- You MUST call `trace.finish` when that task is completed, even if the conversation continues, to mark outcome/status for downstream analysis.
- Treat a "task" as a single user goal; if the user pivots to a new goal, start a new trace.
- If a task is completed and the user continues with a new goal, start a new trace (optionally link the prior trace in metadata).

## Core tools

- `trace.start`
- `trace.add_node`
- `trace.add_edge`
- `trace.attach_artifact`
- `trace.finish`
- `trace.query`
- `trace.get_subgraph`
- `trace.find_paths`
- `trace.explain_decision`
- `trace.similarity`
- `trace.risk_check`

## Example tool calls

```json
{
  "tool": "trace.start",
  "input": {
    "intent": "Investigate alert",
    "tags": ["incident", "p1"],
    "metadata": { "ticket": "INC-123" }
  }
}
```

```json
{
  "tool": "trace.add_node",
  "input": {
    "trace_id": "trace-uuid",
    "type": "Decision",
    "summary": "Roll back release",
    "data": { "reason": "error rate spike" },
    "confidence": 0.8
  }
}
```

```json
{
  "tool": "trace.add_edge",
  "input": {
    "trace_id": "trace-uuid",
    "from_node_id": "decision-node-id",
    "to_node_id": "action-node-id",
    "relation_type": "causes"
  }
}
```

```json
{
  "tool": "trace.explain_decision",
  "input": {
    "trace_id": "trace-uuid",
    "decision_node_id": "decision-node-id",
    "depth": 4
  }
}
```

```json
{
  "tool": "trace.similarity",
  "input": {
    "decision_node_id": "decision-node-id",
    "scope": "all",
    "limit": 5
  }
}
```

```json
{
  "tool": "trace.risk_check",
  "input": {
    "decision_node_id": "decision-node-id",
    "threshold": 0.6
  }
}
```

## Resources

- `trace://{trace_id}`
- `trace://{trace_id}/timeline`
- `trace://{trace_id}/graph`
- `trace://{trace_id}/subgraph?center=...&depth=...&dir=...`
- `trace://{trace_id}/explain?decision=...&depth=...`
- `trace://search?text=...&trace_id=...&type=...`
- `trace://{trace_id}/similarity?decision=...&scope=...&limit=...&depth=...&max_traces=...`
- `trace://{trace_id}/risk?decision=...&scope=...&limit=...&depth=...&threshold=...&max_traces=...`

## MCP config example

```json
{
  "mcpServers": {
    "ctx": {
      "command": "npx",
      "args": ["ctx-mcp"]
    }
  }
}
```

## Testing

```bash
npm test
```

## Seed a sample trace

```bash
npm run seed
```

## CLI examples

```bash
npm run risk-check -- decision-node-id
```

```bash
npm run similarity -- decision-node-id
```