@delorenj/mcp-server-trello 1.7.1 → 1.8.0

package/README.md

@@ -15,7 +15,7 @@ A Model Context Protocol (MCP) server that provides tools for interacting with T
 ### ✨ 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.
+  - **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!
@@ -39,154 +39,40 @@ For a detailed list of changes, please refer to the [CHANGELOG.md](CHANGELOG.md)
 
 ## Installation
 
-### 🚀 Install from MCP Registry (Recommended)
+This repository is distributed as 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.
 
-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:
-
-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
-
-### 🚀 Quick Start with Bun (Fastest)
-
-If you have [Bun](https://bun.sh) installed, using `bunx` is the fastest way to run the server:
-
-```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"
-      }
-    }
-  }
-}
-```
-
-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
-
-This will generate the token required for integration.
-
-> [\!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/):
-
-```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
-```
-
-### Installing via npm
-
-If you prefer using `npm` directly:
+When an agent activates the skill, it follows `skill/SKILL.md`. On first use,
+the agent runs the bundled installer:
 
 ```bash
-npm install -g @delorenj/mcp-server-trello
+bash skill/scripts/install.sh
 ```
 
-*(A fast alternative is `bun add -g @delorenj/mcp-server-trello`)*
+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.
 
-Then use `npx mcp-server-trello` as the command in your MCP configuration.
+## Skill package structure
 
-### Installing via Smithery
+The skill is the agent-facing entry point for this repository.
 
-To install Trello Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@delorenj/mcp-server-trello):
+- `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
-# 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
-```
-
-### Docker Installation
-
-For containerized environments:
-
-1.  Clone the repository:
-
-<!-- end list -->
-
-```bash
-git clone https://github.com/delorenj/mcp-server-trello
-cd mcp-server-trello
-```
+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.
 
-2.  Copy the environment template and fill in your Trello credentials:
-
-<!-- end list -->
+Maintainers can refresh the bundled source before packaging with:
 
 ```bash
-cp .env.template .env
-```
-
-3.  Build and run with Docker Compose:
-
-<!-- end list -->
-
-```bash
-docker compose up --build
+mise run package
 ```
 
 ## Configuration
@@ -205,13 +91,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 +125,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:
@@ -381,6 +299,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.
@@ -528,6 +480,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.
@@ -587,6 +570,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 +719,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