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

package/LICENSE

@@ -0,0 +1,166 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.
+

package/README.md

@@ -1,3 +1,169 @@
-# Temporary Holding Version
+# @webda/mcp module
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This module is part of Webda Application Framework that allows you to quickly develop applications with all modern prerequisites: Security, Extensibility, GraphQL, REST, CloudNative [https://webda.io](https://webda.io)
+
+<img src="https://webda.io/images/webda.svg" width="128" />
+
+![CI](https://github.com/loopingz/webda.io/workflows/CI/badge.svg)
+
+[![Join the chat at https://gitter.im/loopingz/webda](https://badges.gitter.im/loopingz/webda.svg)](https://gitter.im/loopingz/webda?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![codecov](https://codecov.io/gh/loopingz/webda.io/branch/main/graph/badge.svg?token=8N9DNM3K3O)](https://codecov.io/gh/loopingz/webda.io)
+[![SonarCloud.io](https://sonarcloud.io/api/project_badges/measure?project=loopingz_webda.io&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=loopingz_webda.io)
+![CodeQL](https://github.com/loopingz/webda.io/workflows/CodeQL/badge.svg)
+
+<!-- README_HEADER -->
+
+# @webda/mcp
+
+> Model Context Protocol transport for Webda — exposes registered operations as MCP tools and models as MCP resources, over Streamable HTTP and stdio.
+
+## When to use it
+
+- You want AI assistants (Claude Code, Claude Desktop, any MCP client) to call your Webda operations as tools.
+- You want models readable as MCP resources through `webda://{Model}/{pk...}` URIs.
+- You want the same permissions as your REST API: each caller only sees and runs what their session allows.
+
+### What it exposes
+
+- **Tools**: every non-hidden operation, the tool name being the operation id (for example `Post.Get`, `Posts.Query`, `User.Login`).
+- **Resources**: models with a `{Model}.Get` operation, as `webda://{Model}/{pk...}` resource templates (for example `webda://Post/{slug}`).
+- **Progress**: `AsyncGenerator` operations stream their chunks as MCP progress notifications.
+- **Truncated outputs**: tool outputs larger than `maxOutputBytes` are truncated with a notice and returned with `isError: true`.
+
+## Install
+
+```bash
+pnpm add @webda/mcp
+```
+
+## Configuration
+
+```jsonc
+{
+  "services": {
+    "mcp": {
+      "type": "Webda/McpService",
+      "url": "/mcp", // HTTP endpoint; false disables HTTP (stdio only)
+      "operations": ["*", "!User.Delete"], // standard OperationsTransport filter
+      "resources": { "models": ["*"] }, // false disables resources; model ids or "*"
+      "sessionTimeout": 1800, // seconds of inactivity before an MCP session is evicted
+      "allowedOrigins": [], // extra Origin values accepted besides the request host
+      "allowedHosts": ["localhost", "127.0.0.1", "::1"], // Host header hostnames accepted (any port); "*" disables the check
+      "maxSessions": 1000, // cap on open MCP HTTP sessions; at the cap the least recently used one is closed
+      "maxOutputBytes": 1048576 // larger tool/resource outputs are truncated with a notice
+      // "serverName": "my-app", // defaults to the application package name
+      // "serverVersion": "1.0.0", // defaults to the application package version
+      // "stdio": { "user": "<userId>" }, // default --user for `webda mcp`
+      // "authenticator": "myAuthenticator" // service implementing McpAuthenticator; default uses the Webda session
+    }
+  }
+}
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `url` | string \| false | `"/mcp"` | HTTP endpoint; `false` disables HTTP (stdio only) |
+| `operations` | string[] | `["*"]` | Operation filter, with `!` for exclusions |
+| `resources` | `{ models: string[] }` \| false | `{ "models": ["*"] }` | Models exposed as resources; `false` disables resources |
+| `sessionTimeout` | number | `1800` | Seconds of inactivity before an MCP session is evicted |
+| `allowedOrigins` | string[] | `[]` | Extra `Origin` values accepted besides the request host |
+| `allowedHosts` | string[] | `["localhost", "127.0.0.1", "::1"]` | Hostnames accepted on the `Host` header (any port); `"*"` disables the check |
+| `maxSessions` | number | `1000` | Cap on open HTTP sessions; at the cap a new `initialize` closes the least recently used session, whose next request gets `404` (clients then re-initialize) |
+| `maxOutputBytes` | number | `1048576` | Larger tool/resource outputs are truncated with a notice |
+| `serverName` | string | application package name | Server name announced to clients |
+| `serverVersion` | string | application package version | Server version announced to clients |
+| `stdio.user` | string | none | Default `--user` for `webda mcp` |
+| `authenticator` | string | none | Name of a service implementing `McpAuthenticator`; the default uses the Webda session |
+
+> **Remote deployments must set `allowedHosts`.** The Host header is checked on every HTTP request as DNS-rebinding protection: unless your public hostname(s) are listed (or the value is `"*"`), every request gets `403 Host not allowed`.
+>
+> **Behind a reverse proxy**, the hostname checked is the `X-Forwarded-Host` header when present, otherwise `Host`. `X-Forwarded-*` headers are only accepted from proxies listed in the HttpServer `trustedProxies` parameter (anything else gets `400` from the HttpServer). A proxy that rewrites `Host` without a trusted `X-Forwarded-Host` gets `403` unless the rewritten hostname is in `allowedHosts`.
+
+## Usage
+
+```bash
+# stdio: Claude launches the application and acts as the given user
+claude mcp add blog -- webda mcp --user <userId>
+
+# HTTP: register the endpoint of a running application
+claude mcp add --transport http blog http://localhost:18080/mcp
+```
+
+Use `https://` when the HttpServer serves TLS. With `autoTls` (as in the [blog sample](../../sample-apps/blog-system/README.md#mcp)) the certificate is self-signed: start the MCP client with `NODE_EXTRA_CA_CERTS=<app>/.webda/dev-tls/cert.pem` so it trusts it.
+
+`webda mcp` keeps stdout for protocol frames: from the moment the command starts, log lines and any other stdout output go to stderr, whatever `--log-stream` says. Lines logged while the application boots (before the command starts) follow `--log-stream`; its default (`auto`) already sends them to stderr because MCP clients pipe stdout.
+
+### Who is the HTTP caller?
+
+The default `SessionAuthenticator` uses Webda's cookie session. MCP clients (Claude Code, the SDK HTTP transports) do not keep cookies, so **HTTP callers are anonymous in practice**: they see and run only the operations anonymous users may call. To act as a user, use stdio (`webda mcp --user <userId>`), or plug a custom authenticator service until OAuth support (planned) lands:
+
+```typescript
+import { Service, Session, WebContext, WebdaError } from "@webda/core";
+import type { McpAuthenticator } from "@webda/mcp";
+
+// Your own key lookup (a model query, a secret store...)
+declare function lookupUserForKey(key: string): Promise<string | undefined>;
+
+/**
+ * Resolve MCP callers from an API key header
+ */
+export class ApiKeyAuthenticator extends Service implements McpAuthenticator {
+  async authenticate(ctx: WebContext): Promise<Session> {
+    const key = ctx.getHttpContext().getUniqueHeader("x-api-key");
+    const session = new Session();
+    if (key === undefined) {
+      return session; // anonymous
+    }
+    const userId = await lookupUserForKey(key);
+    if (!userId) {
+      throw new WebdaError.Unauthorized("Invalid API key");
+    }
+    session.login(userId, userId);
+    return session;
+  }
+}
+```
+
+```jsonc
+{
+  "services": {
+    "apiKeys": { "type": "MyApp/ApiKeyAuthenticator" },
+    "mcp": { "type": "Webda/McpService", "authenticator": "apiKeys" }
+  }
+}
+```
+
+### Multiple instances
+
+MCP HTTP sessions live in the memory of the instance that created them. When running several instances behind a load balancer, route each client to the same instance (sticky sessions on the `Mcp-Session-Id` header or the client address); a request reaching another instance gets `404 Session not found`.
+
+Control how an operation appears to MCP clients:
+
+```typescript
+import { Operation, OperationContext, Service } from "@webda/core";
+
+export class PostService extends Service {
+  // Not exposed as a tool
+  @Operation({ mcp: false })
+  async internalCleanup() {}
+
+  // Exposed with a title and explicit hints
+  @Operation({ mcp: { title: "Delete a post", readOnly: false, destructive: true } })
+  async deletePost(ctx: OperationContext) {}
+}
+```
+
+## Security
+
+- Permissions apply per caller: an operation is run with the caller's session and `tools/list` is filtered to what that caller may call.
+- HTTP sessions are random ids bound to the user who created them; another user presenting the id is rejected with `403`.
+- Every HTTP request is checked against `allowedHosts` and `Origin` (request host plus `allowedOrigins`) to prevent DNS rebinding.
+- Open sessions are capped by `maxSessions`; at the cap the least recently used session is closed rather than refusing new ones, so nobody can lock the endpoint by opening sessions.
+- With the default authenticator, HTTP callers are anonymous in practice (see [Who is the HTTP caller?](#who-is-the-http-caller)).
+- `webda mcp` over stdio trusts whoever launches it: that process acts with the permissions of `--user` (or anonymous permissions without it).
+- OAuth 2.1 (authorization server and bearer validation) is planned as a second step and will plug in through the `authenticator` hook.
+
+## Reference
+
+- Source: [`packages/mcp`](https://github.com/loopingz/webda.io/tree/main/packages/mcp)
+- Design: `docs/superpowers/specs/2026-10-03-webda-mcp-design.md`

package/lib/auth.d.ts

@@ -0,0 +1,27 @@
+import type { Session, WebContext } from "@webda/core";
+/**
+ * Resolve the caller of an MCP HTTP request.
+ *
+ * Implementations throw `WebdaError.Unauthorized` to reject the request.
+ * Configure a service implementing it through the McpService `authenticator`
+ * parameter; spec 2 adds an OAuth bearer-token implementation.
+ */
+export interface McpAuthenticator {
+    /**
+     * @param ctx - the HTTP request context
+     * @returns the caller session
+     */
+    authenticate(ctx: WebContext): Promise<Session>;
+}
+/**
+ * Default authenticator: the Webda session already loaded for the request
+ * (cookie session, filled by RequestFilters); anonymous callers get an empty session.
+ */
+export declare class SessionAuthenticator implements McpAuthenticator {
+    /**
+     * @param ctx - the HTTP request context
+     * @returns the request session
+     */
+    authenticate(ctx: WebContext): Promise<Session>;
+}
+//# sourceMappingURL=auth.d.ts.map

package/lib/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjD;AAED;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,gBAAgB;IAC3D;;;OAGG;IACG,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAEpD;CACF"}

package/lib/auth.js

@@ -0,0 +1,14 @@
+/**
+ * Default authenticator: the Webda session already loaded for the request
+ * (cookie session, filled by RequestFilters); anonymous callers get an empty session.
+ */
+export class SessionAuthenticator {
+    /**
+     * @param ctx - the HTTP request context
+     * @returns the request session
+     */
+    async authenticate(ctx) {
+        return ctx.getSession();
+    }
+}
+//# sourceMappingURL=auth.js.map

package/lib/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAiBA;;;GAGG;AACH,MAAM,OAAO,oBAAoB;IAC/B;;;OAGG;IACH,KAAK,CAAC,YAAY,CAAC,GAAe;QAChC,OAAO,GAAG,CAAC,UAAU,EAAE,CAAC;IAC1B,CAAC;CACF"}

package/lib/bridge.d.ts

@@ -0,0 +1,26 @@
+import type { WebContext } from "@webda/core";
+/**
+ * Build a web-standard Request from a Webda context
+ * @param ctx - the request context
+ * @param body - raw request body (POST only)
+ * @param origin - request origin, when HttpContext.getAbsoluteUrl cannot represent it (IPv6 hosts)
+ * @returns the Request handed to the SDK transport
+ */
+export declare function toRequest(ctx: WebContext, body?: string, origin?: URL): Request;
+/**
+ * Write a web-standard Response into a Webda context, streaming the body
+ * chunk by chunk (SSE) and stopping when the client disconnects.
+ * The returned promise settles when the body is fully written.
+ * @param ctx - the request context
+ * @param response - the SDK transport response
+ */
+export declare function writeResponse(ctx: WebContext, response: Response): Promise<void>;
+/**
+ * Answer with a JSON-RPC error body
+ * @param ctx - the request context
+ * @param status - HTTP status
+ * @param code - JSON-RPC error code
+ * @param message - error message
+ */
+export declare function jsonRpcError(ctx: WebContext, status: number, code: number, message: string): void;
+//# sourceMappingURL=bridge.d.ts.map

package/lib/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,GAAG,OAAO,CAe/E;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBtF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAGjG"}

package/lib/bridge.js

@@ -0,0 +1,72 @@
+/**
+ * Build a web-standard Request from a Webda context
+ * @param ctx - the request context
+ * @param body - raw request body (POST only)
+ * @param origin - request origin, when HttpContext.getAbsoluteUrl cannot represent it (IPv6 hosts)
+ * @returns the Request handed to the SDK transport
+ */
+export function toRequest(ctx, body, origin) {
+    const http = ctx.getHttpContext();
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(http.getHeaders())) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            value.forEach(v => headers.append(name, v));
+        }
+        else {
+            headers.set(name, String(value));
+        }
+    }
+    const method = http.getMethod();
+    const uri = http.getUrl();
+    const url = origin && !/^\w{1,10}:\/\//.test(uri) ? `${origin.origin}${uri.startsWith("/") ? "" : "/"}${uri}` : http.getAbsoluteUrl();
+    return new Request(url, { method, headers, body: method === "POST" ? (body ?? "") : undefined });
+}
+/**
+ * Write a web-standard Response into a Webda context, streaming the body
+ * chunk by chunk (SSE) and stopping when the client disconnects.
+ * The returned promise settles when the body is fully written.
+ * @param ctx - the request context
+ * @param response - the SDK transport response
+ */
+export async function writeResponse(ctx, response) {
+    const headers = {};
+    response.headers.forEach((value, name) => (headers[name] = value));
+    ctx.writeHead(response.status, headers);
+    const out = await ctx.getOutputStream();
+    if (!response.body) {
+        return;
+    }
+    const reader = response.body.getReader();
+    const onClose = () => {
+        reader.cancel().catch(() => { });
+    };
+    out.once?.("close", onClose);
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            out.write(Buffer.from(value));
+        }
+    }
+    catch {
+        // client went away; nothing left to write
+    }
+    finally {
+        out.off?.("close", onClose);
+    }
+}
+/**
+ * Answer with a JSON-RPC error body
+ * @param ctx - the request context
+ * @param status - HTTP status
+ * @param code - JSON-RPC error code
+ * @param message - error message
+ */
+export function jsonRpcError(ctx, status, code, message) {
+    ctx.writeHead(status, { "content-type": "application/json" });
+    ctx.write(JSON.stringify({ jsonrpc: "2.0", error: { code, message }, id: null }));
+}
+//# sourceMappingURL=bridge.js.map

package/lib/bridge.js.map

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

package/lib/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./schema.js";
+export * from "./tools.js";
+export * from "./invoke.js";
+export * from "./resources.js";
+export * from "./auth.js";
+export * from "./server.js";
+export * from "./sessions.js";
+export * from "./bridge.js";
+export * from "./mcpservice.service.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC"}

package/lib/index.js

@@ -0,0 +1,10 @@
+export * from "./schema.js";
+export * from "./tools.js";
+export * from "./invoke.js";
+export * from "./resources.js";
+export * from "./auth.js";
+export * from "./server.js";
+export * from "./sessions.js";
+export * from "./bridge.js";
+export * from "./mcpservice.service.js";
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC"}

package/lib/invoke.d.ts

@@ -0,0 +1,108 @@
+import { Session, SimpleOperationContext } from "@webda/core";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { ToolEntry } from "./tools.js";
+/**
+ * Raised when an MCP client cancels a running operation
+ */
+export declare class CancelledError extends Error {
+    /**
+     * Build the cancellation error
+     */
+    constructor();
+}
+/**
+ * Operation context used for MCP calls: collects AsyncGenerator chunks
+ * instead of concatenating them into the output, and stops on cancellation.
+ */
+export declare class McpOperationContext extends SimpleOperationContext {
+    /**
+     * Chunks yielded by a streaming operation
+     */
+    chunks: unknown[];
+    /**
+     * Abort signal of the MCP request
+     */
+    signal?: AbortSignal;
+    /**
+     * Called for every streamed chunk with its 1-based index
+     */
+    onChunk?: (chunk: unknown, index: number) => void;
+    /**
+     * @param output - chunk or result
+     * @param encoding - unused for chunks
+     * @param cb - unused for chunks
+     * @returns true
+     */
+    write(output: any, encoding?: any, cb?: any): boolean;
+}
+/**
+ * Options to run an operation for MCP
+ */
+export interface RunOptions {
+    /**
+     * Session of the caller; permissions are evaluated against it
+     */
+    session: Session;
+    /**
+     * Operation input (tool arguments)
+     */
+    input?: unknown;
+    /**
+     * Abort signal of the MCP request
+     */
+    signal?: AbortSignal;
+    /**
+     * Streaming chunk callback
+     */
+    onChunk?: (chunk: unknown, index: number) => void;
+}
+/**
+ * Build a context holding a session, for permission checks
+ * @param session - caller session
+ * @returns a context with that session
+ */
+export declare function sessionContext(session: Session): SimpleOperationContext;
+/**
+ * Run an operation as the caller through core `callOperation`
+ * (permission, validation, events, audit and dispatch all apply)
+ * @param operationId - operation id
+ * @param options - session, input, cancellation and streaming hooks
+ * @returns the parsed result, or the chunks when the operation streamed
+ */
+export declare function runOperation(operationId: string, options: RunOptions): Promise<{
+    value: unknown;
+    streamed: boolean;
+}>;
+/**
+ * Truncate a string to at most `maxBytes` UTF-8 bytes without cutting a character
+ * @param text - the text
+ * @param maxBytes - maximum number of bytes kept
+ * @returns the (possibly) truncated text, whether it was truncated and the original byte length
+ */
+export declare function truncateUtf8(text: string, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+    bytes: number;
+};
+/**
+ * Convert an operation result into an MCP tool result.
+ *
+ * Tools declare no outputSchema (serialized models rarely match their schema exactly),
+ * so structuredContent is informative only: the object itself, `{ value }` for scalars
+ * and arrays, `{ items }` for streamed chunks, and nothing for void.
+ * @param _entry - the tool
+ * @param value - operation result
+ * @param streamed - whether value is the list of streamed chunks
+ * @param maxOutputBytes - truncation threshold for the text content
+ * @returns the tool result
+ */
+export declare function toToolResult(_entry: ToolEntry, value: unknown, streamed: boolean, maxOutputBytes: number): CallToolResult;
+/**
+ * Convert an error into an MCP tool error result.
+ * Client errors (4xx) are returned so the agent can correct its input;
+ * anything else is logged and masked.
+ * @param err - the error
+ * @returns the tool error result
+ */
+export declare function errorToToolResult(err: unknown): CallToolResult;
+//# sourceMappingURL=invoke.d.ts.map

package/lib/invoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../src/invoke.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,OAAO,EAAE,sBAAsB,EAAc,MAAM,aAAa,CAAC;AACzF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC;;OAEG;IACH,cAGC;CACF;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,sBAAsB;IAC7D;;OAEG;IACH,MAAM,EAAE,OAAO,EAAE,CAAM;IACvB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAElD;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,GAAG,GAAG,OAAO,CAepD;CACF;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,sBAAsB,CAIvE;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAuB3H;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAWhH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,cAAc,CA0BzH;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAY9D"}