things-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Development Setup

# Install dependencies (uses uv package manager)
uv sync

# Run the MCP server (stdio transport, default)
uv run things-mcp

# Run with HTTP transport
THINGS_MCP_TRANSPORT=http uv run things-mcp

Testing

The project includes a comprehensive unit test suite covering URL scheme construction and data formatting functions.

# Install test dependencies
uv sync --extra test

# Run all tests
uv run pytest

# Run tests with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_url_scheme.py

# Run tests matching a pattern
uv run pytest -k "test_format"

Test coverage includes:

• All URL construction functions (add, update, show, search)
• Authentication token handling
• Data formatting for todos, projects, areas, and tags
• Error handling and edge cases
• Mock external dependencies (Things.py, shell commands)

Architecture Overview

This is a Model Context Protocol (MCP) server that bridges Claude Desktop with the Things 3 task management app on macOS. The architecture consists of:

1. src/things_mcp/server.py - Main MCP server implementation using FastMCP (3.x)
   • Defines all MCP tools for interacting with Things (26 tools)
   • List views (inbox, today, upcoming, etc.)
   • CRUD operations for todos/projects/areas (Areas have create/read/update — no delete by design; see below)
   • Search and tag operations
   • Things URL scheme integration
   • Implements Someday project filtering to match Things UI behavior
   • Pagination + structured responses: the 16 list/search read tools accept optional limit/offset and return a FastMCP ToolResult carrying both a human-readable text channel and a structured_content envelope {items, count, total, offset, limit}. Two helpers drive this: _paginate_format (text) and _paginate_result (wraps text + JSON-safe structured data); _error_result wraps early-return/validation errors. get_tag_usage intentionally stays a plain string.