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

package/dist/tools/knowledge.js

@@ -0,0 +1,382 @@
+import { z } from "zod";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { BackboneApiError, formatErrorForMcp } from "../errors.js";
+import { getMimeType } from "../mime.js";
+const ChunkingStrategy = z.enum(["AUTO", "FIXED", "HIERARCHICAL", "CUSTOM"]);
+const DocumentStatus = z.enum(["PENDING", "PARSING", "CHUNKING", "EMBEDDING", "READY", "ERROR"]);
+/**
+ * Fields shared by knowledge-base create and update — the backend treats
+ * every one of these as mandatory on both requests (name, slug,
+ * embeddingProviderId, embeddingModel, embeddingDim), so there is no partial
+ * update: an update omitting one of them would be rejected by validation.
+ */
+const knowledgeBaseFields = {
+    name: z.string().min(1).describe("Knowledge base name"),
+    slug: z.string().min(1).describe("URL-safe slug, lowercase letters and digits joined by single dashes"),
+    embeddingProviderId: z.string().min(1).describe("Provider id serving the embedding model"),
+    embeddingModel: z.string().min(1).describe("Embedding model id"),
+    embeddingDim: z.number().int().positive().describe("Embedding dimension. Fixed at creation — on update this must match the existing value, it is not applied as a change."),
+    description: z.string().optional().describe("Knowledge base description"),
+    chunkingStrategy: ChunkingStrategy.optional().describe("Chunking strategy"),
+    chunkSize: z.number().int().min(50).max(4000).optional().describe("Chunk size (50-4000)"),
+    chunkOverlap: z.number().int().min(0).max(2000).optional().describe("Chunk overlap (0-2000), must be smaller than chunkSize"),
+    parentChunkSize: z.number().int().min(100).max(8000).optional().describe("Parent chunk size for hierarchical chunking (100-8000), must exceed chunkSize"),
+    hybridSearchEnabled: z.boolean().optional().describe("Enable hybrid dense + lexical search"),
+    rerankerProviderId: z.string().optional().describe("Provider id used for reranking"),
+};
+function buildKnowledgeBaseBody(params) {
+    const body = {
+        name: params.name,
+        slug: params.slug,
+        embeddingProviderId: params.embeddingProviderId,
+        embeddingModel: params.embeddingModel,
+        embeddingDim: params.embeddingDim,
+    };
+    for (const key of [
+        "description",
+        "chunkingStrategy",
+        "chunkSize",
+        "chunkOverlap",
+        "parentChunkSize",
+        "hybridSearchEnabled",
+        "rerankerProviderId",
+    ]) {
+        if (params[key] !== undefined)
+            body[key] = params[key];
+    }
+    return body;
+}
+/**
+ * Format a hybrid search response, surfacing each hit's chunkId prominently
+ * so an agent can chain a hit straight into 2kw_resolve_citation.
+ */
+function formatSearchResponse(data) {
+    const result = data;
+    const hits = result.hits ?? [];
+    const lines = hits.map((h, i) => {
+        const pages = h.pageStart !== undefined ? ` pages ${h.pageStart}-${h.pageEnd ?? h.pageStart}` : "";
+        const heading = h.headingPath?.length ? ` [${h.headingPath.join(" > ")}]` : "";
+        return `${i + 1}. chunkId=${h.chunkId} score=${h.score?.toFixed(4)} document="${h.documentName}" (id: ${h.documentId})${pages}${heading}\n   ${h.content}`;
+    });
+    const header = `Search results for "${result.query}"${result.degraded ? ` (degraded: ${result.degraded})` : ""} — ${hits.length} hit(s). Use 2kw_resolve_citation with a chunkId to re-fetch a passage.`;
+    return `${header}\n${lines.join("\n") || "(no hits)"}`;
+}
+export function register(server, client) {
+    // ── list_knowledge_bases ─────────────────────────────────────────────────
+    server.tool("2kw_list_knowledge_bases", "List the organization's knowledge bases as a page, newest first by default.", {
+        page: z.number().optional().default(0).describe("Page number (0-based)"),
+        size: z.number().optional().default(20).describe("Page size"),
+    }, async ({ page, size }) => {
+        try {
+            const { data } = await client.GET("/v1/knowledge-bases", {
+                params: { query: { pageable: { page, size } } },
+            });
+            const result = data;
+            const lines = (result.content ?? []).map((kb) => `- ${kb.name} (id: ${kb.id}, slug: ${kb.slug}, status: ${kb.status})${kb.description ? ` — ${kb.description}` : ""}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Knowledge bases (${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,
+            };
+        }
+    });
+    // ── create_knowledge_base ────────────────────────────────────────────────
+    server.tool("2kw_create_knowledge_base", "Create a knowledge base and its first configuration version. The embedding dimension is fixed at creation.", knowledgeBaseFields, async (params) => {
+        try {
+            const { data } = await client.POST("/v1/knowledge-bases", {
+                body: buildKnowledgeBaseBody(params),
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_knowledge_base ───────────────────────────────────────────────────
+    server.tool("2kw_get_knowledge_base", "Retrieve a single knowledge base by id.", { knowledgeBaseId: z.string().describe("The knowledge base ID") }, async ({ knowledgeBaseId }) => {
+        try {
+            const { data } = await client.GET("/v1/knowledge-bases/{id}", {
+                params: { path: { id: knowledgeBaseId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── update_knowledge_base ────────────────────────────────────────────────
+    server.tool("2kw_update_knowledge_base", "Apply the request's fields to a knowledge base and snapshot the result as the next configuration version. name, slug, embeddingProviderId, embeddingModel and embeddingDim are required on every update; embeddingDim cannot actually change — it must match the existing value or the update is rejected.", { knowledgeBaseId: z.string().describe("The knowledge base ID"), ...knowledgeBaseFields }, async ({ knowledgeBaseId, ...params }) => {
+        try {
+            const { data } = await client.PATCH("/v1/knowledge-bases/{id}", {
+                params: { path: { id: knowledgeBaseId } },
+                body: buildKnowledgeBaseBody(params),
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── delete_knowledge_base ────────────────────────────────────────────────
+    server.tool("2kw_delete_knowledge_base", "Soft-delete a knowledge base, releasing its slug. Version history is retained. Requires admin role.", { knowledgeBaseId: z.string().describe("The knowledge base ID to delete") }, async ({ knowledgeBaseId }) => {
+        try {
+            await client.DELETE("/v1/knowledge-bases/{id}", {
+                params: { path: { id: knowledgeBaseId } },
+            });
+            return {
+                content: [{ type: "text", text: `Knowledge base ${knowledgeBaseId} deleted successfully.` }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── list_knowledge_documents ──────────────────────────────────────────────
+    server.tool("2kw_list_knowledge_documents", "List a knowledge base's documents as a page, newest first by default. The optional status filter matches on the document's current revision.", {
+        knowledgeBaseId: z.string().describe("The knowledge base ID"),
+        status: DocumentStatus.optional().describe("Filter by the document's current revision status"),
+        page: z.number().optional().default(0).describe("Page number (0-based)"),
+        size: z.number().optional().default(20).describe("Page size"),
+    }, async ({ knowledgeBaseId, status, page, size }) => {
+        try {
+            const { data } = await client.GET("/v1/knowledge-bases/{knowledgeBaseId}/documents", {
+                params: {
+                    path: { knowledgeBaseId },
+                    query: { status, pageable: { page, size } },
+                },
+            });
+            const result = data;
+            const lines = (result.content ?? []).map((d) => `- ${d.name} (id: ${d.id}, currentVersion: ${d.currentVersion?.status ?? "—"})`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Documents (${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_knowledge_documents ────────────────────────────────────────────
+    server.tool("2kw_upload_knowledge_documents", "Upload one or more local files into a knowledge base for asynchronous ingestion. Always accepted (202); poll each entry's version with 2kw_get_knowledge_document_version. Files are accepted independently, so one rejected file does not discard the others.", {
+        knowledgeBaseId: z.string().describe("The knowledge base ID"),
+        filePaths: z.array(z.string()).min(1).describe("Local paths of the files to upload"),
+    }, async ({ knowledgeBaseId, filePaths }) => {
+        try {
+            const formData = new FormData();
+            for (const filePath of filePaths) {
+                const buffer = await readFile(filePath);
+                const filename = basename(filePath);
+                formData.append("files", new Blob([buffer], { type: getMimeType(filename) }), filename);
+            }
+            const { baseUrl, apiKey } = client._config;
+            const res = await fetch(`${baseUrl}/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/documents`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${apiKey}` },
+                body: formData,
+            });
+            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 data = (await res.json());
+            const lines = data.map((r) => r.error
+                ? `- ${r.filename}: rejected — ${r.error}`
+                : `- ${r.filename}: accepted, documentId=${r.upload?.document?.id}, versionId=${r.upload?.acceptedVersion?.id}, status=${r.upload?.acceptedVersion?.status}`);
+            return {
+                content: [{ type: "text", text: `Upload accepted:\n${lines.join("\n")}` }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── attach_knowledge_document_file ───────────────────────────────────────
+    server.tool("2kw_attach_knowledge_document_file", "Ingest a file uploaded earlier with 2kw_upload_file (purpose=knowledge) into a knowledge base. Always accepted (202); poll acceptedVersion with 2kw_get_knowledge_document_version. 400 for a file whose purpose is not knowledge, 404 for an unknown file, 410 for a deleted one.", {
+        knowledgeBaseId: z.string().describe("The knowledge base ID"),
+        fileId: z.string().describe("Id of a file uploaded with purpose=knowledge through 2kw_upload_file"),
+    }, async ({ knowledgeBaseId, fileId }) => {
+        try {
+            const { data } = await client.POST("/v1/knowledge-bases/{knowledgeBaseId}/documents/attach", {
+                params: { path: { knowledgeBaseId } },
+                body: { fileId },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_knowledge_document ────────────────────────────────────────────────
+    server.tool("2kw_get_knowledge_document", "Retrieve a knowledge base document together with the revision retrieval is serving.", {
+        knowledgeBaseId: z.string().describe("The knowledge base ID"),
+        documentId: z.string().describe("The document ID"),
+    }, async ({ knowledgeBaseId, documentId }) => {
+        try {
+            const { data } = await client.GET("/v1/knowledge-bases/{knowledgeBaseId}/documents/{documentId}", { params: { path: { knowledgeBaseId, documentId } } });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── delete_knowledge_document ─────────────────────────────────────────────
+    server.tool("2kw_delete_knowledge_document", "Soft-delete a document and take every revision out of retrieval. Previously issued citations still resolve. Requires admin role.", {
+        knowledgeBaseId: z.string().describe("The knowledge base ID"),
+        documentId: z.string().describe("The document ID to delete"),
+    }, async ({ knowledgeBaseId, documentId }) => {
+        try {
+            await client.DELETE("/v1/knowledge-bases/{knowledgeBaseId}/documents/{documentId}", {
+                params: { path: { knowledgeBaseId, documentId } },
+            });
+            return {
+                content: [{ type: "text", text: `Document ${documentId} deleted successfully.` }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_knowledge_document_version ────────────────────────────────────────
+    server.tool("2kw_get_knowledge_document_version", "Retrieve one revision of a document by id — the polling endpoint for an accepted upload. Superseded revisions remain readable.", {
+        knowledgeBaseId: z.string().describe("The knowledge base ID"),
+        documentId: z.string().describe("The document ID"),
+        versionId: z.string().describe("The version ID"),
+    }, async ({ knowledgeBaseId, documentId, versionId }) => {
+        try {
+            const { data } = await client.GET("/v1/knowledge-bases/{knowledgeBaseId}/documents/{documentId}/versions/{versionId}", { params: { path: { knowledgeBaseId, documentId, versionId } } });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── search_knowledge_base ─────────────────────────────────────────────────
+    server.tool("2kw_search_knowledge_base", "Hybrid dense + lexical retrieval with Reciprocal Rank Fusion over a knowledge base. topK is clamped to 1..100. Not paginated — raise topK instead of asking for a later page. Each hit carries a chunkId that can be passed to 2kw_resolve_citation to re-fetch the passage later.", {
+        knowledgeBaseId: z.string().describe("The knowledge base ID"),
+        query: z.string().min(1).describe("The search query"),
+        topK: z.number().int().min(1).max(100).optional().describe("Number of results to return (default backend-defined, clamped 1-100)"),
+        metadataFilter: z.record(z.string(), z.unknown()).optional().describe("Filter hits by document metadata"),
+    }, async ({ knowledgeBaseId, query, topK, metadataFilter }) => {
+        try {
+            const body = { query };
+            if (topK !== undefined)
+                body.topK = topK;
+            if (metadataFilter !== undefined)
+                body.metadataFilter = metadataFilter;
+            const { data } = await client.POST("/v1/knowledge-bases/{knowledgeBaseId}/search", {
+                params: { path: { knowledgeBaseId } },
+                body: body,
+            });
+            return { content: [{ type: "text", text: formatSearchResponse(data) }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── resolve_citation ──────────────────────────────────────────────────────
+    server.tool("2kw_resolve_citation", "Resolve a citation's chunkId (from 2kw_search_knowledge_base or a response citation) to the passage it points at, exactly as it was indexed. Deliberately resolves passages from superseded revisions — flagged with isCurrentVersion=false. If the document was deleted the citation still resolves with ids/pages/headings intact but the passage withheld (textStatus=WITHDRAWN).", {
+        knowledgeBaseId: z.string().describe("The knowledge base ID"),
+        chunkId: z.string().describe("The chunk ID from a search hit or response citation"),
+    }, async ({ knowledgeBaseId, chunkId }) => {
+        try {
+            const { data } = await client.GET("/v1/knowledge-bases/{knowledgeBaseId}/citations/{chunkId}", { params: { path: { knowledgeBaseId, chunkId } } });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── list_provider_embedding_models ────────────────────────────────────────
+    server.tool("2kw_list_provider_embedding_models", "List embedding models served by a provider that fit a provisioned embedding dimension. Empty when the provider type has no catalogued embedding models; never an error. Use this to pick embeddingModel/embeddingDim for 2kw_create_knowledge_base.", { providerId: z.string().describe("The provider ID") }, async ({ providerId }) => {
+        try {
+            const { data } = await client.GET("/v1/providers/{providerId}/embedding-models", {
+                params: { path: { providerId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=knowledge.js.map

package/dist/tools/plugins.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClient } from "../client.js";
+/** Register plugin install/sync/detach tools (#640). Writes need an admin key. */
+export declare function register(server: McpServer, client: ApiClient): void;
+//# sourceMappingURL=plugins.d.ts.map

package/dist/tools/plugins.js

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { formatErrorForMcp } from "../errors.js";
+// Spring accepts flat pagination parameters despite the generated pageable wrapper.
+function paginationParams(params) {
+    return {
+        page: params.page ?? 0,
+        size: params.size ?? 20,
+        sort: params.sort ? [params.sort] : undefined,
+    };
+}
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function failed(error) {
+    return { content: [{ type: "text", text: formatErrorForMcp(error) }], isError: true };
+}
+const refPolicy = z
+    .string()
+    .optional()
+    .describe("track:<branch-or-tag> to follow it, pin:<sha> to freeze (default track:main)");
+/** Register plugin install/sync/detach tools (#640). Writes need an admin key. */
+export function register(server, client) {
+    server.tool("2kw_list_plugins", "List Claude Code plugins installed in the org, with optional status filter and pagination.", {
+        status: z.enum(["ACTIVE", "DISABLED"]).optional(),
+        page: z.number().int().min(0).optional(),
+        size: z.number().int().min(1).max(100).optional(),
+        sort: z.string().optional().describe("Sort field and direction"),
+    }, async (params) => {
+        try {
+            const { data } = await client.GET("/v1/plugins", {
+                params: { query: { status: params.status, ...paginationParams(params) } },
+            });
+            return ok(data);
+        }
+        catch (error) {
+            return failed(error);
+        }
+    });
+    server.tool("2kw_get_plugin", "Get an installed plugin by ID, including its last sync report.", { pluginId: z.string() }, async (params) => {
+        try {
+            const { data } = await client.GET("/v1/plugins/{id}", { params: { path: { id: params.pluginId } } });
+            return ok(data);
+        }
+        catch (error) {
+            return failed(error);
+        }
+    });
+    server.tool("2kw_install_plugin", "Install a plugin from a git repository (https, allow-listed host) and run its first sync: skills are imported with provenance and the sync report is returned.", {
+        gitUrl: z.string().url().describe("https remote of a repository in Claude Code plugin layout"),
+        name: z.string().optional().describe("Org-local name; default is the manifest name, slugified"),
+        refPolicy,
+    }, async (params) => {
+        try {
+            const { data } = await client.POST("/v1/plugins", {
+                body: { gitUrl: params.gitUrl, name: params.name, refPolicy: params.refPolicy },
+            });
+            return ok(data);
+        }
+        catch (error) {
+            return failed(error);
+        }
+    });
+    server.tool("2kw_update_plugin", "Change how an installed plugin follows its repository, or pause it.", {
+        pluginId: z.string(),
+        refPolicy,
+        status: z.enum(["ACTIVE", "DISABLED"]).optional(),
+    }, async (params) => {
+        try {
+            const { data } = await client.PATCH("/v1/plugins/{id}", {
+                params: { path: { id: params.pluginId } },
+                body: { refPolicy: params.refPolicy, status: params.status },
+            });
+            return ok(data);
+        }
+        catch (error) {
+            return failed(error);
+        }
+    });
+    server.tool("2kw_sync_plugin", "Sync an installed plugin now: resolves the ref, imports changed skills and moves the plugin label. Unchanged is a no-op.", { pluginId: z.string() }, async (params) => {
+        try {
+            const { data } = await client.POST("/v1/plugins/{id}/sync", { params: { path: { id: params.pluginId } } });
+            return ok(data);
+        }
+        catch (error) {
+            return failed(error);
+        }
+    });
+    server.tool("2kw_delete_plugin", "Detach an installed plugin. Imported skills remain as ordinary skills and stop receiving updates.", { pluginId: z.string() }, async (params) => {
+        try {
+            await client.DELETE("/v1/plugins/{id}", { params: { path: { id: params.pluginId } } });
+            return ok({ detached: params.pluginId });
+        }
+        catch (error) {
+            return failed(error);
+        }
+    });
+}
+//# sourceMappingURL=plugins.js.map

package/dist/tools/scores.js

@@ -1,12 +1,30 @@
 import { z } from "zod";
 import { formatErrorForMcp } from "../errors.js";
+const SUBJECT_TYPE = z.enum(["RUN_RESULT", "TRACE", "SPAN", "DATASET_ITEM"]);
 export function register(server, client) {
-    server.tool("2kw_record_human_score", "Record a human score for an experiment run result. Upserts by (runResultId, evaluatorId, annotatorId) — a reviewer calling this again replaces their own score, not anyone else's. Score must be between 0.0 and 1.0.", {
-        runResultId: z.string().describe("Run result id"),
+    server.tool("2kw_record_human_score", "Record a human score for a subject — a run result, trace, span, or dataset item. Upserts " +
+        "by (subject, evaluatorId, annotatorId), so a reviewer calling this again replaces their " +
+        "own score, not anyone else's. Pass either runResultId (legacy shape) or subjectType + " +
+        "subjectId; when reviewing an annotation queue item, also pass annotationQueueItemId so " +
+        "the server validates the subject matches and can advance the item's status. Score, when " +
+        "given, must be between 0.0 and 1.0 — it may be omitted for an open-coding annotation that " +
+        "carries only a label or comment.", {
+        runResultId: z.string().optional().describe("Run result id (legacy shape)"),
+        subjectType: SUBJECT_TYPE.optional().describe("The subject's type — RUN_RESULT, TRACE, SPAN, or DATASET_ITEM"),
+        subjectId: z.string().optional().describe("The subject's id"),
+        annotationQueueItemId: z
+            .string()
+            .optional()
+            .describe("The annotation queue item this score resolves, if reviewing from a queue"),
         evaluatorId: z
             .string()
             .describe("Evaluator identifier (e.g. 'helpfulness' or a template id)"),
-        score: z.number().min(0).max(1).describe("Score between 0.0 and 1.0"),
+        score: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe("Score between 0.0 and 1.0 (optional for open-coding annotations)"),
         label: z
             .string()
             .optional()
@@ -17,6 +35,9 @@ export function register(server, client) {
             const { data } = await client.POST("/v1/evaluation-scores/human", {
                 body: {
                     runResultId: params.runResultId,
+                    subjectType: params.subjectType,
+                    subjectId: params.subjectId,
+                    annotationQueueItemId: params.annotationQueueItemId,
                     evaluatorId: params.evaluatorId,
                     score: params.score,
                     label: params.label,
@@ -39,5 +60,34 @@ export function register(server, client) {
             };
         }
     });
+    // ── list_human_scores ────────────────────────────────────────────────────
+    server.tool("2kw_list_human_scores", "List human scores filed against a subject. Defaults to the caller's own scores — pass " +
+        "annotatorId to see another reviewer's (or 'me' explicitly).", {
+        subjectType: SUBJECT_TYPE.describe("The subject's type"),
+        subjectId: z.string().describe("The subject's id"),
+        annotatorId: z.string().optional().describe("Annotator id (defaults to the caller)"),
+    }, async ({ subjectType, subjectId, annotatorId }) => {
+        try {
+            const { data } = await client.GET("/v1/evaluation-scores/human", {
+                params: { query: { subjectType, subjectId, annotatorId } },
+            });
+            const scores = (data ?? []);
+            const lines = scores.map((s) => `- ${s.evaluatorId}: score=${s.score ?? "—"} label=${s.label ?? "—"} annotator=${s.annotatorId}${s.comment ? ` — ${s.comment}` : ""}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Human scores for ${subjectType} ${subjectId} (${scores.length}):\n${lines.join("\n") || "(none)"}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
 }
 //# sourceMappingURL=scores.js.map

package/dist/tools/skills.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClient } from "../client.js";
+/** Register skill read and import tools (#642). */
+export declare function register(server: McpServer, client: ApiClient): void;
+//# sourceMappingURL=skills.d.ts.map