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

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

Category	Tool	Description
Management	diagram_create	Create a new diagram
	diagram_load	Load diagram structure from memory/disk
	diagram_save	Force immediate sync to disk
	diagram_list_saved	List all diagram IDs on disk
	diagram_delete	Permanently remove from memory and disk
Navigation	navigate_breadth_first	Level-by-level exploration
	navigate_guided	Target-guided shortest path
	analyze_reachability	Connectivity and distance analysis
	explore_reasoning_space	Curiosity-based wandering
Reasoning	pattern_match	Find structural patterns
	apply_rewrite_rule	Apply formal DPO transformation
	diagram_extract	Abstract subgraph into composite node
	export_proof	View transformation history as proof
	check_diagram_equivalence	Check for isomorphism
	explore_equivalent_states	Generate state-space from rules
Metrics	compute_metrics	Graph-theoretic complexity metrics
	node_semantic_search	Search nodes by vector embedding
	server_info	Metadata and capability discovery

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 ✅

• [x] Core data structures (Diagram, Pattern, NavigationMemory)
• [x] GraphEngine implementation
• [x] Basic MCP tools (create, load, navigate)
• [x] Comprehensive testing (Pytest suite)

Phase 2: Advanced Navigation ✅

• [x] Memory-augmented exploration with vectorized embeddings
• [x] Hierarchical reasoning with diagram composition
• [x] Vector-assisted search and guided navigation

Phase 3: Pattern & Rewriting ✅

• [x] Structural pattern matching
• [x] Double-pushout (DPO) rewriting mathematical engine

Phase 4: Reasoning Integration ✅

• [x] Proof derivation chain construction
• [x] Isomorphism checking (Structural Equivalence)
• [x] State-space exploration (Reasoning Space Discovery)

Phase 5: Production & Resilience ✅

• [x] Persistence layer (Atomic JSON Storage)
• [x] LRU Eviction Policy
• [x] Advanced error handling & Resilience Audit
• [x] 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.