Manifold Engine MCP Server

A Model Context Protocol server that gives AI coding assistants high-speed, structural codebase analysis and dynamic context management. Instead of reading code token-by-token, it maps repositories structurally — treating source files as continuous byte-streams, computing structural signatures, and detecting architectural chaos in O(1) time.

Current Status: All Phase 0 critical bugs have been resolved, including FAISS semantic search deserialization, ingest_repo relative path resolution, combined risk formula transparency, and distinct cluster naming heuristics. All 21 analysis tools are fully functional.

---

Core Capabilities

| Capability | Description | |---|---| | Structural Indexing | Scans every file into a Valkey-backed grid with compressed signatures and chaos profiles. Sub-millisecond retrieval. | | Chaos Detection | Calculates a chaos_score per file. Predicts which files will become unmaintainable. | | Dependency & Risk Analysis | Traces import graphs via AST parsing, measures blast radius, combines chaos × blast into a single risk score. | | Working Memory | Inject persistent facts (project conventions, architecture rules) into a Dynamic Semantic Codebook for zero-shot learning. | | Real-Time Sync | Filesystem watcher auto-ingests file saves in milliseconds, keeping the index current without manual re-scans. |

---

Installation

Prerequisites

Python 3.10+
Valkey (or Redis) running on localhost:6379
C++20 compiler (for building the native structural engine)
faiss-cpu (required for running the cluster_codebase_structure tool)

Setup

# 1. Start the Valkey backend
valkey-server

# 2. Install the manifold engine
pip install -e .

# 3. Configure your MCP client (Kilo Code, Claude Desktop, Cursor, etc.)

Add to your MCP client configuration:

{
  "mcpServers": {
    "manifold": {
      "command": "path/to/virtualenv/bin/python",
      "args": ["path/to/SEP-mcp/mcp_server.py"],
      "cwd": "path/to/SEP-mcp"
    }
  }
}

---

Common Workflows & Use Cases

1. New Repository Analysis

When entering a new codebase, execute an initial mapping to immediately understand technical debt distribution. ```

1. Index the repository

ingest_repo (root_dir=".", clear_first=true, compute_chaos=true)

2. Verify ingestion was successful

get_index_stats

3. Quickly identify the most complex, chaotic files

batch_chaos_scan (pattern="*.py", max_files=30) ```

2. Refactoring Decisions & Sprint Planning

Use the structural risk metrics to objectively decide what code to rewrite. ```

1. Scan for files with BOTH high complexity and high import dependencies

scan_critical_files (pattern="*.py", max_files=10)

2. For candidates, predict how soon the file will become unmaintainable

predict_structural_ejection (path="target.py", horizon_days=30)

3. For visual confirmation, generate a 4-panel chaos dashboard

visualize_manifold_trajectory (path="target.py") ```

3. Finding Implementation Patterns

Rather than searching by text, search by structural signatures to find similar logic blocks or clones. ```

1. Get the mathematical signature of an existing file

get_file_signature (path="found_file.py")

2. Search for any other files that match this structure globally

search_by_structure (signature="c0.213_s0.000_e0.928", tolerance=0.05) ```

4. Continuous Flow

# Run the watcher inside the repo
start_watcher  (watch_dir=".")

# The engine now automatically syncs and re-evaluates risk natively whenever files are saved.

---

Tool Reference (20 Tools)

All tools are documented with parameters, examples, and workflows in MCP_TOOL_GUIDE.md.

Indexing & Monitoring

| Tool | Purpose | Quick Command | |---|---|---| | ingest_repo | Full repository scan into Valkey with signatures and chaos profiles | ingest_repo root_dir="." clear_first=true compute_chaos=true | | get_index_stats | Real-time index health: document count, memory, chaos averages | get_index_stats | | start_watcher | Background filesystem observer — auto-ingests on file save/delete | start_watcher watch_dir="." |

File Discovery & Search

| Tool | Purpose | Quick Command | |---|---|---| | list_indexed_files | Browse indexed files by glob pattern | list_indexed_files pattern=".py" max_results=200 | | get_file | Read full file content from the Valkey index | get_file path="src/manifold/sidecar.py" | | search_code | Keyword or regex search across all indexed files with context | search_code query="chaos_score" file_pattern=".py" | | get_file_signature | Structural fingerprint (c/s/e) for a file | get_file_signature path="mcp_server.py" | | search_by_structure | Find files with similar structural signatures | search_by_structure signature="c0.213_s0.000_e0.928" tolerance=0.05 | | search_by_signature_sequence | Find files containing a contiguous signature sequence | search_by_signature_sequence text="..." min_signatures=3 |

Chaos Analysis

| Tool | Purpose | Quick Command | |---|---|---| | analyze_code_chaos | Per-file chaos score, entropy, coherence, collapse risk | analyze_code_chaos path="mcp_server.py" | | batch_chaos_scan | Rank all files by chaos score (highest risk first) | batch_chaos_scan pattern=".py" max_files=50 | | predict_structural_ejection | Forecast when a file becomes unmaintainable | predict_structural_ejection path="mcp_server.py" horizon_days=30 | | visualize_manifold_trajectory | Generate a 4-panel dashboard of chaos dynamics | visualize_manifold_trajectory path="mcp_server.py" | | cluster_codebase_structure | K-Means clustering of files by structural signatures | cluster_codebase_structure pattern=".py" n_clusters=5 |

Dependency & Combined Risk

| Tool | Purpose | Quick Command | |---|---|---| | analyze_blast_radius | Import dependency tree and impact file count | analyze_blast_radius path="src/manifold/sidecar.py" | | compute_combined_risk | Combined risk = 0.6×chaos + 0.4×blast | compute_combined_risk path="src/manifold/sidecar.py" | | scan_critical_files | Repository-wide scan for highest combined risk | scan_critical_files pattern="*.py" max_files=20 |

Verification & Memory

| Tool | Purpose | Quick Command | |---|---|---| | compute_signature | Compress arbitrary text into manifold signatures | compute_signature text="def hello(): ..." | | verify_snippet | Check if code structurally matches existing codebase patterns | verify_snippet snippet="..." coverage_threshold=0.5 scope="*.py" | | inject_fact | Add persistent knowledge to the Dynamic Semantic Codebook | inject_fact fact_id="api_rules" fact_text="All endpoints use snake_case." | | remove_fact | Remove a previously injected fact | remove_fact fact_id="api_rules" |

---

Empirical Validation

React 15.0 Case Study

The structural engine flagged the exact files (ReactReconcileTransaction.js, ReactInstanceHandles.js) that the React core team subsequently deleted and rewrote as React Fiber — without any semantic understanding of JavaScript. → Read the study

Langchain ROC Analysis

A blind forward-prediction study on langchain v0.0.300 proved that a chaos score threshold of 0.396 optimally predicts architectural ejection, achieving ~91% of the predictive power of expensive AST-parsing tools at O(1) speed. → Read the study

Memory Optimization

Zstandard compression reduced the cpython index from 3.4 GB to 28 MB (>99% reduction) with zero loss in retrieval accuracy.

---

Documentation

| Document | Purpose | |---|---| | MCP_TOOL_GUIDE.md | Comprehensive tool reference, workflows, best practices | | reports/ | Validation studies and generated reports |

---

License

MIT — see LICENSE

Manifold Engine MCP Server