mcp-memory/mcp_tools_review.md

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).