dev-diary-mcp

A Model Context Protocol server that turns a plain folder of Markdown files into a searchable work journal any LLM can read and write.

No database. No app. Your work log is just diary/2026-08-22.md — human-readable, diffable, git-friendly — and your AI assistant gets four tools to use it:

| Tool | What it does | |---|---| | log_work | Appends a timestamped entry (with tags) to today's file | | search_diary | Full-text search across all entries, optional tag filter | | daily_summary | Everything logged on a given day | | stats | Totals, active days, current streak, top tags |

Why

"Log what I did today" is the task everyone abandons after a week. But your AI assistant already knows what you did — it helped you do it. Give it tools against a Markdown folder and keeping a work journal becomes a byproduct of working with AI.

Run the demo

The repo ships a real MCP client that drives the server end-to-end (handshake → listTools → tool calls), so you can verify everything without an editor:

npm install
npm run build
npm run demo

Output:

=== 1. listTools ===
 • log_work — Append a timestamped entry...
 • search_diary — Full-text search across every entry...
 • daily_summary — Everything logged on a given date...
 • stats — Totals, active days, streaks, top tags...

=== 2. log_work x3 ===
Logged to 2026-08-22.md at 19:05 (tags: bugfix, websocket)
...

=== 5. stats ===
📊 1 entries across 2 day(s)
🔥 Streak: 2 consecutive day(s)
🏷️ Top tags: #bugfix (1), #websocket (1)

Then look at diary/*.md — that's your data. Plain Markdown.

Connect it to your editor / agent

Claude Desktop / Cursor / any MCP client

{
  "mcpServers": {
    "dev-diary": {
      "command": "node",
      "args": ["/absolute/path/to/dev-diary-mcp/dist/server.js"],
      "env": { "DIARY_DIR": "/absolute/path/to/your/diary" }
    }
  }
}

Hermes Agent

hermes mcp add dev-diary --command node --args /path/to/dist/server.js

Inspect it interactively

npx @modelcontextprotocol/inspector node dist/server.js

The storage format

One file per day (diary/YYYY-MM-DD.md), entries as H2 headings with embedded tags:

## 14:32 #bugfix #websocket
Fixed the race condition in the WebSocket broadcast queue

## 16:10 #testing
Wrote E2E test covering two-client sync

Because it's just files, you can grep it, back it up, edit it by hand, or commit it. The server reads whatever is on disk on every call — no cache to invalidate.

How it works (~190 lines of TypeScript)

Built with the official @modelcontextprotocol/server SDK (2026-07-28 spec):

• McpServer + registerTool(name, { description, inputSchema }, handler) — schemas are Standard Schema; this project uses Zod v4
• StdioServerTransport — the editor spawns the process and talks JSON-RPC over stdin/stdout
• Tool handlers read/write Markdown under DIARY_DIR (default: ./diary)

Companion article: "I Built an MCP Server That Keeps My Work Journal — Here's Everything I Learned" (draft in this repo).

License

MIT