mcp-gtw-provider 0.0.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paulo Coutinho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+<p align="center">
+    <img src="extras/images/logo-icon.png" width="150" alt="mcp-gtw-provider" />
+</p>
+
+<h1 align="center">mcp-gtw-provider</h1>
+
+<p align="center">
+    The framework-agnostic JavaScript client for mcp-gateway — a small, dependency-free ES module that
+    publishes and runs your MCP tools, resources, prompts and more from any web app over WebSocket.
+</p>
+
+<p align="center">
+    <a href="https://github.com/mcp-gtw/mcp-gtw-provider/actions/workflows/ci.yml"><img src="https://github.com/mcp-gtw/mcp-gtw-provider/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+    <a href="https://www.npmjs.com/package/mcp-gtw-provider"><img src="https://img.shields.io/npm/v/mcp-gtw-provider.svg" alt="npm"></a>
+    <a href="LICENSE.md"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
+</p>
+
+---
+
+There is no dependency on React, Vue, or any DOM framework — it uses only standard web platform APIs
+(`WebSocket`, `AbortController`, timers). Import it into a plain HTML page, or wire it into React,
+Vue, Svelte, or anything else.
+
+## 🔌 How it fits
+
+An MCP client talks to the gateway over Streamable HTTP. The gateway never knows the capabilities in
+advance — this provider connects from your app, registers them, and executes their handlers:
+
+```text
+MCP client  ⇄  mcp-gateway (/mcp)  ⇄  gateway (/provider)  ⇄  McpGtwProvider (your app)
+```
+
+## 📦 Install
+
+```bash
+npm install mcp-gtw-provider
+```
+
+No build step is required — it ships as ES modules. You can also import the file directly in a page.
+
+## 🚀 Quick start
+
+```javascript
+import { McpGtwProvider } from "mcp-gtw-provider";
+
+const provider = new McpGtwProvider({
+    url: "wss://your-gateway.example.com/provider?token=...",
+    onStatusChange: (status) => console.log("gateway:", status),
+});
+
+provider.registerTool(
+    {
+        name: "add",
+        description: "Add two numbers",
+        inputSchema: {
+            type: "object",
+            properties: { a: { type: "number" }, b: { type: "number" } },
+            required: ["a", "b"],
+            additionalProperties: false,
+        },
+    },
+    async ({ a, b }) => a + b,
+);
+
+await provider.connect();
+```
+
+The handler's return value is wrapped into an MCP result automatically: a string becomes text, an
+object becomes text plus `structuredContent`, and returning a full `{ content: [...] }` object gives
+you exact control. Throwing turns into an error result.
+
+## 📚 Documentation
+
+| Guide | What it covers |
+| --- | --- |
+| [Usage](docs/usage.md) | Every constructor option, tools, resources, prompts, completion, logging, progress, sampling, elicitation, lifecycle. |
+| [Protocol](docs/protocol.md) | The private WebSocket frames this module speaks. |
+| [Frameworks](docs/frameworks.md) | Using it from vanilla JS, React, and Vue. |
+
+## ✅ Requirements
+
+- A browser, or any runtime with `WebSocket`, `AbortController`, and timers.
+- Node 20+ only to develop this package — tested on 20, 22 and 24 in CI.
+- A running [`mcp-gateway`](https://github.com/mcp-gtw/mcp-gateway) to connect to.
+
+## 💜 Support
+
+If this project saved you time, consider supporting it:
+[GitHub Sponsors](https://github.com/sponsors/paulocoutinhox) · [Ko-fi](https://ko-fi.com/paulocoutinho).
+
+Made with care by [Paulo Coutinho](https://github.com/paulocoutinhox).
+
+Licensed under [MIT](LICENSE.md).

package/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "mcp-gtw-provider",
+    "version": "0.0.1",
+    "description": "Framework-agnostic browser provider for the mcp-gateway: publish and run your MCP tools from any web app over WebSocket.",
+    "type": "module",
+    "license": "MIT",
+    "keywords": [
+        "mcp",
+        "model-context-protocol",
+        "gateway",
+        "websocket",
+        "browser",
+        "tools",
+        "provider"
+    ],
+    "homepage": "https://github.com/mcp-gtw/mcp-gtw-provider",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/mcp-gtw/mcp-gtw-provider.git"
+    },
+    "bugs": {
+        "url": "https://github.com/mcp-gtw/mcp-gtw-provider/issues"
+    },
+    "sideEffects": false,
+    "exports": {
+        ".": {
+            "types": "./types/index.d.ts",
+            "default": "./src/index.js"
+        }
+    },
+    "main": "./src/index.js",
+    "module": "./src/index.js",
+    "types": "./types/index.d.ts",
+    "files": [
+        "src",
+        "types",
+        "README.md",
+        "LICENSE.md"
+    ],
+    "scripts": {
+        "lint": "biome check .",
+        "format": "biome check --write .",
+        "test": "vitest run",
+        "coverage": "vitest run --coverage"
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^2.3.0",
+        "@vitest/coverage-v8": "^3.2.0",
+        "vitest": "^3.2.0"
+    }
+}

package/src/index.js

@@ -0,0 +1,507 @@
+const EMPTY_INPUT_SCHEMA = { type: "object", properties: {}, additionalProperties: false };
+
+export class McpGtwProvider {
+    constructor({
+        url,
+        reconnect = true,
+        reconnectMinDelayMs = 500,
+        reconnectMaxDelayMs = 10_000,
+        heartbeatIntervalMs = 20_000,
+        onStatusChange = null,
+    }) {
+        if (!url) {
+            throw new Error("A WebSocket URL is required");
+        }
+
+        this.url = url;
+        this.reconnect = reconnect;
+        this.reconnectMinDelayMs = reconnectMinDelayMs;
+        this.reconnectMaxDelayMs = reconnectMaxDelayMs;
+        this.heartbeatIntervalMs = heartbeatIntervalMs;
+        this.onStatusChange = onStatusChange;
+
+        this.socket = null;
+        this.tools = new Map();
+        this.resources = new Map();
+        this.resourceTemplates = new Map();
+        this.prompts = new Map();
+        this.onComplete = null;
+        this.onSubscribe = null;
+        this.onUnsubscribe = null;
+
+        this.runningCalls = new Map();
+        this.outgoingCalls = new Map();
+        this.outgoingId = 0;
+        this.reconnectAttempt = 0;
+        this.reconnectTimer = null;
+        this.heartbeatTimer = null;
+        this.connectPromise = null;
+    }
+
+    get connected() {
+        return this.socket?.readyState === WebSocket.OPEN;
+    }
+
+    registerTool(definition, handler) {
+        return this.#register(this.tools, "tools", definition, "name", handler, {
+            title: definition.title,
+            description: definition.description ?? "",
+            inputSchema: definition.inputSchema ?? EMPTY_INPUT_SCHEMA,
+            ...(definition.outputSchema ? { outputSchema: definition.outputSchema } : {}),
+            ...(definition.annotations ? { annotations: definition.annotations } : {}),
+        });
+    }
+
+    registerResource(definition, reader) {
+        return this.#register(this.resources, "resources", definition, "uri", reader, {
+            name: definition.name,
+            ...(definition.title ? { title: definition.title } : {}),
+            ...(definition.description ? { description: definition.description } : {}),
+            ...(definition.mimeType ? { mimeType: definition.mimeType } : {}),
+        });
+    }
+
+    registerResourceTemplate(definition) {
+        return this.#register(
+            this.resourceTemplates,
+            "resourceTemplates",
+            definition,
+            "uriTemplate",
+            null,
+            {
+                name: definition.name,
+                ...(definition.title ? { title: definition.title } : {}),
+                ...(definition.description ? { description: definition.description } : {}),
+                ...(definition.mimeType ? { mimeType: definition.mimeType } : {}),
+            },
+        );
+    }
+
+    registerPrompt(definition, handler) {
+        return this.#register(this.prompts, "prompts", definition, "name", handler, {
+            ...(definition.title ? { title: definition.title } : {}),
+            ...(definition.description ? { description: definition.description } : {}),
+            ...(definition.arguments ? { arguments: definition.arguments } : {}),
+        });
+    }
+
+    #register(registry, kind, definition, key, handler, extra) {
+        const identifier = definition[key];
+
+        if (!identifier || typeof identifier !== "string") {
+            throw new Error(`A ${kind} entry needs a string ${key}`);
+        }
+
+        registry.set(identifier, { definition: { [key]: identifier, ...extra }, handler });
+        this.#publish(kind);
+
+        return () => {
+            registry.delete(identifier);
+            this.#publish(kind);
+        };
+    }
+
+    async requestSampling(params) {
+        return this.#callClient("sampling/createMessage", params);
+    }
+
+    async requestElicit(message, requestedSchema) {
+        return this.#callClient("elicitation/create", { message, requestedSchema });
+    }
+
+    notifyResourceUpdated(uri) {
+        this.#notify("notifications/resources/updated", { uri });
+    }
+
+    log(level, data, logger) {
+        this.#notify("notifications/message", { level, data, logger });
+    }
+
+    async connect() {
+        if (this.connected) {
+            return;
+        }
+
+        if (this.connectPromise) {
+            return this.connectPromise;
+        }
+
+        this.connectPromise = this.#openSocket();
+
+        try {
+            await this.connectPromise;
+        } finally {
+            this.connectPromise = null;
+        }
+    }
+
+    disconnect() {
+        this.#clearReconnectTimer();
+        this.#stopHeartbeat();
+        this.#abortAllCalls("Provider disconnected");
+
+        if (this.socket) {
+            this.socket.close(1000, "Provider disconnected");
+            this.socket = null;
+        }
+    }
+
+    async #openSocket() {
+        const socket = new WebSocket(this.url);
+        this.socket = socket;
+
+        await new Promise((resolve, reject) => {
+            const handleOpen = () => {
+                cleanup();
+                resolve();
+            };
+
+            const handleError = () => {
+                cleanup();
+                reject(new Error("Could not connect to the MCP gateway"));
+            };
+
+            const handleClose = () => {
+                cleanup();
+                reject(new Error("The MCP gateway connection closed before it opened"));
+            };
+
+            const cleanup = () => {
+                socket.removeEventListener("open", handleOpen);
+                socket.removeEventListener("error", handleError);
+                socket.removeEventListener("close", handleClose);
+            };
+
+            socket.addEventListener("open", handleOpen, { once: true });
+            socket.addEventListener("error", handleError, { once: true });
+            socket.addEventListener("close", handleClose, { once: true });
+        });
+
+        if (socket !== this.socket) {
+            throw new Error("The MCP gateway connection was replaced before it opened");
+        }
+
+        this.reconnectAttempt = 0;
+        this.#installSocketListeners(socket);
+        this.#publishAll();
+        this.#startHeartbeat();
+        this.#emitStatus("connected");
+    }
+
+    #installSocketListeners(socket) {
+        socket.addEventListener("message", (event) => {
+            void this.#handleMessage(event).catch((error) => {
+                console.error("Failed to handle gateway message:", error);
+            });
+        });
+
+        socket.addEventListener("close", () => {
+            if (socket !== this.socket) {
+                return;
+            }
+
+            this.socket = null;
+            this.#stopHeartbeat();
+            this.#abortAllCalls("Gateway connection closed");
+            this.#emitStatus("disconnected");
+
+            if (this.reconnect) {
+                this.#scheduleReconnect();
+            }
+        });
+
+        socket.addEventListener("error", (error) => {
+            console.error("Gateway WebSocket error:", error);
+        });
+    }
+
+    async #handleMessage(event) {
+        const message = JSON.parse(event.data);
+
+        switch (message.type) {
+            case "hello.ack":
+            case "ack":
+            case "pong":
+                return;
+            case "request":
+                void this.#handleRequest(message);
+                return;
+            case "cancel": {
+                const controller = this.runningCalls.get(message.requestId);
+                controller?.abort(message.reason ?? "Cancelled by MCP gateway");
+                return;
+            }
+            case "response":
+                this.#resolveOutgoing(message);
+                return;
+            case "protocol.error":
+                console.error("MCP gateway protocol error:", message.message);
+                return;
+            default:
+                console.warn("Unknown MCP gateway message:", message);
+        }
+    }
+
+    async #handleRequest(message) {
+        const { requestId, method, params } = message;
+        const controller = new AbortController();
+        this.runningCalls.set(requestId, controller);
+
+        const context = {
+            signal: controller.signal,
+            requestId,
+            progress: (progress, total, msg) =>
+                this.#notify("notifications/progress", {
+                    requestId,
+                    progress,
+                    total,
+                    message: msg,
+                }),
+            requestSampling: (samplingParams) =>
+                this.#callClient("sampling/createMessage", samplingParams, requestId),
+            requestElicit: (message, requestedSchema) =>
+                this.#callClient("elicitation/create", { message, requestedSchema }, requestId),
+        };
+
+        try {
+            const result = await this.#dispatch(method, params, context);
+            this.#send({ type: "result", requestId, result });
+        } catch (error) {
+            const messageText = error instanceof Error ? error.message : String(error);
+
+            try {
+                this.#send({ type: "result", requestId, error: messageText });
+            } catch {
+                // The socket vanished mid-request; the result can no longer be delivered.
+            }
+        } finally {
+            this.runningCalls.delete(requestId);
+        }
+    }
+
+    async #dispatch(method, params, context) {
+        if (method === "tools/call") {
+            const entry = this.#require(this.tools, params.name, "tool");
+
+            const value = await entry.handler(params.arguments ?? {}, {
+                ...context,
+                toolName: params.name,
+            });
+
+            return normalizeToolResult(value);
+        }
+
+        if (method === "resources/read") {
+            const entry = this.#require(this.resources, params.uri, "resource");
+            const value = await entry.handler(params.uri, context);
+            return normalizeResourceResult(params.uri, value);
+        }
+
+        if (method === "prompts/get") {
+            const entry = this.#require(this.prompts, params.name, "prompt");
+            return entry.handler(params.arguments ?? {}, { ...context, promptName: params.name });
+        }
+
+        if (method === "completion/complete") {
+            if (!this.onComplete) {
+                return { values: [] };
+            }
+
+            return normalizeCompletion(
+                await this.onComplete(params.ref, params.argument, params.context),
+            );
+        }
+
+        if (method === "resources/subscribe") {
+            await this.onSubscribe?.(params.uri);
+            return {};
+        }
+
+        if (method === "resources/unsubscribe") {
+            await this.onUnsubscribe?.(params.uri);
+            return {};
+        }
+
+        throw new Error(`Unsupported method: ${method}`);
+    }
+
+    #require(registry, identifier, kind) {
+        const entry = registry.get(identifier);
+
+        if (!entry) {
+            throw new Error(`Unknown ${kind}: ${identifier}`);
+        }
+
+        return entry;
+    }
+
+    async #callClient(method, params, originatingRequestId = null) {
+        this.outgoingId += 1;
+        const requestId = `c${this.outgoingId}`;
+
+        const promise = new Promise((resolve, reject) => {
+            this.outgoingCalls.set(requestId, { resolve, reject });
+        });
+
+        const frame = { type: "call", requestId, method, params };
+
+        if (originatingRequestId !== null) {
+            frame.originatingRequestId = originatingRequestId;
+        }
+
+        try {
+            this.#send(frame);
+        } catch (error) {
+            this.outgoingCalls.delete(requestId);
+            throw error;
+        }
+
+        return promise;
+    }
+
+    #resolveOutgoing(message) {
+        const pending = this.outgoingCalls.get(message.requestId);
+
+        if (!pending) {
+            return;
+        }
+
+        this.outgoingCalls.delete(message.requestId);
+
+        if (message.error != null) {
+            pending.reject(new Error(message.error));
+        } else {
+            pending.resolve(message.result);
+        }
+    }
+
+    #publishAll() {
+        for (const kind of ["tools", "resources", "resourceTemplates", "prompts"]) {
+            if (this[kind].size > 0) {
+                this.#publish(kind);
+            }
+        }
+    }
+
+    #publish(kind) {
+        if (!this.connected) {
+            return;
+        }
+
+        const registry = this[kind];
+        const items = Array.from(registry.values(), (entry) => entry.definition);
+        this.#send({ type: "register", registry: kind, items });
+    }
+
+    #notify(method, params) {
+        if (this.connected) {
+            this.#send({ type: "notify", method, params });
+        }
+    }
+
+    #send(message) {
+        if (!this.connected) {
+            throw new Error("MCP gateway WebSocket is not connected");
+        }
+
+        this.socket.send(JSON.stringify(message));
+    }
+
+    #startHeartbeat() {
+        this.#stopHeartbeat();
+
+        this.heartbeatTimer = setInterval(() => {
+            if (this.connected) {
+                this.#send({ type: "ping" });
+            }
+        }, this.heartbeatIntervalMs);
+    }
+
+    #stopHeartbeat() {
+        if (this.heartbeatTimer !== null) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+
+    #scheduleReconnect() {
+        this.#clearReconnectTimer();
+        const exponentialDelay = this.reconnectMinDelayMs * 2 ** this.reconnectAttempt;
+        const delay = Math.min(exponentialDelay, this.reconnectMaxDelayMs);
+        const jitteredDelay = Math.round(delay * (0.8 + Math.random() * 0.4));
+        this.reconnectAttempt += 1;
+
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+
+            void this.connect().catch((error) => {
+                console.error("MCP gateway reconnect failed:", error);
+                this.#scheduleReconnect();
+            });
+        }, jitteredDelay);
+    }
+
+    #clearReconnectTimer() {
+        if (this.reconnectTimer !== null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+
+    #abortAllCalls(reason) {
+        for (const controller of this.runningCalls.values()) {
+            controller.abort(reason);
+        }
+
+        this.runningCalls.clear();
+
+        for (const pending of this.outgoingCalls.values()) {
+            pending.reject(new Error(reason));
+        }
+
+        this.outgoingCalls.clear();
+    }
+
+    #emitStatus(status) {
+        this.onStatusChange?.(status);
+    }
+}
+
+function normalizeToolResult(value) {
+    if (value && typeof value === "object" && Array.isArray(value.content)) {
+        return value;
+    }
+
+    const text = typeof value === "string" ? value : JSON.stringify(value ?? null);
+    const result = { content: [{ type: "text", text }], isError: false };
+
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        result.structuredContent = value;
+    }
+
+    return result;
+}
+
+function normalizeResourceResult(uri, value) {
+    if (value && typeof value === "object" && Array.isArray(value.contents)) {
+        return value;
+    }
+
+    if (Array.isArray(value)) {
+        return { contents: value };
+    }
+
+    if (typeof value === "string") {
+        return { contents: [{ uri, text: value }] };
+    }
+
+    return { contents: [{ uri, ...value }] };
+}
+
+function normalizeCompletion(value) {
+    if (Array.isArray(value)) {
+        return { values: value };
+    }
+
+    return value;
+}

