Logbook MCP

@cocaxcode/logbook-mcp

Your developer logbook, always one sentence away.

Notes · TODOs · Reminders · Code scanning · Full-text search · Native CLI · Obsidian-only

⚠️ v2.0中断更改： SQLite已删除。V2只支持后台黑曜石。数据输入 ~/.logbook/logbook.db （v1） 不会自动迁移 -他们在迪斯科舞厅完好无损。如果您需要访问它们，请继续 @cocaxcode/logbook-mcp@0.4.工具10→5 （不推荐使用垫片）。版本 更改日志.md 关于细节。

Overview · Usage · Installation · Features · Tool Reference · Storage · Architecture

______________________________________________________________________

快速概览

logbook mcp是一个mcp服务器，它将你的AI助手变成一个持久的开发人员日志。无需离开编辑器，即可捕获决策、跟踪TODO、设置提醒、扫描TODO代码并使用全文搜索搜索所有内容。

它可以自动检测您的git项目，在本地存储所有内容，并与任何兼容MCP的客户端配合使用：Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、Codex CLI或Gemini CLI。 所有数据都保留在你的机器上——没有同步，没有跟踪，没有离开你的磁盘。 注释的范围会自动按项目确定，但您可以随时在所有项目中进行全局搜索。

两种存储模式： SQLite （默认，零配置）或 黑曜石 （带有frontmatter的标记文件，在您的黑曜石保管库中可见，带有图形视图、数据视图、任务和日历）。从SQLite切换到Obsidian 自动迁移您的数据 在启动时。

______________________________________________________________________

只需与它对话

没有命令要记住。说出你需要什么。

记录笔记

"I decided to use JWT instead of sessions for scalability"
→ Saved as a decision — retrievable months from now

"The CI is failing due to a timeout in integration tests"
→ Captured as a blocker — shows up when you review activity

跟踪所有

"TODO: implement email validation"
→ Created with auto-inferred topic

"Add these: fix token refresh. update deps. add rate limiting"
→ 3 TODOs created at once, each categorized

"Mark 5 and 8 as done"
→ Both completed

"What's pending across all projects?"
→ Global view of everything, including code TODOs

设置提醒

"Remind me tomorrow to deploy"
→ One-time reminder

"Remind me every Tuesday to review PRs"
→ Recurring weekly — auto-acknowledged after each session

"Remind me on weekdays to check the CI"
→ Monday to Friday

搜索任何内容

"Why did we choose JWT?"
→ Finds the decision note, even months later

"Search everything about auth"
→ FTS5 search across all notes and TODOs

______________________________________________________________________

安装

克劳德代码（推荐）

claude mcp add --scope user logbook -- npx -y @cocaxcode/logbook-mcp@latest --mcp

使用黑曜石模式：

claude mcp add --scope user logbook -- npx -y @cocaxcode/logbook-mcp@latest --mcp --storage obsidian --dir "/path/to/vault/logbook"

克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "logbook-mcp": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/logbook-mcp@latest", "--mcp"]
    }
  }
}

使用黑曜石模式：

{
  "mcpServers": {
    "logbook-mcp": {
      "command": "npx",
      "args": [
        "-y", "@cocaxcode/logbook-mcp@latest", "--mcp",
        "--storage", "obsidian",
        "--dir", "/path/to/vault/logbook"
      ]
    }
  }
}

Config file locations

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Cursor, Windsurf, VS Code, Codex CLI, Gemini CLI

光标 --添加到 .cursor/mcp.json:

{
  "mcpServers": {
    "logbook-mcp": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/logbook-mcp@latest", "--mcp"]
    }
  }
}

帆板运动 --添加到 .windsurf/mcp.json:

{
  "mcpServers": {
    "logbook-mcp": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/logbook-mcp@latest", "--mcp"]
    }
  }
}

VS Code --添加到 .vscode/mcp.json:

{
  "servers": {
    "logbook-mcp": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/logbook-mcp@latest", "--mcp"]
    }
  }
}

Codex CLI:

codex mcp add logbook-mcp -- npx -y @cocaxcode/logbook-mcp@latest --mcp

