@webda/mcp 0.0.0-stage → 4.0.0-beta.4

package/lib/tools.d.ts

@@ -0,0 +1,62 @@
+import type { OperationDefinition } from "@webda/core";
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { SchemaResolver } from "./schema.js";
+/**
+ * A tool exposed over MCP and the operation backing it
+ */
+export interface ToolEntry {
+    /**
+     * MCP tool definition
+     */
+    tool: Tool;
+    /**
+     * Webda operation id
+     */
+    operationId: string;
+    /**
+     * True when the operation input is not an object and is wrapped as `{ value }`
+     */
+    wrapped: boolean;
+}
+/**
+ * Map a Webda operation to an MCP tool
+ * @param id - operation id, used as the tool name
+ * @param op - operation definition
+ * @param resolve - schema resolver
+ * @returns the tool entry, or undefined when the operation must not be exposed
+ */
+export declare function operationToTool(id: string, op: OperationDefinition, resolve: SchemaResolver): ToolEntry | undefined;
+/**
+ * Fingerprint of the registered operation ids, to detect runtime registrations
+ * @param ops - operations map
+ * @returns a stable string for the set of ids
+ */
+export declare function operationsFingerprint(ops: Record<string, OperationDefinition>): string;
+/**
+ * Registry of MCP tools built from operations
+ */
+export declare class ToolRegistry {
+    protected resolve: SchemaResolver;
+    protected entries: Map<string, ToolEntry>;
+    /**
+     * @param resolve - schema resolver used to build input/output schemas
+     */
+    constructor(resolve: SchemaResolver);
+    /**
+     * Rebuild the registry from operations
+     * @param ops - visible operations of the transport
+     */
+    build(ops: Record<string, OperationDefinition>): void;
+    /**
+     * All tool entries, sorted by name
+     * @returns tool entries
+     */
+    list(): ToolEntry[];
+    /**
+     * Find a tool by name
+     * @param name - tool name
+     * @returns the entry or undefined
+     */
+    get(name: string): ToolEntry | undefined;
+}
+//# sourceMappingURL=tools.d.ts.map

package/lib/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,EAA4B,cAAc,EAAE,MAAM,aAAa,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB;;OAEG;IACH,IAAI,EAAE,IAAI,CAAC;IACX;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAiCD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,mBAAmB,EAAE,OAAO,EAAE,cAAc,GAAG,SAAS,GAAG,SAAS,CAoCnH;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAAG,MAAM,CAEtF;AAED;;GAEG;AACH,qBAAa,YAAY;IAMX,SAAS,CAAC,OAAO,EAAE,cAAc;IAL7C,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAa;IAEtD;;OAEG;IACH,YAAsB,OAAO,EAAE,cAAc,EAAI;IAEjD;;;OAGG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAAG,IAAI,CAQpD;IAED;;;OAGG;IACH,IAAI,IAAI,SAAS,EAAE,CAElB;IAED;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAEvC;CACF"}

package/lib/tools.js

