extension/docs/README_MCP.md

Hanzo AI Extension - MCP Edition

A powerful VS Code extension that brings AI-enhanced development capabilities through the Model Context Protocol (MCP). Works seamlessly with VS Code, Cursor, Windsurf, and Claude Desktop.

Features

• 55+ AI-Powered Tools: Comprehensive toolset for file operations, search, web fetching, process management, and more
• Multi-Platform Support: Single codebase works across VS Code, Cursor, Windsurf, and Claude Desktop
• Unified Search: Parallel search across code, symbols, git history, and filenames
• Smart Project Analysis: Automatic codebase understanding and metrics
• Background Process Management: Run and monitor long-running tasks
• Tool Palettes: Context-aware tool sets for different development scenarios
• Web Content Fetching: Research documentation and APIs directly
• Structured Thinking: Built-in tools for planning and reasoning

Installation

VS Code / Cursor / Windsurf

1. Install dependencies:

   npm install
   

2. Compile the extension:

   npm run compile
   

3. Package the extension:

   npm run package
   

4. Install the .vsix file in your editor

Claude Desktop

1. Build the MCP server:

   npm run build:mcp
   

2. Add to Claude Desktop configuration:

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

3. Restart Claude Desktop

Quick Start

In VS Code/Cursor/Windsurf

1. Open Command Palette (Cmd+Shift+P)
2. Run "Hanzo: Analyze Project" to scan your codebase
3. Use "Hanzo: Show Analysis" to view insights

In Claude Desktop

Simply ask Claude to use the tools:

Search for authentication-related code in the project

Create a comprehensive analysis of the codebase architecture

Find all TODO comments and create a task list

Core Tools

Search & Navigation

• unified_search - Parallel search across all dimensions
• grep - Pattern search with ripgrep
• symbols - Find functions, classes, methods
• find_files - Locate files by pattern

File Operations

• read - Read file contents with pagination
• write - Create or overwrite files
• edit - Precise text replacement
• multi_edit - Multiple edits in one operation

Development

• todo - Advanced task management
• think - Structured reasoning space
• critic - Code review and analysis
• process - Background task management

Web & External

• web_fetch - Fetch and parse web content
• open - Open files/URLs in default apps

Configuration

• palette - Switch tool contexts
• rules - Read project conventions
• config - Manage settings

Tool Palettes

Pre-configured tool sets for different workflows:

• Minimal: Basic file operations only
• Python: Python development tools
• JavaScript: JS/TS development tools
• DevOps: System and deployment tools
• Data Science: Analysis and notebook tools

Activate a palette:

{
  "action": "activate",
  "name": "python"
}

Configuration

VS Code Settings

{
  "hanzo.analysis.enabled": true,
  "hanzo.analysis.autoAnalyze": true,
  "hanzo.analysis.excludePatterns": ["**/node_modules/**", "**/dist/**"],
  "hanzo.mcp.enabled": true,
  "hanzo.mcp.enabledTools": ["read", "write", "search"],
  "hanzo.auth.apiKey": "your-api-key"
}

Environment Variables

# Core settings
HANZO_WORKSPACE=/path/to/project
HANZO_API_KEY=your-api-key

# 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

Advanced Features

Project Analysis

The extension automatically analyzes your codebase to understand:

• Technology stack and frameworks
• Code complexity and quality metrics
• Dependency relationships
• Common patterns and anti-patterns

Background Processes

Run long-running tasks without blocking:

{
  "action": "run",
  "command": "npm run build",
  "name": "build-process"
}

Monitor with:

{
  "action": "logs",
  "id": "process-id",
  "tail": 50
}

Web Research

Fetch documentation or API responses:

{
  "url": "https://docs.example.com/api",
  "format": "text",
  "max_length": 10000
}

Development

Building from Source

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Run tests
npm test

# Build MCP server
npm run build:mcp

# Package extension
npm run package

Testing Tools

# Test MCP server
node out/mcp-server-standalone.js --version

# Test with sample workspace
node out/mcp-server-standalone.js --workspace ./test-project

Debug Mode

1. Open project in VS Code
2. Press F5 to launch Extension Development Host
3. Test commands in the new window

Architecture

extension/
├── src/
│   ├── extension.ts          # Main entry point
│   ├── mcp/
│   │   ├── server.ts         # MCP server integration
│   │   ├── tools/            # Tool implementations
│   │   └── prompts/          # AI prompts
│   ├── services/             # Core services
│   │   ├── AnalysisService.ts
│   │   ├── ProjectManager.ts
│   │   └── FileCollectionService.ts
│   └── auth/                 # Authentication
├── out/                      # Compiled JavaScript
└── docs/                     # Documentation

Troubleshooting

Extension not loading

1. Check VS Code version (requires 1.85.0+)
2. Verify compilation: npm run compile
3. Check extension logs: View > Output > Hanzo

MCP tools not available in Claude

1. Verify server runs: node out/mcp-server-standalone.js --help
2. Check Claude Desktop config path
3. Restart Claude Desktop
4. Check Claude developer console for errors

Search not finding results

1. Install ripgrep: brew install ripgrep (macOS)
2. Check file permissions
3. Verify git repository for git search

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

See CONTRIBUTING.md for details.

Security

• All file operations respect workspace boundaries
• Shell commands run with limited permissions
• API keys stored securely in VS Code
• No telemetry or data collection

License

This project is licensed under the MIT License - see LICENSE for details.

Support

• Documentation: docs/MCP_TOOLS.md
• Issues: GitHub Issues
• Discord: Hanzo Community

Acknowledgments

• Built on the Model Context Protocol
• Inspired by the Python FastMCP framework
• Uses ripgrep for fast searching

---

Made with ❤️ by the Hanzo team