@alacrity-ai/kbrelaymcp 0.3.1 → 0.5.0

package/README.md

@@ -54,18 +54,23 @@ claude mcp add kbrelay --scope user \
 | `create_project` | write | New project (`code` required, seeds columns). |
 | `update_project` | write | Edit a project's name/code/description/color/status. |
 | `list_cards` | read | Cards in a project (filter by column/assignee/q). |
-| `get_card` | read | One card (read the spec before working it). |
+| `get_card` | read | One card (read the spec before working it). Returns `attachments[]` — each with `filename`, `kind`, `sizeBytes`, and a same-origin `url` to fetch the bytes (v0.16.0). |
 | `create_card` | write | New card (markdown body; `@handle` to notify). |
 | `update_card` | write | Edit and/or **move** (set `columnId` — status = column). |
 | `delete_card` | write | Delete a card (cascades). |
 | `get_timeline` | read | A card's activity log (events + comments). |
-| `add_comment` | write | Report results on the timeline (note or handoff). |
+| `get_project_activity` | read | Newest-first card events across a whole board — "what happened while I was away?" (cursor-paginated, v0.17.0). |
+| `add_comment` | write | Report results on the timeline (note or handoff); `attachmentIds` links uploaded files. |
+| `add_attachment` | write | Upload a file to a card (`filePath` or base64, ≤25 MB) → attachment + markdown snippet (v0.17.0). |
+| `delete_attachment` | write | Delete an attachment (uploader or admin; bytes purged). |
 | `redact_comment` | write | Soft-delete your own comment (leaves a tombstone). |
+| `list_my_queue` | read | Your actionable queue — cards assigned to you in a `ready`-role column (v0.15.0). Work these first. |
 | `get_mentions` | read | Your @-mentions — "what did people ask me?". |
 | `mark_mentions_read` | write | Acknowledge mentions after handling them. |
 
 The `get_mentions` + `add_comment` pair makes *"check your mentions and respond to
-them"* a first-class flow.
+them"* a first-class flow, and `add_attachment` + `add_comment` (`attachmentIds`)
+makes *"attach the evidence to the handoff"* one too.
 
 ## Requirements
 

package/dist/client.d.ts

@@ -10,4 +10,15 @@ export declare class KbRelayClient {
     private readonly config;
     constructor(config: Config);
     request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+    /**
+     * Multipart upload (v0.17.0, KBR-66) — POST one file part named `file`, the
+     * shape `POST /cards/:id/attachments` expects. fetch sets the boundary; we
+     * must NOT set content-type ourselves.
+     */
+    upload<T = unknown>(path: string, file: {
+        data: Uint8Array;
+        filename: string;
+        contentType?: string;
+    }): Promise<T>;
+    private send;
 }

package/dist/client.js

