surecore-studio-mcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Surecore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# surecore-studio-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server that lets Claude read your SurecoreStudio tasks and update task status.
+
+## Install (developers)
+
+1. In the app, generate a token: **Settings → Developer → Generate** (copy it — it's shown once).
+
+2. Install the server, then register it with Claude Code:
+
+       npm install -g surecore-studio-mcp
+       claude mcp add surecore-tasks \
+         --env SURECORE_PAT=sc_pat_your_token \
+         -- surecore-tasks-mcp
+
+   Or add it to your `.mcp.json` by hand:
+
+       {
+         "mcpServers": {
+           "surecore-tasks": {
+             "command": "surecore-tasks-mcp",
+             "env": {
+               "SURECORE_PAT": "sc_pat_your_token",
+               "SURECORE_API_URL": "https://surecorestudio.surecore.cc/api",
+               "SURECORE_TENANT": "surecorestudio"
+             }
+           }
+         }
+       }
+
+   `SURECORE_API_URL` and `SURECORE_TENANT` are optional — they default to the values shown.
+
+   > **Zero-install (npx):** `npx -y surecore-studio-mcp` also works on most setups. If Claude Code shows the server as failed with `command not found`, that's a known `npx` bin-linking quirk on some npm versions — use the global install above (reliable), or clear the npx cache with `rm -rf ~/.npm/_npx`.
+
+## Tools
+
+Reads:
+
+- `list_my_tasks` — your assigned tasks (filter by status, project or tag)
+- `get_task` — one task in full: fields, description, assignee names, comment thread and the list of attached files. No second call needed to see comments.
+- `search_tasks` — by status, project, tag and/or free text
+- `list_comments` — just the comment thread, oldest first
+- `get_attachment` — pull one attached file into the conversation; images render inline
+- `list_members` — the workspace members with their ids, for turning a member id into a person
+
+Writes (each asks you to confirm first):
+
+- `create_task` — create a task or issue under a project (by project name or id; not tickets)
+- `update_task` — change title, description, priority, status, due date, tags or assignees; only the fields you pass are touched. Assignees accept member names or ids.
+- `update_task_status` — move a task across the workflow
+- `add_comment` — post a comment, always attributed to the token holder
+
+### Statuses and tags come from your workspace
+
+SurecoreStudio lets you define your own board columns and tags, so this server
+reads `/task-statuses` and `/task-tags` at startup and offers exactly what your
+workspace has. Nothing is hardcoded — a status or tag you add today is usable
+here as soon as the server restarts. (Before 0.1.4 the status list was fixed at
+release, which made any status added later impossible to set or filter by.)
+
+## Local development
+
+    cd mcp/surecore-tasks
+    npm install
+    npm run build
+    npm test
+
+To run a local build instead of the published package, point Claude at `dist/index.js`:
+
+    {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp/surecore-tasks/dist/index.js"],
+      "env": { "SURECORE_PAT": "sc_pat_..." }
+    }

package/dist/apiClient.js

@@ -0,0 +1,74 @@
+export class ApiError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ApiError';
+    }
+}
+export function createApiClient(cfg, fetchImpl = fetch) {
+    async function req(path, init = {}) {
+        let res;
+        try {
+            res = await fetchImpl(`${cfg.apiUrl}${path}`, {
+                ...init,
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...init.headers,
+                    'Authorization': `Bearer ${cfg.pat}`,
+                    'X-Tenant-Id': cfg.tenant,
+                },
+            });
+        }
+        catch (err) {
+            throw new ApiError('network', `Network error reaching the API: ${err.message}`);
+        }
+        if (!res.ok) {
+            const code = res.status === 401 ? 'auth' : res.status === 403 ? 'forbidden' : res.status === 404 ? 'not_found' : 'server';
+            throw new ApiError(code, `API returned ${res.status}`);
+        }
+        // The API wraps success responses as { ok: true, data: <T> } — unwrap to the payload.
+        const payload = (await res.json());
+        return (payload && typeof payload === 'object' && 'data' in payload ? payload.data : payload);
+    }
+    return {
+        getMe: () => req('/v1/auth/me'),
+        listTasks: () => req('/v1/tasks'),
+        getTask: (id) => req(`/v1/tasks/${encodeURIComponent(id)}`),
+        moveTask: (id, status) => req(`/v1/tasks/${encodeURIComponent(id)}/move`, { method: 'POST', body: JSON.stringify({ status }) }),
+        listProjects: () => req('/v1/projects'),
+        createTask: (input) => req('/v1/tasks', { method: 'POST', body: JSON.stringify(input) }),
+        updateTask: (id, patch) => req(`/v1/tasks/${encodeURIComponent(id)}`, { method: 'PATCH', body: JSON.stringify(patch) }),
+        // The workspace's own workflow and tag catalogue — fetched, never assumed.
+        listStatuses: () => req('/v1/task-statuses'),
+        listTags: () => req('/v1/task-tags'),
+        listMembers: () => req('/v1/members'),
+        listComments: (taskId) => req(`/v1/comments/${encodeURIComponent(taskId)}`),
+        addComment: (input) => req('/v1/comments', { method: 'POST', body: JSON.stringify(input) }),
+        listAttachments: (taskId) => req(`/v1/attachments/${encodeURIComponent(taskId)}`),
+        getAttachmentDataUrl: (id) => req(`/v1/attachments/${encodeURIComponent(id)}/data-url`),
+        uploadAttachment: async (taskId, file) => {
+            // Multipart, so Content-Type must be left to fetch (it has to add the
+            // boundary). req() always sets application/json, hence the direct call.
+            const form = new FormData();
+            form.append('file', new Blob([file.bytes], { type: file.mimeType }), file.name);
+            let res;
+            try {
+                res = await fetchImpl(`${cfg.apiUrl}/v1/attachments/${encodeURIComponent(taskId)}/upload`, {
+                    method: 'POST',
+                    headers: { Authorization: `Bearer ${cfg.pat}`, 'X-Tenant-Id': cfg.tenant },
+                    body: form,
+                });
+            }
+            catch (err) {
+                throw new ApiError('network', `Network error reaching the API: ${err.message}`);
+            }
+            if (!res.ok) {
+                const code = res.status === 401 ? 'auth' : res.status === 403 ? 'forbidden' : res.status === 404 ? 'not_found' : 'server';
+                throw new ApiError(code, `Upload returned ${res.status}`);
+            }
+            const payload = (await res.json());
+            return payload?.data ?? [];
+        },
+    };
+}

