Architecture - ReasonKit Think MCP v2

System Diagram

flowchart TD
  C[Client MCP Host] --> S[reasonkit-think-mcp]
  S --> T[Tool Router]
  S --> P[Prompt Router]
  S --> R[Resource Router]

  T --> DE[Deliberation Engine]
  T --> VE[Verification Engine]
  T --> SA[Skills Adapter]
  T --> AL[Assumption Ledger]
  T --> CP[Checkpoint + Convergence Gates]
  T --> PR[Pattern Registry]
  T --> SOT[Skeleton-of-Thought Phases]
  T --> AG[Audit Exporter]
  T --> AP[Analysis Provider Boundary]

  DE --> TS[Thought Store DAG]
  VE --> TS
  SA --> TS
  AL --> TS
  CP --> TS
  PR --> TS
  SOT --> TS
  AG --> TS
  AP --> HP[Heuristic Provider]
  AP -. fail-closed boundary .-> LLM[Model-backed Provider]
  AP -. fail-closed boundary .-> RET[Retrieval / Evidence Provider]

  VE --> VM[Verification Matrix]
  SA --> RD[Route Decision]
  AG --> AR[Audit Record JSON]

Thinking Modes & Profiles

ReasonKit Think exposes user-facing Thinking Modes while preserving internal wire values for compatibility.

User-facing modes:

• Auto: hybrid router/adaptive selector, implemented by run_thinking_mode and the compatibility reasoning_autopilot flow.
• Quick: CoT-style concise reasoning audit; no raw hidden chain-of-thought.
• Explore: Tree-of-Thoughts branching, scoring, and pruning.
• Map: Graph-of-Thoughts dependencies, conflicts, refinements, and merges.
• Sketch: Skeleton-of-Thought outline-first planning and controlled expansion.
• Test: CoVe plus ReasonKit verification/governance pipeline.

Compatible internal values:

• cot: linear tracking behind Quick.
• tot: branching and pruning behind Explore.
• got: DAG synthesis behind Map and Sketch.
• reasonkit: governed reasoning with quality gates and stages behind Test.

Profiles:

• quick: Low overhead, minimal branching.
• balanced: Standard exploration and validation.
• deep: Exhaustive expansion and scoring.
• paranoid: Strict verification and adversarial critique.

Mode contract resource:

• reasoning://thinking-modes exposes the mode catalog, active aliases, compatible internal values, estimated cost, primary tools, prompt packs, resources, required behavior, safety rules, and output expectations.
• run_thinking_mode, reasoning_intent_router, and reasoning_autopilot return user_mode, internal_method, mode_rationale, safety_notes, estimated_cost, and mode_contract so clients can display why a route was selected.
• The MCP server also exposes native resources/list, resources/templates/list, and resources/read handlers for the public ReasonKit resource catalog.

Data Model

Core entities

• Session
  • session_id, created_at, mode, budgets.
• Deliberation
  • deliberation_id, goal, constraints, status.
• DeliberationNode
  • node_id, parent_ids, content, score, branch_id, created_at, tags, provenance.
• VerificationClaim
  • claim_id, text, criticality, status.
• EvidenceItem
  • source, tier, independence_group, supports_claims.
• AssumptionRecord
  • assumption_id, text, criticality, status, verifiable, source_node_ids, evidence, analysis.
• QualityCheckpoint
  • checkpoint_id, quality_score, route_decision, blocking_gaps, recommended_tools.
• SkeletonPhase
  • phase_id, source_node_id, state, style, suitability, skeleton_node_ids, elaboration_node_ids_by_skeleton, prompt_pack, score_run_ids, checkpoint_ids, merge_node_id, analysis.
• RouteDecision
  • decision, confidence, rationale, blocking_gaps.
• AnalysisMetadata
  • mode, method, provider, model, generated_at, source_node_ids, limitations.
• ThinkingModeContract
  • mode, internal_method, aliases, estimated_cost, primary_tools, prompt_packs, resources, required_behavior, safety_rules, output_expectations.

Analysis Contract

The current server is a deterministic reasoning workspace. It stores and organizes reasoning artifacts, but it does not invoke an LLM or retrieval provider for semantic expansion, factual verification, synthesis, or calibrated confidence. Provider boundaries are explicit and fail closed: if model or retrieval provider environment variables are present, the server reports that a boundary is configured but still refuses to fabricate semantic output until a real invocation binding is implemented.

Current provider mode:

• heuristic: deterministic templates, rule checks, weighted structural scores, and caller-supplied evidence evaluation.
• sot_heuristic_scaffold: Skeleton-of-Thought preserves phase structure and prompt packs, but scaffold nodes are not semantic model output.

Reserved provider modes:

• model_backed: reserved LLM-backed expansion, scoring, verification, or synthesis. Current behavior is unavailable/fail-closed, not heuristic fallback disguised as model output.
• retrieval: reserved evidence retrieval/fact-check provider. Current factual verification is limited to caller-supplied evidence.
• unavailable: capability is not configured in the current build.

Every derived output includes analysis or provenance metadata. A confidence field in current outputs is route/heuristic confidence, not semantic calibration; semantic confidence is represented separately and remains null unless a model-backed provider supplies it.

