Tree Climber MCP

Tree Climber MCP

Safely connect AI models to a local shell environment.

xonsh-powered • Secure command execution • MCP compliant

关于

Tree Climber MCP是一个模型上下文协议（MCP）服务器，允许AI模型与本地 xonsh shell和一小部分文件系统帮助程序。Shell命令通过块列表进行过滤，默认情况下，文件系统操作仅限于Shell的当前工作目录树。

特性

• 符合MCP标准： 实现模型上下文协议，与MCP客户端（如Claude Desktop或其他AI代理）无缝集成。
• 安全外壳执行： 用途 xonsh （Python驱动的shell）用于命令执行。
• 文件系统助手： 暴露 read_file, write_file，以及 list_directory 在shell工具旁边。
• 安全第一： 阻止危险的shell命令（例如 rm -rf /, sudo bash，以及 curl ... | bash)并限制文件系统对活动工作目录的访问，除非您明确选择进入更广泛的范围。
• 异步服务器接口： 用途 asyncio 用于MCP请求处理和生命周期管理。
• 广泛测试： 包括一个全面的单元测试套件，确保可靠性和安全性。

先决条件

• Python 3.12+
• 紫外线：建议用于依赖关系管理。
• uv sync 安装Python依赖项，包括 xonsh，进入项目环境。

安装和设置

1. 克隆存储库：

   git clone https://github.com/crybo-rybo/tree-climber-mcp.git
   cd tree-climber-mcp

1. 安装依赖项：

此项目使用 uv 用于包管理。

   uv sync

用法

运行服务器

服务器通常作为子进程运行，通过以下方式进行通信 stdio.要手动启动它（例如，用于调试）：

uv run tree-climber-mcp

可选的文件系统作用域标志：

• uv run tree-climber-mcp --filesystem-root /some/folder：保持启用文件系统保护，但使用 /some/folder 作为受信任的根目录，而不是shell的工作目录。
• uv run tree-climber-mcp --allow-all-paths：完全禁用文件系统路径限制 read_file, write_file，以及 list_directory.

--allow-all-paths 和 --filesystem-root 是相互排斥的。

与MCP客户端集成

要将其与MCP客户端（如Claude Desktop）一起使用，请将客户端配置为从存储库目录运行服务器命令。

示例 claude_desktop_config.json:

{
  "mcpServers": {
    "tree-climber": {
      "command": "/path/to/uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/tree-climber-mcp",
        "tree-climber-mcp"
      ]
    }
  }
}

要扩大Claude Desktop中的文件系统访问权限，请在 args 数组：

{
  "mcpServers": {
    "tree-climber": {
      "command": "/path/to/uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/tree-climber-mcp",
        "tree-climber-mcp",
        "--filesystem-root",
        "/absolute/path/to/workspace"
      ]
    }
  }
}

“当前工作目录”是什么意思

默认情况下，文件系统工具信任MCP服务器进程的当前工作目录。在实践中，对于Claude Desktop来说，这是服务器命令启动方式所隐含的目录。

• 如果你使用 uv run --directory /absolute/path/to/tree-climber-mcp tree-climber-mcp，默认的受信任根将是 /absolute/path/to/tree-climber-mcp.
• 如果你想要一个不同的根，通过 --filesystem-root /absolute/path/to/workspace.
• 如果你根本不想进行文件系统包含检查，请通过 --allow-all-paths.

安全

爬树人MCP应用了两个安全层：

• Shell命令将根据中的正则表达式列表进行检查 src/tree_climber_mcp/security.py.
• 默认情况下，文件系统工具在shell的当前工作目录树中运行。
• --filesystem-root PATH 保持相同的保护，但将受信任的根更改为 PATH.
• --allow-all-paths 完全禁用文件系统路径包含检查。

阻塞外壳类别包括：

• 系统破坏： rm -rf /，格式化磁盘。
• 特权升级： sudo bash，系统关闭命令。
• 远程代码执行： curl | bash, wget | sh.
• 资源消耗/扫描： 叉式炸弹， masscan, nmap.

注： 虽然有重要的保障措施，但在授予AI代理访问您的终端时，请务必谨慎行事。

发展

运行测试

此项目使用 pytest 用于单元测试。测试套件涵盖了命令验证、shell交互和服务器逻辑。

PYTHONPATH=src uv run pytest

项目结构

• src/tree_climber_mcp/__main__.py：使用的CLI入口点 uv run tree-climber-mcp.
• src/tree_climber_mcp/server.py：向MCP服务器注册shell和文件系统工具。
• src/tree_climber_mcp/tools/command.py：验证并运行shell命令。
• src/tree_climber_mcp/tools/filesystem.py：执行 list_directory, read_file，以及 write_file.
• src/tree_climber_mcp/shell.py：管理持久 xonsh 子流程。
• src/tree_climber_mcp/config.py 和 src/tree_climber_mcp/security.py：运行时配置和被阻止的命令定义。
• tests/：pytest覆盖率镜像包布局。