@mauvable/flowboards-mcp 1.0.0

package/README.md

@@ -0,0 +1,78 @@
+# @mauvable/flowboards-mcp
+
+MCP server for [Flow Boards](https://fb.mauvable.com) — exposes the full Flow Boards REST API as Claude tools.
+
+## Installation
+
+Add to your Claude / MCP-compatible AI tool config:
+
+```json
+{
+  "mcpServers": {
+    "flowboards": {
+      "command": "npx",
+      "args": ["-y", "@mauvable/flowboards-mcp"],
+      "env": {
+        "FLOW_BOARDS_URL": "https://<host>/rest/2/<org-id>",
+        "FLOW_BOARDS_TOKEN": "<your-bearer-token>"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Variable | Description |
+|----------|-------------|
+| `FLOW_BOARDS_URL` | Full API base URL including org path, e.g. `https://n1.fb.mauvable.com/rest/2/<org-id>` |
+| `FLOW_BOARDS_TOKEN` | Bearer token for authentication |
+
+## Available Tools
+
+### Tickets
+- `create_ticket` — Create a ticket in a flow (accepts flow name, resolves IDs automatically)
+- `get_ticket` — Get ticket details
+- `list_tickets` — List tickets by bin, parent, or child
+- `update_ticket` — Update ticket fields
+- `move_ticket` — Move ticket to a different bin
+- `delete_ticket` / `delete_tickets` — Delete one or many tickets
+- `archive_tickets` / `restore_tickets` — Archive or restore tickets
+- `link_to_parent` — Link stories to an epic
+- `unlink_from_parent` — Remove parent relationship
+- `list_ticket_moves` — Movement history for a ticket
+
+### Flows
+- `list_flows` — List all flows
+- `get_flow` — Get flow details
+- `list_flow_tickets` — List tickets in a flow
+- `list_flow_moves` — Movement history for a flow
+
+### Bins
+- `list_bins` / `get_bin` — List or get bins
+- `create_bin` / `update_bin` — Create or update bins
+
+### Boards
+- `list_boards` / `get_board`
+
+### Comments
+- `add_comment` — Add a comment to a ticket
+- `list_comments` / `get_comment` — Read comments
+- `update_comment` / `delete_comment`
+
+### Other
+- `list_ticket_types` — Available ticket types (User Story, Epic, etc.)
+- `list_custom_fields`
+- `list_users` / `get_user` / `invite_user`
+- `list_user_groups`
+- `search_tickets`
+- `list_webhooks` / `create_webhook` / `delete_webhook` / `test_webhook`
+
+## Example Usage
+
+Once configured, just talk to Claude naturally:
+
+> "Create 3 user stories in the Backlog flow"
+> "Move all stories in 'In Progress' to 'Done' in the Dev flow"
+> "Add a comment 'Ready for review' to ticket abc123"
+> "Link stories X, Y, Z to epic E"

package/dist/client.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+export declare function apiGet<T>(path: string): Promise<T>;
+export declare function apiPost(path: string, body?: unknown): Promise<void>;
+export declare function apiPut(path: string, body?: unknown): Promise<void>;
+export declare function apiDelete(path: string): Promise<void>;
+export declare function generateId(): string;

package/dist/client.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+const BASE_URL = process.env.FLOW_BOARDS_URL?.replace(/\/$/, '');
+const TOKEN = process.env.FLOW_BOARDS_TOKEN;
+if (!BASE_URL) {
+    process.stderr.write([
+        '',
+        '  flowboards-mcp: missing required configuration',
+        '',
+        '  FLOW_BOARDS_URL is not set.',
+        '',
+        '  Add the following to your MCP server config (e.g. ~/.claude/settings.json):',
+        '',
+        '    {',
+        '      "mcpServers": {',
+        '        "flowboards": {',
+        '          "command": "npx",',
+        '          "args": ["-y", "flowboards-mcp"],',
+        '          "env": {',
+        '            "FLOW_BOARDS_URL": "https://app.getflowboard.com",',
+        '            "FLOW_BOARDS_TOKEN": "<your-api-token>"',
+        '          }',
+        '        }',
+        '      }',
+        '    }',
+        '',
+        '  Get your API token at: https://app.getflowboard.com/settings/api',
+        '',
+    ].join('\n'));
+    process.exit(1);
+}
+if (!TOKEN) {
+    process.stderr.write([
+        '',
+        '  flowboards-mcp: missing required configuration',
+        '',
+        '  FLOW_BOARDS_TOKEN is not set.',
+        '',
+        '  Add the following to your MCP server config (e.g. ~/.claude/settings.json):',
+        '',
+        '    {',
+        '      "mcpServers": {',
+        '        "flowboards": {',
+        '          "command": "npx",',
+        '          "args": ["-y", "flowboards-mcp"],',
+        '          "env": {',
+        '            "FLOW_BOARDS_URL": "https://app.getflowboard.com",',
+        '            "FLOW_BOARDS_TOKEN": "<your-api-token>"',
+        '          }',
+        '        }',
+        '      }',
+        '    }',
+        '',
+        '  Get your API token at: https://app.getflowboard.com/settings/api',
+        '',
+    ].join('\n'));
+    process.exit(1);
+}
+const HEADERS = {
+    'Authorization': `Bearer ${TOKEN}`,
+    'Content-Type': 'application/json',
+};
+export async function apiGet(path) {
+    const res = await fetch(`${BASE_URL}${path}`, { headers: HEADERS });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`GET ${path} failed (${res.status}): ${text}`);
+    }
+    return res.json();
+}
+export async function apiPost(path, body) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method: 'POST',
+        headers: HEADERS,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (res.status !== 200 && res.status !== 201 && res.status !== 204) {
+        const text = await res.text();
+        throw new Error(`POST ${path} failed (${res.status}): ${text}`);
+    }
+}
+export async function apiPut(path, body) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method: 'PUT',
+        headers: HEADERS,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (res.status !== 200 && res.status !== 201 && res.status !== 204) {
+        const text = await res.text();
+        throw new Error(`PUT ${path} failed (${res.status}): ${text}`);
+    }
+}
+export async function apiDelete(path) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method: 'DELETE',
+        headers: HEADERS,
+    });
+    if (res.status !== 200 && res.status !== 201 && res.status !== 204) {
+        const text = await res.text();
+        throw new Error(`DELETE ${path} failed (${res.status}): ${text}`);
+    }
+}
+export function generateId() {
+    const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+    const bytes = new Uint8Array(17);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, b => chars[b % chars.length]).join('');
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerTicketTools } from './tools/tickets.js';
+import { registerFlowTools } from './tools/flows.js';
+import { registerBinTools } from './tools/bins.js';
+import { registerBoardTools } from './tools/boards.js';
+import { registerCommentTools } from './tools/comments.js';
+import { registerMiscTools } from './tools/misc.js';
+const server = new McpServer({
+    name: 'flowboards',
+    version: '1.0.0',
+});
+registerTicketTools(server);
+registerFlowTools(server);
+registerBinTools(server);
+registerBoardTools(server);
+registerCommentTools(server);
+registerMiscTools(server);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/resolver.d.ts