Edge types (GoT-ready)

• supports
• conflicts
• depends_on
• refines
• subsumes
• analogous_to
• contradicts_fatally
• temporally_precedes
• requires_grounding
• contextualizes
• exemplifies

Tool Pipeline

sequenceDiagram
  participant Client
  participant MCP
  participant Deliberation
  participant Verification
  participant Skills

  Client->>MCP: run_thinking_mode
  MCP->>Deliberation: route mode + execute audited workflow
  Client->>MCP: start_deliberation
  MCP->>Deliberation: optional lower-level graph/session control
  Client->>MCP: apply_algorithm_template
  MCP->>Deliberation: scaffold structured algorithm nodes
  Client->>MCP: expand_thoughts
  MCP->>Deliberation: create heuristic branch candidates
  Client->>MCP: add_thought_node
  MCP->>Deliberation: inject agent-authored node
  Client->>MCP: start_skeleton_of_thought / run_skeleton_elaboration
  MCP->>Deliberation: create routed SoT phase + scaffold elaborations
  Client->>MCP: set_scoring_rubric
  MCP->>Deliberation: update dimension weights
  Client->>MCP: score_thoughts
  MCP->>Deliberation: heuristic score and rank
  Client->>MCP: prune_thoughts
  MCP->>Deliberation: beam prune
  Client->>MCP: refine_thoughts
  MCP->>Deliberation: create feedback correction node + refines edge
  Client->>MCP: record_assumption / set_assumption_status
  MCP->>Deliberation: update assumption ledger + blocking indexes
  Client->>MCP: apply_reasoning_pattern
  MCP->>Deliberation: insert pattern prompts/nodes
  Client->>MCP: verify_thoughts
  MCP->>Verification: evaluate supplied evidence + matrix
  Client->>MCP: evaluate_reasoning_quality
  MCP->>Deliberation: detect biases, compute quality tier
  Client->>MCP: run_reasoning_checkpoint / converge_reasoning
  MCP->>Deliberation: gate convergence on assumptions, verification, quality
  Client->>MCP: run_reasonkit_pipeline
  MCP->>Skills: emit selected heuristic stage markers
  Client->>MCP: consensus_answer
  MCP-->>Client: answer + heuristic confidence + route + analysis metadata

Policy Guard

Mandatory checks before consensus_answer success:

1. No unresolved critical VerificationClaim.
2. No unhandled source-conflict on critical claims.
3. No unresolved or falsified high/critical verifiable AssumptionRecord.
4. Diversity floor met when in deliberate mode.
5. Route decision emitted in governed mode.

Reliability and Performance Controls

• Direct node lookup by HashMap<node_id, ThoughtNode>.
• Maintained indexes:
  • children_by_parent
  • branch_index
  • strict_adjacency for depends_on / refines cycle checks
• Session budgets:
  • max nodes
  • max depth
  • max expansions per call
  • max verification questions
• Timeouts per tool.
• Bounded in-memory retention with MAX_HISTORY_SIZE.
• Persisted JSON snapshots at ~/.local/share/sh.reasonkit.think/state.json; mutations update state after releasing store locks to avoid self-deadlock.
• Store lock poisoning is mapped to structured MCP error responses rather than panicking tool calls.
• replay_reasoning_session reconstructs a timeline from node, assumption, verification, and checkpoint timestamps.
• converge_reasoning creates a convergence summary node only after blockers are cleared and the selected quality threshold is met.
• OpenTelemetry metric instruments are registered for tool latency, verification outcomes, pruned nodes, and graph depth. An in-process summary is also exposed at reasoning://telemetry/summary for MCP clients without an OTel collector.

Operational Resources

• reasoning://thinking-modes reports the public Thinking Mode catalog and compatibility mapping for clients.
• reasoning://config/providers reports active heuristic mode, provider boundaries, required environment variables, and unavailable modes without leaking configured endpoint URLs.
• reasoning://config/transports reports active stdio transport and the not-active streamable HTTP boundary for this build.
• reasoning://patterns lists reusable pattern registry entries.
• reasoning://memory/sinks lists memory snapshot sinks and explicit boundary states.
• reasoning://session/{id}/assumptions returns the assumption ledger, node-to-assumption index, and current blocking assumptions.
• reasoning://session/{id}/checkpoints returns persisted quality gates.
• reasoning://session/{id}/skeleton-phases returns all SoT phase records.
• reasoning://session/{id}/skeleton-phase/{phase_id} returns one SoT phase with prompts, skeleton ids, elaboration ids, and merge/checkpoint references.
• reasoning://telemetry/summary reports aggregate tool calls, latency totals, verification outcomes, pruning counts, latest/max graph depth, and SoT suitability/fanout counters.
• reasoning://schemas/{name} reports Vertex/Gemini-compatible JSON schemas for tools and resources.

Security Controls

• Existing prompt-injection scan/redaction remains enabled.
• Extend redaction to evidence and claim payloads.
• Validate all tool args with strict schemas.
• Reject unsafe oversized payloads.

Compatibility

• Keep v1 tools stable and available.
• New tools are additive; no breaking rename.
• Documented protocol contract in docs/research/SOURCES.md and per-tool docs.