commitment-tracker-mcp

An MCP server that tracks commitments — promises people make in conversation ("I'll send the report by Friday") — so they can be listed, closed out, and flagged when they go overdue.

The repo currently covers Phase 1 (core data model + standalone, reusable MCP server over SQLite) and Phase 2 (the agent orchestrator that does LLM classification, extraction, and drafting, and talks to the server over MCP).

Layout

Phase 1 — storage (MCP server side):

File	Responsibility
schema.sql	The commitments table definition + indexes.
models.py	Typed models (Commitment, Status) and UTC time helpers.
db.py	SQLite data-access layer. Knows nothing about MCP.
server.py	FastMCP server exposing the storage/query tools.
test_client.py	Manual end-to-end test that drives the server over stdio.

Phase 2 — agent (MCP client side):

File	Responsibility
llm.py	All Gemini API calls: flash-lite classification gate, flash extraction/drafting/digest (structured outputs). Includes a StubLLM for offline testing.
mcp_client.py	Async client for the commitment-tracker server. The orchestrator's only path to storage.
orchestrator.py	Reactive loop: classify → extract → store → draft → confirm.
digest.py	Proactive daily job: overdue sweep + due-soon summary + nudge drafts.
sample_emails.json	Demo inbox for the orchestrator.

Setup

pip install -r requirements.txt

Requires Python 3.10+.

Run the server

python server.py          # stdio transport, for local/agent use

It creates commitments.db next to the code on first run. Point it elsewhere with the COMMITMENT_DB_PATH environment variable.

Prove it works

python test_client.py

This spins up the server over stdio against a throwaway database, discovers the tools, and runs a full lifecycle (add → list → fulfill → overdue), printing PASS/FAIL for each assertion. It touches your real commitments.db never.

Run the agent (Phase 2)

The live path uses Google Gemini's free tier (no billing). Get a key at https://aistudio.google.com/apikey, then put it in a .env file:

cp .env.example .env      # then edit .env and paste your key

.env is gitignored — the key never gets committed. The entrypoints call load_dotenv(), so it's picked up automatically:

python orchestrator.py                 # process sample_emails.json
python digest.py                       # daily digest + nudge drafts

# Offline — full pipeline & MCP wiring with a deterministic stub LLM (no key):
python orchestrator.py --dry-run
python digest.py --dry-run             # digest without the LLM summary

(You can also just export GEMINI_API_KEY=... in your shell instead of .env.) If a model isn't enabled on your key, override the IDs: GEMINI_CLASSIFIER_MODEL / GEMINI_EXTRACTOR_MODEL.

The reactive loop per email: classify (Haiku — cheap gate) → extract commitments (Opus, structured outputs, relative deadlines resolved against an injected UTC date) → store via the MCP add_commitment tool → draft a grounded reply → confirm with the user. Nothing is ever auto-sent — every draft requires explicit approval (--yes exists for demos/CI only).

The digest job is the proactive side, meant for cron/Task Scheduler: it runs check_overdue, lists what's due this week, and drafts nudges for review.

Model choices: gemini-2.5-flash-lite for classification (runs on every email, so cheap/fast, thinking disabled), gemini-2.5-flash for extraction, drafting, and the digest (runs only on emails that pass the gate). All LLM outputs use structured outputs (Gemini response_schema + pydantic → response.parsed), so no free-form JSON parsing anywhere. The provider is isolated to llm.py — the server, MCP client, orchestrator, and digest are provider-agnostic.

Tool surface

The server exposes storage and query tools only:

Tool	Purpose
add_commitment(...)	Record a new, already-structured commitment.
list_open_commitments(before_date=None)	List outstanding commitments.
mark_fulfilled(commitment_id)	Close a commitment (stamps fulfilled_at).
check_overdue(as_of=None)	Flag & return open commitments past their deadline.
get_commitment(commitment_id)	Fetch one commitment by id.

Design boundaries

• Extraction lives in the agent, not the server. Turning raw messages into structured commitments is an LLM job that lives in llm.py on the orchestrator side, which then calls add_commitment with the resolved fields. Keeping the LLM call out of the server keeps this a pure, client-agnostic interop layer that a CLI, a Slack bot, or the agent can all reuse.
• The orchestrator never imports db.py. All storage goes through mcp_client.py over stdio — proving the MCP boundary is real, not decorative.
• The user confirms every outward action. Drafts (replies, nudges) are always presented for approval; the agent proposes, the human disposes.
• LLM calls are isolated in llm.py. orchestrator.py takes any object with the same three methods, so the Phase 4 eval harness can call extract_commitments() directly on a labeled set — and StubLLM runs the whole pipeline offline.
• db.py has no MCP dependency. It is plain functions over sqlite3, so it is directly unit-testable and reusable — the seam that makes the Phase 4 eval harness cheap.

Data-model decisions (Step 2 & Step 7)

• Deadlines stored twice. deadline holds the resolved absolute ISO-8601 value (source of truth for queries and overdue logic). deadline_raw keeps the original phrase ("by Friday") for debugging/eval only.
• UTC internally, always. Every timestamp (created_at, fulfilled_at) and every resolved deadline is UTC ISO-8601. Convert to local time only at display. Overdue comparison relies on lexicographic ISO ordering.
• NULL deadlines are never overdue. A commitment with no resolvable deadline is excluded from check_overdue and from before_date filtering.
• Overdue is strict (deadline < as_of). A date-only deadline becomes overdue the day after it, not on the day itself.
• Idempotent inserts. Re-processing the same message won't create duplicates: add_commitment dedups on (source_msg_id, text, who_promised) and returns the existing record. There is intentionally no hard UNIQUE constraint on source_msg_id alone, because one message can carry several distinct commitments.

Status lifecycle

open ──mark_fulfilled──▶ fulfilled
 │
 └──check_overdue (deadline passed)──▶ overdue