@@ -0,0 +1,126 @@
+import { inlineSchema } from "./schema.js";
+/**
+ * Resolve an operation schema reference ("void", "Name" or optional "Name?")
+ * @param ref - the operation input/output reference
+ * @param resolve - schema resolver
+ * @returns the inlined schema, or undefined for "void"/unknown
+ */
+function resolveRef(ref, resolve) {
+    if (!ref || ref === "void") {
+        return undefined;
+    }
+    const optional = ref.endsWith("?");
+    const raw = resolve(optional ? ref.slice(0, -1) : ref);
+    if (!raw) {
+        return undefined;
+    }
+    const schema = inlineSchema(raw, resolve);
+    if (optional) {
+        delete schema.required;
+    }
+    return schema;
+}
+/**
+ * Whether a schema describes a JSON object
+ * @param schema - the schema
+ * @returns true for object schemas
+ */
+function isObjectSchema(schema) {
+    return !!schema && (schema.type === "object" || (schema.type === undefined && schema.properties !== undefined));
+}
+/**
+ * Map a Webda operation to an MCP tool
+ * @param id - operation id, used as the tool name
+ * @param op - operation definition
+ * @param resolve - schema resolver
+ * @returns the tool entry, or undefined when the operation must not be exposed
+ */
+export function operationToTool(id, op, resolve) {
+    if (op.hidden || op.mcp === false) {
+        return undefined;
+    }
+    const hints = op.mcp || {};
+    const input = op.input === undefined || op.input === "void" ? undefined : resolveRef(op.input, resolve);
+    let inputSchema;
+    let wrapped = false;
+    if (op.input === undefined || op.input === "void") {
+        inputSchema = { type: "object", properties: {} };
+    }
+    else if (!input) {
+        inputSchema = { type: "object" };
+    }
+    else if (isObjectSchema(input)) {
+        inputSchema = { ...input, type: "object" };
+    }
+    else {
+        inputSchema = { type: "object", properties: { value: input } };
+        if (!op.input.endsWith("?")) {
+            inputSchema.required = ["value"];
+        }
+        wrapped = true;
+    }
+    const description = [op.summary, op.description].filter(Boolean).join("\n\n") || `Call operation ${id}`;
+    const tool = {
+        name: id,
+        description: op.deprecated ? `${description} (deprecated)` : description,
+        inputSchema: inputSchema,
+        annotations: {
+            readOnlyHint: hints.readOnly ?? (op.rest !== false && op.rest?.method === "get" ? true : /\.(Get|Query)$/.test(id)),
+            destructiveHint: hints.destructive ?? (op.rest !== false && op.rest?.method === "delete" ? true : id.endsWith(".Delete"))
+        }
+    };
+    if (hints.title) {
+        tool.title = hints.title;
+    }
+    return { tool, operationId: id, wrapped };
+}
+/**
+ * Fingerprint of the registered operation ids, to detect runtime registrations
+ * @param ops - operations map
+ * @returns a stable string for the set of ids
+ */
+export function operationsFingerprint(ops) {
+    return Object.keys(ops).sort().join("|");
+}
+/**
+ * Registry of MCP tools built from operations
+ */
+export class ToolRegistry {
+    resolve;
+    entries = new Map();
+    /**
+     * @param resolve - schema resolver used to build input/output schemas
+     */
+    constructor(resolve) {
+        this.resolve = resolve;
+    }
+    /**
+     * Rebuild the registry from operations
+     * @param ops - visible operations of the transport
+     */
+    build(ops) {
+        this.entries.clear();
+        for (const [id, op] of Object.entries(ops)) {
+            const entry = operationToTool(id, op, this.resolve);
+            if (entry) {
+                this.entries.set(id, entry);
+            }
+        }
+    }
+    /**
+     * All tool entries, sorted by name
+     * @returns tool entries
+     */
+    list() {
+        return [...this.entries.values()].sort((a, b) => a.tool.name.localeCompare(b.tool.name));
+    }
+    /**
+     * Find a tool by name
+     * @param name - tool name
+     * @returns the entry or undefined
+     */
+    get(name) {
+        return this.entries.get(name);
+    }
+}
+//# sourceMappingURL=tools.js.map

package/lib/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@webda/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "4.0.0-beta.4",
+  "description": "MCP transport for Webda.io — exposes operations as Model Context Protocol tools and resources",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.0",
+    "@webda/workout": "4.0.0-beta.3"
+  },
+  "peerDependencies": {
+    "@webda/core": "^4.0.0-beta.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.2",
+    "typescript": "7.1.0-dev.20260929.1",
+    "vite": "^6.0.0",
+    "vitest": "^4.0.0",
+    "@webda/compiler": "^4.0.0-beta.4",
+    "@webda/core": "^4.0.0-beta.4",
+    "@webda/test": "^4.0.0-beta.3",
+    "@webda/utils": "^4.0.0-beta.4"
+  },
+  "files": [
+    "lib",
+    "webda.module.json"
+  ],
+  "webda": {
+    "namespace": "Webda",
+    "capabilities": {
+      "mcp": "Webda/McpService"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "LGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/loopingz/webda.io.git",
+    "directory": "packages/mcp"
+  },
+  "scripts": {
+    "build": "webdac build",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "lint:fix": "eslint --fix src/"
+  }
 }

package/webda.module.json

