使用说明

项目简介

Lootbox-Bun 是一个专为大型语言模型（LLM）设计的后端服务，它实现了“代码模式”的概念。不同于传统的工具调用方式，Lootbox-Bun 允许LLM直接编写TypeScript代码来编排和执行一系列操作。它内部封装了多种实用工具，例如用于文件操作、键值存储、数据库交互、知识图谱、AI模型（如Gemini, Claude, Codex）调用以及浏览器自动化等。通过其内置的MCP桥接器，Lootbox-Bun 能将其提供的所有工具和功能以标准化的MCP协议暴露给兼容的LLM客户端（如Claude Code），从而扩展LLM的能力范围。

主要功能点

代码模式执行: 允许LLM生成和执行真实的TypeScript代码，以调用外部API和工具，实现复杂的任务链。
丰富内置工具: 提供多种开箱即用的工具，包括：
- 数据管理: 键值存储 (KV), SQLite, 本地文件系统等数据访问能力。
- 知识与文档: 'basic_memory' (本地知识库管理), 'deepwiki' (GitHub仓库文档理解与问答)。
- AI模型集成: 'gemini' (文本分析与研究), 'gemini_image' (图像分析), 'council' (多AI模型并行查询与比较)。
- 自动化: 'chrome_devtools' (浏览器自动化), 'tmux' (终端会话管理)。
- 开发工具: 'promptfoo' (LLM提示词测试与评估), 'mcp_cli' (与其他MCP服务器交互)。
工作流管理: 支持定义多步骤的YAML工作流，集成Handlebars模板引擎，实现复杂任务的自动化。
MCP桥接器: 内置MCP服务器桥接器，能将Lootbox-Bun的所有工具自动转换为MCP工具，供LLM客户端通过标准MCP协议调用。
类型安全与IntelliSense: 为工具提供TypeScript类型定义，提升LLM代码生成的准确性。
沙盒执行: 用户脚本在隔离的Bun进程中运行，具备有限权限和超时机制，确保安全性。

安装步骤

安装Bun: 确保您的系统已安装Bun v1.0或更高版本。您可以访问Bun官网获取安装指南。

克隆仓库: 打开终端，运行以下命令克隆Lootbox-Bun仓库：

git clone https://github.com/johnlindquist/lootbox-bun
cd lootbox-bun

安装依赖: 在仓库目录中运行以下命令安装项目依赖：
```
bun install
```

（可选）安装'basic-memory' CLI: 如果您计划使用'basic_memory'工具，需要额外安装其CLI（需要Python 3.10+）：

pip install basic-memory
# 或者
pipx install basic-memory

服务器配置 (用于MCP客户端连接)

Lootbox-Bun 作为一个MCP服务器，通过其 'mcp-bridge.ts' 文件提供标准MCP接口。您需要先启动Lootbox-Bun的主服务器，然后通过 'mcp-bridge.ts' 启动MCP桥接服务器。

启动Lootbox-Bun主服务器: 打开一个终端窗口，运行以下命令启动Lootbox-Bun的主服务器。
```
bun run src/lootbox-cli.ts server --port 3456
```
请记住 '--port' 参数的值，例如 '3456'，它将在下一步的MCP桥接器配置中使用。
配置MCP客户端连接: 您的MCP客户端（例如Claude Code、其他LLM应用或支持MCP的IDE插件）需要配置以下信息才能连接到Lootbox-Bun提供的MCP服务器。请将以下MCP服务器配置片段添加到您的MCP客户端配置文件中（例如 '~/.claude/claude_desktop_config.json' 或您LLM应用指定的配置文件）：
```
{
  "mcpServers": {
    "lootbox": {
      "command": "bun",
      "args": ["run", "/path/to/lootbox-bun/mcp-bridge.ts"],
      "env": {
        "LOOTBOX_URL": "ws://localhost:3456/ws"
      },
      "description": "Lootbox-Bun MCP服务器，提供LLM代码模式和各种工具访问能力"
    }
  }
}
```
- '"lootbox"': 这是一个自定义的MCP服务器名称，您可以根据需要更改。
- '"command": "bun"': 启动MCP桥接器的命令。
- '"args": ["run", "/path/to/lootbox-bun/mcp-bridge.ts"]': 传递给'bun'命令的参数，用于运行 'mcp-bridge.ts' 脚本。务必将 '/path/to/lootbox-bun/' 替换为Lootbox-Bun仓库在您系统中的实际路径。
- '"env": { "LOOTBOX_URL": "ws://localhost:3456/ws" }': 环境变量，'LOOTBOX_URL' 指定Lootbox-Bun主服务器的WebSocket地址。务必将 'ws://localhost:3456/ws' 中的端口号与您启动Lootbox-Bun主服务器时使用的 '--port' 参数值 ('3456') 保持一致。
- '"description"': 对该MCP服务器的简要描述，帮助您在MCP客户端中识别。

基本使用方法

一旦MCP客户端连接成功，Lootbox-Bun的所有工具将通过 'namespace__function' 的格式暴露给LLM。

（通过MCP客户端）发现可用工具: 您的MCP客户端通常会提供一个界面或命令来发现已连接MCP服务器所提供的所有工具。例如，在Claude Code中，您连接配置完成后，可以直接在聊天界面中询问或查看可用工具列表。

（通过MCP客户端）调用工具示例: LLM客户端将能够以其支持的格式（例如，使用LLM的工具调用语法或通过生成TypeScript代码）来调用 Lootbox-Bun 提供的工具。

示例1：调用 'basic_memory' 工具来写入一条记忆： LLM可能会生成类似以下的调用（具体语法取决于您使用的LLM客户端）：

basic_memory__write_memory({
  title: "项目会议记录",
  content: "今日会议讨论了Q4目标，并制定了下一步计划。",
  folder: "工作记录",
  tags: "会议,Q4计划"
})

示例2：调用 'deepwiki' 工具来查询GitHub仓库文档并提问：

deepwiki__ask_question({
  repo_name: "facebook/react",
  question: "How does React Fiber work?"
})

这些工具调用将在Lootbox-Bun服务器上执行，并将结果返回给LLM客户端。

关键词