rtm-mcp CLAUDE.md

RTM MCP Server - Developer Documentation

Architecture Overview

src/rtm_mcp/
├── server.py           # FastMCP server, lifespan, tool registration
├── client.py           # Async RTM API client with signing
├── config.py           # Pydantic settings (env + file)
├── types.py            # Pydantic models for type safety
├── exceptions.py       # RTMError hierarchy
├── response_builder.py # Consistent response formatting
├── tools/
│   ├── tasks.py        # Task CRUD + metadata (19 tools)
│   ├── lists.py        # List management (7 tools)
│   ├── notes.py        # Note operations (4 tools)
│   └── utilities.py    # Tags, locations, settings, undo
└── scripts/
    └── setup_auth.py   # Interactive auth setup CLI

Key Patterns

Tool Registration

Tools are registered via functions that receive the mcp instance and a client getter:

def register_task_tools(mcp: Any, get_client: Any) -> None:
    @mcp.tool()
    async def list_tasks(ctx: Context, filter: str | None = None) -> dict:
        client: RTMClient = await get_client()
        result = await client.call("rtm.tasks.getList", filter=filter)
        return build_response(data=parse_tasks_response(result))

Response Format

All tools return consistent structure:

{
    "data": {...},                    # Main response data
    "analysis": {"insights": [...]},  # Optional insights
    "metadata": {
        "fetched_at": "ISO timestamp",
        "transaction_id": "..."       # For undo support
    }
}

RTM Client

Async client with automatic:

• MD5 request signing
• Timeline creation for writes
• Rate limiting (1 RPS)
• Error code mapping to exceptions

client = RTMClient(config)
result = await client.call("rtm.tasks.add", require_timeline=True, name="Task")

Task Identification

RTM uses three IDs for task operations:

• list_id: Which list the task is in
• taskseries_id: The task series (for recurring tasks)
• task_id: The specific task instance