Cognitive Diagram Navigation MCP Server

An advanced MCP server implementing diagrammatic reasoning with memory-augmented spatial exploration, enabling structured chain-of-thought reasoning through visual reasoning spaces.

Overview

This MCP server combines three research domains:

1. Diagrammatic Reasoning (Quantomatic-inspired)

   • String diagrams for formal proof construction

   • Graph rewriting with double-pushout semantics

   • Pattern matching and structural transformation

2. Cognitive Navigation (Hippocampal-inspired)

   • Place cell-like encoding of reasoning points

   • Reward-based spatial navigation

   • Memory-augmented exploration of reasoning spaces

3. Chain-of-Thought Reasoning

   • Sequential logic bonds stronger than keywords

   • Multi-step derivation tracking

   • Formal proof verification

Related MCP server: krusch-sequential-mcp

Features

Core Capabilities

• Diagram Creation: Build reasoning graphs from node/edge specifications

• Guided Navigation: Find optimal paths through reasoning spaces

• Breadth-First Exploration: Systematically discover diagram structure

• Pattern Matching: Locate subgraph patterns for formal rule application

• Double-Pushout (DPO) Rewriting: Apply formal structural transformations

• Hierarchical Reasoning: Extract sub-diagrams into composite nodes

• Reachability Analysis: Understand connectivity and distance metrics

• Structural Metrics: Compute graph properties (chain length, branching factor, etc.)

Advanced Reasoning

• Proof Derivation: Automatic tracking of transformation history

• Proof Export: Export structured or natural language proof chains

• Equivalence Checking: Verify if two diagrams are structurally identical (isomorphic)

• State Space Exploration: Discover all possible diagrams reachable via a set of rules

• Curiosity-Driven Exploration: Wander reasoning spaces based on "surprise" metrics

Production Features

• Automatic Persistence: Diagrams are automatically saved to disk as JSON

• LRU Memory Management: Efficiently manages memory by evicting least-recently used diagrams

• Persistence Management: Tools to manually save, list, and delete diagrams on disk

• Encrypted/Safe Randomization: Uses SystemRandom for non-cryptographic but robust stochasticity

Installation

Prerequisites

• Python 3.12+

• uv package manager (recommended)

Setup

# Clone the repository
cd cognitive-diagram-nav-mcp

# Create virtual environment with uv
uv venv

# Activate virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install project in development mode
uv pip install -e ".[dev]"

# Or with just the MCP dependencies
uv pip install -e .

Usage

Starting the Server

# Using uv
uv run src/cognitive_diagram_nav/server.py

# Or with Python directly
python src/cognitive_diagram_nav/server.py

The server will start on stdio by default and be ready to accept MCP connections.

Configuring with Claude

Add to your Claude configuration (usually ~/.config/Claude/claude_desktop_config.json or %AppData%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "cognitive-diagram-nav": {
      "command": "uv",
      "args": [
        "--directory",
        "/your-path-to/cognitive-diagram-nav-mcp",
        "run",
        "cognitive-diagram-nav"
      ]
    }
  }
}

Replace /path/to/ with the actual path to the project.

Examples

Example 1: Create and Navigate a Simple Diagram

# This would be executed through Claude's MCP interface

# Create a simple reasoning diagram
diagram = diagram_create(
    nodes=[
        {"id": "premise1", "label": "Premise 1", "type": "terminal"},
        {"id": "logic", "label": "Logical operation", "type": "operation"},
        {"id": "conclusion", "label": "Conclusion", "type": "terminal"},
    ],
    edges=[
        {"source": "premise1", "target": "logic", "label": "input"},
        {"source": "logic", "target": "conclusion", "label": "output"},
    ]
)
# Returns: diagram_id = "abc123..."

# Explore the diagram
result = navigate_breadth_first(
    diagram_id="abc123...",
    start_node="premise1",
    max_depth=3
)
# Shows connected nodes and structure

Example 2: Find Optimal Path

# Find shortest reasoning path
path_result = navigate_guided(
    diagram_id="abc123...",
    start_node="premise1",
    goal_node="conclusion",
    heuristic="distance"
)
# Returns path with cost and steps

Example 3: Analyze Reachability

# Understand what can be reached from a starting point
reachability = analyze_reachability(
    diagram_id="abc123...",
    source="premise1",
    targets=["logic", "conclusion"]
)
# Shows all reachable nodes and distances

Persistence

By default, the server persists diagrams to the local filesystem:

• Location: ~/.cognitive_diagram_nav/diagrams/

