Agent 与 MCP

本页适用于 Depsilo v0.9.4。Depsilo 提供两种互补的 Agent 集成：

• depsilo init-agent 把人类可读、可审阅的包管理器指令写入项目规则文件。
• POST /mcp 为支持 MCP 的客户端提供经过认证的结构化只读工具。

不要复用 bootstrap token

bootstrap token 只用于首次 Setup。Agent 文件不需要密钥；MCP 应使用在 Admin 中创建的普通只读 API token。

写入项目 Agent 指令

Docker 快速开始只会启动服务容器，不会在宿主机安装 depsilo 命令。先安装与服务匹配的 CLI；下面的安装器与目标版本都固定为 v0.9.4，适用于 Linux 和 macOS。其他平台请从 v0.9.4 发布页下载对应归档。

1. 安装并核对 CLI 版本

   终端

   curl -fsSL https://github.com/depsilo/depsilo/releases/download/v0.9.4/install.sh \
     | DEPSILO_VERSION=v0.9.4 bash
   depsilo version

2. 进入目标项目并预览

   cd my-project
   DEPSILO_URL=http://localhost:23333 depsilo init-agent --dry-run

3. 确认目标文件后写入

   DEPSILO_URL=http://localhost:23333 depsilo init-agent

4. 审阅变更

   自动模式会检测 CLAUDE.md、AGENTS.md、.claude/、.cursor/ 或 .cursorrules；没有任何已知约定时会创建 AGENTS.md。只审阅并提交你希望与团队共享的文件。

Depsilo 只管理带 marker 的区块：

<!-- depsilo:start -->
...
<!-- depsilo:end -->

再次运行会原位更新该区块，区块外的用户内容保持不变。--format=all 可显式生成全部三种格式，--out 可选择目录，--endpoint 可覆盖 DEPSILO_URL：

depsilo init-agent --format=all --out ./my-project \
  --endpoint http://depsilo.lan:23333

命令会优先读取实例公开的 GET /api/v1/agent-prompt；服务暂时不可达时，会使用 CLI 内置模板。两种情况都只写连接说明，不会把 bootstrap token、API token 或管理员凭据写入项目。

连接 MCP

MCP endpoint 是 Depsilo 服务根下的 /mcp。v0.9.4 的传输和认证约定如下：

项目	值
URL	http://localhost:23333/mcp
Transport	Streamable HTTP，JSON-RPC 2.0
HTTP method	POST
Header	Authorization: Bearer <token>
Token	Admin 中创建的 readonly API token

这不是 stdio server，也没有独立 MCP 端口或 depsilo mcp 子命令。不同 MCP 客户端的配置文件格式各不相同；按客户端要求填写上面的 URL 和 Authorization header 即可。

创建并保存 token

在 Admin 的 Users 页面创建 readonly API token。明文 token 只在创建响应中显示一次，请立即交给你使用的密钥管理器，然后在当前 shell 中设置：

export DEPSILO_READ_TOKEN='rc_...'

验证协议

initialize

curl -fsS -X POST http://localhost:23333/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $DEPSILO_READ_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

成功响应会标识 Depsilo server，并协商协议版本 2024-11-05。

tools/list

curl -fsS -X POST http://localhost:23333/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $DEPSILO_READ_TOKEN" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

tools/call

curl -fsS -X POST http://localhost:23333/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $DEPSILO_READ_TOKEN" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"depsilo_status","arguments":{}}}'

只读工具

v0.9.4 暴露以下工具，当前全部是只读操作：

Tool	返回内容
depsilo_status	服务版本、健康状态、最近 24 小时请求、命中率、缓存和已配置生态
depsilo_doctor	带 ok / warn / fail 提示的诊断检查
depsilo_configure	指定生态的 shell 或配置片段；不会修改客户端文件
depsilo_search	按名称和可选生态搜索本地缓存
depsilo_recent	最近的缓存命中与未命中事件
depsilo_warmup	只返回预热所需的 Admin API 请求模板

warmup 不执行预热

depsilo_warmup 的结果包含 executed: false。它不会排队或下载包，只会返回一个需要管理员凭据的 POST /api/v1/admin/cache/warmup 模板。只有操作者审阅后，另行发送该请求，才会发生写操作。

Resources 与 Prompt

MCP 还提供：

• depsilo://discover：当前实例的生态、endpoint 和版本目录。
• depsilo://stats：请求数、命中率、缓存大小和 upstream 健康快照。
• setup prompt：面向 coding agent 的项目接入说明。

可通过 resources/list、resources/read、prompts/list 和 prompts/get 发现并读取它们。

安全边界

• 为 MCP 使用最小权限的 readonly token，并设置合理的有效期。
• 不要把 token 提交到 AGENTS.md、CLAUDE.md、.cursorrules 或仓库中的 MCP 配置。
• depsilo_configure 返回的片段仍需人工审阅，尤其是 APT sources 和 Docker daemon 等主机级配置。
• /mcp 要求 Bearer 认证；GET /api/v1/agent-prompt 和 GET /api/v1/discover 则是公开的自描述接口。