# 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

```bash
# 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:

```json
{
  "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](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](reports/react_validation_case_study.md)

### 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](reports/true_validation_study.md)

### 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](MCP_TOOL_GUIDE.md) | Comprehensive tool reference, workflows, best practices |
| [reports/](reports/) | Validation studies and generated reports |

---

## License

MIT — see [LICENSE](LICENSE)