• Format: JSON with full structural and transformation metadata.

• LRU Cache: Memory is managed using an LRU policy (default 100 diagrams); diagrams are seamlessly reloaded from disk on demand.

Tools

Architecture

Components

┌─────────────────────────────────┐
│   MCP Client (Claude/LLM)       │
└────────────────┬────────────────┘
                 │ JSON-RPC 2.0
┌────────────────▼────────────────┐
│   FastMCP Server                │
├─────────────────────────────────┤
│   Tools Layer (MCP Interface)   │
├─────────────────────────────────┤
│   GraphEngine (Core Logic)      │
│   - Navigation & Exploration    │
│   - DPO Rewriting & Matching    │
│   - Memory & LRU Caching        │
├─────────────────────────────────┤
│   StorageManager (Persistence)  │
│   - JSON Serialization          │
│   - Disk I/O (Async Syncing)    │
├─────────────────────────────────┤
│   Models (Data Structures)      │
│   - Diagram / Node / Edge       │
│   - DerivationStep (Proofs)     │
│   - NavigationMemory            │
└─────────────────────────────────┘

Key Classes

• Diagram: Complete reasoning graph with nodes, edges, and transformation metadata.

• GraphEngine: Core reasoning engine with navigation, DPO rewriting, and LRU cache.

• StorageManager: Handles atomic JSON serialization and disk persistence.

• Pattern: Specification for structural subgraph matching.

• NavigationMemory: Tracks traversal history and position for curiosity-based exploration.

• DerivationStep: Represents a single transformation for formal proof tracking.

Development

Running Tests

# Run all tests
uv run pytest

# With coverage
uv run pytest --cov=src/cognitive_diagram_nav

# Specific test
uv run pytest tests/test_models.py

Code Quality

# Format code
uv run black src tests

# Lint
uv run ruff check src tests

# Type checking
uv run mypy src

Building Documentation

cd docs
uv run sphinx-build -b html . _build

Roadmap

Phase 1: Foundation ✅

• Core data structures (Diagram, Pattern, NavigationMemory)

• GraphEngine implementation

• Basic MCP tools (create, load, navigate)

• Comprehensive testing (Pytest suite)

Phase 2: Advanced Navigation ✅

• Memory-augmented exploration with vectorized embeddings

• Hierarchical reasoning with diagram composition

• Vector-assisted search and guided navigation

Phase 3: Pattern & Rewriting ✅

• Structural pattern matching

• Double-pushout (DPO) rewriting mathematical engine

Phase 4: Reasoning Integration ✅

• Proof derivation chain construction

• Isomorphism checking (Structural Equivalence)

• State-space exploration (Reasoning Space Discovery)

Phase 5: Production & Resilience ✅

• Persistence layer (Atomic JSON Storage)

• LRU Eviction Policy

• Advanced error handling & Resilience Audit

• Fully typed and lint-clean codebase

Security Considerations

• Input Validation: All diagram specifications validated before processing

• Resource Limits: Max diagrams and exploration depth configurable

• Error Handling: Comprehensive exception handling with logging

• Isolation: Each diagram is independent; no cross-contamination

Performance Notes

• Scalability: Designed to handle 100s-1000s of nodes efficiently

• Memory: In-memory storage; configurable max diagram count

• Algorithms: Uses NetworkX for optimized graph operations

• Caching: NetworkX graphs cached after initial construction

References

• Kissinger & Zamdzhiev (2015): "Quantomatic: A Proof Assistant for Diagrammatic Reasoning"

• Hippocampal place cells and reward-based navigation research

• Chain-of-Thought prompting literature

• Model Context Protocol (MCP) specification

License

MIT - See LICENSE file

Contributing

Contributions welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Ensure tests pass and code is formatted

4. Submit a pull request

Contact

For questions or feedback about this MCP server, please open an issue on GitHub.

Status: Beta (v0.5.0) - Core reasoning, production persistence, and advanced DPO transformations complete.

Live Demo Trace: Creation: Built a logic diagram for $(A \land B) \to (B \land A)$. Exploration: Used the curiosity-based explore_reasoning_space to "wander" and successfully discover the reasoning path. Abstraction: Extracted the internal logic steps into a Composite Node, creating a hierarchical proof structure. Persistence: Forced a sync to disk with diagram_save and verified it with the diagram_list_saved tool. Proof: Exported a structural trace confirming the transformation history. The system handled everything—from the sub-diagram creation to the atomic disk persistence—while maintaining a valid logical structure.

Please see docs/demo_results.md for the full trace and proof.