@@ -0,0 +1,211 @@
+{
+  "$schema": "https://webda.io/schemas/webda.module.v4.json",
+  "beans": {},
+  "deployers": {},
+  "moddas": {
+    "Webda/McpService": {
+      "Import": "lib/mcpservice.service:McpService",
+      "Schema": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "additionalProperties": false,
+        "definitions": {
+          "resources#2": {
+            "additionalProperties": false,
+            "properties": {
+              "models": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              }
+            },
+            "type": "object"
+          },
+          "stdio": {
+            "additionalProperties": false,
+            "description": "stdio defaults",
+            "properties": {
+              "user": {
+                "description": "Default user for `webda mcp`",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        },
+        "description": "Parameters for the MCP transport",
+        "properties": {
+          "allowedHosts": {
+            "default": [
+              "localhost",
+              "127.0.0.1",
+              "::1"
+            ],
+            "description": "Hostnames (any port) accepted in the request Host, against DNS rebinding;\n\"*\" disables the check",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "allowedOrigins": {
+            "default": [],
+            "description": "Extra Origin values accepted besides the request's own origin",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "authenticator": {
+            "description": "Name of a service implementing McpAuthenticator; default uses the Webda session",
+            "type": "string"
+          },
+          "maxOutputBytes": {
+            "default": 1048576,
+            "description": "Larger tool/resource outputs are truncated",
+            "type": "number"
+          },
+          "maxSessions": {
+            "default": 1000,
+            "description": "Maximum number of concurrent MCP HTTP sessions; at the limit the least\nrecently used session is closed to make room for a new one",
+            "type": "number"
+          },
+          "operations": {
+            "default": [
+              "*"
+            ],
+            "description": "List of operations to include/exclude\nSupports wildcards and negation: [\"*\", \"!User.Delete\"]",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "resources": {
+            "anyOf": [
+              {
+                "const": false,
+                "type": "boolean"
+              },
+              {
+                "$ref": "#/definitions/resources%232"
+              }
+            ],
+            "default": {
+              "models": [
+                "*"
+              ]
+            },
+            "description": "Models exposed as resources (short ids or \"*\"); false disables resources"
+          },
+          "serverName": {
+            "description": "Server name announced to clients (defaults to the application package name)",
+            "type": "string"
+          },
+          "serverVersion": {
+            "description": "Server version announced to clients (defaults to the application package version)",
+            "type": "string"
+          },
+          "sessionTimeout": {
+            "default": 1800,
+            "description": "Seconds of inactivity before an MCP session is evicted",
+            "type": "number"
+          },
+          "stdio": {
+            "$ref": "#/definitions/stdio",
+            "description": "stdio defaults"
+          },
+          "type": {
+            "description": "Type of the service",
+            "type": "string"
+          },
+          "url": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "const": false,
+                "type": "boolean"
+              }
+            ],
+            "default": "/mcp",
+            "description": "HTTP endpoint; false disables HTTP (stdio only)"
+          },
+          "openapi": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        },
+        "required": [
+          "type"
+        ],
+        "type": "object",
+        "title": "McpService"
+      },
+      "Configuration": "lib/mcpservice.service:McpServiceParameters",
+      "commands": {
+        "mcp": {
+          "description": "Serve operations as MCP tools over stdio",
+          "method": "mcp",
+          "args": {
+            "user": {
+              "type": "string",
+              "default": ""
+            }
+          },
+          "requires": [
+            "mcp"
+          ]
+        }
+      }
+    }
+  },
+  "models": {},
+  "schemas": {
+    "Webda/BinaryFile": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "WebdaSchema": true,
+      "additionalProperties": false,
+      "description": "Represent a file to store",
+      "properties": {
+        "challenge": {
+          "description": "Will be computed by the service\n\nhash of the content prefixed by 'WEBDA'",
+          "type": "string"
+        },
+        "hash": {
+          "description": "Will be computed by the service\n\nhash of the content",
+          "type": "string"
+        },
+        "metadata": {
+          "description": "Metadatas stored along with the binary"
+        },
+        "mimetype": {
+          "description": "Mimetype of the binary",
+          "type": "string"
+        },
+        "name": {
+          "description": "Current name",
+          "type": "string"
+        },
+        "originalname": {
+          "description": "Original name",
+          "type": "string"
+        },
+        "size": {
+          "description": "Size of the binary",
+          "type": "number"
+        }
+      },
+      "required": [
+        "mimetype",
+        "name",
+        "size"
+      ],
+      "type": "object",
+      "title": "BinaryFile"
+    }
+  },
+  "behaviors": {},
+  "capabilities": {
+    "mcp": "Webda/McpService"
+  }
+}