Heimdall MCP Server

使用说明（Markdown 版本）

• 项目简介

  • Heimdall 是一个基于 MCP 的 TypeScript 后端服务器，旨在向 LLM 客户端提供规范化的资源管理、工具执行和提示渲染能力，并通过 JSON-RPC 与客户端进行通信，支持多种传输方式（如标准输入输出、WebSocket 等）。核心特点包括在浏览器/ WASM 沙箱中执行 Python（通过 Pyodide）和 Bash（通过 just-bash），以及安全的虚拟文件系统与工作区同步。

• 主要功能点

  • 沙箱执行
    • Python 运行在 WebAssembly 沙箱中（Pyodide），具备工作区 /workspace 的文件 I/O 与包管理能力，默认禁止网络访问。
    • Bash 在不创建真实子进程的情况下执行命令，提供对工作区的共享虚拟文件系统（Virtual FS）访问。
  • 资源与工具管理
    • 提供 MCP 资源（如工作区文件列表、特定文件内容、系统信息等）和 MCP 工具（执行 Python、执行 Bash、文件读写/列举等）。
  • 安全与隔离
    • 通过虚拟文件系统、路径验证、符号链接保护、执行超时、工作区大小限制等机制，防止对宿主机的未授权访问或越权操作。
  • 跨语言协同
    • Bash 与 Python 共享同一工作区，支持在 Python 中生成数据再由 Bash 读取、或由 Bash 产出数据给 Python 进一步处理。
  • 灵活的部署与配置
    • 通过环境变量控制工作区路径、文件大小、工作区总大小、Python 执行超时等参数，方便在不同环境中调整。

• 安装步骤

  • 直接在支持 Node.js 的环境中安装依赖并构建。
  • 常见流程：npm install，然后根据需要运行开发模式（如 npm run dev）或生产构建（npm run build；npm start）。

• 服务器配置（MCP 客户端连接所需信息）

  • MCP 客户端需要的配置信息不是代码，而是描述服务器如何被启动与访问的文本信息。以下为可参考的配置要素（以 JSON 结构描述，非代码块展示，便于阅读）：
  • server 名称：heimdall，对应同仓库中的 MCP 服务器名称。
  • command：node
  • args：dist/server.js（生产构建后的入口），或 tsx src/server.ts（开发时直接运行 TS 源码）
  • cwd：/path/to/heimdall（服务器项目根目录的实际路径）
  • env/可选：HEIMDALL_WORKSPACE、HEIMDALL_MAX_FILE_SIZE、HEIMDALL_MAX_WORKSPACE_SIZE、HEIMDALL_PYTHON_EXECUTION_TIMEOUT_MS 等环境变量，用于覆盖默认行为
  • 说明：MCP 客户端在首次连接前需要知道服务器的启动命令与工作目录，以及环境变量设置，以便正确创建并维持会话。

• 基本使用方法

  • 启动服务器后，确保工作区目录存在并具有读写权限。
  • 使用 MCP 客户端（如 Cursor、其他实现）与 Heimdall 建立 JSON-RPC 连接，调用工具（如 execute_python、execute_bash、write_file、read_file、list_files 等）来执行任务、管理文件、读取资源等。
  • 使用资源接口读取 heimdall-info、workspace 文件等信息，或通过工具完成跨语言的数据处理工作流。
  • 调整环境变量以适配不同的运行场景，例如更改工作区路径、增加安全阈值或延长 Python 执行时间等。

• 运行与测试的注意事项

  • 首次启动 Pyodide 及工作空间初始化可能需要一定时间，请在初次调用工具前留出准备时间。
  • 对于安全性测试，请在受控环境中执行，结合仓库中的安全策略验证等。

• 典型场景示例

  • Python 与 Bash 协作分析数据：Bash 生成数据文件，Python 读取并分析，结果再由 Bash 格式化输出。
  • 通过 install_packages 安装纯 Python 包（如 numpy、pandas）并在 Python 代码中使用。
  • 通过 read_file / write_file 对工作区内文件进行读写并在两种运行环境之间共享数据。

• 重要配置要点

  • HEIMDALL_WORKSPACE 用于指定工作区的宿主机路径（如 /path/to/workspace）。
  • HEIMDALL_MAX_FILE_SIZE 指定单个文件最大字节数（默认 10MB）。
  • HEIMDALL_MAX_WORKSPACE_SIZE 指定工作区总大小上限（默认 100MB）。
  • HEIMDALL_PYTHON_EXECUTION_TIMEOUT_MS 指定 Python 代码执行超时（单位毫秒，默认 5000）。
  • 服务器以 MCP JSON-RPC 的形式对外提供服务，客户端通过标准输入输出（stdio）或其他传输方式进行通信。

• 交互要点与安全要点

  • 保护工作区不被符号链接导向外部路径，确保对外部系统的访问被严格限制。
  • 运行时执行超时机制，防止无限循环导致服务器阻塞。
  • 文件 I/O 的同步与原子性通过锁实现，防止并发写入造成的竞态条件。