Gemini CLI --添加到 .gemini/settings.json:

{
  "mcpServers": {
    "logbook-mcp": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/logbook-mcp@latest", "--mcp"]
    }
  }
}

______________________________________________________________________

配置

logbook mcp支持三种配置存储的方式，优先级顺序如下：

1. CLI参数 （最高优先级）： --storage obsidian --dir "/path" --workspace "name"
2. 环境变量: LOGBOOK_STORAGE, LOGBOOK_DIR, LOGBOOK_WORKSPACE
3. 配置文件: ~/.logbook/config.json （首次运行时自动创建）

{
  "storage": "sqlite",
  "dir": null,
  "workspace": null,
  "autoMigrate": true
}

从SQLite切换到Obsidian

只需更改配置并重新启动。如果 autoMigrate 是 true （默认），您现有的SQLite数据将在下次启动时自动迁移到Obsidian。无需手动操作。

您还可以通过以下方式查看当前状态 logbook_setup action:status.

______________________________________________________________________

特性

7个内置主题

每条笔记、待办事项和提醒都会由您的AI自动分类，或者您可以明确指定一个主题。

自定义主题可以随时创建——只需说 *“创建一个名为安全性的主题”*.

自定义主题，包括类型、文件夹和仪表板

主题可以定义自己的行为(kind)，黑曜石文件夹，以及它们是否出现在项目仪表板中(index.md):

• 种类： note （默认）--每个条目都是单独的 .md 文件
• 种类： todo --条目是合并中的复选框 .md 文件
• show_in_index： true （默认）--添加数据视图部分和快速链接 index.md
• show_in_index： false --主题存在，但在仪表板中隐藏

"Create a topic called incident with its own folder"
→ logbook_topics action:add name:"incident" kind:"note" folder:"incidents"
→ Entries saved to: project/incidents/2026-03-24-server-down.md
→ Dashboard updated with Incidents section

"Create a topic called sprint-task as todo type"
→ logbook_topics action:add name:"sprint-task" kind:"todo" folder:"sprint"
→ Entries saved to: project/sprint.md (as checkboxes)

"Create a private topic not shown in the dashboard"
→ logbook_topics action:add name:"internal" kind:"note" folder:"internal" show_in_index:false
→ Entries saved to: project/internal/ (not visible in index.md)

没有a folder，条目将变为默认值 notes/ 或 todos/ 目录。仪表板(index.md)当主题包含以下内容时，会自动重新生成 show_in_index: true 和 folder 创建。

代码TODO扫描

你的 TODO, FIXME, HACK，以及 BUG 通过以下方式检测评论 git grep 并与手动TODO一起显示：

feature (2)
  [ ] #12 [manual] Implement email validation
      [code]  TODO: add OAuth support — src/auth/service.ts:45

fix (3)
  [ ] #8  [manual] Token doesn't refresh
      [code]  FIXME: handle null case — src/users/controller.ts:78
      [code]  BUG: race condition — src/chat/gateway.ts:112

当代码TODO从源代码中消失时（因为您修复了它），日志会自动检测到它并将其标记为已解决。

提醒事项

支持一次性和重复模式：

重复提醒每天显示一次后会自动确认。错过的一次性提醒显示为过期。

