Overview

The CRASH MCP Server implements a Model Context Protocol (MCP) that facilitates structured, iterative, and branching reasoning between models, tools, and humans. Instead of a single linear chain of thought, CRASH treats reasoning as a multi-branch, revision-capable process: agents can produce candidate decisions, attach confidence scores, validate or invalidate outputs, and submit revisions. This makes it easier to explore alternatives, detect contradictions, and converge on higher-quality outcomes.

This server is intended for developers building assistants, evaluators, or pipeline orchestrators that require disciplined communication between components. By exposing a small set of primitives for session management, branching, validation, and confidence tracking, CRASH helps you turn ambiguous chains of thought into auditable, testable decision graphs.

Features

Session-based MCP server supporting multiple concurrent reasoning sessions
Branching: create and manage multiple candidate hypotheses per session
Iteration: submit revisions that reference prior nodes and branches
Validation primitives: validators that accept/reject outputs and attach metadata
Confidence tracking: numeric confidence scores per node and aggregated views
Revision history: immutable nodes with links to revisions for auditability
Pluggable configuration: customize validators, timeouts, and persistence
HTTP/REST API (and optional WebSocket) for integration with models and tools
Docker-ready and local development modes

Installation / Configuration

Clone the repository and run locally or in Docker. The server requires Node.js 18+ (or the runtime stated in the repo).

Bash (clone + npm):

git clone https://github.com/nikkoxgonzales/crash-mcp.git
cd crash-mcp
npm install
# configure env in .env
npm run start

Docker:

docker build -t crash-mcp .
docker run -p 3000:3000 \
  -e MCP_PORT=3000 \
  -e MCP_PERSISTENCE=memory \
  crash-mcp

Environment variables (examples):

MCP_PORT=3000           # HTTP port (default 3000)
MCP_PERSISTENCE=memory  # memory | sqlite | postgres
MCP_VALIDATOR_URL=...   # optional external validators
MCP_LOG_LEVEL=info

Configuration file (YAML/JSON) sample:

persistence:
  driver: sqlite
  database: ./data/crash.db
validators:
  - id: basic-sanity
    type: rule
    rules:
      - mustContain: "answer"
timeouts:
  branchTTL: 86400  # seconds before branch is considered stale

Available Resources

API endpoints (examples)

Endpoint	Method	Purpose
/sessions	POST	Create a new reasoning session
/sessions/:id	GET	Get session metadata and branches
/sessions/:id/branches	POST	Create a new branch (candidate)
/nodes	POST	Submit a reasoning node (content, confidence, parent)
/nodes/:id/validate	POST	Run validators against a node
/sessions/:id/aggregate	GET	Get aggregated confidences and status

Sample node payload (JSON):

{
  "session_id": "s_123",
  "branch_id": "b_1",
  "parent_node_id": "n_5",
  "content": "Hypothesis: The user wants X because...",
  "confidence": 0.63,
  "metadata": { "agent": "llm-v2" }
}

Sample validation result:

{
  "node_id": "n_10",
  "valid": false,
  "reasons": ["missing required field 'answer'"],
  "validator_id": "basic-sanity"
}

Use Cases

Iterative assistant reasoning: Have an LLM propose multiple candidate answers as branches, run validators, then request targeted revisions on the highest-confidence, but flawed, branch.
Tool orchestration: Coordinate chains of tools (search, calculator, extractor) where each tool’s output is a node. Validators check tool outputs and request re-run or correction when outputs fail checks.
Human-in-the-loop review: Present branches to a human reviewer who marks validity and provides a revision prompt; the system tracks which revisions improved confidence.
Model evaluation and A/B testing: Compare multiple model outputs per prompt as branches, automatically aggregate confidence and validation results to determine best-performing models.
Auditable decision making: Store immutable nodes with revision links to produce an explanation trail for compliance or debugging.

Tips for Developers

Use small, focused validators to keep feedback actionable.
Treat confidence scores as relative signals — combine them with validation results for decision logic.
Design branch TTLs and persistence according to expected session lifetimes to avoid unbounded storage growth.
Integrate a WebSocket listener for real-time updates when building interactive developer tools or dashboards.

For full API details, reference the repository’s API docs and example client integrations in the repo. The MCP model encourages explicit, auditable communication patterns—use CRASH to make complex reasoning pipelines maintainable and testable.

CRASH MCP Server for Iterative, Branching Reasoning