Hanzo MCP

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

<a href="https://glama.ai/mcp/servers/@hanzoai/mcp"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@hanzoai/mcp/badge" /> </a>

概述

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

功能

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

已实现的工具

工具	描述
read_files	读取一个或多个文件，具有编码检测
write_file	创建或覆盖文件
edit_file	对文本文件进行基于行的编辑
directory_tree	获取目录的递归树状视图
get_file_info	获取文件或目录的元数据
search_content	在文件内容中搜索模式
content_replace	替换文件内容中的模式
run_command	执行 shell 命令（也用于目录创建、文件移动和目录列表）
run_script	使用指定的解释器执行脚本
script_tool	以特定编程语言执行脚本
project_analyze_tool	分析项目结构和依赖项
rule_check	搜索和检索定义特定技术的 AI 编码标准的游标规则
run_mcp	管理和交互多个 MCP 服务器（浏览器自动化、Slack、GitHub 等）
read_notebook	从 Jupyter Notebook 的所有单元格中提取和读取源代码，包括输出
edit_notebook	在 Jupyter Notebook 中编辑、插入或删除单元格
symbol_find	在文件或目录中查找符号定义
symbol_references	在文件或目录中查找对符号的引用
ast_explore	探索和可视化文件的 AST
ast_query	使用 tree-sitter 查询语言查询 AST
symbolic_search	执行各种符号搜索操作（相关符号、模式、用法等）
vector_index	在向量存储中索引文件或目录以进行语义搜索
vector_search	使用语义搜索功能搜索向量存储
vector_delete	从向量存储中删除文档
vector_list	列出向量存储中已索引的文档
think	用于复杂推理和分析的结构化空间，无需进行更改

开始使用

用法

配置 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 可以与其他 MCP 服务器（如 iTerm2-MCP 或 Neovim-MCP）集成。您可以通过以下几种方式启用和管理这些服务器：

1. 使用命令行:

# 直接指定 MCP 服务器命令
uvx run hanzo-mcp --allow-path /path/to/project --mcp="npx -y iterm-mcp" --mcp="npx -y @bigcodegen/mcp-neovim-server"

# 或使用管理 UI
uvx run hanzo-mcp-servers ui

2. 使用注册表:

# 查看可用的服务器
uvx run hanzo-mcp-servers registry search

# 从注册表安装服务器
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 frontmatter，后跟 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",             # 搜索与 React 相关的规则
    project_dir="/path/to/project",  # 可选：在项目目录中查找
    include_preinstalled=True,      # 包括内置规则
    detailed=False                  # 设置为 True 以获取完整的规则内容
)

这有助于像 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 工具访问符号工具：

# 在文件中查找符号
result = await dev(
    ctx,
    operation="symbol_find",
    path="/path/to/file.py",
    symbol_name="MyClass"  # 可选：要查找的特定符号
)

# 查找对符号的引用
result = await dev(
    ctx,
    operation="symbol_references",
    path="/path/to/project",
    symbol_name="my_function",
    recursive=True
)

# 探索文件的 AST
result = await dev(
    ctx,
    operation="ast_explore",
    path="/path/to/file.py",
    output_format="structure"  # 选项：json、text、html、structure
)

# 执行符号搜索
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 控制 Web 浏览器、导航到 URL、单击按钮、填写表单等。

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

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

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

使用 Run MCP 工具

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

# 列出可用的 MCP 服务器
result = await dev(ctx, operation="run_mcp", subcommand="list")

# 启动特定的 MCP 服务器
result = await dev(ctx, operation="run_mcp", subcommand="start", server_name="browser-use")

# 获取有关服务器的信息
result = await dev(ctx, operation="run_mcp", subcommand="info", server_name="browser-use")

# 添加自定义 MCP 服务器
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 服务器中实现这些功能。

Meta MCP 服务器

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

功能

• 统一界面: 通过单个入口点管理所有内容
• 自动配置: 根据可用的 API 密钥检测和初始化服务器
• 异步操作: 所有服务器操作都使用 asyncio 以获得流畅的性能
• 动态工具发现: 自动公开来自所有正在运行的子服务器的工具

安装

安装所有可选依赖项：

pip install hanzo-mcp[all]  # 包括所有可选依赖项

或者只安装您需要的：

pip install hanzo-mcp[subservers]  # 仅子服务器支持
pip install hanzo-mcp[rules]       # 仅规则支持
pip install hanzo-mcp[vector]            # 具有基于 API 的嵌入的向量存储（VoyageAI、OpenAI、Anthropic）
pip install hanzo-mcp[vector,sentencetransformer]  # 具有本地嵌入支持的向量存储

命令行用法

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 文件中定义您的 Meta 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():
    # 创建 Meta MCP 服务器
    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"]
            }
        }
    )

    # 启动子 MCP 服务器
    await meta_server.start()

    # 运行服务器
    meta_server.run()

# 运行异步 main 函数
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 均不可用，则向量操作将失败并显示清晰的错误消息。

使用向量搜索

# 为向量搜索索引目录
result = await dev(
    ctx,
    operation="vector_index",
    path="/path/to/project",
    recursive=True,
    file_pattern="*.py"  # 可选：仅索引 Python 文件
)

# 执行语义搜索
result = await dev(
    ctx,
    operation="vector_search",
    query_text="How does authentication work?",
    project_dir="/path/to/project",
    n_results=5  # 返回前 5 个结果
)

许可证

此项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。