package/dist/config.js

@@ -0,0 +1,12 @@
+export function loadConfig() {
+    const pat = process.env.SURECORE_PAT ?? '';
+    if (!pat) {
+        process.stderr.write('surecore-tasks: SURECORE_PAT is required.\n');
+        process.exit(1);
+    }
+    return {
+        apiUrl: (process.env.SURECORE_API_URL ?? 'https://surecorestudio.surecore.cc/api').replace(/\/+$/, ''),
+        pat,
+        tenant: process.env.SURECORE_TENANT ?? 'surecorestudio',
+    };
+}

package/dist/index.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { loadConfig } from './config.js';
+import { createApiClient } from './apiClient.js';
+import { CREATE_TASK_TYPES, listMyTasks, getTaskTool, searchTasks, updateTaskStatus, createTaskTool, updateTask, listComments, addComment, getAttachment, addAttachment, listMembersTool, } from './tools.js';
+// ---------------------------------------------------------------------------
+// Workspace cache — statuses and tags are user-definable and change at any
+// time. Re-fetch at most once per TTL so every tool call uses a fresh list
+// without hammering the API on every keystroke.
+// ---------------------------------------------------------------------------
+const WS_TTL_MS = 60_000;
+class WorkspaceCache {
+    api;
+    ws = null;
+    fetchedAt = 0;
+    constructor(api) {
+        this.api = api;
+    }
+    async get() {
+        if (this.ws && Date.now() - this.fetchedAt < WS_TTL_MS)
+            return this.ws;
+        const [statuses, tags, members] = await Promise.all([
+            this.api.listStatuses(),
+            this.api.listTags().catch(() => []),
+            this.api.listMembers().catch(() => []),
+        ]);
+        this.ws = { statuses, tags, members };
+        this.fetchedAt = Date.now();
+        return this.ws;
+    }
+    /** Call after a local mutation so the next read is always fresh. */
+    invalidate() { this.fetchedAt = 0; }
+}
+async function main() {
+    const cfg = loadConfig();
+    const api = createApiClient(cfg);
+    // Fail fast with a clear message if the PAT is invalid/revoked.
+    let me;
+    try {
+        me = await api.getMe();
+    }
+    catch {
+        process.stderr.write('surecore-tasks: could not authenticate — check SURECORE_PAT (generate one in Settings › Developer).\n');
+        process.exit(1);
+    }
+    const wsCache = new WorkspaceCache(api);
+    // -------------------------------------------------------------------------
+    // Status and tag params use z.string() rather than z.enum(). The enum was
+    // baked in at startup and silently rejected any value added after the
+    // process started. The server validates the value anyway (and returns a
+    // clear error listing current valid values), so the enum gate is redundant
+    // and harmful.
+    // -------------------------------------------------------------------------
+    const statusParam = z.string().describe('A status value (e.g. "todo", "in-progress"). The server validates against the workspace\'s current list and returns valid options on a mismatch.');
+    const tagParam = z.string().describe('A tag value defined in this workspace.');
+    const server = new McpServer({ name: 'surecore-tasks', version: '0.1.7' });
+    server.tool('list_my_tasks', 'List the tasks assigned to you, optionally filtered by status, project or tag.', { status: statusParam.optional(), projectId: z.string().optional(), tag: tagParam.optional() }, async (args) => listMyTasks(api, me, args));
+    server.tool('get_task', 'Get one task in full: its fields, description, assignee names, comment thread and the list of attached files. Use this for "read task N" — a second call is not needed for comments.', { task: z.string().describe('Task number or appId') }, async (args) => getTaskTool(api, args, await wsCache.get(), me));
+    server.tool('search_tasks', 'Search tasks by status, project, tag and/or free text. Statuses and tags are fetched fresh on each call so newly created values are always recognised.', { status: statusParam.optional(), projectId: z.string().optional(), text: z.string().optional(), tag: tagParam.optional() }, async (args) => searchTasks(api, args, await wsCache.get()));
+    server.tool('create_task', 'Create a new task or issue under a project (NOT a ticket — tickets come from support intake). Confirm the title, project, and type with the user before calling. `project` accepts a project name or id.', {
+        title: z.string().describe('The task title'),
+        project: z.string().describe('Project name (e.g. "AAIB") or project id'),
+        type: z.enum(CREATE_TASK_TYPES).default('task').describe('task or issue'),
+        description: z.string().optional(),
+        priority: z.enum(['low', 'medium', 'high']).optional(),
+    }, (args) => createTaskTool(api, args));
+    server.tool('update_task', 'Change a task\'s details: title, description, priority, status, due date, tags or assignees. Only the fields you pass are changed. Confirm the change with the user before calling.', {
+        task: z.string().describe('Task number or appId'),
+        title: z.string().optional(),
+        description: z.string().optional(),
+        priority: z.enum(['low', 'medium', 'high']).optional(),
+        status: statusParam.optional(),
+        dueDate: z.string().optional().describe('YYYY-MM-DD'),
+        tags: z.array(tagParam).optional().describe('Replaces the task\'s tags'),
+        assignees: z.array(z.string()).optional().describe('Member names or ids; replaces the current assignees'),
+    }, async (args) => { const ws = await wsCache.get(); return updateTask(api, args, ws); });
+    server.tool('update_task_status', 'Move a task to a new status. Confirm the task and the target status with the user before calling. For customer-linked tickets this notifies the customer, exactly like the web app.', { task: z.string().describe('Task number or appId'), status: statusParam }, async (args) => { const ws = await wsCache.get(); return updateTaskStatus(api, args, ws); });
+    server.tool('get_attachment', 'Pull one file attached to a task into the conversation. Images are shown inline; other types are reported by name and type. `file` accepts the file name or its id.', { task: z.string().describe('Task number or appId'), file: z.string().describe('Attachment file name or id') }, (args) => getAttachment(api, args));
+    server.tool('list_members', 'List the workspace members with their ids. Use this to turn a member id seen on a task into a person, or to find the id for an assignee.', {}, async () => listMembersTool(await wsCache.get()));
+    server.tool('add_attachment', 'Attach a file from this machine to a task. Give the full path. Used to attach a work report to a task when the work is finished.', { task: z.string().describe('Task number or appId'), path: z.string().describe('Full path to the file on this machine') }, (args) => addAttachment(api, args));
+    server.tool('list_comments', 'Read the comment thread on a task, oldest first.', { task: z.string().describe('Task number or appId') }, (args) => listComments(api, args));
+    server.tool('add_comment', 'Post a comment on a task. It is always attributed to you (the token holder). Confirm the wording with the user before calling.', { task: z.string().describe('Task number or appId'), text: z.string().describe('The comment body') }, (args) => addComment(api, me, args));
+    await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+    process.stderr.write(`surecore-tasks: fatal ${err?.message ?? err}\n`);
+    process.exit(1);
+});

