@delorenj/mcp-server-trello 0.2.1 → 1.0.0

package/README.md

@@ -1,14 +1,45 @@
 # MCP Server Trello
-[![smithery badge](https://smithery.ai/badge/@modelcontextprotocol/mcp-server-trello)](https://smithery.ai/server/@modelcontextprotocol/mcp-server-trello)
 
-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.
+[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/27359682-7632-4ba7-981d-7dfecadf1c4b)
 
 <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.
+
 ## Changelog
 
-### 0.1.2
+### 1.0.0
+
+- Fixed MCP protocol compatibility by removing all console output that interfered with JSON-RPC communication
+- Improved pnpx support - now works seamlessly with `pnpx @delorenj/mcp-server-trello`
+- Updated installation docs to feature pnpx as the primary installation method
+- Added mise installation instructions for convenient tool management
+- Production-ready release with stable API
+
+### 0.3.0
+
+- Added multi-board support - all methods now accept optional `boardId` parameter (thanks @blackoutnet!)
+- `TRELLO_BOARD_ID` environment variable is now optional and serves as default board
+- Added board and workspace management capabilities:
+  - `list_boards` - List all boards the user has access to
+  - `set_active_board` - Set the active board for future operations
+  - `list_workspaces` - List all workspaces the user has access to
+  - `set_active_workspace` - Set the active workspace for future operations
+  - `list_boards_in_workspace` - List all boards in a specific workspace
+  - `get_active_board_info` - Get information about the currently active board
+- Added persistent configuration storage to remember active board/workspace
+- Improved error handling with MCP-specific error types
+- Full backward compatibility maintained
 
+### 0.2.1
+
+- Added detailed JSDoc comments to rate limiter functions
+- Improved error handling for image attachment functionality
+- Updated documentation for attach_image_to_card tool
+
+### 0.2.0
+
+- Added `attach_image_to_card` tool to attach images to cards from URLs
 - Added Docker support with multi-stage build
 - Improved security by moving environment variables to `.env`
 - Added Docker Compose configuration
@@ -30,29 +61,68 @@ A Model Context Protocol (MCP) server that provides tools for interacting with T
 - **Type-Safe Implementation**: Written in TypeScript with comprehensive type definitions
 - **Input Validation**: Robust validation for all API inputs
 - **Error Handling**: Graceful error handling with informative messages
+- **Dynamic Board Selection**: Switch between boards and workspaces without restarting
 
 ## Installation
 
-### Docker Installation (Recommended)
+### Quick Start with pnpx (Recommended)
 
-The easiest way to run the server is using Docker:
+The easiest way to use the Trello MCP server is with `pnpx`, which doesn't require a global install:
 
-1. Clone the repository:
-```bash
-git clone https://github.com/delorenj/mcp-server-trello
-cd mcp-server-trello
+```json
+{
+  "mcpServers": {
+    "trello": {
+      "command": "pnpx",
+      "args": ["@delorenj/mcp-server-trello"],
+      "env": {
+        "TRELLO_API_KEY": "your-api-key",
+        "TRELLO_TOKEN": "your-token"
+      }
+    }
+  }
+}
 ```
 
-2. Copy the environment template and fill in your Trello credentials:
+Or if you're using mise:
+
+```json
+{
+  "mcpServers": {
+    "trello": {
+      "command": "mise",
+      "args": ["x", "--", "pnpx", "@delorenj/mcp-server-trello"],
+      "env": {
+        "TRELLO_API_KEY": "your-api-key",
+        "TRELLO_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+#### Don't have pnpm?
+
+The simplest way to get `pnpm` (and thus `pnpx`) is through [mise](https://mise.jdx.dev/):
+
 ```bash
-cp .env.template .env
+# Install mise (if you don't have it)
+curl https://mise.run | sh
+
+# Install pnpm with mise
+mise install pnpm
 ```
 
-3. Build and run with Docker Compose:
+### Installing via npm
+
+If you prefer using npm directly:
+
 ```bash
-docker compose up --build
+npm install -g @delorenj/mcp-server-trello
 ```
 
+Then use `mcp-server-trello` as the command in your MCP configuration.
+
 ### Installing via Smithery
 
 To install Trello Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@modelcontextprotocol/mcp-server-trello):
@@ -61,25 +131,120 @@ To install Trello Server for Claude Desktop automatically via [Smithery](https:/
 npx -y @smithery/cli install @modelcontextprotocol/mcp-server-trello --client claude
 ```
 
-### Manual Installation
+### Docker Installation
+
+For containerized environments:
+
+1. Clone the repository:
+
+```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:
+
+```bash
+cp .env.template .env
+```
+
+3. Build and run with Docker Compose:
+
 ```bash
-npm install @delorenj/mcp-server-trello
+docker compose up --build
 ```
 
 ## Configuration
 
+### Environment Variables
+
 The server can be configured using environment variables. Create a `.env` file in the root directory with the following variables:
 
 ```env
+# Required: Your Trello API credentials
 TRELLO_API_KEY=your-api-key
 TRELLO_TOKEN=your-token
+
+# Optional (Deprecated): Default board ID (can be changed later using set_active_board)
 TRELLO_BOARD_ID=your-board-id
+
+# Optional: Initial workspace ID (can be changed later using set_active_workspace)
+TRELLO_WORKSPACE_ID=your-workspace-id
 ```
 
 You can get these values from:
-- API Key: https://trello.com/app-key
+
+- API Key: <https://trello.com/app-key>
 - Token: Generate using your API key
-- Board ID: Found in the board URL
+- Board ID (optional, deprecated): Found in the board URL (e.g., <https://trello.com/b/BOARD_ID/board-name>)
+- Workspace ID: Found in workspace settings or using `list_workspaces` tool
+
+### Board and Workspace Management
+
+Starting with version 0.3.0, the MCP server supports multiple ways to work with boards:
+
+1. **Multi-board support**: All methods now accept an optional `boardId` parameter
+   - Omit `TRELLO_BOARD_ID` and provide `boardId` in each API call
+   - Set `TRELLO_BOARD_ID` as default and optionally override with `boardId` parameter
+
+2. **Dynamic board selection**: Use workspace management tools
+   - The `TRELLO_BOARD_ID` in your `.env` file is used as the initial/default board ID
+   - You can change the active board at any time using the `set_active_board` tool
+   - The selected board persists between server restarts (stored in `~/.trello-mcp/config.json`)
+   - Similarly, you can set and persist an active workspace using `set_active_workspace`
+
+This allows you to work with multiple boards and workspaces without restarting the server.
+
+#### Example Workflow
+
+1. Start by listing available boards:
+
+```typescript
+{
+  name: 'list_boards',
+  arguments: {}
+}
+```
+
+2. Set your active board:
+
+```typescript
+{
+  name: 'set_active_board',
+  arguments: {
+    boardId: "abc123"  // ID from list_boards response
+  }
+}
+```
+
+3. List workspaces if needed:
+
+```typescript
+{
+  name: 'list_workspaces',
+  arguments: {}
+}
+```
+
+4. Set active workspace if needed:
+
+```typescript
+{
+  name: 'set_active_workspace',
+  arguments: {
+    workspaceId: "xyz789"  // ID from list_workspaces response
+  }
+}
+```
+
+5. Check current active board info:
+
+```typescript
+{
+  name: 'get_active_board_info',
+  arguments: {}
+}
+```
 
 ## Available Tools
 
@@ -91,31 +256,35 @@ Fetch all cards from a specific list.
 {
   name: 'get_cards_by_list_id',
   arguments: {
-    listId: string  // ID of the Trello list
+    boardId?: string, // Optional: ID of the board (uses default if not provided)
+    listId: string    // ID of the Trello list
   }
 }
 ```
 
 ### get_lists
 
-Retrieve all lists from the configured board.
+Retrieve all lists from a board.
 
 ```typescript
 {
   name: 'get_lists',
-  arguments: {}
+  arguments: {
+    boardId?: string  // Optional: ID of the board (uses default if not provided)
+  }
 }
 ```
 
 ### get_recent_activity
 
-Fetch recent activity on the board.
+Fetch recent activity on a board.
 
 ```typescript
 {
   name: 'get_recent_activity',
   arguments: {
-    limit?: number  // Optional: Number of activities to fetch (default: 10)
+    boardId?: string, // Optional: ID of the board (uses default if not provided)
+    limit?: number    // Optional: Number of activities to fetch (default: 10)
   }
 }
 ```
@@ -128,6 +297,7 @@ Add a new card to a specified list.
 {
   name: 'add_card_to_list',
   arguments: {
+    boardId?: string,     // Optional: ID of the board (uses default if not provided)
     listId: string,       // ID of the list to add the card to
     name: string,         // Name of the card
     description?: string, // Optional: Description of the card
@@ -145,6 +315,7 @@ Update an existing card's details.
 {
   name: 'update_card_details',
   arguments: {
+    boardId?: string,     // Optional: ID of the board (uses default if not provided)
     cardId: string,       // ID of the card to update
     name?: string,        // Optional: New name for the card
     description?: string, // Optional: New description
@@ -162,20 +333,22 @@ Send a card to the archive.
 {
   name: 'archive_card',
   arguments: {
-    cardId: string  // ID of the card to archive
+    boardId?: string, // Optional: ID of the board (uses default if not provided)
+    cardId: string    // ID of the card to archive
   }
 }
 ```
 
 ### add_list_to_board
 
-Add a new list to the board.
+Add a new list to a board.
 
 ```typescript
 {
   name: 'add_list_to_board',
   arguments: {
-    name: string  // Name of the new list
+    boardId?: string, // Optional: ID of the board (uses default if not provided)
+    name: string      // Name of the new list
   }
 }
 ```
@@ -188,7 +361,8 @@ Send a list to the archive.
 {
   name: 'archive_list',
   arguments: {
-    listId: string  // ID of the list to archive
+    boardId?: string, // Optional: ID of the board (uses default if not provided)
+    listId: string    // ID of the list to archive
   }
 }
 ```
@@ -212,12 +386,165 @@ Move a card to a different list.
 {
   name: 'move_card',
   arguments: {
-    cardId: string,  // ID of the card to move
-    listId: string   // ID of the target list
+    boardId?: string,  // Optional: ID of the target board (uses default if not provided)
+    cardId: string,    // ID of the card to move
+    listId: string     // ID of the target list
+  }
+}
+```
+
+### attach_image_to_card
+
+Attach an image to a card directly from a URL.
+
+```typescript
+{
+  name: 'attach_image_to_card',
+  arguments: {
+    boardId?: string, // Optional: ID of the board (uses default if not provided)
+    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")
+  }
+}
+```
+
+### list_boards
+
+List all boards the user has access to.
+
+```typescript
+{
+  name: 'list_boards',
+  arguments: {}
+}
+```
+
+### set_active_board
+
+Set the active board for future operations.
+
+```typescript
+{
+  name: 'set_active_board',
+  arguments: {
+    boardId: string  // ID of the board to set as active
+  }
+}
+```
+
+### list_workspaces
+
+List all workspaces the user has access to.
+
+```typescript
+{
+  name: 'list_workspaces',
+  arguments: {}
+}
+```
+
+### set_active_workspace
+
+Set the active workspace for future operations.
+
+```typescript
+{
+  name: 'set_active_workspace',
+  arguments: {
+    workspaceId: string  // ID of the workspace to set as active
   }
 }
 ```
 
+### list_boards_in_workspace
+
+List all boards in a specific workspace.
+
+```typescript
+{
+  name: 'list_boards_in_workspace',
+  arguments: {
+    workspaceId: string  // ID of the workspace to list boards from
+  }
+}
+```
+
+### get_active_board_info
+
+Get information about the currently active board.
+
+```typescript
+{
+  name: 'get_active_board_info',
+  arguments: {}
+}
+```
+
+## Integration Examples
+
+### 🎨 Pairing with Ideogram MCP Server
+
+The Trello MCP server pairs beautifully with [@flowluap/ideogram-mcp-server](https://github.com/flowluap/ideogram-mcp-server) for AI-powered visual content creation. Generate images with Ideogram and attach them directly to your Trello cards!
+
+![Ideogram + Trello Integration Example](https://ss.delo.sh/hosted/20250717-0619.png)
+
+#### Example Workflow
+
+1. **Generate an image with Ideogram:**
+```typescript
+// Using ideogram-mcp-server
+{
+  name: 'generate_image',
+  arguments: {
+    prompt: "A futuristic dashboard design with neon accents",
+    aspect_ratio: "16:9"
+  }
+}
+// Returns: { image_url: "https://..." }
+```
+
+2. **Attach the generated image to a Trello card:**
+```typescript
+// Using trello-mcp-server
+{
+  name: 'attach_image_to_card',
+  arguments: {
+    cardId: "your-card-id",
+    imageUrl: "https://...", // URL from Ideogram
+    name: "Dashboard Mockup v1"
+  }
+}
+```
+
+#### Setting up both servers
+
+Add both servers to your Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "trello": {
+      "command": "pnpx",
+      "args": ["@delorenj/mcp-server-trello"],
+      "env": {
+        "TRELLO_API_KEY": "your-trello-api-key",
+        "TRELLO_TOKEN": "your-trello-token"
+      }
+    },
+    "ideogram": {
+      "command": "pnpx",
+      "args": ["@flowluap/ideogram-mcp-server"],
+      "env": {
+        "IDEOGRAM_API_KEY": "your-ideogram-api-key"
+      }
+    }
+  }
+}
+```
+
+Now you can seamlessly create visual content and organize it in Trello, all within Claude!
+
 ## Rate Limiting
 
 The server implements a token bucket algorithm for rate limiting to comply with Trello's API limits:
@@ -265,6 +592,13 @@ npm install
 npm run build
 ```
 
+## Running evals
+
+The evals package loads an mcp client that then runs the index.ts file, so there is no need to rebuild between tests. You can load environment variables by prefixing the npx command. Full documentation can be found [here](https://www.mcpevals.io/docs).
+
+```bash
+OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/index.ts
+```
 
 ## Contributing
 

package/build/evals/evals.d.ts

@@ -0,0 +1,5 @@
+import { EvalConfig } from 'mcp-evals';
+import { EvalFunction } from "mcp-evals";
+declare const config: EvalConfig;
+export default config;
+export declare const evals: EvalFunction[];

package/build/evals/evals.js

@@ -0,0 +1,50 @@
+//evals.ts
+import { openai } from "@ai-sdk/openai";
+import { grade } from "mcp-evals";
+const get_cards_by_list_idEval = {
+    name: 'get_cards_by_list_id Tool Evaluation',
+    description: 'Evaluates the get_cards_by_list_id tool functionality',
+    run: async () => {
+        const result = await grade(openai("gpt-4"), "Can you fetch all cards from the Trello list with ID abc123?");
+        return JSON.parse(result);
+    }
+};
+const get_listsEval = {
+    name: 'get_lists Tool Evaluation',
+    description: 'Evaluates the get_lists tool by retrieving all lists from a specified board',
+    run: async () => {
+        const result = await grade(openai("gpt-4"), "Please retrieve all lists from the board with ID 12345 and provide their names.");
+        return JSON.parse(result);
+    }
+};
+const get_recent_activityEvalFunction = {
+    name: 'get_recent_activity Tool Evaluation',
+    description: 'Evaluates the ability to fetch recent activity on the Trello board',
+    run: async () => {
+        const result = await grade(openai("gpt-4"), "Fetch the recent activity on the Trello board, limit it to 5 items");
+        return JSON.parse(result);
+    }
+};
+const add_card_to_listEval = {
+    name: 'add_card_to_listEval',
+    description: 'Evaluates the add_card_to_list tool',
+    run: async () => {
+        const result = await grade(openai("gpt-4"), "Please add a new card named 'Demo Card' to the list with ID 'abc123', with a description of 'This is a test card', due date '2023-12-31T12:00:00Z', and a label 'priority'.");
+        return JSON.parse(result);
+    }
+};
+const update_card_detailsEval = {
+    name: 'update_card_details Evaluation',
+    description: 'Evaluates the update_card_details tool functionality',
+    run: async () => {
+        const result = await grade(openai("gpt-4"), "Please update the card with ID 'abc123' to have the name 'Updated Card Name', the description 'New description for the card', a due date of '2024-01-01T10:00:00Z', and labels ['priority','review'].");
+        return JSON.parse(result);
+    }
+};
+const config = {
+    model: openai("gpt-4"),
+    evals: [get_cards_by_list_idEval, get_listsEval, get_recent_activityEvalFunction, add_card_to_listEval, update_card_detailsEval]
+};
+export default config;
+export const evals = [get_cards_by_list_idEval, get_listsEval, get_recent_activityEvalFunction, add_card_to_listEval, update_card_detailsEval];
+//# sourceMappingURL=evals.js.map

package/build/evals/evals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evals.js","sourceRoot":"","sources":["../../src/evals/evals.ts"],"names":[],"mappings":"AAAA,UAAU;AAGV,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAE,KAAK,EAAgB,MAAM,WAAW,CAAC;AAEhD,MAAM,wBAAwB,GAAiB;IAC3C,IAAI,EAAE,sCAAsC;IAC5C,WAAW,EAAE,uDAAuD;IACpE,GAAG,EAAE,KAAK,IAAI,EAAE;QACZ,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,8DAA8D,CAAC,CAAC;QAC5G,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;CACJ,CAAC;AAEF,MAAM,aAAa,GAAiB;IAChC,IAAI,EAAE,2BAA2B;IACjC,WAAW,EAAE,6EAA6E;IAC1F,GAAG,EAAE,KAAK,IAAI,EAAE;QACZ,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,iFAAiF,CAAC,CAAC;QAC/H,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;CACJ,CAAC;AAEF,MAAM,+BAA+B,GAAiB;IAClD,IAAI,EAAE,qCAAqC;IAC3C,WAAW,EAAE,oEAAoE;IACjF,GAAG,EAAE,KAAK,IAAI,EAAE;QACZ,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,oEAAoE,CAAC,CAAC;QAClH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;CACJ,CAAC;AAEF,MAAM,oBAAoB,GAAiB;IACvC,IAAI,EAAE,sBAAsB;IAC5B,WAAW,EAAE,qCAAqC;IAClD,GAAG,EAAE,KAAK,IAAI,EAAE;QACZ,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,6KAA6K,CAAC,CAAC;QAC3N,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;CACJ,CAAC;AAEF,MAAM,uBAAuB,GAAiB;IAC1C,IAAI,EAAE,gCAAgC;IACtC,WAAW,EAAE,sDAAsD;IACnE,GAAG,EAAE,KAAK,IAAI,EAAE;QACZ,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,uMAAuM,CAAC,CAAC;QACrP,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;CACJ,CAAC;AAEF,MAAM,MAAM,GAAe;IACvB,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC;IACtB,KAAK,EAAE,CAAC,wBAAwB,EAAE,aAAa,EAAE,+BAA+B,EAAE,oBAAoB,EAAE,uBAAuB,CAAC;CACnI,CAAC;AAEF,eAAe,MAAM,CAAC;AAEtB,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,wBAAwB,EAAE,aAAa,EAAE,+BAA+B,EAAE,oBAAoB,EAAE,uBAAuB,CAAC,CAAC"}