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

package/dist/index.js

@@ -18,6 +18,8 @@ import * as datasets from "./tools/datasets.js";
 import * as experiments from "./tools/experiments.js";
 import * as evaluators from "./tools/evaluators.js";
 import * as prompts from "./tools/prompts.js";
+import * as skills from "./tools/skills.js";
+import * as plugins from "./tools/plugins.js";
 import * as providers from "./tools/providers.js";
 import * as billing from "./tools/billing.js";
 import * as scores from "./tools/scores.js";
@@ -83,6 +85,8 @@ async function main() {
     experiments.register(server, client);
     evaluators.register(server, client);
     prompts.register(server, client);
+    skills.register(server, client);
+    plugins.register(server, client);
     providers.register(server, client);
     billing.register(server, client);
     scores.register(server, client);

package/dist/tools/conversations.js

@@ -27,6 +27,27 @@ export function register(server, client) {
         }
     });
     // ── get_conversation ─────────────────────────────────────────────────────
+    server.tool("2kw_list_conversations", "List conversations, most recently active first. scope 'mine' (default) lists the caller's own; 'org' lists the whole organisation and needs MEMBER or above.", {
+        agentId: z.string().optional().describe("Only conversations bound to this agent"),
+        scope: z.enum(["mine", "org"]).optional().describe("mine (default) or org"),
+        page: z.number().int().min(0).optional().describe("Page number, starting at 0"),
+        size: z.number().int().min(1).max(100).optional().describe("Page size, 1 to 100 (default 30)"),
+    }, async ({ agentId, scope, page, size }) => {
+        try {
+            const { data } = await client.GET("/v1/conversations", {
+                params: { query: { agent_id: agentId, scope, page, size } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
     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}", {

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/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

package/dist/tools/skills.js

@@ -0,0 +1,177 @@
+import { z } from "zod";
+import { readFile, stat } from "node:fs/promises";
+import { basename, extname } from "node:path";
+import { BackboneApiError, 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,
+    };
+}
+/** Register skill read and import tools (#642). */
+export function register(server, client) {
+    server.tool("2kw_list_skills", "List org skills with optional name/status filter and pagination.", {
+        search: z.string().optional().describe("Filter by name"),
+        status: z.enum(["ACTIVE", "ARCHIVED"]).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/skills", {
+                params: {
+                    query: {
+                        search: params.search,
+                        status: params.status,
+                        ...paginationParams(params),
+                    },
+                },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("2kw_get_skill", "Get a skill by ID, including its latest version number.", { skillId: z.string() }, async (params) => {
+        try {
+            const { data } = await client.GET("/v1/skills/{id}", {
+                params: { path: { id: params.skillId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("2kw_list_skill_versions", "List versions of a skill with pagination.", {
+        skillId: z.string(),
+        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/skills/{id}/versions", {
+                params: {
+                    path: { id: params.skillId },
+                    query: paginationParams(params),
+                },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("2kw_get_skill_version", "Get a skill version, including description, body, frontmatter and resources.", {
+        skillId: z.string(),
+        versionNumber: z.number().int().min(1),
+    }, async (params) => {
+        try {
+            const { data } = await client.GET("/v1/skills/{id}/versions/{versionNumber}", {
+                params: { path: { id: params.skillId, versionNumber: params.versionNumber } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("2kw_list_skill_labels", "List skill labels and the versions they point to.", { skillId: z.string() }, async (params) => {
+        try {
+            const { data } = await client.GET("/v1/skills/{id}/labels", {
+                params: { path: { id: params.skillId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("2kw_resolve_skill", "Resolve a skill by name, name@label or name@version number.", { ref: z.string().min(1).describe("Skill reference: name, name@label or name@<n>") }, async (params) => {
+        try {
+            const { data } = await client.GET("/v1/skills/resolve", {
+                params: { query: { ref: params.ref } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("2kw_import_skill", "Import a local SKILL.md or .zip file. Returns outcome, version, renamedFrom and skipped files. Zip directories before importing.", { filePath: z.string().min(1).describe("Local path to SKILL.md or a .zip archive") }, async (params) => {
+        try {
+            const info = await stat(params.filePath);
+            if (info.isDirectory())
+                throw new Error("Cannot import a directory; zip it first.");
+            const filename = basename(params.filePath);
+            const isZip = extname(filename).toLowerCase() === ".zip";
+            if (filename !== "SKILL.md" && !isZip) {
+                throw new Error("Import requires a SKILL.md or .zip file.");
+            }
+            const buffer = await readFile(params.filePath);
+            const formData = new FormData();
+            formData.append("file", new Blob([buffer], {
+                type: isZip ? "application/zip" : "text/markdown",
+            }), filename);
+            const { baseUrl, apiKey } = client._config;
+            const res = await fetch(`${baseUrl.replace(/\/+$/, "")}/v1/skills/import`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${apiKey}` },
+                body: formData,
+            });
+            if (!res.ok) {
+                const body = await res.json().catch(() => ({}));
+                throw new BackboneApiError({
+                    status: body.status ?? res.status,
+                    error: body.title ?? body.error ?? res.statusText,
+                    message: body.detail ?? body.message ?? `HTTP ${res.status}: ${res.statusText}`,
+                    timestamp: body.timestamp ?? new Date().toISOString(),
+                });
+            }
+            const data = await res.json();
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=skills.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2kw/ai-mcp-server",
-  "version": "6.1.0",
+  "version": "6.2.0-dev.13",
   "description": "MCP server for 2kw.ai — EU-hosted AI platform: OpenAI-compatible LLM gateway, schema-driven document extraction, transcription, agents with a knowledge base, and cost observability. 158 tools for Claude Code, Cursor, and Windsurf.",
   "mcpName": "ai.2kw/mcp-server",
   "keywords": [
@@ -48,7 +48,7 @@
     "openapi-fetch": "^0.13.5"
   },
   "devDependencies": {
-    "@types/node": "^22.19.17",
+    "@types/node": "^22.20.1",
     "openapi-typescript": "^7.13.0",
     "tsx": "^4.21.1",
     "typescript": "^5.9.3"