Skip to content

feat: bake MCP server into the CLI (things mcp) #82

@ryanlewis

Description

@ryanlewis

Summary

Add a things mcp subcommand that runs an MCP server over STDIO, exposing the read-only side of the CLI as MCP tools. The motivating case is Claude Desktop, which can't shell out; other MCP hosts that can shell out (Cursor, Claude Code) get it for free as a typed alternative to driving the CLI via Bash.

Scope (v1)

  • New subcommand things mcpSTDIO only
  • Read-only tools mirroring the CLI 1:1: list, show, search (filter args preserved — --area, --tag, --status, --project, etc.)
  • Output: JSON via the existing --json output path (no lipgloss/ANSI bleeding into MCP responses)
  • DB connection: open-per-call, mirroring current CLI semantics — sidesteps WAL/snapshot concerns vs. Things3's writes
  • Fails fast at startup if the Things3 DB is missing/unreachable, with a clear error message
  • Install is docs only — README snippets for Claude Desktop, Cursor, and a generic JSON block. No config-editing command.
  • Existing internal/skill/SKILL.md stays as-is; MCP and skill coexist independently

Out of scope (v1)

  • Write operations (add/complete/cancel/edit) — punted; AppleScript dependency + side effects deserve their own design pass
  • HTTP/SSE transport
  • Auto-detecting/editing client configs (claude_desktop_config.json et al.)
  • Curated agent-ergonomic tools (e.g. find_or_create_project) — straight 1:1 CLI mapping for now

Open question — spike before committing

Library choice. Spike both against the three read tools and pick the one that feels right:

Done = shippable

  • things mcp STDIO server with list, show, search tools
  • README config snippets for Claude Desktop, Cursor, and generic
  • Tool-handler unit tests
  • STDIO round-trip integration test (spawn the binary, send JSON-RPC, assert response)

Worth flagging (not blockers)

  • For Claude Desktop users there's no Bash and no skill — the MCP tool descriptions become the entire UX hint surface. Invest in them.
  • Tool-name churn post-v1 is a silent breaking change for installed users. Settle naming before tagging.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestfeatNew feature

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions