Hanzo MCP

Hanzo AI + 平台功能通过模型上下文协议 (MCP) 提供。

概述

该项目提供了一个 MCP 服务器，使用户能够访问 Hanzo API 和平台功能，并提供了用于管理和改进项目的开发工具。通过利用模型上下文协议，该服务器可以与各种 MCP 客户端（包括 Claude Desktop）无缝集成，允许 LLM 直接访问 Hanzo 平台的功能。

功能

• 代码理解：通过文件访问和模式搜索分析和理解代码库
• 代码修改：在适当权限处理的情况下对文件进行有针对性的编辑
• 增强的命令执行：运行多种语言的命令和脚本，改进错误处理和 shell 支持
• 文件操作：通过 shell 命令以适当的安全控制管理文件
• 代码发现：在整个项目中查找相关文件和代码模式
• 项目分析：理解项目结构、依赖项和框架
• Jupyter Notebook 支持：读取和编辑 Jupyter 笔记本，支持完整的单元格和输出处理
• 向量搜索：使用多种嵌入提供程序选项对代码库进行语义搜索

实现的工具

入门

使用方法

配置 Claude Desktop

无需安装，你可以直接使用 uvx run hanzo-mcp 运行它。通过在你的 Claude Desktop 配置文件中添加以下内容来配置 Claude Desktop 以使用此服务器：

{
  "mcpServers": {
    "hanzo": {
      "command": "uvx",
      "args": [
        "--from",
        "hanzo-mcp",
        "hanzo-mcp",
        "--allow-path",
        "/path/to/your/project"
      ]
    }
  }
}

请确保将 /path/to/your/project 替换为你希望 Claude 访问的实际项目路径。

高级配置选项

你可以使用其他选项来自定义服务器：

{
  "mcpServers": {
    "hanzo": {
      "command": "uvx",
      "args": [
        "--from",
        "hanzo-mcp",
        "hanzo-mcp",
        "--allow-path",
        "/path/to/project",
        "--name",
        "custom-hanzo",
        "--transport",
        "stdio"
      ]
    }
  }
}

与外部 MCP 服务器一起使用

Hanzo MCP 可以与像 iTerm2-MCP 或 Neovim-MCP 这样的其他 MCP 服务器集成。你可以通过几种方式启用和管理这些服务器：

1. 使用命令行：

# Directly specify MCP server commands
uvx run hanzo-mcp --allow-path /path/to/project --mcp="npx -y iterm-mcp" --mcp="npx -y @bigcodegen/mcp-neovim-server"

# Or use the management UI
uvx run hanzo-mcp-servers ui

1. 使用注册表：

# View available servers
uvx run hanzo-mcp-servers registry search

# Install a server from the registry
uvx run hanzo-mcp-servers registry install iterm2

配置 Claude Desktop 系统提示

为了获得 Hanzo MCP 的最佳体验，你需要将提供的系统提示添加到你的 Claude Desktop 客户端中。这个系统提示引导 Claude 通过一个结构化的工作流程来与 Hanzo 平台服务进行交互并管理项目文件。

按照以下步骤操作：

1. 在此仓库的 doc/system_prompt 找到系统提示文件。
2. 打开你的 Claude Desktop 客户端。
3. 创建新项目或打开现有项目。
4. 导航至 Claude Desktop 侧边栏中的“项目说明”部分。
5. 复制 doc/system_prompt 的内容并粘贴到“项目说明”部分。
6. 将 {project_path} 替换为你的项目的实际绝对路径。

系统提示为 Claude 提供了：

• 分析和修改代码的结构化工作流程
• 项目探索和分析的最佳实践
• 开发、重构和质量保证指南
• 数学内容的特殊格式化指令

这一步骤至关重要，因为它使 Claude 能够在帮助你修改代码时遵循一致的方法。

光标规则支持

Hanzo MCP 包含对 光标规则 的支持，允许你为 AI 生成的代码定义自定义指南。这些规则有助于确保代码生成遵循你项目的特定最佳实践和编码标准。

工作原理

1. 内置规则：该包预装了针对 JavaScript、TypeScript、Python 及其框架等常见技术的规则。

2. 项目特定规则：你可以在项目目录中创建自己的 .cursorrules 或 .rules 文件。

3. 规则格式：规则文件支持带有规则元数据的 YAML 前置事项，后跟 markdown 格式的指南。

---
name: My Custom Rules
description: Custom rules for my project
technologies:
  - JavaScript
  - React
focus:
  - frontend
---

# My Custom Rules

