extension/docs/MCP_TOOLS.md

Hanzo MCP Tools Documentation

This document provides comprehensive documentation for all tools available in the Hanzo VS Code extension with Model Context Protocol (MCP) support.

Overview

The Hanzo extension provides 55+ tools across multiple categories to enhance AI-assisted development. These tools work seamlessly with VS Code, Cursor, Windsurf, and Claude Desktop.

Tool Categories

1. File System Operations

read

Read the contents of a file with optional pagination.

{
  "path": "src/index.ts",    // File path (absolute or relative)
  "offset": 0,               // Line offset (optional)
  "limit": 100               // Number of lines to read (optional)
}

write

Write content to a file (creates if doesn't exist).

{
  "path": "src/new-file.ts",
  "content": "// File content here"
}

edit

Edit a file by replacing exact text patterns.

{
  "path": "src/index.ts",
  "old_text": "const oldValue = 1",
  "new_text": "const newValue = 2",
  "replace_all": false       // Replace all occurrences (optional)
}

multi_edit

Make multiple edits to a file in one atomic operation.

{
  "path": "src/index.ts",
  "edits": [
    {
      "old_text": "import old from 'old'",
      "new_text": "import new from 'new'"
    },
    {
      "old_text": "const x = 1",
      "new_text": "const x = 2"
    }
  ]
}

directory_tree

Display directory structure as a tree.

{
  "path": "src",             // Directory path
  "max_depth": 3,            // Maximum depth (optional)
  "show_hidden": false,      // Show hidden files (optional)
  "ignore_patterns": ["node_modules", "*.log"]  // Patterns to ignore
}

find_files

Find files matching a pattern.

{
  "pattern": "**/*.ts",      // Glob pattern
  "path": "src",             // Search path (optional)
  "max_results": 50          // Maximum results (optional)
}

2. Search Operations

unified_search

Comprehensive parallel search across code, symbols, git history, and filenames.

{
  "query": "authentication",
  "include": ["grep", "symbol", "git", "filename"],  // Search types
  "file_pattern": "*.ts",    // File filter (optional)
  "max_results": 20          // Max results per type
}

grep

Search for patterns in files using ripgrep.

{
  "pattern": "TODO",         // Search pattern (regex)
  "path": "src",             // Search path (optional)
  "include": "*.ts",         // Include pattern (optional)
  "case_sensitive": false    // Case sensitivity (optional)
}

search

Unified search across files, symbols, and git history.

{
  "query": "handleAuth",
  "type": "all",             // all, files, symbols, git
  "max_results": 30
}

symbols

Search for code symbols (functions, classes, etc.).

{
  "query": "Controller",     // Symbol name pattern
  "kind": "class",           // Symbol kind filter (optional)
  "in_file": "src/**/*.ts"   // File pattern (optional)
}

3. Shell & System Operations

run_command

Execute a shell command with timeout support.

{
  "command": "npm test",
  "cwd": ".",                // Working directory (optional)
  "timeout": 30000,          // Timeout in ms (optional)
  "shell": true              // Use shell (optional)
}

process

Unified process management with background execution.

{
  "action": "run",           // run, list, kill, logs, clean
  "command": "npm run dev",  // Command for run action
  "name": "dev-server",      // Process name (optional)
  "id": "uuid",              // Process ID for kill/logs
  "tail": 50                 // Lines to tail for logs
}

open

Open a file or URL in the default application.

{
  "target": "https://docs.hanzo.ai",  // File path or URL
  "wait": false              // Wait for app to close (optional)
}

4. Development Tools

todo (Unified)

Comprehensive todo management.

{
  "action": "read",          // read, write, add, update, delete, clear
  "task": "Implement auth",  // Task content for add
  "tasks": [{                // Tasks array for write
    "id": "1",
    "content": "Task content",
    "status": "pending",     // pending, in_progress, completed
    "priority": "high"       // high, medium, low
  }],
  "id": "1",                 // Task ID for update/delete
  "status": "pending",       // Filter by status for read
  "priority": "high"         // Filter by priority
}

think

Structured thinking and reasoning space.

{
  "thought": "Breaking down the authentication flow...",
  "category": "analysis",    // analysis, planning, debugging, design, reflection, hypothesis
  "metadata": {              // Additional context (optional)
    "component": "auth",
    "complexity": "high"
  }
}

critic

Critical analysis and code review.

{
  "code": "function auth() { ... }",  // Code to review
  "file": "src/auth.ts",     // Or file path to review
  "aspect": "security"       // security, performance, readability, correctness, all
}

5. Configuration & Project Tools

palette

Tool palette management for context switching.

{
  "action": "list",          // list, activate, show, create
  "name": "python",          // Palette name
  "tools": ["read", "write"], // Tools for create action
  "environment": {           // Environment vars for create
    "PYTHON_VERSION": "3.9"
  }
}

Built-in palettes:

• minimal: Basic file operations
• python: Python development tools
• javascript: JavaScript/TypeScript tools
• devops: DevOps and system tools
• data-science: Data analysis tools

rules

Read project rules and conventions.

{
  "path": ".",               // Project path (optional)
  "format": "full"           // full, summary, list
}

Searches for:

• .cursorrules
• .claude_instructions
• .continuerules
• CONVENTIONS.md
• CONTRIBUTING.md
• And more...

config

Git-style configuration management.

{
  "action": "get",           // get, set, list, unset
  "key": "hanzo.theme",      // Config key
  "value": "dark",           // Value for set action
  "global": false            // Global vs workspace config
}

6. Web & External Tools

web_fetch

Fetch and extract content from web URLs.

{
  "url": "https://api.example.com/data",
  "method": "GET",           // HTTP method
  "headers": {               // HTTP headers (optional)
    "Authorization": "Bearer token"
  },
  "body": "{}",              // Request body for POST/PUT
  "format": "text",          // text, json, raw, metadata
  "max_length": 50000        // Max content length
}

7. AI & Advanced Tools

dispatch_agent (Planned)

Delegate tasks to specialized sub-agents.

{
  "task": "Analyze this codebase for security issues",
  "context": {},             // Additional context
  "tools": ["read", "grep"], // Tools available to agent
  "max_iterations": 10       // Max agent iterations
}

llm (Planned)

Direct LLM integration for complex reasoning.

{
  "prompt": "Explain this code",
  "model": "gpt-4",          // Model selection
  "temperature": 0.7,        // Generation parameters
  "max_tokens": 1000
}

8. Jupyter & Notebook Support

notebook_read

Read Jupyter notebook contents.

{
  "path": "analysis.ipynb",
  "cell_id": "cell-123",     // Specific cell (optional)
  "include_outputs": true    // Include cell outputs
}

notebook_edit

Edit Jupyter notebook cells.

{
  "path": "analysis.ipynb",
  "cell_id": "cell-123",
  "content": "print('Hello')",
  "cell_type": "code"        // code or markdown
}

9. Database Tools (Planned)

db_query

Execute database queries.

{
  "connection": "postgres://...",
  "query": "SELECT * FROM users",
  "params": [],              // Query parameters
  "limit": 100               // Result limit
}

10. Vector Search (Planned)

vector_search

Semantic search using embeddings.

{
  "query": "authentication flow",
  "index": "codebase",       // Vector index name
  "top_k": 10,               // Number of results
  "threshold": 0.7           // Similarity threshold
}

Tool Configuration

Environment Variables

Configure tools via environment variables:

# Workspace directory
HANZO_WORKSPACE=/path/to/project

# Tool configuration
HANZO_MCP_ENABLED_TOOLS=read,write,search,unified_search
HANZO_MCP_DISABLED_TOOLS=db_query,vector_search

# Feature flags
HANZO_MCP_DISABLEWRITETOOLS=false
HANZO_MCP_DISABLESEARCHTOOLS=false

VS Code Settings

Configure in .vscode/settings.json:

{
  "hanzo.mcp.enabled": true,
  "hanzo.mcp.enabledTools": ["read", "write", "unified_search"],
  "hanzo.mcp.disabledTools": ["db_query"],
  "hanzo.mcp.disableWriteTools": false,
  "hanzo.mcp.disableSearchTools": false
}

Claude Desktop Integration

Installation

1. Build the MCP server:

   npm run build:mcp
   

2. Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

   {
     "mcpServers": {
       "hanzo": {
         "command": "node",
         "args": ["/path/to/extension/out/mcp-server-standalone.js"],
         "env": {
           "HANZO_WORKSPACE": "/path/to/your/project"
         }
       }
     }
   }
   

3. Restart Claude Desktop

Usage in Claude

Once configured, you can use tools directly:

Please search for "authentication" across the codebase

Claude will automatically use the unified_search tool.

Best Practices

1. Use Unified Search First: The unified_search tool provides the most comprehensive results by searching across multiple dimensions in parallel.

2. Leverage Palettes: Switch tool palettes based on your current task (Python development, DevOps, etc.).

3. Think Before Acting: Use the think tool to plan complex operations before executing them.

4. Batch Operations: Use multi_edit for multiple file changes and batch for multiple tool operations.

5. Background Processes: Use the process tool for long-running operations to avoid blocking.

6. Project Rules: Always check rules tool output to understand project conventions.

Error Handling

All tools provide structured error messages:

{
  "error": "File not found",
  "details": "The file 'src/missing.ts' does not exist",
  "suggestion": "Use 'find_files' to search for similar files"
}

Performance Considerations

• File operations are limited to reasonable sizes (default 2MB)
• Search operations have result limits to prevent overwhelming output
• Background processes are managed with resource limits
• Vector operations are chunked for large codebases

Security

• File operations respect .gitignore and workspace boundaries
• Shell commands run with limited permissions
• Web fetch validates URLs and has timeout protection
• No operations outside the workspace without explicit paths

Troubleshooting

Tools not appearing in Claude Desktop

1. Check the MCP server is running:

   node out/mcp-server-standalone.js --help
   

2. Verify configuration in Claude Desktop settings

3. Check logs in Claude Desktop developer console

Search not finding results

1. Ensure ripgrep is installed for grep operations
2. Check file permissions in the workspace
3. Verify git repository for git search features

Process management issues

1. Check process logs in ~/.hanzo/logs/
2. Use process action:clean to clean up stale processes
3. Verify shell permissions for command execution