@unisonworkspace/mcp-tasks 1.1.0

package/README.md

@@ -0,0 +1,37 @@
+# @unisonworkspace/mcp-tasks
+
+MCP server that connects Claude Code to your Unison workspace. Manage tasks, track status, and add comments — all from your terminal.
+
+## Setup
+
+1. Go to **Settings > API Keys** in your Unison workspace and create an API key
+2. Run this in your terminal:
+
+```bash
+claude mcp add --transport stdio \
+  -e UNISON_API_TOKEN=sk-your-key \
+  -e UNISON_API_URL=https://app.unisonworkspace.com \
+  unison-tasks -- npx -y @unisonworkspace/mcp-tasks
+```
+
+3. Restart Claude Code
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_space_schema` | Get a team space's statuses, task type, and custom fields |
+| `list_tasks` | List tasks with optional filters (status, priority, assignee) |
+| `get_task` | Get a single task with its comments |
+| `create_task` | Create a new task |
+| `update_task` | Update an existing task |
+| `delete_task` | Delete a task |
+| `add_comment` | Add a comment to a task |
+| `move_task` | Move a task to a different status column |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `UNISON_API_TOKEN` | Your Unison API key (required) |
+| `UNISON_API_URL` | Your Unison workspace URL (required) |

package/dist/client.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnisonClient = exports.ApiError = void 0;
+const REQUEST_TIMEOUT_MS = 30000;
+class ApiError extends Error {
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'ApiError';
+    }
+}
+exports.ApiError = ApiError;
+class UnisonClient {
+    constructor() {
+        const token = process.env.UNISON_API_TOKEN;
+        if (!token) {
+            console.error('[unison-tasks] UNISON_API_TOKEN environment variable is required');
+            process.exit(1);
+        }
+        this.token = token;
+        this.baseUrl = (process.env.UNISON_API_URL || 'http://localhost:3200').replace(/\/$/, '');
+    }
+    async request(method, path, body, query) {
+        let url = `${this.baseUrl}${path}`;
+        if (query) {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined && value !== null && value !== '') {
+                    params.set(key, value);
+                }
+            }
+            const qs = params.toString();
+            if (qs)
+                url += `?${qs}`;
+        }
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.token}`,
+                },
+                body: body ? JSON.stringify(body) : undefined,
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'TimeoutError') {
+                throw new ApiError(0, `Request timed out after ${REQUEST_TIMEOUT_MS / 1000}s: ${method} ${path}`);
+            }
+            throw new ApiError(0, `Cannot reach Unison API at ${this.baseUrl}`);
+        }
+        if (!res.ok) {
+            let message;
+            try {
+                const json = await res.json();
+                message = json.error || json.message || res.statusText;
+            }
+            catch {
+                message = res.statusText;
+            }
+            throw new ApiError(res.status, message);
+        }
+        return res.json();
+    }
+    async get(path, query) {
+        return this.request('GET', path, undefined, query);
+    }
+    async post(path, body) {
+        return this.request('POST', path, body);
+    }
+    async put(path, body) {
+        return this.request('PUT', path, body);
+    }
+    async delete(path) {
+        return this.request('DELETE', path);
+    }
+}
+exports.UnisonClient = UnisonClient;

