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