logbook-mcp: Instructions file for Claude Code

logbook-mcp (v2)

Cuaderno de bitácora del developer via MCP. Notas, TODOs y code TODOs sin salir de tu AI. Obsidian-only desde v2.0 (SQLite eliminado).

Stack

• TypeScript 5 (ESM)
• MCP SDK (@modelcontextprotocol/sdk)
• Archivos Markdown con frontmatter YAML — backend Obsidian
• @orama/orama — search full-text BM25+fuzzy (puro JS)
• @clack/prompts — wizard interactivo setup init
• chokidar — watcher de cambios externos en el vault
• Vitest para tests
• tsup para build

Arquitectura

src/
├── index.ts                 # Entry: --mcp → server, else CLI dispatcher
├── server.ts                # createServer() — registra 5 tools + 5 shims
├── cli.ts                   # Shim que llama a cli/dispatcher
├── config.ts                # Config legacy (~/.logbook/config.json)
├── types.ts                 # Re-exports de storage/types
├── config/                  # Sistema de config en capas (v2)
│   ├── types.ts             # ConfigLayer, ResolvedConfig, ConfigTrace
│   ├── defaults.ts          # Hardcoded defaults
│   ├── resolve.ts           # resolveConfig() merge + trace
│   ├── detect-vaults.ts     # Cascade obsidian.json → common-folder scan
│   ├── detect-plugins.ts    # community-plugins.json
│   └── reminders-state.ts   # .logbook/reminders-state.json (atomic R/W)
├── core/
│   └── auto-wikilinks.ts    # autoWrapIds + expandRefShortcut middleware
├── cli/
│   ├── dispatcher.ts        # --mcp vs CLI mode routing
│   ├── snippet.ts           # MCP snippets per client (7 clientes)
│   └── commands/
│       ├── setup.ts         # init wizard (@clack/prompts) + status + reorganize
│       ├── note.ts          # logbook-mcp note <content>
│       ├── todo.ts          # logbook-mcp todo add <content>
│       └── search.ts        # logbook-mcp search <query>
├── storage/
│   ├── types.ts             # StorageBackend + tipos compartidos
│   ├── index.ts             # Factory getStorage() — sólo Obsidian
│   └── obsidian/
│       ├── index.ts         # ObsidianStorage (monolito de v1, conserva)
│       ├── orama-adapter.ts # Búsqueda full-text (Orama, lazy + cache)
│       ├── frontmatter.ts   # Parser/serializer YAML
│       ├── slug.ts          # Slugify con acentos
│       ├── workspace.ts     # Autodetección workspace/project
│       ├── wikilinks.ts     # [[wikilinks]] (rendering existente)
│       ├── files.ts         # Helpers .md
│       └── formatting.ts    # Callouts, checkboxes
├── git/
│   ├── detect-repo.ts       # detectRepoPath via git rev-parse
│   └── code-todos.ts        # Scan TODO/FIXME/HACK/BUG via git grep
├── tools/                   # 5 main tools + 5 shims deprecated
│   ├── note.ts              # logbook_note
│   ├── todo.ts              # logbook_todo (add/list/done/edit/rm)
│   ├── entry.ts             # logbook_entry (list/edit/delete/standup/decision/debug)
│   ├── query.ts             # logbook_query (search/log/timeline/tags/reminders/review/get)
│   ├── setup.ts             # logbook_setup (init/status/inbox/topics)
│   └── shims/               # Deprecated, eliminados en v2.2
│       ├── tags.ts
│       ├── reminders.ts
│       ├── review.ts
│       ├── inbox.ts
│       └── topics.ts
└── resources/
    └── reminders.ts         # MCP resource: logbook://reminders