使用说明

• 项目简介

  • 这是一个面向 MCP 客户端的服务器实现，核心功能是通过缓存机制向 LLM 客户端提供文件读取相关的资源与工具，并通过 MCP 规范进行请求-响应。它还提供缓存统计、清理等辅助能力，减少重复读取带来的 token 开销。

• 主要功能点

  • 4 个 MCP 工具：
    • read_file：带缓存的单文件读取。首次读取返回完整内容并缓存，后续若未改动返回简短确认或差异（diff），支持按行偏移与限额进行分页读取。
    • read_files：批量读取多个文件，返回每个文件的缓存/差异结果。
    • cache_status：显示缓存统计信息（已跟踪的文件数量、_token_saved_等）。
    • cache_clear：清空缓存。
  • 多个会话隔离：不同的会话ID会维护各自的读取指针和缓存状态，确保并发场景中的正确性。
  • 差异化传输：在文件变化时返回 diff，而非整文件内容，显著减少 token 消耗。
  • partial read 支持：可指定 offset 与 limit 进行局部读取，并且如果变化未涉及所请求的范围则会返回“unchanged”提示以节省 token。
  • 服务器通过 Stdio 传输与 MCP 客户端通信，具备会话管理、能力声明与可扩展的传输方式。

• 安装步骤

  • 确保环境中安装了 bun 或兼容运行时（示例中使用 bun 的执行方式）。
  • 获取依赖并安装：按照项目常规的依赖安装流程执行，例如使用 bun install。
  • 启动 MCP 服务器：执行命令 npx cachebro serve（或等效的 bun-based 启动方式），服务器将监听并对接 MCP 客户端。

• 服务器配置（MCP 客户端需要的最小信息） 说明：MCP 客户端必须配置服务器的启动信息，以便建立连接。以下为示例配置，实际使用应以你的客户端支持的配置格式为准。

  { "name": "cachebro", "command": "npx", "args": ["cachebro", "serve"] }

  说明与要点：

  • name：服务器在 MCP 客户端的标识，应与实际服务器名称保持一致（此实现中名称为 cachebro）。
  • command 与 args：用于启动服务器的命令及其参数，客户端将据此启动并连接到该 MCP 服务器。
  • 额外可选项：如果需要自定义缓存目录、会话ID、要监视的路径等，可以在部署时根据需要扩展命令行参数或环境变量。

• 基本使用方法

  • 启动后，MCP 客户端可以通过 tool 调用以下工具：
    • read_file：传入 path、可选的 offset、limit，以及 force（强制 bypass 缓存返回全量内容）。
    • read_files：传入 paths 数组，获取多文件的缓存/差异结果。
    • cache_status：获取当前缓存统计信息。
    • cache_clear：清空已缓存的内容。
  • 具体使用时，LLM 客户端会根据工具描述自动发现适用的参数与返回格式，服务器会按 MCP 规定返回 JSON-RPC 风格的响应。

• 兼容性与注意事项

  • 该实现依赖嵌入式数据库（Turso）来实现文件版本与会话状态的持久化，适合离线或本地运行场景。
  • 对于大文件，partial read 提供了跨会话的缓存效率与 diff 传输能力，能显著降低 token 消耗。
  • 环境变量 CACHEBRO_DIR 可以控制缓存数据库路径。