# CLAUDE.md

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

## Project Overview

MCP server for Trello API integration, built with FastMCP. Published as `mcp-server-trello` on PyPI. Single-file server (`mcp_client.py`) exposing Trello operations as MCP tools.

## Commands

```bash
# Install dependencies
uv sync

# Run the MCP server
uv run mcp_client.py

# Run as installed package
uvx mcp-server-trello

# Run tests
uv run python test_filtering.py

# Build for distribution
uv build
```

## Gotchas

- Tests are plain Python scripts with print-based assertions (no pytest). Run them directly with `uv run python <test_file>.py`.
- Hatch build config uses `packages = ["."]` — the entire repo root is the package. The importable module is `mcp_client`, not a nested package.
- Adding a new tool: define a function with `@mcp.tool()` in `mcp_client.py`, call `trello_request()` for the API, and gate through `should_optimize()` / `simplify_*` if the endpoint returns verbose data.

## Architecture

**Single-module design** - all server logic lives in `mcp_client.py`:

- `FastMCP("Trello")` instance at module level, tools registered via `@mcp.tool()` decorator
- `trello_request()` - central HTTP helper that injects API key/token auth params into all Trello API calls
- Response optimization: when `TRELLO_OPTIMIZE_RESPONSE=1` env var is set, `simplify_*` functions strip verbose Trello API responses down to essential fields. This reduces token usage when the MCP server is consumed by an LLM.
- Entry point: `mcp_client:main` (defined in `pyproject.toml` `[project.scripts]`)

**Tool categories**: Boards, Lists, Cards, Actions/Comments, Members - each maps directly to Trello REST API endpoints.

## Environment Variables

- `TRELLO_API_KEY` - Trello API key (required)
- `TRELLO_API_TOKEN` - Trello API token (required)
- `TRELLO_OPTIMIZE_RESPONSE` - Set to `"1"` to enable simplified/smaller API responses

## Key Dependencies

- `fastmcp` - MCP server framework
- `requests` - HTTP client for Trello API calls
