trollo-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,145 @@
+# Trollo MCP Server
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets AI agents manage [Trollo](https://trollo.lol) kanban boards. Works with any MCP-compatible client: Cursor, Claude Desktop, and others.
+
+## Quick Start
+
+### Using npx (no install)
+
+The fastest way to get started. Your MCP client runs the server on demand:
+
+```json
+{
+  "mcpServers": {
+    "trollo": {
+      "command": "npx",
+      "args": ["-y", "trollo-mcp-server"],
+      "env": {
+        "TROLLO_URL": "https://trollo.lol",
+        "TROLLO_API_KEY": "trlo_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Global install
+
+```bash
+npm install -g trollo-mcp-server
+```
+
+Then configure your client to run `trollo-mcp`:
+
+```json
+{
+  "mcpServers": {
+    "trollo": {
+      "command": "trollo-mcp",
+      "env": {
+        "TROLLO_URL": "https://trollo.lol",
+        "TROLLO_API_KEY": "trlo_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### From source (this repo)
+
+```bash
+cd mcp
+npm install
+npm run build
+```
+
+Then point your client to the local build:
+
+```json
+{
+  "mcpServers": {
+    "trollo": {
+      "command": "node",
+      "args": ["mcp/dist/index.js"],
+      "env": {
+        "TROLLO_URL": "https://trollo.lol",
+        "TROLLO_API_KEY": "trlo_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Environment Variable | Description |
+|---|---|
+| `TROLLO_URL` | Base URL of the Trollo instance (e.g. `https://trollo.lol`) |
+| `TROLLO_API_KEY` | API key starting with `trlo_` — create one in Trollo under Settings > API Keys |
+
+## Where to put the config
+
+| Client | Config file |
+|---|---|
+| Cursor | `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
+
+## Tools
+
+### Reading
+
+| Tool | Description |
+|---|---|
+| `list_boards` | List all boards accessible to the API key |
+| `get_board` | Get full board state: lists, cards, checklists, comments, labels, users |
+
+### Lists
+
+| Tool | Parameters | Description |
+|---|---|---|
+| `add_list` | `boardId`, `title`, `position?` | Add a new list |
+| `rename_list` | `boardId`, `listId`, `title` | Rename a list |
+| `move_list` | `boardId`, `listId`, `position` | Reorder a list |
+| `remove_list` | `boardId`, `listId` | Remove a list |
+
+### Cards
+
+| Tool | Parameters | Description |
+|---|---|---|
+| `add_card` | `boardId`, `listId`, `title` | Add a card to a list |
+| `move_card` | `boardId`, `cardId`, `toListId`, `position` | Move a card |
+| `remove_card` | `boardId`, `cardId`, `fromListId` | Remove a card |
+| `edit_card` | `boardId`, `cardId`, `title?`, `description?` | Edit title and/or description |
+| `set_card_due` | `boardId`, `cardId`, `due?` | Set or remove due date |
+| `set_card_points` | `boardId`, `cardId`, `points?` | Set or remove story points |
+| `manage_card_label` | `boardId`, `cardId`, `labelIndex`, `action` | Add or remove a label |
+
+### Comments
+
+| Tool | Parameters | Description |
+|---|---|---|
+| `add_comment` | `boardId`, `cardId`, `body` | Add a comment (supports markdown) |
+
+### Checklists
+
+| Tool | Parameters | Description |
+|---|---|---|
+| `add_checklist` | `boardId`, `cardId`, `title` | Add a checklist to a card |
+| `add_checklist_item` | `boardId`, `cardId`, `checklistId`, `title` | Add a checklist item |
+| `toggle_checklist_item` | `boardId`, `cardId`, `itemId`, `checked` | Check or uncheck an item |
+
+## API Key Permissions
+
+Each API key in Trollo has per-action permissions. If a tool call is denied, the key may not have the required permission enabled. Manage permissions in Trollo under Settings > API Keys.
+
+## Publishing
+
+To publish a new version to npm:
+
+```bash
+cd mcp
+npm version patch   # or minor / major
+npm publish
+```
+
+The `prepublishOnly` script builds automatically before publishing.

package/dist/client.d.ts

@@ -0,0 +1,27 @@
+export interface TrolloBoard {
+    id: string;
+    title: string;
+    shared: number;
+    archived?: boolean;
+    groupId?: number;
+    isOwner: boolean;
+    role: number | string | null;
+}
+export interface ActionResult {
+    result: string;
+    userId?: number;
+    value?: string | number | null;
+}
+export declare class TrolloClient {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    private request;
+    listBoards(): Promise<{
+        boards: TrolloBoard[];
+    }>;
+    getBoard(boardId: string): Promise<{
+        board: Record<string, unknown>;
+    }>;
+    performAction(boardId: string, type: string, data: unknown[]): Promise<ActionResult>;
+}

package/dist/client.js

@@ -0,0 +1,33 @@
+export class TrolloClient {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+        this.apiKey = apiKey;
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const res = await fetch(url, {
+            method,
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => res.statusText);
+            throw new Error(`Trollo API ${method} ${path} failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    async listBoards() {
+        return this.request('GET', '/api/v1/boards');
+    }
+    async getBoard(boardId) {
+        return this.request('GET', `/api/v1/boards/${encodeURIComponent(boardId)}`);
+    }
+    async performAction(boardId, type, data) {
+        return this.request('POST', `/api/v1/boards/${encodeURIComponent(boardId)}/action`, { type, data });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { TrolloClient } from './client.js';
+import { registerBoardTools } from './tools/boards.js';
+import { registerListTools } from './tools/lists.js';
+import { registerCardTools } from './tools/cards.js';
+import { registerCommentTools } from './tools/comments.js';
+import { registerChecklistTools } from './tools/checklists.js';
+const url = process.env.TROLLO_URL;
+const key = process.env.TROLLO_API_KEY;
+if (!url || !key) {
+    console.error('Missing required environment variables: TROLLO_URL and TROLLO_API_KEY');
+    process.exit(1);
+}
+const client = new TrolloClient(url, key);
+const server = new McpServer({ name: 'trollo', version: '1.0.0' }, {
+    capabilities: { tools: {} },
+    instructions: [
+        'Trollo is a Trello-like kanban board app.',
+        '',
+        'Data model: Board contains labels[] ({color, title?} indexed 0-based), users[] ({id, name, email}), and lists[] ({id, title}). Each list contains cards[] ({id, title, slug, description, due?, points?}). Each card has labels[] (array of label indices), users[] (array of user IDs), checklists[] ({id, title} with items[] ({id, title, checked?})), comments[] ({id, body, userId}), and files[] ({id, name, url}).',
+        '',
+        'All entity IDs are integers. Always call get_board first to discover IDs before performing actions.',
+        '',
+        'Workflow patterns:',
+        '- Reading: call list_boards to find board IDs, then get_board for the full state.',
+        '- Adding cards: get_board to find the target listId, then add_card with boardId, listId, and title.',
+        '- Moving cards between lists: get_board to read source list cards, then move_card for each card with its id, the destination listId, and position.',
+        '- Checklists: add_checklist on a card, note the returned checklist ID, then add_checklist_item for each item.',
+        '',
+        'Limitations: encrypted boards are not accessible, file uploads are not supported, viewer-role keys cannot write, each API key has per-action permissions.',
+    ].join('\n'),
+});
+registerBoardTools(server, client);
+registerListTools(server, client);
+registerCardTools(server, client);
+registerCommentTools(server, client);
+registerChecklistTools(server, client);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tools/boards.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { TrolloClient } from '../client.js';
+export declare function registerBoardTools(server: McpServer, client: TrolloClient): void;

package/dist/tools/boards.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+export function registerBoardTools(server, client) {
+    server.tool('list_boards', 'List all Trollo boards accessible to the configured API key', async () => {
+        const { boards } = await client.listBoards();
+        return {
+            content: [{ type: 'text', text: JSON.stringify(boards, null, 2) }],
+        };
+    });
+    server.tool('get_board', 'Get full board state including lists, cards, labels, users, checklists, and comments', { boardId: z.string().describe('The board ID') }, async ({ boardId }) => {
+        const { board } = await client.getBoard(boardId);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(board, null, 2) }],
+        };
+    });
+}

package/dist/tools/cards.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { TrolloClient } from '../client.js';
+export declare function registerCardTools(server: McpServer, client: TrolloClient): void;

package/dist/tools/cards.js

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+export function registerCardTools(server, client) {
+    server.tool('add_card', 'Add a new card to a list', {
+        boardId: z.string().describe('The board ID'),
+        listId: z.number().int().describe('The list ID to add the card to'),
+        title: z.string().describe('Title for the new card'),
+    }, async ({ boardId, listId, title }) => {
+        const result = await client.performAction(boardId, 'CardAdded', [listId, title]);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    server.tool('move_card', 'Move a card to a different list and/or position', {
+        boardId: z.string().describe('The board ID'),
+        cardId: z.number().int().describe('The card ID to move'),
+        toListId: z.number().int().describe('Destination list ID'),
+        position: z.number().int().describe('Position index in the destination list'),
+    }, async ({ boardId, cardId, toListId, position }) => {
+        const result = await client.performAction(boardId, 'CardMoved', [cardId, toListId, position]);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    server.tool('remove_card', 'Remove a card from a list', {
+        boardId: z.string().describe('The board ID'),
+        cardId: z.number().int().describe('The card ID to remove'),
+        fromListId: z.number().int().describe('The list ID the card belongs to'),
+    }, async ({ boardId, cardId, fromListId }) => {
+        const result = await client.performAction(boardId, 'CardRemoved', [cardId, fromListId]);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    server.tool('edit_card', 'Edit a card\'s title and/or description. Provide at least one of title or description.', {
+        boardId: z.string().describe('The board ID'),
+        cardId: z.number().int().describe('The card ID to edit'),
+        title: z.string().optional().describe('New title (omit to leave unchanged)'),
+        description: z.string().optional().describe('New description in markdown (omit to leave unchanged)'),
+    }, async ({ boardId, cardId, title, description }) => {
+        const results = [];
+        if (title !== undefined) {
+            results.push(await client.performAction(boardId, 'CardTitleChange', [cardId, title]));
+        }
+        if (description !== undefined) {
+            results.push(await client.performAction(boardId, 'CardDescriptionChange', [cardId, description]));
+        }
+        if (results.length === 0) {
+            return { content: [{ type: 'text', text: 'No changes specified — provide title and/or description.' }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(results.length === 1 ? results[0] : results) }] };
+    });
+    server.tool('set_card_due', 'Set or remove a card\'s due date', {
+        boardId: z.string().describe('The board ID'),
+        cardId: z.number().int().describe('The card ID'),
+        due: z.number().optional().describe('Due date as Unix timestamp in milliseconds. Omit to remove the due date.'),
+    }, async ({ boardId, cardId, due }) => {
+        const result = due !== undefined
+            ? await client.performAction(boardId, 'CardDueSet', [cardId, due])
+            : await client.performAction(boardId, 'CardDueRemoved', [cardId]);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    server.tool('set_card_points', 'Set or remove story points on a card', {
+        boardId: z.string().describe('The board ID'),
+        cardId: z.number().int().describe('The card ID'),
+        points: z.number().optional().describe('Story points value. Omit to remove.'),
+    }, async ({ boardId, cardId, points }) => {
+        const result = points !== undefined
+            ? await client.performAction(boardId, 'CardPointsSet', [cardId, points])
+            : await client.performAction(boardId, 'CardPointsRemoved', [cardId]);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    server.tool('manage_card_label', 'Add or remove a label on a card', {
+        boardId: z.string().describe('The board ID'),
+        cardId: z.number().int().describe('The card ID'),
+        labelIndex: z.number().int().describe('Index of the label in the board\'s labels array'),
+        action: z.enum(['add', 'remove']).describe('Whether to add or remove the label'),
+    }, async ({ boardId, cardId, labelIndex, action }) => {
+        const type = action === 'add' ? 'CardLabelAdd' : 'CardLabelRemove';
+        const result = await client.performAction(boardId, type, [cardId, labelIndex]);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+}

package/dist/tools/checklists.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { TrolloClient } from '../client.js';
+export declare function registerChecklistTools(server: McpServer, client: TrolloClient): void;

package/dist/tools/checklists.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+export function registerChecklistTools(server, client) {
+    server.tool('add_checklist', 'Add a checklist to a card', {
+        boardId: z.string().describe('The board ID'),
+        cardId: z.number().int().describe('The card ID to add the checklist to'),
+        title: z.string().describe('Checklist title'),
+    }, async ({ boardId, cardId, title }) => {
+        const result = await client.performAction(boardId, 'CLAdded', [cardId, title]);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    server.tool('add_checklist_item', 'Add an item to an existing checklist', {
+        boardId: z.string().describe('The board ID'),
+        cardId: z.number().int().describe('The card ID'),
+        checklistId: z.number().int().describe('The checklist ID'),
+        title: z.string().describe('Item title'),
+    }, async ({ boardId, cardId, checklistId, title }) => {
+        const result = await client.performAction(boardId, 'CLIAdded', [cardId, checklistId, title]);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    server.tool('toggle_checklist_item', 'Check or uncheck a checklist item', {
+        boardId: z.string().describe('The board ID'),
+        cardId: z.number().int().describe('The card ID'),
+        itemId: z.number().int().describe('The checklist item ID'),
+        checked: z.boolean().describe('true to check, false to uncheck'),
+    }, async ({ boardId, cardId, itemId, checked }) => {
+        const type = checked ? 'CLIChecked' : 'CLIUnchecked';
+        const result = await client.performAction(boardId, type, [cardId, itemId]);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+}

package/dist/tools/comments.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { TrolloClient } from '../client.js';
+export declare function registerCommentTools(server: McpServer, client: TrolloClient): void;

package/dist/tools/comments.js

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+export function registerCommentTools(server, client) {
+    server.tool('add_comment', 'Add a comment to a card', {
+        boardId: z.string().describe('The board ID'),
+        cardId: z.number().int().describe('The card ID to comment on'),
+        body: z.string().describe('Comment body (supports markdown)'),
+    }, async ({ boardId, cardId, body }) => {
+        const result = await client.performAction(boardId, 'CMAdded', [cardId, body]);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+}

package/dist/tools/lists.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { TrolloClient } from '../client.js';
+export declare function registerListTools(server: McpServer, client: TrolloClient): void;

package/dist/tools/lists.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+export function registerListTools(server, client) {
+    server.tool('add_list', 'Add a new list to a board', {
+        boardId: z.string().describe('The board ID'),
+        title: z.string().describe('Title for the new list'),
+        position: z.number().int().optional().describe('Position index to insert at (appends to end if omitted)'),
+    }, async ({ boardId, title, position }) => {
+        const result = await client.performAction(boardId, 'ListAdded', [position ?? null, title]);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    server.tool('rename_list', 'Rename an existing list', {
+        boardId: z.string().describe('The board ID'),
+        listId: z.number().int().describe('The list ID'),
+        title: z.string().describe('New title for the list'),
+    }, async ({ boardId, listId, title }) => {
+        const result = await client.performAction(boardId, 'ListRenamed', [listId, title]);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    server.tool('move_list', 'Move a list to a new position on the board', {
+        boardId: z.string().describe('The board ID'),
+        listId: z.number().int().describe('The list ID'),
+        position: z.number().int().describe('New position index'),
+    }, async ({ boardId, listId, position }) => {
+        const result = await client.performAction(boardId, 'ListMoved', [listId, position]);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    server.tool('remove_list', 'Remove a list from the board', {
+        boardId: z.string().describe('The board ID'),
+        listId: z.number().int().describe('The list ID to remove'),
+    }, async ({ boardId, listId }) => {
+        const result = await client.performAction(boardId, 'ListRemoved', [listId]);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "trollo-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for managing Trollo kanban boards from AI agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "trollo-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "trollo",
+    "kanban",
+    "ai",
+    "agent"
+  ],
+  "license": "none",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Q42/Trollo",
+    "directory": "mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.8.2"
+  }
+}