## Code Style
1. Use functional components with hooks
2. Follow naming conventions...

使用规则检查工具

你可以使用 dev 工具中的 rule_check 操作来搜索和检索规则：

result = await dev(
    ctx,
    operation="rule_check",
    query="react",             # Search for React-related rules
    project_dir="/path/to/project",  # Optional: look in project directory
    include_preinstalled=True,      # Include built-in rules
    detailed=False                  # Set to True for full rule content
)

这有助于像 Claude 这样的 AI 助手在生成或修改代码时遵循你项目的编码标准和最佳实践。

符号工具支持

Hanzo MCP 包括由 tree-sitter 支持的高级符号分析工具，提供了强大的代码理解和导航能力。

功能

• 符号查找: 查找变量、函数、类、方法等的定义
• 引用查找: 发现符号在整个代码库中的使用位置
• AST 探索: 通过抽象语法树浏览和理解代码结构
• 符号搜索: 在文件中查找相关的符号和模式

语言支持

符号工具支持多种编程语言，包括：

• Python
• JavaScript/TypeScript
• Java
• C/C++
• Go
• Ruby
• Rust
• 以及更多

安装

要使用符号工具，您需要安装可选依赖项：

pip install hanzo-mcp[symbols]

或者包含所有依赖项进行安装：

pip install hanzo-mcp[all]

使用符号工具

通过 dev 工具访问符号工具：

# Find symbols in a file
result = await dev(
    ctx,
    operation="symbol_find",
    path="/path/to/file.py",
    symbol_name="MyClass"  # Optional: specific symbol to find
)

# Find references to a symbol
result = await dev(
    ctx,
    operation="symbol_references",
    path="/path/to/project",
    symbol_name="my_function",
    recursive=True
)

# Explore AST of a file
result = await dev(
    ctx,
    operation="ast_explore",
    path="/path/to/file.py",
    output_format="structure"  # Options: json, text, html, structure
)

# Perform symbolic search
result = await dev(
    ctx,
    operation="symbolic_search",
    project_dir="/path/to/project",
    search_type="related_symbols",
    symbol_name="MyClass"
)

子 MCP 服务器支持

Hanzo MCP 可以与多个专门的 MCP 服务器集成并管理，提供一个统一的界面来访问各种功能：

内置服务器支持

1. 浏览器自动化: browser-use 服务器允许 Claude 控制网络浏览器，导航到 URL、点击按钮、填写表单等。

2. 计算机使用: computer-use 服务器（默认禁用）提供完整的计算机访问能力。

3. 服务集成: 当 API 密钥可用时自动启用：

   • Slack: 与 Slack 频道和消息互动
   • GitHub: 管理仓库、问题和拉取请求
   • Linear: 处理工单和项目管理

使用 run_mcp 工具

使用 dev 工具中的 run_mcp 操作来管理和与子 MCP 服务器交互：

# List available MCP servers
result = await dev(ctx, operation="run_mcp", subcommand="list")

# Start a specific MCP server
result = await dev(ctx, operation="run_mcp", subcommand="start", server_name="browser-use")

# Get info about a server
result = await dev(ctx, operation="run_mcp", subcommand="info", server_name="browser-use")

# Add a custom MCP server
result = await dev(
    ctx,
    operation="run_mcp",
    subcommand="add",
    name="custom-server",
    command="uvx",
    args=["my-custom-mcp-server"],
    env={"API_KEY": "your-api-key"}
)

启用这些额外的 MCP 服务器后，Claude 可以执行更广泛的任务，而无需在主 MCP 服务器中实现这些功能。

元 MCP 服务器

对于希望同时运行多个 MCP 服务器的高级用户，我们提供了 MetaMCPServer，它可以无缝协调一个主 MCP 服务器和多个子 MCP 服务器：

特性

• 统一接口: 通过单一入口点管理一切
• 自动配置: 根据可用的 API 密钥检测并初始化服务器
• 异步操作: 所有服务器操作都使用 asyncio 以确保流畅性能
• 动态工具发现: 自动暴露来自所有运行子服务器的工具

安装

安装所有可选依赖项：

pip install hanzo-mcp[all]  # Includes all optional dependencies

或仅安装所需内容：

pip install hanzo-mcp[subservers]  # Just sub-server support
pip install hanzo-mcp[rules]       # Just rules support
pip install hanzo-mcp[vector]            # Vector store with API-based embeddings (VoyageAI, OpenAI, Anthropic)
pip install hanzo-mcp[vector,sentencetransformer]  # Vector store with local embedding support

命令行使用

