MCP Thread Persistence Demo

A minimal MCP (Model Context Protocol) server that persists chat-thread notes to SQLite, with a real client that exercises it over the actual stdio transport (not just calling the underlying functions directly).

Built as a learning exercise mirroring a real freelance job pattern: "fix/implement MCP tool calls that persist chat thread state to a database, with upsert semantics (create if new, update if existing, no duplicate rows per thread)."

What's here

• server.py — MCP server exposing three tools:

  • save_note(user_id, thread_id, content) — upsert into SQLite, keyed on (user_id, thread_id). Second call on the same thread updates the existing row instead of creating a duplicate.

  • get_note(user_id, thread_id) — read back the saved note.

  • list_threads(user_id) — list all threads for a user.

• test_client.py — a real MCP client that connects to server.py over stdio, calls list_tools, then exercises all three tools in sequence (including calling save_note twice on the same thread to verify the upsert doesn't create a duplicate row).

Related MCP server: notes-box

Running it

python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

python test_client.py

Notes

Pinned to mcp<2 deliberately: the mcp SDK's 2.x release renamed FastMCP to MCPServer and changed other APIs. Most existing tutorials/codebases in the wild still target the 1.x FastMCP API, so that's what this targets too.