@@ -0,0 +1,5 @@
+export declare function resolveFlowId(nameOrId: string): Promise<string>;
+export declare function resolveFlowFirstBin(nameOrId: string): Promise<string>;
+export declare function resolveBinId(nameOrId: string): Promise<string>;
+export declare function resolveTicketTypeId(nameOrId: string): Promise<string>;
+export declare function resolveBoardId(nameOrId: string): Promise<string>;

package/dist/resolver.js

@@ -0,0 +1,75 @@
+/**
+ * Resolves human-readable names to Flow Boards IDs.
+ * Caches results for the lifetime of the process.
+ */
+import { apiGet } from './client.js';
+let flowsCache = null;
+let binsCache = null;
+let typesCache = null;
+let boardsCache = null;
+async function getFlows() {
+    if (!flowsCache)
+        flowsCache = await apiGet('/flows');
+    return flowsCache;
+}
+async function getBins() {
+    if (!binsCache)
+        binsCache = await apiGet('/bins');
+    return binsCache;
+}
+async function getTypes() {
+    if (!typesCache)
+        typesCache = await apiGet('/ticket-types');
+    return typesCache;
+}
+async function getBoards() {
+    if (!boardsCache)
+        boardsCache = await apiGet('/boards');
+    return boardsCache;
+}
+export async function resolveFlowId(nameOrId) {
+    const flows = await getFlows();
+    const flow = flows.find(f => f._id === nameOrId || f.name === nameOrId);
+    if (!flow)
+        throw new Error(`Flow not found: "${nameOrId}". Available: ${flows.map(f => f.name).join(', ')}`);
+    return flow._id;
+}
+export async function resolveFlowFirstBin(nameOrId) {
+    const flows = await getFlows();
+    const flow = flows.find(f => f._id === nameOrId || f.name === nameOrId);
+    if (!flow)
+        throw new Error(`Flow not found: "${nameOrId}"`);
+    if (!flow.bin_ids?.length)
+        throw new Error(`Flow "${nameOrId}" has no bins`);
+    return flow.bin_ids[0];
+}
+export async function resolveBinId(nameOrId) {
+    const bins = await getBins();
+    const bin = bins.find(b => b._id === nameOrId || b.name === nameOrId);
+    if (bin)
+        return bin._id;
+    // Fall back to direct fetch — board-specific bins may not appear in the global list
+    try {
+        const direct = await apiGet(`/bins/${nameOrId}`);
+        if (direct?._id)
+            return direct._id;
+    }
+    catch {
+        // ignore, throw the original error below
+    }
+    throw new Error(`Bin not found: "${nameOrId}". Available: ${bins.map(b => b.name).join(', ')}`);
+}
+export async function resolveTicketTypeId(nameOrId) {
+    const types = await getTypes();
+    const type = types.find(t => t._id === nameOrId || t.name === nameOrId);
+    if (!type)
+        throw new Error(`Ticket type not found: "${nameOrId}". Available: ${types.map(t => t.name).join(', ')}`);
+    return type._id;
+}
+export async function resolveBoardId(nameOrId) {
+    const boards = await getBoards();
+    const board = boards.find(b => b._id === nameOrId || b.name === nameOrId);
+    if (!board)
+        throw new Error(`Board not found: "${nameOrId}". Available: ${boards.map(b => b.name).join(', ')}`);
+    return board._id;
+}

