@delorenj/mcp-server-trello 1.7.1 → 1.8.1

package/README.md

@@ -6,30 +6,32 @@
 
 <a href="https://glama.ai/mcp/servers/klqkamy7wt"><img width="380" height="200" src="https://glama.ai/mcp/servers/klqkamy7wt/badge" alt="Server Trello MCP server" /></a>
 
-A Model Context Protocol (MCP) server that provides tools for interacting with Trello boards. This server enables seamless integration with Trello's API while handling rate limiting, type safety, and error handling automatically.
+A Model Context Protocol (MCP) server that gives AI agents full access to your Trello boards — cards, lists, checklists, attachments, comments, custom fields, and workspaces — with built-in rate limiting, type safety, and workflow-level tools you won't find in a plain API wrapper, like acceptance-criteria extraction and checklist dependency queries. 57 tools, one `npx` install, powered by Bun.
 
-## 🎉 New in v1.5.0: Now Powered by Bun! ⚡
+## Highlights
 
-**This project is now powered by Bun!** 🚀 We've migrated the entire project to the Bun runtime, resulting in a 2.8-4.4x performance boost. All existing `npx`, `pnpx`, and `npm` commands will **continue to work perfectly**.
-
-### ✨ New in This Release:
-
-  - 🚀 **Performance Boost**: Enjoy a faster, more responsive server.
-  -  BUN **Bun-Powered**: The project now runs on the lightning-fast Bun runtime.
-  - 📖 **Comprehensive Examples**: A new `examples` directory with detailed implementations in JavaScript, Python, and TypeScript.
-
-**Plus:** Modern MCP SDK architecture, enhanced type safety, and comprehensive documentation!
+- **Acceptance criteria, natively**: `get_acceptance_criteria` pulls a card's AC checklist straight into your agent's context — no competitor offers it.
+- **Watch anything**: `watch_card` and `watch_list` route card and list activity into your Trello notifications.
+- **Full list management**: create, update, reorder (`update_list_position`), and archive lists.
+- **Board and workspace switching on the fly**: no restarts, no config edits.
+- **Rate limiting handled for you**: respects Trello's API limits automatically (300 req/10s per key, 100 req/10s per token).
+- **Bun-powered**: fast startup and a 2.8-4.4x performance boost over the old Node build. `npx` and `npm` work too.
 
 ## Changelog
 
-For a detailed list of changes, please refer to the [CHANGELOG.md](CHANGELOG.md) file.
+For a detailed list of changes, see [CHANGELOG.md](CHANGELOG.md).
 
 ## Features
 
   - **Full Trello Board Integration**: Interact with cards, lists, and board activities
-  - **🆕 Complete Card Data Extraction**: Fetch all card details including checklists, attachments, labels, members, and comments
+  - **Acceptance Criteria Extraction**: Pull a card's acceptance criteria checklist directly into agent context
+  - **Checklist Intelligence**: Query checklist items by name or description, track completion, manage items
+  - **Complete Card Data Extraction**: Fetch all card details including checklists, attachments, labels, members, and comments
   - **💬 Comment Management**: Add, update, delete, and retrieve comments on cards
+  - **Activity Subscriptions**: Watch cards and lists so their activity surfaces in Trello notifications
+  - **List Management**: Create, update, reorder, and archive lists
   - **File Attachments**: Attach any type of file to cards (PDFs, documents, videos, images, etc.) from URLs
+  - **Custom Fields**: Read board custom field definitions and update card values
   - **Built-in Rate Limiting**: Respects Trello's API limits (300 requests/10s per API key, 100 requests/10s per token)
   - **Type-Safe Implementation**: Written in TypeScript with comprehensive type definitions
   - **Input Validation**: Robust validation for all API inputs
@@ -39,154 +41,80 @@ For a detailed list of changes, please refer to the [CHANGELOG.md](CHANGELOG.md)
 
 ## Installation
 
-### 🚀 Install from MCP Registry (Recommended)
-
-The MCP Server Trello is now available in the official MCP Registry\! MCP clients can automatically discover and install this server.
-
-For clients that support the MCP Registry:
+The server is published on npm as `@delorenj/mcp-server-trello`. Add it to your MCP client and you're done — no clone, no build.
 
