tasqr-mcp-python: Instructions file for Claude Code

CLAUDE.md

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

What this is

tasqr-mcp is a thin local MCP proxy. It runs as a stdio process, authenticates with a Tasqr API key, and forwards every list_tools/call_tool request to the remote Tasqr Lambda MCP server over streamable HTTP (https://mcp.tasqr.ai/mcp by default). The actual task-management logic (task storage, claiming, tags, etc.) lives server-side — this repo does not implement it. The only substantial local logic is credential/auth bootstrapping and optional client-side (BYOK) encryption of task fields before they leave the process.

Commands

# Install for local dev (editable + dev deps)
pip install -e ".[dev]"

# Run the full test suite
uv run pytest        # or: pytest

# Run a single test file / test
uv run pytest tests/test_crypto.py
uv run pytest tests/test_crypto.py::test_create_task_encrypts_title

# Lint / format
uv run ruff check .
uv run ruff format .

# Run against a local dev server instead of production
TASQR_MCP_URL=http://localhost:8000/mcp uvx tasqr-mcp

# Check version / run the CLI directly
tasqr-mcp --version

Lint and format with ruff check . and ruff format . (configured in pyproject.toml, line length 100). CI fails on either. There is no type checker configured.

Tests use pytest-anyio (pytest_plugins = ('anyio',) in tests/conftest.py), so any @pytest.mark.anyio test runs once under asyncio and once under trio — expect [asyncio]/[trio] variants in test output.

Architecture

Entry point (__main__.py): reads the API key via credentials.read_api_key(). If missing and stdin is a TTY, runs the GitHub Device Flow signup (device_flow.py) and persists the resulting key; otherwise exits with an error telling the user to run uvx tasqr-mcp interactively first. Then hands off to proxy.run(api_key).

Proxy loop (proxy.py): opens a streamable_http_client session to the upstream Tasqr MCP server, then starts a local mcp.server.Server over stdio that mirrors it — on_list_tools passes the upstream listing through directly (cursor included), on_call_tool optionally encrypts args before forwarding and decrypts the result after. Both handlers come from _handlers(upstream, crypto) and are passed to the Server constructor: the SDK registers handlers as constructor callables, not decorators, and building them apart from the server is what makes them testable (tests/test_handlers.py) without a live connection. The transport takes no headers= of its own — auth rides on an httpx2.AsyncClient the proxy builds and therefore closes (the transport only manages a client it created itself). A kms_key_id in the credentials config is necessary but not sufficient to encrypt: it only makes the proxy ask. The server has the final say (see BYOK below) and can refuse, in which case ClientCrypto is never constructed and the proxy exits with a ManagedOrgError. With no kms_key_id, calls pass straight through.