提示： 日志mcp公开了mcp资源(logbook://reminders)客户端可以在会话启动时加载。在Claude Code和Claude Desktop中，提醒会自动出现，无需询问。在其他客户中，只需说 *“有什么提醒吗？”*.

全文搜索（FTS5）

由SQLite FTS5提供支持，可立即搜索所有笔记和待办事项。按主题、类型、项目筛选，或在所有项目中全局搜索。

批量操作

"Add: validate email. fix token. update deps"     → 3 TODOs created
"Mark 5, 8, and 12 as done"                       → 3 TODOs completed
"Delete TODOs 3 and 7"                             → 2 TODOs removed

智能项目检测

logbook mcp通过自动检测您所在的git项目 git rev-parse无需配置——默认情况下，它将查询范围限定在当前项目，并使用 global 选择查看所有内容。

______________________________________________________________________

工具参考

logbook_note — Add a note

logbook_todo — Full TODO management

动作： add — 创建全部

动作： list --按主题分组列出TODO

动作： done --标记为已完成/撤消

动作： edit -编辑TODO

动作： rm --删除待办事项

logbook_entry — Structured entries

动作： standup --每日站立

动作： decision --架构决策记录（ADR）

动作： debug --调试会话

动作： list --按类型列出条目

动作： edit / 动作： delete --按ID修改或删除条目

logbook_query — Search and activity

动作： search --全文搜索

动作： log --一段时间的活动

动作： timeline --跨项目时间表

logbook_setup — Admin tools

动作： status --显示当前配置和迁移状态

动作： init --初始化黑曜石保管库（仪表板、模板、收件箱）

动作： migrate --手动将SQLite数据迁移到黑曜石（需要黑曜岩模式）

______________________________________________________________________

存储

SQLite模式（默认）

所有数据都存储在一个SQLite数据库中 ~/.logbook/logbook.db.零配置。

• WAL模式 用于并发读取
• FTS5 用于即时全文搜索的虚拟表
• 触发器 自动保持搜索索引同步
• 对TODO快照进行编码 --跟踪TODO存在的代码，检测它们何时消失

黑曜石模式

使用YAML frontmatter将markdown文件直接写入黑曜石保管库。

通过CLI参数（推荐）、配置文件或环境变量进行配置：

# CLI args (most reliable, especially on Windows)
claude mcp add logbook -- npx -y @cocaxcode/logbook-mcp@latest --mcp --storage obsidian --dir "/path/to/vault/logbook"

// Config file: ~/.logbook/config.json
{
  "storage": "obsidian",
  "dir": "/path/to/vault/logbook",
  "autoMigrate": true
}

文件按工作区、项目和类型组织：

vault/logbook/
├── cocaxcode/
│   ├── cocaxcode-api/
│   │   ├── notes/          ← logbook_note
│   │   ├── todos/          ← logbook_todo
│   │   ├── decisions/      ← logbook_entry action:decision
│   │   ├── debug/          ← logbook_entry action:debug
│   │   ├── standups/       ← logbook_entry action:standup
│   │   └── attachments/    ← copied files
│   └── cocaxcode-web/
├── optimus/
│   └── optimus-hub/

每个文件都有黑曜石插件可以查询的YAML frontmatter：

---
type: todo
date: 2026-03-21
project: cocaxcode-api
workspace: cocaxcode
status: pending
priority: high
due: 2026-03-25
tags: [auth, urgent]
---
- [ ] Fix JWT refresh token

推荐黑曜石插件： 数据视图（类似SQL的查询）、日历（日期视图）、任务（复选框管理）、图形视图（内置，通过以下方式显示连接 [[wikilinks]]).

自动迁移： 从SQLite切换到Obsidian时，启动时会自动迁移现有数据（如果 autoMigrate: true).你也可以跑步 logbook_setup action:migrate 手动。

提示： 与…结合 自托管LiveSync +您的VPS上的CouchDB可以在PC、Android和iOS上免费同步您的保险库。

______________________________________________________________________

建筑

src/
├── index.ts              # Entry: --mcp → server, else CLI
├── server.ts             # createServer() — 10 tools + 1 resource
├── config.ts             # Config resolution (args > env > file > defaults)
├── auto-migrate.ts       # Auto SQLite → Obsidian migration on startup
├── cli.ts                # CLI (help, version)
├── types.ts              # Shared interfaces
├── storage/
│   ├── types.ts          # StorageBackend interface
│   ├── index.ts          # getStorage() factory (uses resolveConfig)
│   ├── sqlite/           # SQLite backend (wraps db/)
│   └── obsidian/         # Obsidian backend (markdown + frontmatter)
├── db/                   # SQLite internals
├── git/                  # Git repo detection + code TODO scanning
├── resources/            # MCP Resource: logbook://reminders
└── tools/                # 10 MCP tools (one file each)

堆栈： TypeScript·MCP SDK·better-splite3·Zod·tsup

______________________________________________________________________