🐱 MCP Agent 日志记录工具

📖 概述

MCP Agent 日志记录工具是一个专为 AI Agent 设计的工作日志管理 MCP 服务器。它提供了简单而强大的日志记录、查询和搜索功能，帮助 Agent 和用户追踪工作历史、回顾任务进度。

为什么需要这个工具？

• 任务追踪：自动记录 Agent 的每个工作阶段，便于回溯和审查
• 知识沉淀：将工作过程中的关键信息保存为可检索的文档
• 历史查询：支持列出、查看和搜索历史记录，快速定位所需信息

✨ 功能特性

• 📝 日志记录 - 自动生成递增编号的 Markdown 日志文件（0001-标题.md 格式）
• 📋 列出记录 - 获取所有历史日志的列表，包含编号、标题和创建时间
• 👁️ 查看记录 - 读取指定编号或文件名的日志内容
• 🔍 智能搜索 - 使用自然语言搜索历史记录（需配置 ACE API）
• 🔒 自动 .gitignore - 自动将日志目录加入 .gitignore，保护隐私
• 🗂️ 可配置目录 - 支持通过环境变量自定义日志目录

🚀 快速开始

使用 npx（推荐）

npx mcp-agentlogs@latest

使用 bunx

bunx mcp-agentlogs@latest

从源码运行

# 克隆仓库
git clone https://github.com/Lynricsy/AgentLogs.git
cd AgentLogs

# 安装依赖
npm install

# 使用 Node.js 运行
npm start

# 或使用 Bun 运行
npm run start:bun

🔧 MCP 配置

Claude Desktop 配置

在 Claude Desktop 配置文件中添加：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agent-logs": {
      "command": "npx",
      "args": ["-y", "mcp-agentlogs@latest"],
      "env": {
        "AGENT_LOG_DIR": "AgentLogs"
      }
    }
  }
}

Cursor 配置

在 MCP 配置文件中添加：

{
  "agent-logs": {
    "type": "stdio",
    "command": "bunx",
    "args": ["-y", "mcp-agentlogs@latest"],
    "env": {
      "AGENT_LOG_DIR": "AgentLogs"
    }
  }
}

启用 ACE 搜索功能

如需使用 search-logs 工具进行语义搜索，需要配置 ACE API：

{
  "agent-logs": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "mcp-agentlogs@latest"],
    "env": {
      "AGENT_LOG_DIR": "AgentLogs",
      "ACE_BASE_URL": "https://your-ace-api-endpoint.com",
      "ACE_API_KEY": "your-api-key"
    }
  }
}

🛠️ 工具说明

record-agent-log

记录 Agent 工作日志，生成递增编号的 Markdown 文件。

输入参数：

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | title | string | ✅ | 工作内容标题 | | content | string | ❌ | 工作记录内容（Markdown 格式） |

输出：

{
  "filePath": "/path/to/AgentLogs/0001-任务标题.md",
  "fileName": "0001-任务标题.md",
  "number": 1,
  "logDir": "AgentLogs"
}

list-logs

列出所有历史日志记录。

输入参数： 无

输出：

{
  "logs": [
    {
      "number": 1,
      "fileName": "0001-任务标题.md",
      "title": "任务标题",
      "createdAt": "2025-01-19T12:00:00.000Z"
    }
  ],
  "total": 1,
  "logDir": "AgentLogs"
}

read-log

读取指定日志的内容。

输入参数：

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | identifier | string/number | ✅ | 日志编号（如 1 或 "1"）或文件名（如 "0001-任务标题.md"） |

输出：

{
  "number": 1,
  "fileName": "0001-任务标题.md",
  "title": "任务标题",
  "content": "# 任务标题\n\n日志内容...",
  "createdAt": "2025-01-19T12:00:00.000Z"
}

search-logs

使用自然语言搜索历史日志记录（仅支持 ACE 语义搜索）。

⚠️ 此工具必须配置 ACE API（ACE_BASE_URL 和 ACE_API_KEY）

输入参数：

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | query | string | ✅ | 自然语言搜索查询 |

查询示例：

• "查找关于数据库连接的日志"
• "之前做过哪些 API 相关的任务？"
• "修复登录 bug 的记录"

输出： 返回与 ace-tool-rs 一致的格式化检索结果。

⚙️ 环境变量

| 变量名 | 描述 | 默认值 | |--------|------|--------| | AGENT_LOG_DIR | 日志目录名称（相对于工作目录） | AgentLogs | | ACE_BASE_URL | ACE 搜索 API 的基础 URL | - | | ACE_API_KEY | ACE 搜索 API 的认证密钥 | - | | ACE_REQUEST_TIMEOUT_MS | ACE 请求超时（毫秒） | 30000 | | ACE_MAX_LINES_PER_BLOB | 单个日志分块最大行数 | 800 |

📝 使用提示

推荐给 Agent 的提示词

在你的 Agent 系统提示词中加入以下内容，以便更好地利用此工具：

## 日志记录与查找规则

1. 使用 `record-agent-log` 记录工作，不直接创建/编辑日志文件
2. 通过 `list-logs` 获取历史列表，不直接浏览 AgentLogs 目录
3. 通过 `read-log` 查看内容，不直接打开日志文件
4. **查找历史记录时优先使用 `search-logs`，禁止使用关键词手动搜索文件**
5. 对于大型复杂任务，每完成一个小阶段或重要节点就记录一次

🔐 安全说明

• 日志目录会自动添加到 .gitignore，避免敏感信息被提交到版本控制
• 日志目录必须位于当前工作目录内，防止写入外部路径
• 文件名会自动清理特殊字符，确保跨平台兼容性

🔄 版本发布

本项目使用 GitHub Actions 自动发布到 npm。

发布新版本

1. 更新 package.json 中的版本号
2. 提交更改：git commit -am "chore: bump version to x.x.x"
3. 创建标签：git tag vx.x.x
4. 推送标签：git push origin vx.x.x

GitHub Actions 将自动：

• 发布包到 npm
• 创建 GitHub Release

🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m ':sparkles: feat: add amazing feature'
4. 推送分支：git push origin feature/amazing-feature
5. 创建 Pull Request

提交规范

使用 Gitmoji + Conventional Commits 格式：

• :tada: :sparkles: :bug: :memo: 等表情符号
• feat: fix: docs: chore: 等类型前缀

📄 许可证

ISC License