package/dist/tools/bins.d.ts

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

package/dist/tools/bins.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { apiGet, apiPost, apiPut, generateId } from '../client.js';
+import { resolveBinId } from '../resolver.js';
+export function registerBinTools(server) {
+    server.tool('list_bins', 'List all bins.', {}, async () => {
+        const bins = await apiGet('/bins');
+        return { content: [{ type: 'text', text: JSON.stringify(bins, null, 2) }] };
+    });
+    server.tool('get_bin', 'Get details for a specific bin by name or ID.', { bin: z.string().describe('Bin name or ID') }, async ({ bin }) => {
+        const id = await resolveBinId(bin);
+        const data = await apiGet(`/bins/${id}`);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+    server.tool('create_bin', 'Create a new bin.', {
+        name: z.string().describe('Bin name'),
+        flowId: z.string().describe('Flow ID to add the bin to'),
+    }, async ({ name, flowId }) => {
+        const id = generateId();
+        await apiPost(`/bins/${id}`, { _id: id, name, flow_id: flowId });
+        return { content: [{ type: 'text', text: `Created bin: ${id} — ${name}` }] };
+    });
+    server.tool('update_bin', 'Update a bin\'s name or configuration.', {
+        bin: z.string().describe('Bin name or ID'),
+        name: z.string().optional().describe('New name'),
+    }, async ({ bin, name }) => {
+        const id = await resolveBinId(bin);
+        const partial = {};
+        if (name)
+            partial.name = { $replace: name };
+        await apiPut(`/bins/${id}`, { $partial: partial });
+        return { content: [{ type: 'text', text: `Updated bin: ${id}` }] };
+    });
+}

package/dist/tools/boards.d.ts

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

package/dist/tools/boards.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { apiGet } from '../client.js';
+import { resolveBoardId } from '../resolver.js';
+export function registerBoardTools(server) {
+    server.tool('list_boards', 'List all boards.', {}, async () => {
+        const boards = await apiGet('/boards');
+        return { content: [{ type: 'text', text: JSON.stringify(boards, null, 2) }] };
+    });
+    server.tool('get_board', 'Get details for a specific board by name or ID.', { board: z.string().describe('Board name or ID') }, async ({ board }) => {
+        const id = await resolveBoardId(board);
+        const data = await apiGet(`/boards/${id}`);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+}

package/dist/tools/comments.d.ts

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

package/dist/tools/comments.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { apiGet, apiPost, apiPut, apiDelete, generateId } from '../client.js';
+export function registerCommentTools(server) {
+    server.tool('add_comment', 'Add a comment to a ticket.', {
+        ticketId: z.string().describe('Ticket ID'),
+        comment: z.string().describe('Comment text'),
+        format: z.enum(['text', 'html']).optional().default('text').describe('Comment format'),
+    }, async ({ ticketId, comment, format }) => {
+        const id = generateId();
+        await apiPost(`/ticket-comments/${id}`, {
+            _id: id,
+            ticket_id: ticketId,
+            comment,
+            rtformat: format,
+        });
+        return { content: [{ type: 'text', text: `Added comment ${id} to ticket ${ticketId}` }] };
+    });
+    server.tool('list_comments', 'List all comments for a ticket.', { ticketId: z.string().describe('Ticket ID') }, async ({ ticketId }) => {
+        const comments = await apiGet(`/ticket-comments?ticket_id=${ticketId}`);
+        return { content: [{ type: 'text', text: JSON.stringify(comments, null, 2) }] };
+    });
+    server.tool('get_comment', 'Get a specific comment by ID.', { id: z.string().describe('Comment ID') }, async ({ id }) => {
+        const comment = await apiGet(`/ticket-comments/${id}`);
+        return { content: [{ type: 'text', text: JSON.stringify(comment, null, 2) }] };
+    });
+    server.tool('update_comment', 'Update a comment\'s text.', {
+        id: z.string().describe('Comment ID'),
+        comment: z.string().describe('New comment text'),
+        format: z.enum(['text', 'html']).optional().default('text'),
+    }, async ({ id, comment, format }) => {
+        await apiPut(`/ticket-comments/${id}`, { comment, rtformat: format });
+        return { content: [{ type: 'text', text: `Updated comment: ${id}` }] };
+    });
+    server.tool('delete_comment', 'Delete a comment by ID.', { id: z.string().describe('Comment ID') }, async ({ id }) => {
+        await apiDelete(`/ticket-comments/${id}`);
+        return { content: [{ type: 'text', text: `Deleted comment: ${id}` }] };
+    });
+}

package/dist/tools/flows.d.ts

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

package/dist/tools/flows.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { apiGet } from '../client.js';
+import { resolveFlowId } from '../resolver.js';
+export function registerFlowTools(server) {
+    server.tool('list_flows', 'List all flows with their bins and metadata.', {}, async () => {
+        const flows = await apiGet('/flows');
+        return { content: [{ type: 'text', text: JSON.stringify(flows, null, 2) }] };
+    });
+    server.tool('get_flow', 'Get details for a specific flow by name or ID.', { flow: z.string().describe('Flow name or ID') }, async ({ flow }) => {
+        const id = await resolveFlowId(flow);
+        const data = await apiGet(`/flows/${id}`);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+    server.tool('list_flow_tickets', 'List all tickets in a flow.', { flow: z.string().describe('Flow name or ID') }, async ({ flow }) => {
+        const id = await resolveFlowId(flow);
+        const tickets = await apiGet(`/flows/${id}/tickets`);
+        return { content: [{ type: 'text', text: JSON.stringify(tickets, null, 2) }] };
+    });
+    server.tool('list_flow_moves', 'List ticket movement history within a flow.', { flow: z.string().describe('Flow name or ID') }, async ({ flow }) => {
+        const id = await resolveFlowId(flow);
+        const moves = await apiGet(`/flows/${id}/moves`);
+        return { content: [{ type: 'text', text: JSON.stringify(moves, null, 2) }] };
+    });
+}

package/dist/tools/misc.d.ts

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

package/dist/tools/misc.js

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { apiGet, apiPost, apiDelete, generateId } from '../client.js';
+export function registerMiscTools(server) {
+    // Ticket Types
+    server.tool('list_ticket_types', 'List all ticket types (e.g. User Story, Epic, Bug).', {}, async () => {
+        const data = await apiGet('/ticket-types');
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+    // Custom Fields
+    server.tool('list_custom_fields', 'List all custom fields.', {}, async () => {
+        const data = await apiGet('/custom-fields');
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+    // Users
+    server.tool('list_users', 'List all users in the organisation.', {}, async () => {
+        const data = await apiGet('/users');
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+    server.tool('get_user', 'Get a user by ID or email.', {
+        idOrEmail: z.string().describe('User ID or email address'),
+    }, async ({ idOrEmail }) => {
+        const data = await apiGet(`/users/${encodeURIComponent(idOrEmail)}`);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+    server.tool('invite_user', 'Send an invitation to a new user.', {
+        email: z.string().email().describe('Email address to invite'),
+    }, async ({ email }) => {
+        await apiPost('/invite-user', { email });
+        return { content: [{ type: 'text', text: `Invitation sent to ${email}` }] };
+    });
+    // User Groups
+    server.tool('list_user_groups', 'List all user groups.', {}, async () => {
+        const data = await apiGet('/user-groups');
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+    // Search
+    server.tool('search_tickets', 'Search tickets by text or criteria.', {
+        query: z.string().describe('Search query'),
+    }, async ({ query }) => {
+        const data = await apiGet(`/ticket-search?q=${encodeURIComponent(query)}`);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+    // Webhooks
+    server.tool('list_webhooks', 'List all webhooks.', {}, async () => {
+        const data = await apiGet('/webhooks');
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+    server.tool('create_webhook', 'Create a new webhook.', {
+        url: z.string().url().describe('Webhook destination URL'),
+        events: z.array(z.string()).optional().describe('Event types to subscribe to'),
+    }, async ({ url, events }) => {
+        const id = generateId();
+        await apiPost(`/webhooks/${id}`, { _id: id, url, events });
+        return { content: [{ type: 'text', text: `Created webhook: ${id}` }] };
+    });
+    server.tool('delete_webhook', 'Delete a webhook by ID.', {
+        id: z.string().describe('Webhook ID'),
+    }, async ({ id }) => {
+        await apiDelete(`/webhooks/${id}`);
+        return { content: [{ type: 'text', text: `Deleted webhook: ${id}` }] };
+    });
+    server.tool('test_webhook', 'Send a test payload to a webhook.', {
+        id: z.string().describe('Webhook ID'),
+    }, async ({ id }) => {
+        const data = await apiGet(`/webhooks/${id}/test`);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+}

package/dist/tools/tickets.d.ts

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

package/dist/tools/tickets.js

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import { apiGet, apiPost, apiPut, apiDelete, generateId } from '../client.js';
+import { resolveFlowFirstBin, resolveTicketTypeId, resolveBinId } from '../resolver.js';
+export function registerTicketTools(server) {
+    server.tool('create_ticket', 'Create a new ticket in a flow. Accepts flow name and ticket type name — resolves IDs automatically.', {
+        name: z.string().describe('Ticket name'),
+        flow: z.string().describe('Flow name or ID to place the ticket in (uses first/backlog bin)'),
+        ticketType: z.string().describe('Ticket type name or ID (e.g. "User Story", "Epic", "Bug")'),
+        bin: z.string().optional().describe('Specific bin name or ID (overrides flow default)'),
+        parentId: z.string().optional().describe('Parent ticket ID to nest this ticket inside (mutually exclusive with bin/flow)'),
+    }, async ({ name, flow, ticketType, bin, parentId }) => {
+        const id = generateId();
+        const typeId = await resolveTicketTypeId(ticketType);
+        const body = { _id: id, name, ticketType_id: typeId };
+        if (parentId) {
+            body.enclosed_id = parentId;
+        }
+        else if (bin) {
+            body.bin_id = await resolveBinId(bin);
+        }
+        else {
+            body.bin_id = await resolveFlowFirstBin(flow);
+        }
+        await apiPost(`/tickets/${id}`, body);
+        return { content: [{ type: 'text', text: `Created ticket: ${id} — ${name}` }] };
+    });
+    server.tool('get_ticket', 'Get details for a specific ticket by ID.', { id: z.string().describe('Ticket ID') }, async ({ id }) => {
+        const ticket = await apiGet(`/tickets/${id}`);
+        return { content: [{ type: 'text', text: JSON.stringify(ticket, null, 2) }] };
+    });
+    server.tool('list_tickets', 'List tickets filtered by bin, parent, or child.', {
+        binId: z.string().optional().describe('Filter by bin ID'),
+        parentId: z.string().optional().describe('Filter by parent ticket ID (list children)'),
+        childId: z.string().optional().describe('Filter by child ticket ID (find parent)'),
+    }, async ({ binId, parentId, childId }) => {
+        const params = new URLSearchParams();
+        if (binId)
+            params.set('bin_id', binId);
+        if (parentId)
+            params.set('parent_id', parentId);
+        if (childId)
+            params.set('child_id', childId);
+        const tickets = await apiGet(`/tickets?${params}`);
+        return { content: [{ type: 'text', text: JSON.stringify(tickets, null, 2) }] };
+    });
+    server.tool('update_ticket', 'Update ticket fields (name, description, bin, etc.).', {
+        id: z.string().describe('Ticket ID'),
+        name: z.string().optional(),
+        description: z.string().optional(),
+        binName: z.string().optional().describe('Move to bin by name or ID'),
+    }, async ({ id, name, description, binName }) => {
+        const partial = {};
+        if (name)
+            partial.name = { $replace: name };
+        if (description)
+            partial.description = { $replace: description };
+        if (binName)
+            partial.bin_id = { $replace: await resolveBinId(binName) };
+        await apiPut(`/tickets/${id}`, { $partial: partial });
+        return { content: [{ type: 'text', text: `Updated ticket: ${id}` }] };
+    });
+    server.tool('move_ticket', 'Move a ticket to a different bin (workflow stage).', {
+        id: z.string().describe('Ticket ID'),
+        bin: z.string().describe('Target bin name or ID'),
+    }, async ({ id, bin }) => {
+        const binId = await resolveBinId(bin);
+        await apiPut(`/tickets/${id}`, { $partial: { bin_id: { $replace: binId } } });
+        return { content: [{ type: 'text', text: `Moved ticket ${id} to bin "${bin}"` }] };
+    });
+    server.tool('delete_ticket', 'Delete a ticket by ID.', { id: z.string().describe('Ticket ID') }, async ({ id }) => {
+        await apiDelete(`/tickets/${id}`);
+        return { content: [{ type: 'text', text: `Deleted ticket: ${id}` }] };
+    });
+    server.tool('delete_tickets', 'Delete multiple tickets by ID.', { ids: z.array(z.string()).describe('List of ticket IDs to delete') }, async ({ ids }) => {
+        await apiDelete(`/tickets?ids=${ids.join(',')}`);
+        return { content: [{ type: 'text', text: `Deleted tickets: ${ids.join(', ')}` }] };
+    });
+    server.tool('archive_tickets', 'Archive one or more tickets.', { ids: z.array(z.string()).describe('Ticket IDs to archive') }, async ({ ids }) => {
+        await apiPut(`/tickets/archive?ids=${ids.join(',')}`);
+        return { content: [{ type: 'text', text: `Archived: ${ids.join(', ')}` }] };
+    });
+    server.tool('restore_tickets', 'Restore one or more archived tickets.', { ids: z.array(z.string()).describe('Ticket IDs to restore') }, async ({ ids }) => {
+        await apiPut(`/tickets/restore?ids=${ids.join(',')}`);
+        return { content: [{ type: 'text', text: `Restored: ${ids.join(', ')}` }] };
+    });
+    server.tool('link_to_parent', 'Link one or more tickets to a parent (epic). Stories become children of the epic.', {
+        ids: z.array(z.string()).describe('Ticket IDs to link'),
+        parentId: z.string().describe('Parent ticket ID'),
+    }, async ({ ids, parentId }) => {
+        await apiPut(`/tickets/addParent?ids=${ids.join(',')}&parent_id=${parentId}`);
+        return { content: [{ type: 'text', text: `Linked ${ids.join(', ')} → parent ${parentId}` }] };
+    });
+    server.tool('unlink_from_parent', 'Remove parent relationship from one or more tickets.', { ids: z.array(z.string()).describe('Ticket IDs to unlink') }, async ({ ids }) => {
+        await apiPut(`/tickets/removeParent?ids=${ids.join(',')}`);
+        return { content: [{ type: 'text', text: `Unlinked: ${ids.join(', ')}` }] };
+    });
+    server.tool('list_ticket_moves', 'Get the movement history for a ticket.', { id: z.string().describe('Ticket ID') }, async ({ id }) => {
+        const moves = await apiGet(`/tickets/${id}/moves`);
+        return { content: [{ type: 'text', text: JSON.stringify(moves, null, 2) }] };
+    });
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@mauvable/flowboards-mcp",
+  "mcpName": "io.github.Germanicus1/flowboards-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for the FlowBoards workflow management API",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "flowboards-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}