Metadata-Version: 2.4
Name: mcp-server-trello
Version: 0.5.2
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.5.0

- **Atomic `create_cards`**: each card spec accepts `checklists: [{name, items: [...]}]` and `comments: ["...", ...]`. Sub-resource failures emit `partial_failure` warnings (not errors) so `envelope.ok` stays True for the card-succeeded case.
- **Idempotent ensure-* operations**:
  - `manage_lists(operation="ensure", name="Done")` — case-insensitive match on open lists; creates if missing.
  - `manage_labels(operation="ensure", name="Urgent", color="red")` — same semantics for labels. Strict match: existing properties are NOT silently updated.
- **Declarative `manage_lists(operation="reorder", ordered_names=[...])`** — listed-first, un-listed open lists trail in their existing order.
- **`manage_lists(operation="move_all_cards")` safety**: `confirm=True` required when source list has >1 card. `dry_run=True` previews `card_count` without requiring confirm.
- **Hardening**: `classify_ref` verifies `/cards/<ref>` before emitting `wrong_tool`; `label_cards` DELETE merges dict response into card (no more sparse receipts); `get_card_context` uses `_board_cards(extra_fields=["desc"])` for description.

## 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.
Mutation tools return compact receipts plus a top-level `verified_by` source:
`"trello_mutation_response"` for real writes, `"trello_board_snapshot"` for
unchanged items, and `"dry_run"` for previews. When the source is a real Trello
write response, call read tools only when extra fields such as description,
checklists, or activity are needed.

## 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.
