@2kw/ai-mcp-server 6.1.0-dev.8 → 6.1.1

package/dist/tools/annotation-queues.js

@@ -0,0 +1,322 @@
+import { z } from "zod";
+import { formatErrorForMcp } from "../errors.js";
+const SUBJECT_TYPE = z.enum(["RUN_RESULT", "TRACE", "SPAN", "DATASET_ITEM"]);
+const ITEM_STATUS = z.enum(["PENDING", "IN_PROGRESS", "DONE", "SKIPPED"]);
+export function register(server, client) {
+    // ── list_annotation_queues ──────────────────────────────────────────────
+    server.tool("2kw_list_annotation_queues", "List annotation queues in the organization.", {
+        archived: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("List archived queues instead of active ones"),
+    }, async ({ archived }) => {
+        try {
+            const { data } = await client.GET("/v1/annotation-queues", {
+                params: { query: { archived } },
+            });
+            const queues = (data ?? []);
+            const lines = queues.map((q) => {
+                const counts = q.itemCounts ?? {};
+                return `- ${q.name} (id: ${q.id}) — pending=${counts.pending ?? 0} inProgress=${counts.inProgress ?? 0} done=${counts.done ?? 0} skipped=${counts.skipped ?? 0}${q.archivedAt ? ` [archived ${q.archivedAt}]` : ""}`;
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Annotation queues (${queues.length}):\n${lines.join("\n") || "(none)"}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_annotation_queue ─────────────────────────────────────────────────
+    server.tool("2kw_get_annotation_queue", "Get an annotation queue by its ID, including item counts by status.", {
+        queueId: z.string().describe("The annotation queue ID"),
+    }, async ({ queueId }) => {
+        try {
+            const { data } = await client.GET("/v1/annotation-queues/{id}", {
+                params: { path: { id: queueId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── create_annotation_queue ──────────────────────────────────────────────
+    server.tool("2kw_create_annotation_queue", "Create a new annotation queue to curate subjects for human (or agent-assisted) review.", {
+        name: z.string().min(1).max(255).describe("Queue name"),
+        description: z.string().max(4000).optional().describe("Queue description"),
+    }, async ({ name, description }) => {
+        try {
+            const { data } = await client.POST("/v1/annotation-queues", {
+                body: {
+                    name,
+                    ...(description !== undefined && { description }),
+                },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── update_annotation_queue ──────────────────────────────────────────────
+    server.tool("2kw_update_annotation_queue", "Update an annotation queue's name or description.", {
+        queueId: z.string().describe("The annotation queue ID"),
+        name: z.string().min(1).max(255).optional().describe("New name"),
+        description: z.string().max(4000).optional().describe("New description"),
+    }, async ({ queueId, name, description }) => {
+        try {
+            const body = {};
+            if (name !== undefined)
+                body.name = name;
+            if (description !== undefined)
+                body.description = description;
+            const { data } = await client.PATCH("/v1/annotation-queues/{id}", {
+                params: { path: { id: queueId } },
+                body: body,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── archive_annotation_queue ─────────────────────────────────────────────
+    server.tool("2kw_archive_annotation_queue", "Archive an annotation queue. Idempotent — archiving an already-archived queue is a no-op.", {
+        queueId: z.string().describe("The annotation queue ID to archive"),
+    }, async ({ queueId }) => {
+        try {
+            await client.POST("/v1/annotation-queues/{id}/archive", {
+                params: { path: { id: queueId } },
+            });
+            return {
+                content: [{ type: "text", text: `Queue ${queueId} archived.` }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── find_queue_items_by_subject ──────────────────────────────────────────
+    server.tool("2kw_find_queue_items_by_subject", "Find every annotation queue item referencing a given subject, across all queues in the " +
+        "organization. Empty when the subject has never been queued. Useful to check whether a " +
+        "run result, trace, span, or dataset item is already under review before adding it again.", {
+        subjectType: SUBJECT_TYPE.describe("The subject's type"),
+        subjectId: z.string().describe("The subject's ID"),
+    }, async ({ subjectType, subjectId }) => {
+        try {
+            const { data } = await client.GET("/v1/annotation-queues/by-subject", {
+                params: { query: { subjectType, subjectId } },
+            });
+            const queueItems = (data ?? []);
+            const lines = queueItems.map((i) => `- queue=${i.queueId} item=${i.id} status=${i.status} assignedTo=${i.assignedTo ?? "(unassigned)"}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Queue items for ${subjectType} ${subjectId} (${queueItems.length}):\n${lines.join("\n") || "(none)"}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── list_queue_items ──────────────────────────────────────────────────────
+    server.tool("2kw_list_queue_items", "List items in a queue, optionally filtered by status or assignee.", {
+        queueId: z.string().describe("The annotation queue ID"),
+        status: ITEM_STATUS.optional().describe("Filter by item status"),
+        assignedTo: z.string().optional().describe("Filter by assignee user ID"),
+        page: z.number().optional().default(0).describe("Page number (0-based)"),
+        size: z.number().optional().default(50).describe("Page size"),
+    }, async ({ queueId, status, assignedTo, page, size }) => {
+        try {
+            const { data } = await client.GET("/v1/annotation-queues/{id}/items", {
+                params: {
+                    path: { id: queueId },
+                    query: { status, assignedTo, page, size },
+                },
+            });
+            const queueItems = (data ?? []);
+            const lines = queueItems.map((i) => `- ${i.id} [${i.status}] ${i.subjectType}:${i.subjectId}${i.assignedTo ? ` assignedTo=${i.assignedTo}` : ""}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Queue ${queueId} items (page ${page ?? 0}, ${queueItems.length} returned):\n${lines.join("\n") || "(none)"}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── add_queue_items ───────────────────────────────────────────────────────
+    server.tool("2kw_add_queue_items", "Bulk-add subjects to a queue for review. Duplicates (same subject already in the queue) " +
+        "are skipped rather than erroring, so this is safe to call repeatedly with an overlapping set.", {
+        queueId: z.string().describe("The annotation queue ID"),
+        items: z
+            .array(z.object({
+            subjectType: SUBJECT_TYPE,
+            subjectId: z.string().min(1),
+        }))
+            .min(1)
+            .max(1000)
+            .describe("Subjects to add, up to 1000 per call"),
+    }, async ({ queueId, items }) => {
+        try {
+            const { data } = await client.POST("/v1/annotation-queues/{id}/items", {
+                params: { path: { id: queueId } },
+                body: { items },
+            });
+            const added = (data ?? []);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Added ${added.length} item(s) to queue ${queueId} (duplicates skipped).\n\n${JSON.stringify(added, null, 2)}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── claim_next_queue_item ─────────────────────────────────────────────────
+    server.tool("2kw_claim_next_queue_item", "Claim the next eligible item in a queue for the caller — the entry point of a review loop. " +
+        "Returns a 'no items available' message when the queue has nothing left to claim, which is " +
+        "a normal end state, not an error. A typical loop: (1) call this to claim an item and read " +
+        "its subjectType/subjectId; (2) inspect that subject with the matching read tool (e.g. an " +
+        "experiment run result, a trace, or a dataset item); (3) file the verdict with " +
+        "2kw_record_human_score, passing the item's subjectType/subjectId and its id as " +
+        "annotationQueueItemId so the server can validate the match; (4) call 2kw_update_queue_item " +
+        "to mark the item DONE (or SKIPPED); (5) repeat from step 1 until this tool reports no items " +
+        "left.", {
+        queueId: z.string().describe("The annotation queue ID to claim from"),
+    }, async ({ queueId }) => {
+        try {
+            const { data, response } = await client.GET("/v1/annotation-queues/{id}/items/next", {
+                params: { path: { id: queueId } },
+            });
+            if (!data || response.status === 204) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No items available to claim in queue ${queueId} — it is empty for you right now.`,
+                        },
+                    ],
+                };
+            }
+            const item = data;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Claimed item ${item.id} (subject: ${item.subjectType}:${item.subjectId}, status: ${item.status}).\n` +
+                            `Next: review the subject, file a score with 2kw_record_human_score ` +
+                            `(annotationQueueItemId="${item.id}"), then call 2kw_update_queue_item to close it out.\n\n` +
+                            `${JSON.stringify(item, null, 2)}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_queue_item ────────────────────────────────────────────────────────
+    server.tool("2kw_get_queue_item", "Get a single queue item by its ID.", {
+        queueId: z.string().describe("The annotation queue ID"),
+        itemId: z.string().describe("The queue item ID"),
+    }, async ({ queueId, itemId }) => {
+        try {
+            const { data } = await client.GET("/v1/annotation-queues/{id}/items/{itemId}", {
+                params: { path: { id: queueId, itemId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── update_queue_item ─────────────────────────────────────────────────────
+    server.tool("2kw_update_queue_item", "Update a queue item's status or assignee — the closing step of a review loop started by " +
+        "2kw_claim_next_queue_item. Set status=DONE once a verdict has been filed (see " +
+        "2kw_record_human_score), or SKIPPED to pass on an item without scoring it. Clear " +
+        "assignedTo (pass an empty string) to release it back to the pool for another reviewer.", {
+        queueId: z.string().describe("The annotation queue ID"),
+        itemId: z.string().describe("The queue item ID"),
+        status: ITEM_STATUS.optional().describe("New status"),
+        assignedTo: z.string().optional().describe("New assignee user ID (empty string to unassign)"),
+    }, async ({ queueId, itemId, status, assignedTo }) => {
+        try {
+            const body = {};
+            if (status !== undefined)
+                body.status = status;
+            if (assignedTo !== undefined)
+                body.assignedTo = assignedTo;
+            const { data } = await client.PATCH("/v1/annotation-queues/{id}/items/{itemId}", {
+                params: { path: { id: queueId, itemId } },
+                body: body,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=annotation-queues.js.map

package/dist/tools/conversations.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClient } from "../client.js";
+export declare function register(server: McpServer, client: ApiClient): void;
+//# sourceMappingURL=conversations.d.ts.map

package/dist/tools/conversations.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { formatErrorForMcp } from "../errors.js";
+export function register(server, client) {
+    // ── create_conversation ─────────────────────────────────────────────────
+    server.tool("2kw_create_conversation", "Create a conversation whose id can be passed as the 'conversation' parameter on the responses API, so an agent turn can be replayed and extended across calls.", {
+        items: z.array(z.unknown()).optional().describe("Initial items to seed the conversation with"),
+        metadata: z.record(z.string(), z.unknown()).optional().describe("Arbitrary metadata (JSON object)"),
+    }, async ({ items, metadata }) => {
+        try {
+            const body = {};
+            if (items !== undefined)
+                body.items = items;
+            if (metadata !== undefined)
+                body.metadata = metadata;
+            const { data } = await client.POST("/v1/conversations", {
+                body: Object.keys(body).length > 0 ? body : undefined,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_conversation ─────────────────────────────────────────────────────
+    server.tool("2kw_get_conversation", "Fetch a conversation by id.", { conversationId: z.string().describe("The conversation ID") }, async ({ conversationId }) => {
+        try {
+            const { data } = await client.GET("/v1/conversations/{conversationId}", {
+                params: { path: { conversationId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── update_conversation ──────────────────────────────────────────────────
+    server.tool("2kw_update_conversation", "Replace a conversation's metadata.", {
+        conversationId: z.string().describe("The conversation ID"),
+        metadata: z.record(z.string(), z.unknown()).optional().describe("Arbitrary metadata (JSON object)"),
+    }, async ({ conversationId, metadata }) => {
+        try {
+            const { data } = await client.POST("/v1/conversations/{conversationId}", {
+                params: { path: { conversationId } },
+                body: { metadata },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── delete_conversation ───────────────────────────────────────────────────
+    server.tool("2kw_delete_conversation", "Delete a conversation and the responses recorded against it.", { conversationId: z.string().describe("The conversation ID to delete") }, async ({ conversationId }) => {
+        try {
+            const { data } = await client.DELETE("/v1/conversations/{conversationId}", {
+                params: { path: { conversationId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── list_conversation_items ──────────────────────────────────────────────
+    server.tool("2kw_list_conversation_items", "Fetch a conversation's items in replay order, oldest first.", { conversationId: z.string().describe("The conversation ID") }, async ({ conversationId }) => {
+        try {
+            const { data } = await client.GET("/v1/conversations/{conversationId}/items", {
+                params: { path: { conversationId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=conversations.js.map

package/dist/tools/files.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClient } from "../client.js";
+export declare function register(server: McpServer, client: ApiClient): void;
+//# sourceMappingURL=files.d.ts.map

package/dist/tools/files.js

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import { readFile, writeFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { BackboneApiError, formatErrorForMcp } from "../errors.js";
+import { getMimeType } from "../mime.js";
+const FilePurpose = z.enum(["agent_input", "knowledge"]);
+export function register(server, client) {
+    // ── list_files ────────────────────────────────────────────────────────────
+    server.tool("2kw_list_files", "List the organization's files as a page, newest first by default, optionally narrowed by purpose.", {
+        purpose: FilePurpose.optional().describe("Narrow the list to one purpose"),
+        page: z.number().optional().default(0).describe("Page number (0-based)"),
+        size: z.number().optional().default(20).describe("Page size"),
+    }, async ({ purpose, page, size }) => {
+        try {
+            const { data } = await client.GET("/v1/files", {
+                params: { query: { purpose, pageable: { page, size } } },
+            });
+            const result = data;
+            const lines = (result.content ?? []).map((f) => `- ${f.filename} (id: ${f.id}, purpose: ${f.purpose}, bytes: ${f.bytes})`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Files (${result.totalElements} total, page ${(result.number ?? 0) + 1}/${result.totalPages}):\n${lines.join("\n") || "(none)"}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── upload_file ───────────────────────────────────────────────────────────
+    server.tool("2kw_upload_file", "Upload a local file and get back its file id. purpose=agent_input files expire after the configured TTL unless referenced by a turn; purpose=knowledge is for organization members only and can be ingested into a knowledge base with 2kw_attach_knowledge_document_file. Size and per-end-user quotas apply.", {
+        filePath: z.string().describe("Local path to the file to upload"),
+        purpose: FilePurpose.describe("Why the file exists — determines its lifecycle"),
+    }, async ({ filePath, purpose }) => {
+        try {
+            const fileBuffer = await readFile(filePath);
+            const filename = basename(filePath);
+            const mimeType = getMimeType(filename);
+            const formData = new FormData();
+            formData.append("file", new Blob([fileBuffer], { type: mimeType }), filename);
+            const { data } = await client.POST("/v1/files", {
+                params: { query: { purpose } },
+                // Provide placeholder body for type checking; actual payload comes from bodySerializer
+                body: { file: "" },
+                bodySerializer: () => formData,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_file ──────────────────────────────────────────────────────────────
+    server.tool("2kw_get_file", "Fetch a file's metadata by id.", { fileId: z.string().describe("The file ID") }, async ({ fileId }) => {
+        try {
+            const { data } = await client.GET("/v1/files/{fileId}", {
+                params: { path: { fileId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── delete_file ───────────────────────────────────────────────────────────
+    server.tool("2kw_delete_file", "Soft-delete an agent_input file. Knowledge files are not deletable through this API; their lifecycle belongs to the knowledge base's document.", { fileId: z.string().describe("The file ID to delete") }, async ({ fileId }) => {
+        try {
+            const { data } = await client.DELETE("/v1/files/{fileId}", {
+                params: { path: { fileId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── download_file ─────────────────────────────────────────────────────────
+    server.tool("2kw_download_file", "Download a file's bytes and save them to a local path.", {
+        fileId: z.string().describe("The file ID"),
+        savePath: z.string().describe("Local path to write the downloaded bytes to"),
+    }, async ({ fileId, savePath }) => {
+        try {
+            const { baseUrl, apiKey } = client._config;
+            const res = await fetch(`${baseUrl}/v1/files/${encodeURIComponent(fileId)}/content`, {
+                headers: { Authorization: `Bearer ${apiKey}` },
+            });
+            if (!res.ok) {
+                let body;
+                try {
+                    body = await res.json();
+                }
+                catch {
+                    body = {
+                        error: res.statusText,
+                        message: `HTTP ${res.status}: ${res.statusText}`,
+                        status: res.status,
+                        timestamp: new Date().toISOString(),
+                    };
+                }
+                throw new BackboneApiError(body);
+            }
+            const buffer = Buffer.from(await res.arrayBuffer());
+            await writeFile(savePath, buffer);
+            const contentType = res.headers.get("content-type") ?? "application/octet-stream";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Downloaded ${buffer.length} bytes (${contentType}) to ${savePath}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=files.js.map

package/dist/tools/knowledge.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClient } from "../client.js";
+export declare function register(server: McpServer, client: ApiClient): void;
+//# sourceMappingURL=knowledge.d.ts.map