feat: MCP server mode (catchme mcp)

[salem221094]

Summary

This PR implements the feature proposed in #5 — exposing CatchMe's activity tree as a proper MCP (Model Context Protocol) stdio server.

Any MCP-compatible host (Claude Desktop, Cursor, Hermes Agent, Windsurf, etc.) can now use CatchMe as a native tool — no skill files, no shell-parsing prose answers, no lock-in.

Changes

File	Change
catchme/mcp_server.py	New: MCP stdio server (~160 lines)
catchme/run.py	Added cmd_mcp() + catchme mcp CLI entry + help text
pyproject.toml	Added mcp[cli]>=1.0 as optional [mcp] extra

Tools Exposed

Tool	Description
search_activity(query, date?)	Natural-language retrieval — wraps existing retrieve() generator, returns {answer, sources} JSON
list_days()	All recorded days with summaries and session counts
get_session(session_id)	Full session detail (app/location breakdown, 2 levels deep)
get_tree(date)	Raw activity tree JSON for a given day

Installation & Usage

pip install 'catchme[mcp]'
catchme mcp   # starts stdio server, blocks until host disconnects

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "catchme": {
      "command": "catchme",
      "args": ["mcp"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "catchme": { "command": "catchme", "args": ["mcp"] }
  }
}

Design Notes

• Zero new capture logic — purely an interface layer over existing retrieve(), _load_all_trees(), and _node_index() from pipelines/retrieve.py
• Optional dependency — mcp is not pulled in unless the user explicitly installs catchme[mcp], so the base install is unaffected
• Graceful error — if mcp is not installed, catchme mcp prints a clear install instruction and exits cleanly instead of crashing with an ImportError
• stdio transport — matches the standard used by Claude Desktop, Cursor, and most MCP hosts; no port binding, no config needed

Testing

Tested locally with Claude Desktop and the MCP Inspector:

• list_days() returns correct day summaries
• search_activity("what was I coding this morning") correctly traverses the tree and returns a structured answer
• get_session() and get_tree() return correct JSON
• Missing mcp package produces a clean error message

---

Happy to adjust the tool schema, add HTTP/SSE transport as an alternative, or split into a smaller first step if preferred.

[pancacake]

thanks for your contribution!