通过 MCP 接入

模型上下文协议(Model Context Protocol,MCP)让 Agent 直接使用 Loci 的文档发现、搜索、阅读和管理工具。Loci 面向本机 Agent 统一使用 CLI stdio:客户端按需启动进程,不需要维护常驻 MCP 服务或固定端口。

快速配置

先安装 CLI:

npm install --global @boses/cli

推荐一次配置 MCP、全局 Skill 和 Rules:

loci agent setup codex

只配置 MCP 时,使用细粒度命令。Codex、Cursor、VS Code、Claude Code 和 Google Antigravity 都使用同一个 stdio 命令:

loci agent connect codex --yes
loci agent connect cursor --yes
loci agent connect vscode --yes
loci agent connect claude-code --yes
loci agent connect antigravity --yes

写入后,新建一个 Agent 会话,使客户端重新加载 MCP 配置。

使用 loci agent status <client> 检查 MCP、Skill 和 Rules 的独立状态;loci agent remove <client> 只移除能确认属于 Loci 的 loci 服务,保留同一文件中的其他 MCP。

手动配置

未内置的客户端可以打印通用配置:

loci agent print-config generic

目标文件已有其他 MCP 服务时,只添加 loci,不要覆盖整个文件:

{
  "mcpServers": {
    "loci": {
      "command": "loci",
      "args": ["mcp", "stdio"]
    }
  }
}

Google Antigravity 的本地 MCP 配置同样使用 command 和 args。Loci 会把配置合并到 ~/.gemini/config/mcp_config.json;也可以先运行下面的命令查看待复制内容:

loci agent print-config antigravity

项目级 MCP 配置会启动本地命令,只应在信任项目时使用。

运行语义

Agent 调用 Loci 工具时,客户端启动 loci mcp stdio;会话结束后 stdio 进程随之退出。同步写操作进入共享的 SQLite 持久任务队列,并由该进程的轻量 worker 执行;如果后台服务已经认领同一来源,当前进程会等待并读取同一任务的最终结果。

等待同步时,Loci 使用 MCP SDK 原生 Progress 逐页发送标题、URL 和结果,并接收 SDK Cancellation。取消本次调用新建的任务会停止实际抓取;取消一个复用已有任务的调用只停止跟随。Host 无法把原生进度或取消暴露给 Agent 时,use-loci Skill 会在任务启动前改用 CLI 降级流程,MCP Server 本身不维护客户端兼容矩阵。

loci service start 启动的是不监听 HTTP、也不承载 MCP 的常驻 worker。默认数据目录中的定时计划和云端每日同步会在开启时自动准备它;普通后台同步使用队列空闲后自动退出的按需 worker。上述自动准备在自定义 LOCI_DATA_DIR 下只启动 detached worker,不安装对应的登录或机器重启自启动定义;需要长期运行时应由外部进程管理器托管。

排查连接

如果客户端没有显示 Loci 工具:

  1. 运行 loci agent print-config <client>,确认客户端格式和配置路径。
  2. 确认 loci 在客户端进程的 PATH 中。
  3. 在终端运行 loci mcp stdio,确认没有启动错误;测试结束后按 Ctrl+C。
  4. 重新运行 loci agent setup <client> --yes 收敛全部接入项,或使用 connect 只修复 MCP,然后新建 Agent 会话。

下一步

客户端官方配置资料