-1.  Search for "mcp-server-trello" or "io.github.delorenj/mcp-server-trello"
-2.  Install directly from the registry
-3.  Configure with your Trello credentials
+### Quickstart (Claude Desktop, Cursor, and other MCP clients)
 
-### 🚀 Quick Start with Bun (Fastest)
-
-If you have [Bun](https://bun.sh) installed, using `bunx` is the fastest way to run the server:
+Add the server to your client's MCP configuration:
 
 ```json
 {
-  "mcpServers": {
-    "trello": {
-      "command": "bunx",
-      "args": ["@delorenj/mcp-server-trello"],
-      "env": {
-        "TRELLO_API_KEY": "your-api-key",
-        "TRELLO_TOKEN": "your-token"
-      }
-    }
-  }
-}
-```
-
-### Quick Start with npx / pnpx / bunx
-
-You can still use `npx` or `pnpx`. This doesn't require a global install and will work just fine, though `bunx` (above) is faster.
-
-```json
-{
-  "mcpServers": {
-    "trello": {
-      "command": "bunx",
-      "args": ["@delorenj/mcp-server-trello"],
-      "env": {
-        "TRELLO_API_KEY": "your-api-key",
-        "TRELLO_TOKEN": "your-token"
-      }
-    }
-  }
-}
-```
-
-Or if you're using mise, you can explicitly execute `bunx` with `mise exec`:
-
-```json
-{
-  "mcpServers": {
-    "trello": {
-      "command": "mise",
-      "args": ["x", "--", "bunx", "@delorenj/mcp-server-trello"],
-      "env": {
-        "TRELLO_API_KEY": "your-api-key",
-        "TRELLO_TOKEN": "your-token"
-      }
-    }
-  }
+  "mcpServers": {
+    "trello": {
+      "command": "bunx",
+      "args": ["@delorenj/mcp-server-trello"],
+      "env": {
+        "TRELLO_API_KEY": "your-trello-api-key",
+        "TRELLO_TOKEN": "your-trello-token"
+      }
+    }
+  }
 }
 ```
 
-To connect a Trello workspace, you'll need to manually retrieve a `TRELLO_TOKEN` once per workspace. After setting up your Trello Power-Up, visit the following URL:
-
-```
-https://trello.com/1/authorize?expiration=never&name=YOUR_APP_NAME&scope=read,write&response_type=token&key=YOUR_API_KEY
-```
-
-Replace:
-
-  * `YOUR_APP_NAME` with a name for your application (e.g., "My Trello Integration"). This name is shown to the user on the Trello authorization screen.
-  * `YOUR_API_KEY` with the API key for your Trello Power-Up
+`bunx` starts fastest, but `npx` works identically. Get your API key at [trello.com/app-key](https://trello.com/app-key) and generate a token from the same page.
 
-This will generate the token required for integration.
+### Claude Code
 
-> [\!NOTE]
-> The `expiration=never` parameter creates a token that does not expire. For enhanced security, consider using `expiration=30days` and renewing the token periodically if your setup allows for it.
-
-#### Don't have Bun?
-
-The simplest way to get `bun` (and thus `bunx`) is through [mise](https://mise.jdx.dev/):
+Register the server with the CLI:
 
 ```bash
-# Install mise (if you don't have it)
-curl https://mise.run | sh
-
-# Install bun and make the @latest version your system default
-mise use bun@latest -g
-
-# Or just run `mise install` from the project directory to install Bun locally
-cd /path/to/mcp-server-trello
-mise install
+claude mcp add trello \
+  --env TRELLO_API_KEY=your-trello-api-key \
+  --env TRELLO_TOKEN=your-trello-token \
+  -- bunx @delorenj/mcp-server-trello
 ```
 
-### Installing via npm
+### MCP Registry
 
-If you prefer using `npm` directly:
+The server is listed on the [official MCP Registry](https://registry.modelcontextprotocol.io/servers/io.github.delorenj/mcp-server-trello) as `io.github.delorenj/mcp-server-trello`, so registry-aware clients can discover and install it directly.
 
-```bash
-npm install -g @delorenj/mcp-server-trello
-```
-
-*(A fast alternative is `bun add -g @delorenj/mcp-server-trello`)*
+### Agent skill package (optional)
 
-Then use `npx mcp-server-trello` as the command in your MCP configuration.
+This repository also ships a **BMAD-compatible skill package** for the
+Trello MCP server. Install the `skill/` directory through your agent's skill
+management workflow, or place it in the agent's skills directory.
 
-### Installing via Smithery
-
-To install Trello Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@delorenj/mcp-server-trello):
+When an agent activates the skill, it follows `skill/SKILL.md`. On first use,
+the agent runs the bundled installer:
 
 ```bash
-# Using bunx (recommended)
-bunx -y @smithery/cli install @delorenj/mcp-server-trello --client claude
-
-# Using npx
-npx -y @smithery/cli install @delorenj/mcp-server-trello --client claude
+bash skill/scripts/install.sh
 ```
 
-### Docker Installation
+The installer builds the MCP server from `skill/assets/source/` when Bun is
+available. If Bun is unavailable, it falls back to the published Smithery
+install path for `@delorenj/mcp-server-trello` and creates the same local
+`build/index.js` command path used by the skill activation check.
 
-For containerized environments:
+## Skill package structure
 
-1.  Clone the repository:
+The skill is the agent-facing entry point for this repository.
 
-<!-- end list -->
-
-```bash
-git clone https://github.com/delorenj/mcp-server-trello
-cd mcp-server-trello
-```
-
-2.  Copy the environment template and fill in your Trello credentials:
-
-<!-- end list -->
+- `skill/SKILL.md`: Activation, routing, and agent workflow rules.
+- `skill/scripts/install.sh`: First-run installer for the bundled server.
+- `skill/references/trello-mcp/`: Focused references for setup, tools,
+  workflows, and gotchas.
+- `skill/assets/source/`: Bundled MCP server source used for local builds.
 
-```bash
-cp .env.template .env
-```
+For AI agents, start with `skill/SKILL.md` rather than this README. The README
+is the human-facing overview; the skill references are the operational surface
+for tool selection and Trello workflow rules.
 
-3.  Build and run with Docker Compose:
-
-<!-- end list -->
+Maintainers can refresh the bundled source before packaging with:
 
 ```bash
-docker compose up --build
+mise run package
 ```
 
 ## Configuration
@@ -205,13 +133,22 @@ TRELLO_BOARD_ID=your-board-id
 
 # Optional: Initial workspace ID (can be changed later using set_active_workspace)
 TRELLO_WORKSPACE_ID=your-workspace-id
+
+# Optional: HTTPS proxy URL (for corporate proxies or restricted networks)
+https_proxy=http://your-proxy:8080
+
+# Optional: Restrict access to specific workspaces (comma-separated IDs)
+# If set, only the listed workspaces will be accessible via MCP tools
+TRELLO_ALLOWED_WORKSPACES=workspace-id-1,workspace-id-2
 ```
 
+> **Proxy Support:** If you're behind a corporate proxy or in an environment that routes traffic through a proxy, set the `https_proxy` or `HTTPS_PROXY` environment variable. The server will automatically route all Trello API requests through the specified proxy.
+
 You can get these values from:
 
   - API Key: [https://trello.com/app-key](https://trello.com/app-key)
   - Token: Generate using your API key
-  - Board ID (optional, deprecated): Found in the board URL (e.g., [suspicious link removed])
+  - Board ID (optional, deprecated): Found in the board URL (e.g., `https://trello.com/b/abc123/example-board`)
   - Workspace ID: Found in workspace settings or using `list_workspaces` tool
 
 ### Board and Workspace Management
@@ -230,6 +167,29 @@ Starting with version 0.3.0, the MCP server supports multiple ways to work with
 
 This allows you to work with multiple boards and workspaces without restarting the server.
 
+### Workspace Access Restriction
+
+You can optionally restrict MCP access to specific workspaces using the `TRELLO_ALLOWED_WORKSPACES` environment variable. This is useful for:
+
+- **Security**: Limiting AI agent access to only approved workspaces
+- **Multi-tenant setups**: Ensuring agents only access relevant workspaces
+- **Testing**: Isolating test environments from production data
+
+When `TRELLO_ALLOWED_WORKSPACES` is set:
+- `list_workspaces` only returns workspaces in the allowed list
+- `list_boards` only returns boards from allowed workspaces
+- `set_active_workspace` rejects workspaces not in the allowed list
+- `list_boards_in_workspace` rejects non-allowed workspace IDs
+- `create_board` rejects creation in non-allowed workspaces
+
+Example configuration:
+```bash
+# Only allow access to two specific workspaces
+TRELLO_ALLOWED_WORKSPACES=697c549ce04dc460af133a75,5f8a3b2c1d4e5f6a7b8c9d0e
+```
+
+If `TRELLO_ALLOWED_WORKSPACES` is not set or empty, all workspaces the token has access to will be available (default behaviour).
+
 #### Example Workflow
 
 1.  Start by listing available boards:
@@ -339,11 +299,11 @@ Search for checklist items containing specific text.
 
 ```typescript
 {
-nbsp; name: 'find_checklist_items_by_description',
+ name: 'find_checklist_items_by_description',
   arguments: {
     description: string,  // Text to search for in checklist item descriptions
     boardId?: string      // Optional: ID of the board (uses default if not provided)
-nbsp; }
+ }
 }
 ```
 
@@ -381,6 +341,40 @@ Get a complete checklist with all items and completion percentage.
   - `items`: Array of `CheckListItem` objects
   - `percentComplete`: Completion percentage (0-100)
 
+#### update\_checklist\_item
+
+Update an existing checklist item.
+
+```typescript
+{
+  name: 'update_checklist_item',
+  arguments: {
+    cardId: string,                          // ID of the card containing the checklist item
+    checkItemId: string,                     // ID of the checklist item to update
+    name?: string,                           // Optional: new checklist item text
+    state?: 'complete' | 'incomplete',       // Optional: new checklist item state
+    pos?: number | 'top' | 'bottom',         // Optional: new checklist item position
+    due?: string | null,                     // Optional: ISO 8601 due date, or null to clear it
+    dueReminder?: number | null,             // Optional: reminder offset in minutes, or null to clear it
+    idMember?: string | null                 // Optional: member ID to assign, or null to clear it
+  }
+}
+```
+
+#### delete\_checklist\_item
+
+Delete an existing checklist item.
+
+```typescript
+{
+  name: 'delete_checklist_item',
+  arguments: {
+    cardId: string,       // ID of the card containing the checklist item
+    checkItemId: string   // ID of the checklist item to delete
+  }
+}
+```
+
 ### get\_card 🆕
 
 Get comprehensive details of a specific Trello card with human-level parity.
@@ -506,7 +500,7 @@ Add a new list to a board.
 
 ```typescript
 {
-nbsp; name: 'add_list_to_board',
+ name: 'add_list_to_board',
   arguments: {
     boardId?: string, // Optional: ID of the board (uses default if not provided)
     name: string      // Name of the new list
@@ -528,6 +522,37 @@ Send a list to the archive.
 }
 ```
 
+### update\_list
+
+Update a list's name, archive state, subscription state, or board. Use `update_list_position` to reorder lists within a board.
+
+```typescript
+{
+  name: 'update_list',
+  arguments: {
+    listId: string,          // ID of the list to update
+    name?: string,           // Optional: New name for the list
+    closed?: boolean,        // Optional: Whether to close (archive) the list
+    subscribed?: boolean,    // Optional: Whether to subscribe to the list
+    idBoard?: string         // Optional: ID of a board to move the list to
+  }
+}
+```
+
+### update\_list\_position
+
+Update the position of a list on the board. Trello uses fractional indexing: each list has a float position, and to place a list between two others, use the average of their positions (e.g., between pos 1024 and 2048, use 1536). Use `"top"`/`"bottom"` shortcuts to move to the edges.
+
+```typescript
+{
+  name: 'update_list_position',
+  arguments: {
+    listId: string,              // ID of the list to reposition
+    position: string             // "top", "bottom", or a positive numeric string (e.g. "1536")
+  }
+}
+```
+
 ### get\_my\_cards
 
 Fetch all cards assigned to the current user.
@@ -563,7 +588,7 @@ Attach an image to a card directly from a URL.
   name: 'attach_image_to_card',
   arguments: {
     boardId?: string, // Optional: ID of the board (uses default if not provided)
-    cardId: string,  nbsp; // ID of the card to attach the image to
+    cardId: string,   // ID of the card to attach the image to
     imageUrl: string, // URL of the image to attach
     name?: string     // Optional: Name for the attachment (defaults to "Image Attachment")
   }
@@ -577,7 +602,7 @@ Attach any type of file to a card from a URL or a local file path (e.g., `file:/
 ```typescript
 {
   name: 'attach_file_to_card',
-nbsp; arguments: {
+ arguments: {
     boardId?: string,  // Optional: ID of the board (uses default if not provided)
     cardId: string,s;   // ID of the card to attach the file to
     fileUrl: string,   // URL or local file path (using the file:// protocol) of the file to attach
@@ -587,6 +612,25 @@ nbsp; arguments: {
 }
 ```
 
+### download\_attachment
+
+Download an attachment from a card by ID. Attachment IDs are available in the `attachments` array returned by `get_card`.
+
+```typescript
+{
+  name: 'download_attachment',
+  arguments: {
+    cardId: string,       // ID of the card containing the attachment
+    attachmentId: string  // ID of the attachment to download
+  }
+}
+```
+
+**Returns:** For image attachments (`image/*`), returns the image as inline viewable data. For all other file types, returns a JSON object with:
+- `fileName`: Original filename
+- `mimeType`: MIME type of the file
+- `data`: Base64-encoded file contents
+
 ### Comment Management Tools
 
 #### add\_comment
@@ -717,6 +761,51 @@ s; name: 'get_active_board_info',
 }
 ```
 
+### Custom Field Management Tools
+
+> **Note:** Custom fields require Trello Standard plan or higher.
+
+#### get\_board\_custom\_fields
+
+Get all custom field definitions on a board. For dropdown/list fields, also returns the available options with their IDs.
+
+```typescript
+{
+  name: 'get_board_custom_fields',
+  arguments: {
+    boardId?: string  // Optional: ID of the board (uses default if not provided)
+  }
+}
+```
+
+**Returns:** Array of custom field definitions including:
+- Field ID, name, type (`text`, `number`, `checkbox`, `date`, `list`)
+- For `list` type fields: available options with IDs (use these IDs when setting values)
+
+#### update\_card\_custom\_field
+
+Set or clear a custom field value on a card.
+
+```typescript
+{
+  name: 'update_card_custom_field',
+  arguments: {
+    cardId: string,       // ID of the card to update
+    customFieldId: string,// ID of the custom field definition
+    type: string,         // Field type: 'text' | 'number' | 'checkbox' | 'date' | 'list' | 'clear'
+    value?: string        // The value to set (not needed when type is 'clear')
+  }
+}
+```
+
+**Value format by type:**
+- `text`: any string
+- `number`: numeric string (e.g. `"42.5"`)
+- `checkbox`: `"true"` or `"false"`
+- `date`: ISO 8601 string (e.g. `"2025-12-31T00:00:00.000Z"`)
+- `list`: option ID from `get_board_custom_fields`
+- `clear`: omit value to remove the field value
+
 ## Integration Examples
 
 ### 🎨 Pairing with Ideogram MCP Server
@@ -767,7 +856,7 @@ Add both servers to your Claude Desktop configuration. Use `bunx` for the fastes
     "trello": {
       "command": "bunx",
       "args": ["@delorenj/mcp-server-trello"],
-nbsp;   "env": {
+   "env": {
         "TRELLO_API_KEY": "your-trello-api-key",
         "TRELLO_TOKEN": "your-trello-token"
       }
@@ -859,7 +948,7 @@ Contributions are welcome\!
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](https://www.google.com/search?q=LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
 ## Acknowledgments