@@ -11,16 +11,32 @@ export class KbRelayClient {
         this.config = config;
     }
     async request(method, path, body) {
+        return this.send(method, path, {
+            headers: { 'content-type': 'application/json' },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+    }
+    /**
+     * Multipart upload (v0.17.0, KBR-66) — POST one file part named `file`, the
+     * shape `POST /cards/:id/attachments` expects. fetch sets the boundary; we
+     * must NOT set content-type ourselves.
+     */
+    async upload(path, file) {
+        const form = new FormData();
+        form.set('file', new Blob([file.data], { type: file.contentType ?? 'application/octet-stream' }), file.filename);
+        return this.send('POST', path, { body: form });
+    }
+    async send(method, path, init) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), 30_000);
         try {
             const res = await fetch(`${this.config.baseUrl}/api${path}`, {
                 method,
                 headers: {
-                    'content-type': 'application/json',
+                    ...init.headers,
                     authorization: `Bearer ${this.config.apiKey}`,
                 },
-                body: body === undefined ? undefined : JSON.stringify(body),
+                body: init.body,
                 signal: controller.signal,
             });
             const text = await res.text();

package/dist/tools/index.js

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { readFile } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
 import { defineTool } from '../define-tool.js';
 /**
  * The kbRelay MCP tool surface. Every tool is RBAC-scoped by the token — a tool
@@ -12,6 +14,17 @@ const qs = (params) => {
     return pairs.length ? '?' + pairs.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&') : '';
 };
 const enc = encodeURIComponent;
+/** Server-side cap on POST /cards/:id/attachments — checked here too for a clear error. */
+const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
+/** Extension → content type for filePath uploads, so the server classifies the
+ *  kind correctly (image ⇒ inline render). Unknown ⇒ octet-stream. */
+const MIME_BY_EXT = {
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+    '.webp': 'image/webp', '.svg': 'image/svg+xml', '.pdf': 'application/pdf',
+    '.txt': 'text/plain', '.md': 'text/markdown', '.csv': 'text/csv',
+    '.json': 'application/json', '.html': 'text/html',
+    '.zip': 'application/zip', '.gz': 'application/gzip', '.tar': 'application/x-tar',
+};
 export const allTools = [
     // ── Identity ──
     defineTool({
@@ -22,7 +35,7 @@ export const allTools = [
     }),
     defineTool({
         name: 'list_users',
-        description: 'List the tenant\'s users (id, name, kind human/agent, @handle). Use to resolve a name to an id for assignment, or a @handle to mention.',
+        description: 'List the tenant\'s users (id, name, kind, @handle, profile). Resolve a name→id for assignment or a @handle to mention; read `profile` for who a person is (role/persona) and how to weigh their feedback.',
         inputSchema: z.object({}),
         handler: (_a, c) => c.request('GET', '/v1/users'),
     }),
@@ -35,7 +48,7 @@ export const allTools = [
     }),
     defineTool({
         name: 'get_project',
-        description: 'Get one project (name, code, description, color, status) and its columns. Read `description` to learn what the project is for. Column ids are per-project — resolve by name here, never hardcode.',
+        description: 'Get a project (name, code, description, color, status) + its columns, each with an optional `role`. Read `description` for context. Resolve target columns by `role`, never by hardcoded name.',
         inputSchema: z.object({ projectId: z.string() }),
         handler: (a, c) => c.request('GET', `/v1/projects/${enc(a.projectId)}`),
     }),
@@ -69,14 +82,15 @@ export const allTools = [
     // ── Cards ──
     defineTool({
         name: 'list_cards',
-        description: 'List cards in a project. Optional filters: column (id), assignee (user id), q (text search on summary/description).',
+        description: 'List cards in a project. Optional filters: column (id), assignee (user id), q (text search on summary/description), archived=true (archived cards only; default excludes them).',
         inputSchema: z.object({
             projectId: z.string(),
             column: z.string().optional(),
             assignee: z.string().optional(),
             q: z.string().optional(),
+            archived: z.boolean().optional(),
         }),
-        handler: (a, c) => c.request('GET', `/v1/projects/${enc(a.projectId)}/cards${qs({ column: a.column, assignee: a.assignee, q: a.q })}`),
+        handler: (a, c) => c.request('GET', `/v1/projects/${enc(a.projectId)}/cards${qs({ column: a.column, assignee: a.assignee, q: a.q, archived: a.archived ? '1' : undefined })}`),
     }),
     defineTool({
         name: 'get_card',
@@ -86,7 +100,7 @@ export const allTools = [
     }),
     defineTool({
         name: 'create_card',
-        description: 'Create a card (defaults to the first column). Write summary plain; description/acceptanceCriteria in markdown; @handle to notify.',
+        description: 'Create a card (defaults to the first column). Write summary plain; description/acceptanceCriteria in markdown; @handle to notify. dueAt = epoch-ms deadline; labels = names (400 on unknown).',
         inputSchema: z.object({
             projectId: z.string(),
             summary: z.string(),
@@ -94,15 +108,21 @@ export const allTools = [
             acceptanceCriteria: z.string().nullish(),
             columnId: z.string().optional(),
             assigneeUserId: z.string().nullish(),
+            reviewerUserId: z.string().nullish(),
+            dueAt: z.number().nullish(),
+            labels: z.array(z.string()).optional(),
         }),
         handler: (a, c) => {
-            const { projectId, ...body } = a;
-            return c.request('POST', `/v1/projects/${enc(projectId)}/cards`, body);
+            const { projectId, labels, ...body } = a;
+            return c.request('POST', `/v1/projects/${enc(projectId)}/cards`, {
+                ...body,
+                ...(labels !== undefined ? { labelNames: labels } : {}),
+            });
         },
     }),
     defineTool({
         name: 'update_card',
-        description: 'Edit a card AND/OR move it. To change status, set columnId (status = column). Rewrite the spec in place; do NOT log progress here — use add_comment.',
+        description: 'Edit and/or move a card (status = column). Pickup → in_progress; finish → review + set reviewerUserId (default: card creator); done only when told; stuck → blocked. Log via add_comment.',
         inputSchema: z.object({
             cardId: z.string(),
             summary: z.string().optional(),
@@ -110,11 +130,18 @@ export const allTools = [
             acceptanceCriteria: z.string().nullish(),
             columnId: z.string().optional(),
             assigneeUserId: z.string().nullish(),
+            reviewerUserId: z.string().nullish(),
+            dueAt: z.number().nullish(),
+            archived: z.boolean().optional(),
+            labels: z.array(z.string()).optional(),
             position: z.number().optional(),
         }),
         handler: (a, c) => {
-            const { cardId, ...body } = a;
-            return c.request('PATCH', `/v1/cards/${enc(cardId)}`, body);
+            const { cardId, labels, ...body } = a;
+            return c.request('PATCH', `/v1/cards/${enc(cardId)}`, {
+                ...body,
+                ...(labels !== undefined ? { labelNames: labels } : {}),
+            });
         },
     }),
     defineTool({
@@ -123,6 +150,21 @@ export const allTools = [
         inputSchema: z.object({ cardId: z.string() }),
         handler: (a, c) => c.request('DELETE', `/v1/cards/${enc(a.cardId)}`),
     }),
+    defineTool({
+        name: 'get_project_activity',
+        description: 'Project activity feed: newest-first card events across the board (creates/moves/assigns/comments) with cardKey + cardSummary. Catch up on "what happened while I was away"; nextCursor pages older.',
+        inputSchema: z.object({
+            projectId: z.string(),
+            since: z.number().optional(),
+            limit: z.number().optional(),
+            cursor: z.string().optional(),
+        }),
+        handler: (a, c) => c.request('GET', `/v1/projects/${enc(a.projectId)}/events${qs({
+            since: a.since != null ? String(a.since) : undefined,
+            limit: a.limit != null ? String(a.limit) : undefined,
+            cursor: a.cursor,
+        })}`),
+    }),
     // ── Timeline ──
     defineTool({
         name: 'get_timeline',
@@ -132,7 +174,7 @@ export const allTools = [
     }),
     defineTool({
         name: 'add_comment',
-        description: 'Report results ON the timeline (not by editing the description). A note or a structured handoff. Body is markdown; @handle to notify.',
+        description: 'Report results ON the timeline (not by editing the description). A note or a structured handoff. Body is markdown; @handle to notify; attachmentIds links files uploaded via add_attachment.',
         inputSchema: z.object({
             cardId: z.string(),
             type: z.enum(['note', 'handoff']).default('note'),
@@ -145,18 +187,74 @@ export const allTools = [
                 spunOff: z.array(z.string()).optional(),
             })
                 .optional(),
+            attachmentIds: z.array(z.string()).optional(),
         }),
         handler: (a, c) => {
             const { cardId, ...body } = a;
             return c.request('POST', `/v1/cards/${enc(cardId)}/comments`, body);
         },
     }),
+    // ── Attachments (v0.17.0, KBR-66) ──
+    defineTool({
+        name: 'add_attachment',
+        description: 'Attach a file to a card: filePath (preferred) OR contentBase64+filename. ≤25 MB. Returns the attachment + a ready-to-paste markdown snippet; link it to a note/handoff via add_comment attachmentIds.',
+        inputSchema: z
+            .object({
+            cardId: z.string(),
+            filePath: z.string().optional(),
+            contentBase64: z.string().optional(),
+            filename: z.string().optional(),
+            contentType: z.string().optional(),
+        })
+            .refine((v) => (v.filePath != null) !== (v.contentBase64 != null), {
+            message: 'Provide exactly one of filePath or contentBase64',
+        })
+            .refine((v) => v.contentBase64 == null || !!v.filename, {
+            message: 'filename is required with contentBase64',
+        }),
+        handler: async (a, c) => {
+            let data;
+            let filename;
+            if (a.filePath != null) {
+                data = new Uint8Array(await readFile(a.filePath));
+                filename = a.filename ?? basename(a.filePath);
+            }
+            else {
+                data = new Uint8Array(Buffer.from(a.contentBase64, 'base64'));
+                filename = a.filename;
+            }
+            if (data.byteLength > MAX_ATTACHMENT_BYTES) {
+                throw new Error(`File too large: ${(data.byteLength / (1024 * 1024)).toFixed(1)} MB (max 25 MB)`);
+            }
+            const contentType = a.contentType ?? MIME_BY_EXT[extname(filename).toLowerCase()];
+            const res = await c.upload(`/v1/cards/${enc(a.cardId)}/attachments`, { data, filename, contentType });
+            const att = res.attachment;
+            // Same snippet convention as the web composer: images inline, else a link.
+            const markdown = att.kind === 'image'
+                ? `![${att.filename}](${att.url})`
+                : `[📎 ${att.filename}](${att.url})`;
+            return { ...res, markdown };
+        },
+    }),
+    defineTool({
+        name: 'delete_attachment',
+        description: 'Delete an attachment (its bytes are purged). Uploader or admin only — others get 403. Remember to edit out any markdown referencing it.',
+        inputSchema: z.object({ attachmentId: z.string() }),
+        handler: (a, c) => c.request('DELETE', `/v1/attachments/${enc(a.attachmentId)}`),
+    }),
     defineTool({
         name: 'redact_comment',
         description: 'Redact (soft-delete) YOUR OWN comment — leaves a tombstone. For a leaked secret / PII / wrong-card post. Author-only.',
         inputSchema: z.object({ cardId: z.string(), commentId: z.string() }),
         handler: (a, c) => c.request('DELETE', `/v1/cards/${enc(a.cardId)}/comments/${enc(a.commentId)}`),
     }),
+    // ── Your queue (what to work now) ──
+    defineTool({
+        name: 'list_my_queue',
+        description: 'Your queue, two sections: work = assigned to you in a ready column (do these); review = you are the reviewer in a review column (verify these). Due-soonest first; finish → review + handoff.',
+        inputSchema: z.object({ projectId: z.string().optional() }),
+        handler: (a, c) => c.request('GET', `/v1/me/queue${qs({ projectId: a.projectId })}`),
+    }),
     // ── Mentions (your inbox) ──
     defineTool({
         name: 'get_mentions',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alacrity-ai/kbrelaymcp",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "MCP server for kbRelay — give an agent kanban powers (projects, cards, timeline, mentions) over the kbRelay API.",
   "type": "module",
   "license": "MIT",