package/dist/tools.js

@@ -0,0 +1,389 @@
+import { randomUUID } from 'node:crypto';
+import { ApiError } from './apiClient.js';
+function statusValues(ws) { return ws.statuses.map((s) => s.value); }
+function tagValues(ws) { return ws.tags.map((t) => t.value); }
+/** A task read shows at most this many comments, newest last. */
+const MAX_INLINE_COMMENTS = 20;
+function humanSize(bytes) {
+    if (!bytes)
+        return '';
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${Math.round(bytes / 1024)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function renderComments(comments) {
+    if (comments.length === 0)
+        return 'Comments: none';
+    const shown = comments.slice(-MAX_INLINE_COMMENTS);
+    const header = comments.length > shown.length
+        ? `Comments (${comments.length} total, showing the most recent ${shown.length}):`
+        : `Comments (${comments.length}):`;
+    return [header, ...shown.map((c) => `  ${c.authorName} — ${c.createdAt}\n    ${c.text.replace(/\n/g, '\n    ')}`)].join('\n');
+}
+/**
+ * Member ids are opaque (`auth-1783682644299`), so a bare id answers nothing.
+ * An id the workspace cannot name is still printed rather than dropped — a
+ * stale member list must degrade to today's output, not hide the assignment.
+ */
+function renderAssignees(ids, ws, me) {
+    return ids
+        .map((id) => {
+        const known = ws?.members.find((m) => m.id === id)?.name;
+        // We always know our own name, even if the member fetch failed at startup.
+        const label = known ?? (me && id === me.id ? me.name : id);
+        return me && id === me.id ? `${label} (you)` : label;
+    })
+        .join(', ');
+}
+function renderAttachments(files) {
+    if (files.length === 0)
+        return 'Attachments: none';
+    return [`Attachments (${files.length}):`, ...files.map((f) => {
+            const size = humanSize(f.size);
+            return `  ${f.name} (${f.mimeType}${size ? `, ${size}` : ''})`;
+        }), 'Use get_attachment to pull one into the conversation.'].join('\n');
+}
+function ok(text) { return { content: [{ type: 'text', text }] }; }
+function err(text) { return { content: [{ type: 'text', text }], isError: true }; }
+function friendly(e) {
+    if (e instanceof ApiError) {
+        switch (e.code) {
+            case 'auth': return 'Your API token is invalid or revoked — generate a new one in Settings › Developer.';
+            case 'forbidden': return 'Your role does not allow that action.';
+            case 'not_found': return 'Task not found.';
+            case 'network': return 'Could not reach the SurecoreStudio API.';
+            default: return 'The API returned an error. Please try again.';
+        }
+    }
+    return `Unexpected error: ${e?.message ?? String(e)}`;
+}
+function line(t) {
+    const tags = t.tags?.length ? ` {${t.tags.join(', ')}}` : '';
+    return `#${t.taskNumber ?? '?'} [${t.status}]${tags} ${t.title} (id: ${t.id})${t.projectId ? ` (project ${t.projectId})` : ''}${t.dueDate ? ` — due ${t.dueDate}` : ''}`;
+}
+/** Resolve a task reference that may be a taskNumber (digits) or an appId. */
+async function resolveId(api, ref) {
+    if (/^\d+$/.test(ref)) {
+        const n = Number(ref);
+        const match = (await api.listTasks()).find((t) => t.taskNumber === n);
+        if (!match)
+            throw new ApiError('not_found', `No task numbered ${ref}.`);
+        return match.id;
+    }
+    return ref;
+}
+export async function listMyTasks(api, me, args) {
+    try {
+        let tasks = (await api.listTasks()).filter((t) => t.assignees.includes(me.id));
+        if (args.status)
+            tasks = tasks.filter((t) => t.status === args.status);
+        if (args.projectId)
+            tasks = tasks.filter((t) => t.projectId === args.projectId);
+        if (args.tag)
+            tasks = tasks.filter((t) => (t.tags ?? []).includes(args.tag));
+        if (tasks.length === 0)
+            return ok('You have no matching tasks.');
+        return ok(tasks.map(line).join('\n'));
+    }
+    catch (e) {
+        return err(friendly(e));
+    }
+}
+export async function getTaskTool(api, args, ws, me) {
+    try {
+        const id = await resolveId(api, args.task);
+        const t = await api.getTask(id);
+        // The thread and the file list are part of reading a task, not a separate
+        // errand — but neither may break the read, so both degrade to a note.
+        const [comments, files] = await Promise.all([
+            api.listComments(id).catch(() => null),
+            api.listAttachments(id).catch(() => null),
+        ]);
+        // Head fields drop out when absent; the sections below are always present
+        // and separated by blank lines, so filter(Boolean) must not touch them.
+        const head = [
+            `#${t.taskNumber ?? '?'} — ${t.title}`,
+            `Status: ${t.status}    Priority: ${t.priority}`,
+            t.projectId ? `Project: ${t.projectId}` : '',
+            t.dueDate ? `Due: ${t.dueDate}` : '',
+            t.assignees.length ? `Assignees: ${renderAssignees(t.assignees, ws, me)}` : 'Unassigned',
+            t.tags?.length ? `Tags: ${t.tags.join(', ')}` : '',
+        ].filter(Boolean).join('\n');
+        const body = [
+            head,
+            t.description || '(no description)',
+            comments === null ? 'Comments: could not be loaded.' : renderComments(comments),
+            files === null ? 'Attachments: could not be loaded.' : renderAttachments(files),
+        ].join('\n\n');
+        return ok(body);
+    }
+    catch (e) {
+        return err(friendly(e));
+    }
+}
+export async function searchTasks(api, args, ws) {
+    try {
+        let tasks = await api.listTasks();
+        if (args.status)
+            tasks = tasks.filter((t) => t.status === args.status);
+        if (args.projectId)
+            tasks = tasks.filter((t) => t.projectId === args.projectId);
+        if (args.tag)
+            tasks = tasks.filter((t) => (t.tags ?? []).includes(args.tag));
+        if (args.text) {
+            const q = args.text.toLowerCase();
+            tasks = tasks.filter((t) => t.title.toLowerCase().includes(q) || t.description.toLowerCase().includes(q));
+        }
+        if (tasks.length === 0)
+            return ok('No tasks match.');
+        return ok(tasks.slice(0, 50).map(line).join('\n'));
+    }
+    catch (e) {
+        return err(friendly(e));
+    }
+}
+export const CREATE_TASK_TYPES = ['task', 'issue'];
+/**
+ * Resolve a `project` reference the user gave — either an exact project id
+ * (appId) or a project name (case-insensitive). Returns the resolved id, or a
+ * helpful message listing the available projects when it can't match
+ * unambiguously. Never guesses between two same-named projects. The message is
+ * returned (not thrown) so it reaches the user verbatim rather than being
+ * flattened to a generic "not found" by friendly().
+ */
+async function resolveProjectId(api, ref) {
+    const projects = await api.listProjects();
+    const wanted = ref.trim();
+    const byId = projects.find((p) => p.id === wanted);
+    if (byId)
+        return { id: byId.id };
+    const byName = projects.filter((p) => p.name.toLowerCase() === wanted.toLowerCase());
+    if (byName.length === 1)
+        return { id: byName[0].id };
+    const names = projects.map((p) => p.name).join(', ') || '(none)';
+    if (byName.length > 1) {
+        return { message: `More than one project is named "${ref}". Use the project id instead. Projects: ${names}.` };
+    }
+    return { message: `No project matches "${ref}". Available projects: ${names}.` };
+}
+export async function createTaskTool(api, args) {
+    const title = (args.title ?? '').trim();
+    if (!title)
+        return err('A task title is required.');
+    const type = (args.type ?? 'task').toLowerCase();
+    if (!CREATE_TASK_TYPES.includes(type)) {
+        return err(`type must be one of: ${CREATE_TASK_TYPES.join(', ')} (tickets are created from support intake, not here).`);
+    }
+    try {
+        const resolved = await resolveProjectId(api, args.project);
+        if ('message' in resolved)
+            return err(resolved.message);
+        const created = await api.createTask({
+            title,
+            taskType: type,
+            projectId: resolved.id,
+            description: args.description?.trim() || undefined,
+            priority: args.priority,
+            status: 'todo',
+            // Guards against an accidental duplicate if the tool is retried.
+            idempotencyKey: randomUUID(),
+        });
+        return ok(`Created ${type} #${created.taskNumber ?? '?'} "${created.title}" in project ${created.projectId} (id: ${created.id}), status ${created.status}.`);
+    }
+    catch (e) {
+        return err(friendly(e));
+    }
+}
+export async function updateTaskStatus(api, args, ws) {
+    if (!statusValues(ws).includes(args.status)) {
+        return err(`"${args.status}" is not a status in this workspace. Valid statuses: ${statusValues(ws).join(', ')}.`);
+    }
+    try {
+        const id = await resolveId(api, args.task);
+        const t = await api.moveTask(id, args.status);
+        return ok(`Moved #${t.taskNumber ?? id} to "${t.status}".`);
+    }
+    catch (e) {
+        return err(friendly(e));
+    }
+}
+/** Resolve assignee refs that may be member ids or human names. */
+function resolveMembers(ws, refs) {
+    const ids = [];
+    for (const raw of refs) {
+        const ref = raw.trim();
+        if (!ref)
+            continue;
+        const byId = ws.members.find((m) => m.id === ref);
+        if (byId) {
+            ids.push(byId.id);
+            continue;
+        }
+        const byName = ws.members.filter((m) => m.name.toLowerCase() === ref.toLowerCase()
+            || m.name.toLowerCase().split(/\s+/)[0] === ref.toLowerCase());
+        if (byName.length === 1) {
+            ids.push(byName[0].id);
+            continue;
+        }
+        if (byName.length > 1) {
+            return { message: `More than one member matches "${ref}": ${byName.map((m) => m.name).join(', ')}. Use the member id.` };
+        }
+        return { message: `No member matches "${ref}". Members: ${ws.members.map((m) => m.name).join(', ') || '(none)'}.` };
+    }
+    return { ids };
+}
+export async function updateTask(api, args, ws) {
+    const patch = {};
+    if (args.title !== undefined) {
+        if (!args.title.trim())
+            return err('A task title cannot be empty.');
+        patch.title = args.title.trim();
+    }
+    if (args.description !== undefined)
+        patch.description = args.description;
+    if (args.priority !== undefined)
+        patch.priority = args.priority;
+    if (args.dueDate !== undefined)
+        patch.dueDate = args.dueDate;
+    if (args.status !== undefined) {
+        if (!statusValues(ws).includes(args.status)) {
+            return err(`"${args.status}" is not a status in this workspace. Valid statuses: ${statusValues(ws).join(', ')}.`);
+        }
+        patch.status = args.status;
+    }
+    if (args.tags !== undefined) {
+        const unknown = args.tags.filter((t) => !tagValues(ws).includes(t));
+        if (unknown.length) {
+            return err(`Unknown tag(s): ${unknown.join(', ')}. Tags in this workspace: ${tagValues(ws).join(', ') || '(none)'}.`);
+        }
+        patch.tags = args.tags;
+    }
+    if (args.assignees !== undefined) {
+        const resolved = resolveMembers(ws, args.assignees);
+        if ('message' in resolved)
+            return err(resolved.message);
+        patch.assignees = resolved.ids;
+    }
+    if (Object.keys(patch).length === 0) {
+        return err('Nothing to update — pass at least one of title, description, priority, status, dueDate, tags or assignees.');
+    }
+    try {
+        const id = await resolveId(api, args.task);
+        const t = await api.updateTask(id, patch);
+        return ok(`Updated #${t.taskNumber ?? id}: ${Object.keys(patch).join(', ')}.`);
+    }
+    catch (e) {
+        return err(friendly(e));
+    }
+}
+export async function listComments(api, args) {
+    try {
+        const id = await resolveId(api, args.task);
+        const comments = await api.listComments(id);
+        if (comments.length === 0)
+            return ok('This task has no comments yet.');
+        return ok(comments
+            .map((c) => `${c.authorName} — ${c.createdAt}\n${c.text}`)
+            .join('\n\n'));
+    }
+    catch (e) {
+        return err(friendly(e));
+    }
+}
+export async function addComment(api, me, args) {
+    const text = (args.text ?? '').trim();
+    if (!text)
+        return err('A comment cannot be empty.');
+    try {
+        const id = await resolveId(api, args.task);
+        // The API requires the author explicitly; it is always the PAT's own user,
+        // so a comment can never be attributed to someone else.
+        await api.addComment({ taskId: id, authorId: me.id, authorName: me.name, text });
+        return ok(`Comment added to #${args.task} as ${me.name}.`);
+    }
+    catch (e) {
+        return err(friendly(e));
+    }
+}
+/**
+ * Pull one attached file into the conversation. Images come back as an image
+ * block so they are actually visible; anything else is reported by name and
+ * type rather than dumped as base64 the model cannot read.
+ */
+export async function getAttachment(api, args) {
+    try {
+        const id = await resolveId(api, args.task);
+        const files = await api.listAttachments(id);
+        const wanted = args.file.trim().toLowerCase();
+        const match = files.find((f) => f.id === args.file.trim())
+            ?? files.find((f) => f.name.toLowerCase() === wanted)
+            ?? (files.filter((f) => f.name.toLowerCase().includes(wanted)).length === 1
+                ? files.find((f) => f.name.toLowerCase().includes(wanted))
+                : undefined);
+        if (!match) {
+            const names = files.map((f) => f.name).join(', ') || '(none)';
+            return err(`No attachment matches "${args.file}" on this task. Attached files: ${names}.`);
+        }
+        const dataUrl = await api.getAttachmentDataUrl(match.id);
+        if (!dataUrl)
+            return err(`"${match.name}" has no stored file to read.`);
+        const comma = dataUrl.indexOf(',');
+        const base64 = comma === -1 ? '' : dataUrl.slice(comma + 1);
+        if (match.mimeType.startsWith('image/') && base64) {
+            return { content: [{ type: 'image', data: base64, mimeType: match.mimeType }] };
+        }
+        return ok(`${match.name} — ${match.mimeType}${match.size ? `, ${humanSize(match.size)}` : ''}. `
+            + 'This file type cannot be shown inline; open it in SurecoreStudio to view it.');
+    }
+    catch (e) {
+        return err(friendly(e));
+    }
+}
+/** The member directory, so an id seen on a task can be turned into a person. */
+export async function listMembersTool(ws) {
+    if (ws.members.length === 0)
+        return ok('This workspace exposes no members.');
+    return ok(ws.members.map((m) => `${m.name} (id: ${m.id})`).join('\n'));
+}
+/**
+ * MIME type for an upload, by extension.
+ *
+ * `.html` is deliberately sent as text/plain: the server's allow-list has no
+ * text/html, and widening it would also let widget visitors upload HTML, which
+ * is a stored-XSS shape nobody needs. text/plain keeps the bytes and the .html
+ * filename intact while forcing a download rather than an inline render.
+ */
+function uploadMimeFor(name) {
+    const ext = name.toLowerCase().split('.').pop() ?? '';
+    const map = {
+        html: 'text/plain', htm: 'text/plain', md: 'text/plain', txt: 'text/plain', log: 'text/plain',
+        json: 'application/json', pdf: 'application/pdf', csv: 'text/csv', zip: 'application/zip',
+        png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp',
+    };
+    return map[ext] ?? 'text/plain';
+}
+export async function addAttachment(api, args) {
+    const { readFile } = await import('node:fs/promises');
+    const { basename } = await import('node:path');
+    let bytes;
+    try {
+        bytes = new Uint8Array(await readFile(args.path));
+    }
+    catch {
+        return err(`Could not read "${args.path}". Give the full path to a file that exists on this machine.`);
+    }
+    if (bytes.length === 0)
+        return err(`"${args.path}" is empty.`);
+    const name = basename(args.path);
+    try {
+        const id = await resolveId(api, args.task);
+        const saved = await api.uploadAttachment(id, { name, mimeType: uploadMimeFor(name), bytes });
+        const label = saved[0]?.name ?? name;
+        return ok(`Attached "${label}" (${humanSize(bytes.length)}) to #${args.task}.`);
+    }
+    catch (e) {
+        return err(friendly(e));
+    }
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "surecore-studio-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "MCP server for SurecoreStudio: read and update tasks, comments and attachments from Claude.",
+  "license": "MIT",
+  "author": "Surecore",
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "surecorestudio",
+    "tasks",
+    "claude"
+  ],
+  "homepage": "https://surecorestudio.surecore.cc",
+  "repository": {
+    "type": "git",
+    "url": "git+https://bitbucket.org/surecore-dev/surecore-studio.git",
+    "directory": "mcp/surecore-tasks"
+  },
+  "type": "module",
+  "bin": {
+    "surecore-tasks-mcp": "dist/index.js",
+    "surecore-studio-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "node --import tsx src/index.ts",
+    "test": "node --import tsx --test src/apiClient.test.ts src/tools.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.4.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}