package/dist/formatters.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatTaskList = formatTaskList;
+exports.formatTaskDetail = formatTaskDetail;
+exports.formatCreated = formatCreated;
+exports.formatUpdated = formatUpdated;
+exports.formatDeleted = formatDeleted;
+exports.formatCommentAdded = formatCommentAdded;
+exports.formatMoved = formatMoved;
+const PRIORITY_BADGE = {
+    urgent: '[!!!]',
+    high: '[!!]',
+    medium: '[!]',
+    low: '[-]',
+    none: '[ ]',
+};
+function priorityBadge(p) {
+    return PRIORITY_BADGE[p] || `[${p}]`;
+}
+function formatDate(d) {
+    if (!d)
+        return '';
+    return new Date(d).toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' });
+}
+function formatTaskList(tasks) {
+    if (tasks.length === 0)
+        return 'No tasks found.';
+    const grouped = {};
+    for (const t of tasks) {
+        const status = t.status || 'unknown';
+        if (!grouped[status])
+            grouped[status] = [];
+        grouped[status].push(t);
+    }
+    const statusOrder = ['todo', 'in_progress', 'review', 'done'];
+    const sortedStatuses = Object.keys(grouped).sort((a, b) => {
+        const ai = statusOrder.indexOf(a);
+        const bi = statusOrder.indexOf(b);
+        return (ai === -1 ? 99 : ai) - (bi === -1 ? 99 : bi);
+    });
+    const lines = [`${tasks.length} task(s)\n`];
+    for (const status of sortedStatuses) {
+        lines.push(`── ${status.toUpperCase().replace('_', ' ')} (${grouped[status].length}) ──`);
+        for (const t of grouped[status]) {
+            const assignee = t.assigneeName ? ` → ${t.assigneeName}` : '';
+            const project = t.projectName ? ` [${t.projectName}]` : '';
+            const due = t.dueDate ? ` due ${formatDate(t.dueDate)}` : '';
+            lines.push(`  ${priorityBadge(t.priority)} ${t.title}${assignee}${project}${due}`);
+            lines.push(`    id: ${t.id}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function formatTaskDetail(task, comments) {
+    const lines = [
+        `# ${task.title}`,
+        `ID: ${task.id}`,
+        `Status: ${task.status}  Priority: ${task.priority}`,
+    ];
+    if (task.assigneeName)
+        lines.push(`Assignee: ${task.assigneeName} (${task.assigneeType})`);
+    if (task.projectName)
+        lines.push(`Project: ${task.projectName}`);
+    if (task.dueDate)
+        lines.push(`Due: ${formatDate(task.dueDate)}`);
+    if (task.description)
+        lines.push(`\nDescription:\n${task.description}`);
+    if (task.fieldValues && Object.keys(task.fieldValues).length > 0) {
+        lines.push(`\n── Fields ──`);
+        for (const fv of Object.values(task.fieldValues)) {
+            const displayValue = fv.value != null && fv.value !== '' && fv.value !== '""' ? String(fv.value).replace(/^"|"$/g, '') : '(empty)';
+            lines.push(`  ${fv.fieldName}: ${displayValue}`);
+        }
+    }
+    if (task.createdAt)
+        lines.push(`\nCreated: ${formatDate(task.createdAt)}`);
+    if (task.updatedAt)
+        lines.push(`Updated: ${formatDate(task.updatedAt)}`);
+    if (comments && comments.length > 0) {
+        lines.push(`\n── Comments (${comments.length}) ──`);
+        for (const c of comments) {
+            lines.push(`  ${c.authorName || 'Unknown'} (${formatDate(c.createdAt)}):`);
+            lines.push(`    ${c.content}`);
+        }
+    }
+    return lines.join('\n');
+}
+function formatCreated(task) {
+    return `Task created: "${task.title}" (${task.id})\nStatus: ${task.status}  Priority: ${task.priority}`;
+}
+function formatUpdated(task) {
+    return `Task updated: "${task.title}" (${task.id})\nStatus: ${task.status}  Priority: ${task.priority}`;
+}
+function formatDeleted(taskId) {
+    return `Task deleted: ${taskId}`;
+}
+function formatCommentAdded(taskId) {
+    return `Comment added to task ${taskId}`;
+}
+function formatMoved(taskId, status) {
+    const statusMsg = status ? ` to ${status}` : '';
+    return `Task ${taskId} moved${statusMsg}`;
+}

package/dist/index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const client_1 = require("./client");
+const tools_1 = require("./tools");
+async function main() {
+    const client = new client_1.UnisonClient();
+    const server = new McpServer({
+        name: 'unison-tasks',
+        version: '1.0.0',
+    });
+    (0, tools_1.registerTools)(server, client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('[unison-tasks] MCP server started');
+}
+main().catch((err) => {
+    console.error('[unison-tasks] Fatal error:', err);
+    process.exit(1);
+});

package/dist/tools.js

@@ -0,0 +1,362 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTools = registerTools;
+const client_1 = require("./client");
+const formatters_1 = require("./formatters");
+function errorResponse(err) {
+    if (err instanceof client_1.ApiError) {
+        const messages = {
+            401: 'Authentication failed. Check your UNISON_API_TOKEN.',
+            403: 'Permission denied.',
+            404: 'Not found.',
+        };
+        const text = messages[err.status] || (err.status === 400 ? err.message : `API error (${err.status}): ${err.message}`);
+        return { content: [{ type: 'text', text }], isError: true };
+    }
+    if (err instanceof Error) {
+        return { content: [{ type: 'text', text: err.message }], isError: true };
+    }
+    return { content: [{ type: 'text', text: `Unexpected error: ${String(err)}` }], isError: true };
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function ok(text) {
+    return { content: [{ type: 'text', text }] };
+}
+function formatSchema(schema) {
+    const lines = [];
+    const taskType = schema.taskType;
+    if (taskType) {
+        lines.push(`Type: ${taskType.name} (${taskType.slug})`);
+    }
+    lines.push(`Default view: ${schema.defaultView || 'board'}`);
+    const columns = schema.kanbanColumns;
+    if (columns && columns.length > 0) {
+        lines.push(`\nStatuses: ${columns.map(c => `${c.label} (${c.id})`).join(' → ')}`);
+    }
+    const fields = taskType?.fields;
+    if (fields && fields.length > 0) {
+        lines.push(`\nCustom fields:`);
+        for (const f of fields) {
+            const req = f.isRequired ? ' (required)' : '';
+            const opts = f.config?.options ? ` [${f.config.options.join(', ')}]` : '';
+            lines.push(`  - ${f.name} (${f.fieldType})${req}${opts}`);
+        }
+    }
+    return lines.join('\n');
+}
+function registerTools(server, client) {
+    // ── list_spaces ──
+    server.tool('list_spaces', {
+        description: 'List all team spaces you have access to. Returns space names and IDs. Use this to discover space UUIDs before creating tasks or querying schemas.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    }, async () => {
+        try {
+            const res = (await client.get('/api/team-spaces'));
+            const spaces = res.data;
+            if (spaces.length === 0)
+                return ok('No team spaces found.');
+            const lines = [`${spaces.length} team space(s)\n`];
+            for (const s of spaces) {
+                const desc = s.description ? ` — ${s.description}` : '';
+                lines.push(`  ${s.name}${desc}`);
+                lines.push(`    id: ${s.id}`);
+            }
+            return ok(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
+    // ── list_projects ──
+    server.tool('list_projects', {
+        description: 'List all projects you have access to. Returns project names, IDs, and task counts. Use this to discover project UUIDs.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                team_space_id: { type: 'string', description: 'Filter by team space UUID' },
+            },
+        },
+    }, async (params) => {
+        try {
+            const query = {};
+            if (params.team_space_id)
+                query.teamSpaceId = params.team_space_id;
+            const res = (await client.get('/api/projects', query));
+            const projects = res.data;
+            if (projects.length === 0)
+                return ok('No projects found.');
+            const lines = [`${projects.length} project(s)\n`];
+            for (const p of projects) {
+                const status = p.status ? ` (${p.status})` : '';
+                const space = p.teamSpaceName ? ` [${p.teamSpaceName}]` : '';
+                const tasks = p.taskCount !== undefined ? ` — ${p.taskCount} tasks` : '';
+                lines.push(`  ${p.name}${status}${space}${tasks}`);
+                lines.push(`    id: ${p.id}`);
+            }
+            return ok(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
+    // ── list_space_schema ──
+    server.tool('list_space_schema', {
+        description: 'Get a team space\'s schema: its statuses (kanban columns), task type, and custom fields. Use before creating tasks to know valid statuses and available fields.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                team_space_id: { type: 'string', description: 'Team space UUID' },
+            },
+            required: ['team_space_id'],
+        },
+    }, async (params) => {
+        try {
+            const spaceId = params.team_space_id;
+            const res = (await client.get(`/api/team-spaces/${spaceId}/schema`));
+            return ok(formatSchema(res.data));
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
+    // ── list_project_schema ──
+    server.tool('list_project_schema', {
+        description: 'Get a project\'s schema: its statuses (kanban columns), task type, and custom fields. Use before creating tasks in a project to know valid statuses and available fields. Falls back to the project\'s team space schema if the project has no own type.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: { type: 'string', description: 'Project UUID' },
+            },
+            required: ['project_id'],
+        },
+    }, async (params) => {
+        try {
+            const projectId = params.project_id;
+            const res = (await client.get(`/api/projects/${projectId}/schema`));
+            return ok(formatSchema(res.data));
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
+    // ── list_tasks ──
+    server.tool('list_tasks', {
+        description: 'List tasks with optional filters. Returns all tasks across projects. Use list_space_schema first to discover valid statuses for a space.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                status: { type: 'string', description: 'Filter by status (e.g. todo, in_progress, review, done, or any custom status from the space)' },
+                priority: { type: 'string', enum: ['urgent', 'high', 'medium', 'low', 'none'], description: 'Filter by priority' },
+                assignee_id: { type: 'string', description: 'Filter by assignee UUID' },
+                my_tasks: { type: 'boolean', description: 'Show only tasks assigned to the authenticated user' },
+                team_space_id: { type: 'string', description: 'Filter by team space UUID' },
+            },
+        },
+    }, async (params) => {
+        try {
+            const query = {};
+            if (params.status)
+                query.status = params.status;
+            if (params.priority)
+                query.priority = params.priority;
+            if (params.assignee_id)
+                query.assignee_id = params.assignee_id;
+            if (params.my_tasks)
+                query.my_tasks = 'true';
+            if (params.team_space_id)
+                query.teamSpaceId = params.team_space_id;
+            const res = (await client.get('/api/projects/tasks', query));
+            return ok((0, formatters_1.formatTaskList)(res.data));
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
+    // ── get_task ──
+    server.tool('get_task', {
+        description: 'Get a single task by ID, including its comments.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: { type: 'string', description: 'Task UUID' },
+            },
+            required: ['task_id'],
+        },
+    }, async (params) => {
+        try {
+            const taskId = params.task_id;
+            const [taskRes, commentsRes] = await Promise.all([
+                client.get(`/api/projects/tasks/${taskId}`),
+                client.get(`/api/projects/tasks/${taskId}/comments`),
+            ]);
+            return ok((0, formatters_1.formatTaskDetail)(taskRes.data, commentsRes.data));
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
+    // ── create_task ──
+    server.tool('create_task', {
+        description: 'Create a new task. Only title is required. Use list_space_schema to discover valid statuses and custom fields for a space.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: { type: 'string', description: 'Task title' },
+                description: { type: 'string', description: 'Task description' },
+                status: { type: 'string', description: 'Initial status (default: first status in space schema, e.g. todo)' },
+                priority: { type: 'string', enum: ['urgent', 'high', 'medium', 'low', 'none'], description: 'Priority (default: medium)' },
+                assignee_id: { type: 'string', description: 'Assignee UUID' },
+                assignee_type: { type: 'string', enum: ['user', 'agent'], description: 'Assignee type (default: user)' },
+                due_date: { type: 'string', description: 'Due date (ISO 8601)' },
+                project_id: { type: 'string', description: 'Project UUID' },
+                team_space_id: { type: 'string', description: 'Team space UUID' },
+                custom_fields: { type: 'object', description: 'Custom field values as { fieldId: value } pairs. Get field IDs from list_space_schema.' },
+            },
+            required: ['title'],
+        },
+    }, async (params) => {
+        try {
+            const body = { title: params.title };
+            if (params.description !== undefined)
+                body.description = params.description;
+            if (params.status !== undefined)
+                body.status = params.status;
+            if (params.priority !== undefined)
+                body.priority = params.priority;
+            if (params.assignee_id !== undefined)
+                body.assignee_id = params.assignee_id;
+            if (params.assignee_type !== undefined)
+                body.assignee_type = params.assignee_type;
+            if (params.due_date !== undefined)
+                body.due_date = params.due_date;
+            if (params.project_id !== undefined)
+                body.project_id = params.project_id;
+            if (params.team_space_id !== undefined)
+                body.team_space_id = params.team_space_id;
+            if (params.custom_fields !== undefined)
+                body.fieldValues = params.custom_fields;
+            const res = (await client.post('/api/projects/tasks', body));
+            return ok((0, formatters_1.formatCreated)(res.data));
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
+    // ── update_task ──
+    server.tool('update_task', {
+        description: 'Update an existing task. Only task_id is required; include only fields to change. Use list_space_schema to discover valid statuses.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: { type: 'string', description: 'Task UUID' },
+                title: { type: 'string', description: 'New title' },
+                description: { type: 'string', description: 'New description' },
+                status: { type: 'string', description: 'New status (use list_space_schema to discover valid statuses)' },
+                priority: { type: 'string', enum: ['urgent', 'high', 'medium', 'low', 'none'], description: 'New priority' },
+                assignee_id: { type: 'string', description: 'New assignee UUID' },
+                assignee_type: { type: 'string', enum: ['user', 'agent'], description: 'Assignee type' },
+                due_date: { type: 'string', description: 'New due date (ISO 8601)' },
+                custom_fields: { type: 'object', description: 'Custom field values as { fieldId: value } pairs' },
+            },
+            required: ['task_id'],
+        },
+    }, async (params) => {
+        try {
+            const taskId = params.task_id;
+            const body = {};
+            if (params.title !== undefined)
+                body.title = params.title;
+            if (params.description !== undefined)
+                body.description = params.description;
+            if (params.status !== undefined)
+                body.status = params.status;
+            if (params.priority !== undefined)
+                body.priority = params.priority;
+            if (params.assignee_id !== undefined)
+                body.assignee_id = params.assignee_id;
+            if (params.assignee_type !== undefined)
+                body.assignee_type = params.assignee_type;
+            if (params.due_date !== undefined)
+                body.due_date = params.due_date;
+            if (params.custom_fields !== undefined)
+                body.fieldValues = params.custom_fields;
+            const res = (await client.put(`/api/projects/tasks/${taskId}`, body));
+            return ok((0, formatters_1.formatUpdated)(res.data));
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
+    // ── delete_task ──
+    server.tool('delete_task', {
+        description: 'Delete a task permanently.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: { type: 'string', description: 'Task UUID' },
+            },
+            required: ['task_id'],
+        },
+    }, async (params) => {
+        try {
+            const taskId = params.task_id;
+            await client.delete(`/api/projects/tasks/${taskId}`);
+            return ok((0, formatters_1.formatDeleted)(taskId));
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
+    // ── add_comment ──
+    server.tool('add_comment', {
+        description: 'Add a comment to a task.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: { type: 'string', description: 'Task UUID' },
+                content: { type: 'string', description: 'Comment text' },
+            },
+            required: ['task_id', 'content'],
+        },
+    }, async (params) => {
+        try {
+            const taskId = params.task_id;
+            await client.post(`/api/projects/tasks/${taskId}/comments`, { content: params.content });
+            return ok((0, formatters_1.formatCommentAdded)(taskId));
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
+    // ── move_task ──
+    server.tool('move_task', {
+        description: 'Move a task to a different status column and/or reorder within a column.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: { type: 'string', description: 'Task UUID' },
+                status: { type: 'string', description: 'Target status column (use list_space_schema to discover valid statuses)' },
+                position: { type: 'number', description: 'Zero-based index in the target column (default: 0 = top)' },
+            },
+            required: ['task_id'],
+        },
+    }, async (params) => {
+        try {
+            const taskId = params.task_id;
+            const body = {
+                taskId,
+                newIndex: params.position !== undefined ? params.position : 0,
+            };
+            if (params.status !== undefined)
+                body.status = params.status;
+            await client.put('/api/projects/tasks/reorder', body);
+            return ok((0, formatters_1.formatMoved)(taskId, params.status));
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@unisonworkspace/mcp-tasks",
+  "version": "1.1.0",
+  "description": "Unison Tasks MCP server — exposes task CRUD via Model Context Protocol",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-tasks": "dist/index.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "ts-node": "^10.9.2"
+  }
+}