# MCP Tools Review & Enhancement Strategy

## Part 1: Current Arsenal Review

Our current MCP ecosystem is highly advanced, utilizing a **Dual-Transport Leader/Stub Architecture** (Windows Host + WSL Proxy) to completely eliminate cross-OS I/O latency. 

### 1. Context & Token Optimization
*   `read_file_skeleton`: Highly effective. Uses tree-sitter to extract ASTs (Rust, Python, TS). **Score: A+ (Massive token savings)**
*   `get_active_worktree_context`: Native git2 integration. Bypasses shell parsing for clean JSON diffs. **Score: A**
*   `process_logs`: Direct file seeking and daemon log management (`watch`, `get`, `clear`). Prevents LLMs from reading multi-megabyte log files. **Score: A**

### 2. Neovim IDE Integration (nvim-core)
*   `nvim_buffer`, `nvim_workspace`, `nvim_intelligence`, `nvim_ui`, `nvim_exec`.
*   **Review:** Exceptional human QoL. The agent interacts with the code where the human's eyes actually are. Ghost text and diagnostic extmarks provide an IDE-like experience usually reserved for closed-source tools like Cursor. **Score: S-Tier**

### 3. Clipboard & Workflow
*   `clipboard` (`read`, `write`).
*   **Review:** Native cross-OS clipboard-win and arboard implementation with on-demand image grab. Bridges the gap between manual human research and the agent's context. **Score: A**

### 4. Graph & Memory Management
*   `create_entities`, `hypotheses`, `agent_signals`, `handoff_routine`.
*   **Review:** Solid foundation for state persistence across branches and days. **Score: A**

---

## Part 2: Proposed Enhancements (Focus: T2R, Token Cost, QoL)

To push the system to the absolute bleeding edge of autonomous coding, I propose the following 5 new tools/enhancements.

### 1. `replace_ast_node` (Robust Structural Editing)
*   **The Problem:** Standard text replacement uses exact string matching and line numbers. Line numbers change when humans edit simultaneously, and string matching fails on whitespace/indentation.
*   **The Solution:** An MCP tool that takes `(file_path, node_type, node_name, new_content)`. It uses tree-sitter to find the exact boundary of `fn execute(...)` and replaces just that AST node.
*   **Impact:** Zero LLM syntax/indentation errors. 100% robust edits. Drastically lowers Time-to-Resolve (T2R) by eliminating failed edit loops.

### 2. `semantic_code_search` (Local Vector Embeddings)
*   **The Problem:** Text search relies on exact regex. If the LLM guesses the wrong variable name, it wastes tokens searching and reading the wrong files.
*   **The Solution:** Using Tantivy and BERT embeddings in our backend. We index the AST blocks of the codebase in the background. The LLM can query *"Where is the auth token validated?"* and get the exact 3 relevant functions instantly.
*   **Impact:** Massive token cost reduction (no blind file reading). Instant T2R for codebase exploration.

### 3. `nvim_exec` terminal execution (Interactive Execution QoL)
*   **The Problem:** When the agent runs a background terminal command (`cargo build`, `npm run dev`), the output is hidden from the human, and interactive prompts cause the background task to hang indefinitely.
*   **The Solution:** Dispatch to Neovim terminal splits where the human can watch the tests run natively, interact with prompts, see ANSI colors, and interact seamlessly.
*   **Impact:** Massive Human QoL.

### 4. `read_directory_architecture` (Bird's-Eye View)
*   **The Problem:** Single file inspection works for one file. When entering a new repository, the LLM usually runs `ls -R` and then has to guess what files do based on their names.
*   **The Solution:** A tool that scans a directory structure and returns a clean hierarchical tree alongside summaries of what each directory and key file is responsible for.
*   **Impact:** Immediate holistic context. Eliminates the "exploration phase" token tax.

### 5. `query_database_schema` (Introspection)
*   **The Problem:** Working with databases usually involves the LLM writing clunky scripts to view table definitions, which often fail due to missing env vars or wrong dialects.
*   **The Solution:** A direct MCP tool that parses the local `.env`, connects to the database (PostgreSQL), and returns a clean Markdown representation of the schema (Tables, Columns, Types, Foreign Keys).
*   **Impact:** Prevents hallucinations about database structure. Fixes DB-related bugs significantly faster (T2R).