DevLog

A local-first MCP (Model Context Protocol) server for keeping a personal engineering journal — and letting an AI assistant query, summarize, and draft from it.

Log what you worked on (by hand or pulled straight from git), then ask Claude to turn a week of entries into a standup update, a changelog, or retro notes.

This project exists as a hands-on, complete example of an MCP server that uses all three MCP primitives — tools, resources, and prompts — for real reasons, not just to check a box.

Why this exists

Most MCP demos only show tools. DevLog is small enough to read end-to-end in one sitting, but touches every primitive the protocol defines:

Related MCP server: Selvedge

Primitives

Tools

Resources

Prompts

How it works

┌─────────────┐     stdio (JSON-RPC)     ┌──────────────┐     SQLite      ┌───────────┐
│ MCP Client   │ ◄──────────────────────► │  server.py   │ ◄─────────────► │ devlog.db │
│ (Claude)     │                          │  (this repo) │                 └───────────┘
└─────────────┘                          └──────┬───────┘
                                                  │
                                                  ▼
                                          local `git log`

The server runs locally over stdio. Nothing leaves your machine except whatever the client (e.g. Claude) chooses to do with the text it gets back.

Setup

Requires Python 3.11+.

git clone <your-repo-url>
cd devlog
pip install -e .
python server.py   # sanity check: starts and waits on stdio

Connect it to Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "devlog": {
      "command": "python",
      "args": ["/absolute/path/to/devlog/server.py"]
    }
  }
}

Restart Claude Desktop. You should see DevLog's tools, resources, and prompts available in the conversation.

Connect it to a local or self-hosted LLM

client.py is a small standalone MCP client that spawns server.py over stdio and drives it from any OpenAI-compatible chat-completions backend — llama.cpp's llama-server, Ollama, vLLM, or OpenAI's own API. It's the tool-calling loop that Claude Desktop/Code provide for you, made explicit, so DevLog isn't limited to Anthropic's clients.

Install the extra dependency (httpx) it needs:

pip install -e ".[client]"

Then, with a backend already running — e.g. llama.cpp:

llama-server --jinja -m qwen2.5-7b-instruct-q4_k_m.gguf --port 8080
python client.py --model qwen2.5-7b-instruct

or against OpenAI's API:

python client.py --base-url https://api.openai.com/v1 --model gpt-4o --api-key sk-...

This starts a REPL:

Connected. 3 DevLog tools available. Type 'tools' to see available tools. Type 'exit' to quit.
you> show the latest git activity for this repo

--base-url defaults to http://127.0.0.1:8080/v1 (llama.cpp's default); --api-key is only needed for backends that require one. Tool-calling reliability depends on the model — it needs to support structured function calling (Qwen2.5-Instruct and Llama 3.1 do; not every local model does), and small models are more likely to guess at arguments (e.g. a placeholder file path) instead of asking a clarifying question, which Claude tends to do more reliably.

Inspect it directly

The official MCP Inspector is the fastest way to poke at the server without a full client:

npx @modelcontextprotocol/inspector python server.py

Example session

You: Log that I fixed the auth token refresh bug in the api project, tagged bugfix.
Claude: [calls add_entry] Logged.

You: Pull in today's commits from ~/code/api since yesterday.
Claude: [calls get_git_activity] Added 4 entries from git history.

You: Give me my standup update.
Claude: [uses weekly_standup prompt, reads devlog://entries/{date} resources]

Yesterday:
- Fixed auth token refresh bug (api)
- Merged rate-limiter PR (api)
Today:
- Continue auth work, start on session-timeout edge cases
Blockers:
- None

Project structure

devlog/
├── server.py              # MCP server entrypoint — registers tools/resources/prompts
├── client.py              # standalone MCP client for local/self-hosted LLM backends
├── devlog/
│   ├── db.py               # all SQLite access
│   ├── git_activity.py     # git log parsing
│   ├── summarize.py        # pure functions for resource/prompt output
│   └── schema.sql
├── tests/
├── pyproject.toml
├── CLAUDE.md               # guidance for Claude Code working in this repo
├── PLAN.md                 # phased build plan
├── demo.md                 # log entries -> weekly_standup walkthrough
└── README.md

Status

Phases 0-8 of PLAN.md are complete: all three tools, resources, and prompts are implemented and tested. See PLAN.md's stretch goals for optional follow-up work.

License

MIT