package/types/index.d.ts

@@ -0,0 +1,264 @@
+export type ProviderStatus = "connected" | "disconnected";
+
+export interface McpGtwProviderOptions {
+    /** WebSocket URL of the gateway's private `/provider` endpoint, including the `token`. */
+    url: string;
+    /** Reconnect automatically after an unexpected close. Defaults to `true`. */
+    reconnect?: boolean;
+    /** Minimum backoff before the first reconnect attempt, in milliseconds. Defaults to `500`. */
+    reconnectMinDelayMs?: number;
+    /** Maximum backoff between reconnect attempts, in milliseconds. Defaults to `10000`. */
+    reconnectMaxDelayMs?: number;
+    /** Interval between `ping` heartbeats while connected, in milliseconds. Defaults to `20000`. */
+    heartbeatIntervalMs?: number;
+    /** Called on every connection state transition. */
+    onStatusChange?: ((status: ProviderStatus) => void) | null;
+}
+
+/** A JSON Schema object describing a tool's input or output. */
+export type JsonSchema = Record<string, unknown>;
+
+/** Removes a previously registered entry and republishes its list. */
+export type Unregister = () => void;
+
+/** Reports incremental progress for the running request. */
+export type ProgressReporter = (progress: number, total?: number, message?: string) => void;
+
+export interface RequestContext {
+    /** Aborts when the gateway cancels the request or the connection drops. */
+    signal: AbortSignal;
+    /** Correlation id of this request. */
+    requestId: string;
+    /** Emits a `notifications/progress` frame for this request. */
+    progress: ProgressReporter;
+    /** Asks the initiating client's LLM to sample a completion, routed back to that client. */
+    requestSampling(params: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Asks the initiating client's user for structured input, routed back to that client. */
+    requestElicit(message: string, requestedSchema: JsonSchema): Promise<Record<string, unknown>>;
+}
+
+export interface ToolDefinition {
+    /** Unique tool name advertised to MCP clients. */
+    name: string;
+    /** Optional human-readable title. */
+    title?: string;
+    /** Human-readable description. Defaults to an empty string. */
+    description?: string;
+    /** JSON Schema for the arguments. Defaults to an empty object schema. */
+    inputSchema?: JsonSchema;
+    /** Optional JSON Schema for the structured result. */
+    outputSchema?: JsonSchema;
+    /** Optional MCP tool annotations. */
+    annotations?: Record<string, unknown>;
+}
+
+export interface ToolHandlerContext extends RequestContext {
+    /** Name of the tool being invoked. */
+    toolName: string;
+}
+
+/** A single MCP content block returned to the client. */
+export interface ToolResultContent {
+    type: string;
+    [key: string]: unknown;
+}
+
+/** A fully formed MCP tool result. Return this to control the content blocks exactly. */
+export interface ToolResult {
+    content: ToolResultContent[];
+    isError?: boolean;
+    structuredContent?: Record<string, unknown>;
+}
+
+/**
+ * A tool handler. Return a {@link ToolResult} to control the payload exactly, or return any
+ * JSON-serializable value and it is wrapped into a text (and structured, for objects) result.
+ */
+export type ToolHandler = (
+    args: Record<string, unknown>,
+    context: ToolHandlerContext,
+) => ToolResult | unknown | Promise<ToolResult | unknown>;
+
+export interface ResourceDefinition {
+    /** Concrete resource URI advertised to MCP clients. */
+    uri: string;
+    /** Human-readable name. */
+    name: string;
+    /** Optional human-readable title. */
+    title?: string;
+    /** Optional description. */
+    description?: string;
+    /** Optional MIME type of the resource contents. */
+    mimeType?: string;
+}
+
+/** A single MCP resource contents block. */
+export interface ResourceContents {
+    uri?: string;
+    mimeType?: string;
+    text?: string;
+    blob?: string;
+    [key: string]: unknown;
+}
+
+/** A fully formed MCP resource read result. */
+export interface ResourceReadResult {
+    contents: ResourceContents[];
+}
+
+/**
+ * A resource reader. Return a full {@link ResourceReadResult}, an array of contents, a string
+ * (wrapped as text), or a single contents object; all are normalized for the client.
+ */
+export type ResourceReader = (
+    uri: string,
+    context: RequestContext,
+) =>
+    | ResourceReadResult
+    | ResourceContents[]
+    | ResourceContents
+    | string
+    | Promise<ResourceReadResult | ResourceContents[] | ResourceContents | string>;
+
+export interface ResourceTemplateDefinition {
+    /** RFC 6570 URI template advertised to MCP clients. */
+    uriTemplate: string;
+    /** Human-readable name. */
+    name: string;
+    /** Optional human-readable title. */
+    title?: string;
+    /** Optional description. */
+    description?: string;
+    /** Optional MIME type of the resources the template produces. */
+    mimeType?: string;
+}
+
+export interface PromptArgument {
+    name: string;
+    description?: string;
+    required?: boolean;
+    [key: string]: unknown;
+}
+
+export interface PromptDefinition {
+    /** Unique prompt name advertised to MCP clients. */
+    name: string;
+    /** Optional human-readable title. */
+    title?: string;
+    /** Optional description. */
+    description?: string;
+    /** Optional declared arguments. */
+    arguments?: PromptArgument[];
+}
+
+export interface PromptHandlerContext extends RequestContext {
+    /** Name of the prompt being requested. */
+    promptName: string;
+}
+
+/** A fully formed MCP `prompts/get` result. */
+export interface PromptResult {
+    description?: string;
+    messages: Array<Record<string, unknown>>;
+}
+
+export type PromptHandler = (
+    args: Record<string, unknown>,
+    context: PromptHandlerContext,
+) => PromptResult | Promise<PromptResult>;
+
+/** A fully formed MCP completion result. */
+export interface CompletionResult {
+    values: string[];
+    total?: number;
+    hasMore?: boolean;
+}
+
+/**
+ * Completion handler. Return a {@link CompletionResult} or a bare array of strings (wrapped as
+ * `{ values }`). Assign it to `onComplete`; when unset, completion returns no candidates.
+ */
+export type CompletionHandler = (
+    ref: Record<string, unknown>,
+    argument: Record<string, unknown>,
+    context: Record<string, unknown> | undefined,
+) => CompletionResult | string[] | Promise<CompletionResult | string[]>;
+
+/** Called when the client subscribes to (or unsubscribes from) a resource URI. */
+export type SubscriptionHandler = (uri: string) => void | Promise<void>;
+
+/** MCP logging levels, from least to most severe. */
+export type LogLevel =
+    | "debug"
+    | "info"
+    | "notice"
+    | "warning"
+    | "error"
+    | "critical"
+    | "alert"
+    | "emergency";
+
+/**
+ * Connects a web application to an MCP gateway over the private WebSocket, publishes its MCP
+ * capabilities, and runs their handlers. Framework agnostic: no React, Vue or DOM framework is
+ * required.
+ */
+export class McpGtwProvider {
+    constructor(options: McpGtwProviderOptions);
+
+    readonly url: string;
+    reconnect: boolean;
+    reconnectMinDelayMs: number;
+    reconnectMaxDelayMs: number;
+    heartbeatIntervalMs: number;
+    onStatusChange: ((status: ProviderStatus) => void) | null;
+
+    /** Handles `completion/complete`. When `null`, completion returns no candidates. */
+    onComplete: CompletionHandler | null;
+    /** Called on `resources/subscribe`. Optional. */
+    onSubscribe: SubscriptionHandler | null;
+    /** Called on `resources/unsubscribe`. Optional. */
+    onUnsubscribe: SubscriptionHandler | null;
+
+    /** Whether the underlying socket is currently open. */
+    get connected(): boolean;
+
+    /** Registers (or replaces) a tool and republishes the list if connected. Returns an unregister fn. */
+    registerTool(definition: ToolDefinition, handler: ToolHandler): Unregister;
+
+    /** Registers (or replaces) a concrete resource and its reader. Returns an unregister fn. */
+    registerResource(definition: ResourceDefinition, reader: ResourceReader): Unregister;
+
+    /** Registers (or replaces) a resource template (listing only). Returns an unregister fn. */
+    registerResourceTemplate(definition: ResourceTemplateDefinition): Unregister;
+
+    /** Registers (or replaces) a prompt and its handler. Returns an unregister fn. */
+    registerPrompt(definition: PromptDefinition, handler: PromptHandler): Unregister;
+
+    /**
+     * Out-of-band sampling (`sampling/createMessage`), routed to the most recently active client.
+     * Inside a handler, prefer `context.requestSampling` so the call reaches the initiating client.
+     */
+    requestSampling(params: Record<string, unknown>): Promise<Record<string, unknown>>;
+
+    /**
+     * Out-of-band elicitation (`elicitation/create`), routed to the most recently active client.
+     * Inside a handler, prefer `context.requestElicit` so the call reaches the initiating client.
+     */
+    requestElicit(
+        message: string,
+        requestedSchema: JsonSchema,
+    ): Promise<Record<string, unknown>>;
+
+    /** Notifies subscribed clients that a resource changed (`notifications/resources/updated`). */
+    notifyResourceUpdated(uri: string): void;
+
+    /** Sends a log message to the client (`notifications/message`). */
+    log(level: LogLevel, data: unknown, logger?: string): void;
+
+    /** Opens the WebSocket and publishes the current registries. Idempotent while connected. */
+    connect(): Promise<void>;
+
+    /** Closes the socket, stops reconnecting, and aborts every in-flight call. */
+    disconnect(): void;
+}