hanzo-meta-mcp --allow-path /path/to/project [options]

选项：

• --name: 服务器名称（默认: "hanzo-meta"）
• --transport: 要使用的传输方式（stdio 或 sse，默认: stdio）
• --allow-path: 允许访问的路径（可以多次指定）
• --config: 配置文件路径（JSON 格式）
• --disable-proxy-tools: 禁用子 MCP 服务器的代理工具
• --disable-auto-start: 禁用子 MCP 服务器的自动启动

配置文件

您可以在 JSON 文件中定义您的元 MCP 服务器配置：

{
  "mcp": {
    "name": "hanzo-meta"
  },
  "sub_mcps": {
    "browser-use": {
      "enabled": "auto",
      "command": "uvx",
      "args": ["mcp-server-browser-use"],
      "env": {
        "CHROME_PATH": "/path/to/chrome"
      }
    },
    "github": {
      "enabled": "auto",
      "command": "uvx",
      "args": ["mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}

程序化使用

您也可以在自己的 Python 脚本中以编程方式使用 MetaMCPServer：

import asyncio
from hanzo_mcp.meta_mcp import MetaMCPServer

async def main():
    # Create the Meta MCP Server
    meta_server = MetaMCPServer(
        name="hanzo-meta",
        allowed_paths=["/path/to/project"],
        sub_mcps_config={
            "browser-use": {
                "enabled": "true",
                "command": "uvx",
                "args": ["mcp-server-browser-use"]
            }
        }
    )

    # Start sub-MCP servers
    await meta_server.start()

    # Run the server
    meta_server.run()

# Run the async main function
if __name__ == "__main__":
    asyncio.run(main())

安全性

此实现遵循保护文件系统访问的最佳实践：

• 文件修改和命令执行的权限提示
• 仅限于指定目录的访问限制
• 输入验证和清理
• 正确的错误处理和报告

开发

要为该项目做贡献，请按照以下步骤操作：

1. 叉分（Fork）仓库
2. 创建一个特性分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 推送到该分支 (git push origin feature/amazing-feature)
5. 打开一个拉取请求（Pull Request）

向量存储嵌入选项

Hanzo MCP 包含一个基于 ChromaDB 的强大的向量存储，用于语义代码搜索。它支持通过设置适当的环境变量来启用多个嵌入提供者：

可用的嵌入提供者

1. VoyageAI（推荐）

   • 模型：voyage-large-2
   • 环境变量：VOYAGE_API_KEY 或 CHROMA_VOYAGE_API_KEY
   • 安装：pip install voyageai

2. OpenAI

   • 模型：text-embedding-3-small, text-embedding-3-large
   • 环境变量：OPENAI_API_KEY 或 CHROMA_OPENAI_API_KEY
   • 安装：pip install openai

3. Anthropic

   • 模型：claude-3-embedding-1
   • 环境变量：ANTHROPIC_API_KEY 或 CHROMA_ANTHROPIC_API_KEY
   • 安装：pip install anthropic

4. SentenceTransformer（可选，无需 API 密钥）

   • 模型：all-MiniLM-L6-v2
   • 不需要环境变量
   • 安装：pip install hanzo-mcp[vector,sentencetransformer]

嵌入提供者配置

Hanzo MCP 支持通过环境变量配置的多个用于向量搜索的嵌入提供者：

1. 默认安装 (pip install hanzo-mcp[vector]) 包括对基于 API 的嵌入提供者的支持，但要求您至少设置以下环境变量之一：

   • VOYAGE_API_KEY 或 CHROMA_VOYAGE_API_KEY 对于 VoyageAI（推荐）
   • OPENAI_API_KEY 或 CHROMA_OPENAI_API_KEY 对于 OpenAI
   • ANTHROPIC_API_KEY 或 CHROMA_ANTHROPIC_API_KEY 对于 Anthropic

2. 对于不需要 API 密钥的本地嵌入支持，请安装：pip install hanzo-mcp[vector,sentencetransformer]

系统将根据可用情况自动选择最佳的嵌入提供者。如果既没有 API 密钥也没有 sentence_transformers 可用，向量操作将以清晰的错误消息失败。

使用向量搜索

# Index a directory for vector search
result = await dev(
    ctx,
    operation="vector_index",
    path="/path/to/project",
    recursive=True,
    file_pattern="*.py"  # Optional: only index Python files
)

# Perform semantic search
result = await dev(
    ctx,
    operation="vector_search",
    query_text="How does authentication work?",
    project_dir="/path/to/project",
    n_results=5  # Return top 5 results
)

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。