mcp/MCP_DEMO.md

Hanzo MCP Search - E2E Demo Guide

✅ Setup Complete

The Hanzo MCP Search has been successfully:

1. Built and installed globally (@hanzo/mcp v2.0.0)
2. Configured with Claude Desktop
3. Tested with the CLI

🚀 How to Use with Claude Desktop

1. Restart Claude Desktop

After installation, restart Claude Desktop to load the MCP tools.

2. Available Tools

Once restarted, Claude will have access to these search tools:

search Tool

Search across your codebase with the following parameters:

• query (required): Search query text
• maxResults (optional): Limit results (default: 10)
• filePattern (optional): File glob pattern (e.g., ".ts", "**/.js")

Example prompts to try in Claude:

"Search for 'LanceDB' in the codebase"
"Find all TypeScript files containing 'search'"
"Look for 'function' in JavaScript files"

fetch Tool

Fetch full document content by ID:

• id (required): Document ID from search results

3. Testing the Integration

In a new Claude conversation, try these commands:

1. Basic Search Test: "Use the search tool to find files containing 'vector'"

2. Pattern Search Test: "Search for 'export' in TypeScript files only"

3. Fetch Document Test: "Search for 'search' and then fetch the first result"

4. CLI Usage

You can also use the CLI directly:

# Start the server
hanzo-mcp serve

# Check version
hanzo-mcp --version
# Output: 2.0.0

# Install to Claude Desktop (already done)
hanzo-mcp install-desktop

🔒 Security Features

Ngrok Integration (Optional)

To enable secure remote access:

# Set ngrok token
export NGROK_AUTHTOKEN=your_token_here
export NGROK_ENABLED=true
export ACCESS_TOKEN=your_secure_token

# Start server with ngrok
hanzo-mcp serve

When ngrok is enabled:

• Files are served over HTTPS with post-quantum TLS
• ACCESS_TOKEN authentication required
• URLs automatically use ngrok tunnel

Local Mode (Default)

Without ngrok configuration:

• Files use file:// URLs
• Only accessible locally
• No external exposure

🧪 Testing

Run Direct Tests

# Run the test script
node test-search.js

Expected Output Format

Search results follow OpenAI MCP specification:

{
  "results": [
    {
      "id": "unique-id",
      "title": "filename.ts:42",
      "url": "file:///path/to/file"
    }
  ]
}

Fetch results return:

{
  "id": "unique-id",
  "title": "filename.ts",
  "text": "file content...",
  "url": "file:///path/to/file",
  "metadata": {
    "type": "code",
    "language": "typescript"
  }
}

📁 Project Structure

/Users/z/work/hanzo/mcp/
├── src/
│   ├── search/          # Unified search implementation
│   │   ├── index.ts     # Main search & fetch tools
│   │   ├── strategies/  # Search strategy pattern
│   │   ├── secure-tunnel.ts  # Ngrok integration
│   │   └── url-helper.ts     # URL generation
│   └── tools/           # All MCP tools
├── dist/                # Built output
├── test-search.js       # Direct test script
└── package.json         # v2.0.0

🎯 Features

• Multi-modal Search: Text, AST, Symbol, Vector, File
• OpenAI MCP Compliance: Standard search and fetch tools
• Extensible Architecture: Strategy pattern for new search types
• Secure Remote Access: Optional ngrok with authentication
• 54 Total Tools: Including UI, AutoGUI, and Orchestration tools

📊 Current Status

• ✅ CLI installed and working
• ✅ Claude Desktop configured
• ✅ Server can be started
• ✅ Search returns MCP-compliant format
• ✅ Build process optimized
• ⚠️ CI has test failures (non-blocking)

🔧 Troubleshooting

If Claude doesn't show the tools:

1. Fully quit Claude Desktop (not just close window)
2. Restart Claude Desktop
3. Check config: ~/Library/Application Support/Claude/claude_desktop_config.json

If search returns no results:

1. Ensure you're in a directory with code files
2. Try broader search terms
3. Check file patterns match your project

📝 Next Steps

1. In Claude Desktop: Try the search commands above
2. Set up ngrok (optional): For remote access capability
3. Customize search: Add project-specific search strategies
4. Monitor usage: Check server logs for debugging

---

Version: 2.0.0
NPM Package: @hanzo/mcp
GitHub: https://github.com/hanzoai/mcp