Metadata-Version: 2.4
Name: mcp-server-trello
Version: 0.4.0
Summary: MCP server for Trello API integration
Author-email: Liad Goren <khgs2411@gmail.com>
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.12.4
Requires-Dist: requests>=2.32.5
Description-Content-Type: text/markdown

# MCP Server for Trello

Agent-native Model Context Protocol server for using Trello as a project-management backend for LLM agents.

The server exposes compact workflow tools first, with guarded raw Trello calls available only as escape hatches.

## What's new in v0.3.0

- Input validation with field-level receipts (`fields_summary.aliased`/`ignored`/`missing`).
- Card label hydration: read and mutation responses now return `labels: ["Feature"]` (name strings) instead of empty arrays.
- Card shortLink resolution: `RIQCFJBW`-style 8-char references resolve everywhere a card is taken.
- New error codes: `partial_resolution`, `wrong_tool`, `no_changes_requested`, `alias_collision`.

**Aliases accepted (move_cards):** `list`, `target_list`, `destination`, `move_to`, `list_name`, `target` → `to_list`.

**Aliases accepted (update_cards):** `description`→`desc`, `title`→`name`, `archived`/`archive`/`is_closed`→`closed`, `due_date`→`due`, `dueComplete`→`due_complete`, `idList`→`id_list`, `idMembers`→`id_members`.

**Aliases accepted (label_cards):** `labels`/`add_labels`/`label`→`add`, `remove_labels`→`remove`.

## Tool Surface

The revised MCP exposes 24 current tools. Prefer compact grouped tools before raw Trello calls.

Board discovery and read tools:

- `open_board`
- `get_board_snapshot`
- `find_cards`
- `get_card_context`
- `get_board_activity`

Card mutation tools:

- `create_cards`
- `update_cards`
- `move_cards`
- `label_cards`
- `comment_on_card`

Grouped project-management tools:

- `manage_boards`
- `manage_cards`
- `manage_comments`
- `manage_checklists`
- `manage_attachments`
- `manage_custom_fields`
- `assign_members`
- `manage_lists`
- `manage_labels`
- `batch_get_compact`

Raw guarded escape hatches:

- `trello_get`
- `trello_post`
- `trello_put`
- `trello_delete`

Raw tools are for cases the compact surface cannot express. They reject unsafe endpoints, credential-bearing URLs, and unconfirmed deletes.

## Response Shape

Tools return compact dict envelopes:

```json
{
  "ok": true,
  "tool": "open_board",
  "board": {"id": "...", "name": "...", "url": "..."},
  "result": {},
  "warnings": [],
  "errors": []
}
```

Errors and warnings use stable machine-readable codes so agents can recover or retry safely.

## Board Maps

`open_board` refreshes a local board map so agents can resolve board-local list and label aliases without rediscovering IDs each turn.

Default storage:

```text
~/.config/mcp-server-trello/boards
```

Override storage with:

```bash
TRELLO_MCP_BOARD_MAP_DIR=/path/to/boards
```

Board maps store board/list/label metadata and aliases. They do not store card contents, comments, or credentials.

## Example Workflows

Open a board:

```text
open_board(name_or_id="Suitepath")
```

Create cards in bulk:

```text
create_cards(board_id_or_name="Suitepath", list="TODO", cards=[{"name": "Draft release notes"}])
```

Label cards in bulk:

```text
label_cards(board_id_or_name="Suitepath", card_refs=["Draft release notes"], add=["Feature"])
```

Inspect recent activity:

```text
get_board_activity(board_id_or_name="Suitepath", limit=10)
```

Run a compact batch read:

```text
batch_get_compact(urls=["/boards/board_id/cards", "/boards/board_id/labels"])
```

## Installation

```bash
uvx mcp-server-trello
```

Required runtime environment:

- `TRELLO_API_KEY`
- `TRELLO_API_TOKEN`

## Deployment

See `DEPLOYMENT.md` for the release and PyPI publish flow.
