Agent Breadcrumbs

面包屑代理商🍞

轻量级日志记录和跨客户端代理工作的可观察性（Codex、Claude、Cursor、ChatGPT、OpenClaw等）。

https://github.com/user-attachments/assets/3eac31a8-107c-4a82-a14c-dcfa500dd1a9

所得

• 一个MCP工具(log_work)它聚合了单个或多个用户在不同代理之间完成的工作。
• 使用自定义模式（或使用内置配置文件）定义自己的日志结构一次，然后使用MCP模式

将引导客户端使用正确的有效载荷登录。

• 这使团队能够一次性标准化日志记录，然后将数据路由到他们需要的地方。
• 输出汇的多种选择：

- 本地JSONL - 网络钩子 - Postgres

• 常见用例的初学者模式配置文件：

- 代理洞察 - 交货跟踪 - 审计追踪 - 知识获取

• 查看记录工作的简单仪表板应用程序。

仓库的规划

• MCP服务器包（已发布）： packages/mcp
• 仪表板应用程序（本地仓库，未发布）： apps/dashboard

快速启动（MCP）

安装并使用默认值运行：

npx -y agent-breadcrumbs

使用显式配置文件：

npx -y agent-breadcrumbs --config /absolute/path/to/server-config.json

Codex配置示例(~/.codex/config.toml):

[mcp_servers.agent_breadcrumbs]
command = "npx"
args = ["-y", "agent-breadcrumbs", "--config", "/absolute/path/to/server-config.json"]

--config 是可选的。如果省略，则使用服务器默认值：

克劳德桌面(claude_desktop_config.json):

{
  "mcpServers": {
    "agent-breadcrumbs": {
      "command": "npx",
      "args": ["-y", "agent-breadcrumbs", "--config", "/absolute/path/to/server-config.json"]
    }
  }
}

OpenClaw：

安装MCP服务器后，请确保使用mcporter，以便可以通过CLI调用服务器。 然后将系统提示添加到您正在使用的频道。

对于cron驱动的工作流，指示代理在每次计划运行时调用log_work 用于常规的基于时间的日志记录。

Every hour, make sure to use mcporter agent-breadcrumbs.log_work to log work.
If spinning up a cron job, make sure to add this context (e.g., logging work every hour) in the cron job description as well.

面向客户的通用示例全局指令/系统提示：

When a meaningful chunk of work is completed, use log_work with agent_breadcrumbs to record your work.

有关完整的MCP服务器设置、配置和接收器详细信息，请参阅 packages/mcp/README.md.

快速入门（回购）

npm install
npm run build:all

使用示例配置在本地运行MCP服务器：

node packages/mcp/dist/index.js --config packages/mcp/examples/server-config.agent-insights.sample.json

在本地运行仪表板：

npm run dev:dashboard -- --config apps/dashboard/examples/dashboard-config.sample.json

MCP配置模型

顶级配置文件是JSON，支持：

• schema 完全定制 log_record 财产，或
• schema_profile 用于中的内置配置文件 packages/mcp/examples/schema_profiles
• user_name 用于将服务器端用户身份注入持久化记录
• sink 用于目标设置(jsonl, webhook, postgres)

不要同时设置这两个 schema 和 schema_profile 一起。

省略时的默认行为：

• 架构：内置默认值(agent_id, timestamp, work_summary, additional)
• 水槽： jsonl
• 输出文件： ~/.agent-breadcrumbs/logs.jsonl
• user_name：未注入

为什么配置

• 您的模式/配置文件直接应用于MCP工具输入模式。
• 代理客户端看到所需 log_record 工具定义中的字段。
• 您不需要为客户端中的每个工具调用重复解释有效载荷格式。

常用命令

npm run build:mcp
npm run dev:mcp
npm run test
npm run test:integration
npm run build:dashboard
npm run dev:dashboard

文档

• MCP包文件： packages/mcp/README.md
• 仪表板应用程序文档： apps/dashboard/README.md