@2kw/ai-mcp-server 6.0.0-dev.4 → 6.1.0-dev.10

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/billing.js

@@ -43,6 +43,27 @@ export function register(server, client) {
             };
         }
     });
+    server.tool("2kw_billing_has_available", "Check whether the org has enough available capacity for a metered resource (extraction credits, conversion credits, gateway tokens) before consuming it.", {
+        type: z
+            .enum(["EXTRACTION_CREDITS", "CONVERSION_CREDITS", "GATEWAY_TOKENS"])
+            .describe("Resource type to check"),
+        required: z.number().optional().describe("Amount required (server defaults to 1)"),
+    }, async (params) => {
+        try {
+            const { data } = await client.GET("/v1/billing/has-available", {
+                params: { query: { type: params.type, required: params.required } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
     server.tool("2kw_billing_check", "Check whether the org can create another resource of the given type before attempting it. Returns a single boolean answer.", {
         resource: z
             .enum(["schema", "prompt", "team-member"])

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/conversion.js

@@ -234,6 +234,87 @@ export function register(server, client) {
             };
         }
     });
+    // ── convert_file ────────────────────────────────────────────────────────
+    server.tool("2kw_convert_file", "Convert one or more local files (PDF, DOCX, XLSX, images, etc.) synchronously via direct multipart upload. Simpler single-purpose alternative to 2kw_convert_document for local-file-only conversions.", {
+        paths: z.array(z.string()).min(1).describe("Local file paths to upload and convert"),
+        pipeline: z
+            .string()
+            .optional()
+            .describe("Processing pipeline: 'fast' (default), 'ocr', or 'vlm'"),
+        outputFormats: z
+            .array(z.string())
+            .optional()
+            .describe("Output formats, e.g. ['md', 'text', 'html', 'json']. Only relevant for ocr/vlm pipelines."),
+    }, async ({ paths, pipeline, outputFormats }) => {
+        try {
+            const formData = new FormData();
+            for (const p of paths) {
+                const buffer = await readFile(p);
+                const filename = basename(p);
+                formData.append("files", new Blob([buffer], { type: getMimeType(filename) }), filename);
+            }
+            if (outputFormats?.length) {
+                formData.append("options", new Blob([JSON.stringify({ outputFormats: outputFormats.map(mapOutputFormat) })], { type: "application/json" }));
+            }
+            const { data } = await client.POST("/v1/convert/file", {
+                params: { query: { pipeline } },
+                // Provide placeholder body for type checking; actual payload comes from bodySerializer
+                body: { files: paths },
+                bodySerializer: () => formData,
+            });
+            return { content: formatConvertResponse(data) };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── convert_file_async ───────────────────────────────────────────────────
+    server.tool("2kw_convert_file_async", "Start an asynchronous conversion of one or more local files via direct multipart upload. Returns a task ID — poll with 2kw_get_task_status / 2kw_get_task_result.", {
+        paths: z.array(z.string()).min(1).describe("Local file paths to upload and convert"),
+        pipeline: z
+            .string()
+            .optional()
+            .describe("Processing pipeline: 'fast' (default), 'ocr', or 'vlm'"),
+        outputFormats: z
+            .array(z.string())
+            .optional()
+            .describe("Output formats, e.g. ['md', 'text', 'html', 'json']. Only relevant for ocr/vlm pipelines."),
+    }, async ({ paths, pipeline, outputFormats }) => {
+        try {
+            const formData = new FormData();
+            for (const p of paths) {
+                const buffer = await readFile(p);
+                const filename = basename(p);
+                formData.append("files", new Blob([buffer], { type: getMimeType(filename) }), filename);
+            }
+            if (outputFormats?.length) {
+                formData.append("options", new Blob([JSON.stringify({ outputFormats: outputFormats.map(mapOutputFormat) })], { type: "application/json" }));
+            }
+            const { data } = await client.POST("/v1/convert/file/async", {
+                params: { query: { pipeline } },
+                body: { files: paths },
+                bodySerializer: () => formData,
+            });
+            const taskId = data?.taskId;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Conversion submitted (task: ${taskId}). Poll with 2kw_get_task_status / 2kw_get_task_result.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
     // ── get_task_status ─────────────────────────────────────────────────────
     server.tool("2kw_get_task_status", "Check the status of an async conversion task. Supports long polling with the wait parameter.", {
         taskId: z.string().describe("The async task ID returned by convert_document"),