@lostgradient/weft 0.2.0

package/dist/mcp/dispatcher.d.ts

@@ -0,0 +1,13 @@
+import type { Engine } from '../core/engine.ts';
+import { type Principal } from '../server/principal.ts';
+import { type McpDispatchResult } from './protocol.ts';
+import type { McpSession } from './session.ts';
+/** Inputs required to dispatch one MCP JSON-RPC message. */
+export type McpDispatchContext = {
+    readonly engine: Engine;
+    readonly session: McpSession;
+    readonly principal: Principal;
+    readonly authRequired: boolean;
+};
+/** Dispatch a parsed MCP JSON-RPC message. */
+export declare function dispatchMcpMessage(message: unknown, context: McpDispatchContext): Promise<McpDispatchResult>;

package/dist/mcp/dispatcher.js

@@ -0,0 +1,198 @@
+import { WeftError } from "../core/weft-error.js";
+import { JSON_RPC_ERROR_CODES } from "../server/json-rpc-protocol.js";
+import { isAuthenticated } from "../server/principal.js";
+import { VERSION } from "../version.js";
+import { McpToolExecutionError } from "./access.js";
+import {
+  forbidden,
+  internalError,
+  invalidParams,
+  isMcpRequest,
+  isNotification,
+  MCP_PROTOCOL_VERSION,
+  MCP_RESOURCE_TEMPLATES_LIST_METHOD,
+  MCP_RESOURCES_LIST_METHOD,
+  MCP_TOOLS_LIST_METHOD,
+  methodNotFound,
+  resourceNotFound,
+  successResponse
+} from "./protocol.js";
+import {
+  listMcpResources,
+  listMcpResourceTemplates,
+  readMcpResource,
+  subscribeMcpResource,
+  unsubscribeMcpResource
+} from "./resources.js";
+import { callMcpTool, listMcpTools } from "./tools.js";
+export async function dispatchMcpMessage(message, context) {
+  if (!isMcpRequest(message))
+    return {
+      kind: "response",
+      response: invalidParams(null, "Invalid MCP JSON-RPC request")
+    };
+  if (isNotification(message)) {
+    try {
+      await dispatchNotification(message, context);
+    } catch (error) {
+      console.error(`[weft.mcp] Ignored MCP notification error for ${message.method}:`, error);
+    }
+    return { kind: "accepted" };
+  }
+  const id = message.id ?? null;
+  try {
+    const result = await dispatchRequest(message, context);
+    return { kind: "response", response: successResponse(id, result) };
+  } catch (error) {
+    if (error instanceof McpProtocolError || error instanceof McpResponseError)
+      return { kind: "response", response: error.toResponse(id) };
+    if (error instanceof McpToolExecutionError)
+      return { kind: "response", response: forbidden(id, error.message) };
+    console.error("[weft.mcp] Unhandled MCP dispatcher error:", error);
+    return { kind: "response", response: internalError(id) };
+  }
+}
+async function dispatchNotification(request, context) {
+  if (request.method === "notifications/initialized") {
+    if (context.session.phase === "initializing")
+      context.session.phase = "ready";
+    return;
+  }
+  if (context.session.phase !== "ready")
+    return;
+  if (request.method === "notifications/cancelled") {
+    const params = objectParams(request.params), workflowId = context.session.cancelRequest(params.requestId);
+    if (workflowId !== void 0)
+      await context.engine.cancel(workflowId);
+  }
+}
+const REQUEST_HANDLERS = {
+  initialize: async (request, context) => initialize(request.params, context.session),
+  ping: async () => ({}),
+  [MCP_TOOLS_LIST_METHOD]: async (_request, context) => ({ tools: listMcpTools(context.engine) }),
+  "tools/call": callTool,
+  [MCP_RESOURCES_LIST_METHOD]: async (_request, context) => ({
+    resources: await listMcpResources(context)
+  }),
+  "resources/read": readResource,
+  "resources/subscribe": subscribeResource,
+  "resources/unsubscribe": unsubscribeResource,
+  [MCP_RESOURCE_TEMPLATES_LIST_METHOD]: async () => ({
+    resourceTemplates: listMcpResourceTemplates()
+  }),
+  "prompts/list": async () => ({ prompts: [] }),
+  "prompts/get": async () => {
+    throw new McpProtocolError(-32002, "Prompt not found");
+  },
+  "logging/setLevel": async () => ({}),
+  "completion/complete": async () => ({ completion: { values: [], total: 0, hasMore: !1 } })
+};
+async function dispatchRequest(request, context) {
+  if (context.authRequired && !isAuthenticated(context.principal) && request.method !== "initialize")
+    throw new McpProtocolError(-32011, "MCP request requires authentication");
+  enforceSessionPhase(request, context);
+  const handler = REQUEST_HANDLERS[request.method];
+  if (handler === void 0)
+    throw new McpResponseError(methodNotFound(request.id ?? null, request.method));
+  return handler(request, context);
+}
+function initialize(params, session) {
+  const record = objectParams(params), requestedVersion = typeof record.protocolVersion === "string" ? record.protocolVersion : void 0;
+  session.protocolVersion = requestedVersion === MCP_PROTOCOL_VERSION ? requestedVersion : MCP_PROTOCOL_VERSION;
+  session.phase = "initializing";
+  return {
+    protocolVersion: session.protocolVersion,
+    capabilities: {
+      tools: { listChanged: !1 },
+      resources: { subscribe: !0, listChanged: !1 },
+      prompts: {},
+      logging: {},
+      completions: {}
+    },
+    serverInfo: {
+      name: "weft",
+      title: "Weft",
+      version: VERSION
+    }
+  };
+}
+function enforceSessionPhase(request, context) {
+  if (request.method === "initialize") {
+    if (context.session.phase !== "new")
+      throw new McpProtocolError(-32000, "MCP session is already initialized");
+    return;
+  }
+  if (context.session.phase === "new")
+    throw new McpProtocolError(-32000, "MCP session must be initialized before requests");
+  if (context.session.phase === "initializing")
+    throw new McpProtocolError(-32000, "MCP session must receive notifications/initialized before requests");
+}
+async function callTool(request, context) {
+  const params = objectParams(request.params), name = params.name;
+  if (typeof name !== "string" || name.length === 0)
+    throw new McpResponseError(invalidParams(request.id ?? null, "tools/call requires name"));
+  return callMcpTool(name, params.arguments ?? {}, {
+    ...context,
+    requestId: request.id
+  });
+}
+async function readResource(request, context) {
+  const uri = requireUri(request), result = await readMcpResource(uri, context);
+  if (result === null)
+    throw new McpResponseError(resourceNotFound(request.id ?? null, uri));
+  return result;
+}
+async function subscribeResource(request, context) {
+  const uri = requireUri(request);
+  if (!await subscribeMcpResource(uri, context.session, context))
+    throw new McpResponseError(resourceNotFound(request.id ?? null, uri));
+  return {};
+}
+function unsubscribeResource(request, context) {
+  const uri = requireUri(request);
+  unsubscribeMcpResource(uri, context.session);
+  return {};
+}
+function requireUri(request) {
+  const uri = objectParams(request.params).uri;
+  if (typeof uri !== "string" || uri.length === 0)
+    throw new McpResponseError(invalidParams(request.id ?? null, `${request.method} requires uri`));
+  return uri;
+}
+function objectParams(params) {
+  if (params === void 0)
+    return {};
+  if (params !== null && typeof params === "object" && !Array.isArray(params))
+    return params;
+  throw new McpProtocolError(JSON_RPC_ERROR_CODES.INVALID_PARAMS, "MCP params must be an object");
+}
+
+class McpProtocolError extends WeftError {
+  jsonRpcCode;
+  data;
+  constructor(jsonRpcCode, message, data) {
+    super("McpProtocolError", message);
+    this.jsonRpcCode = jsonRpcCode;
+    this.data = data;
+  }
+  toResponse(id) {
+    if (this.jsonRpcCode === -32011)
+      return forbidden(id, this.message);
+    return {
+      jsonrpc: "2.0",
+      id,
+      error: this.data === void 0 ? { code: this.jsonRpcCode, message: this.message } : { code: this.jsonRpcCode, message: this.message, data: this.data }
+    };
+  }
+}
+
+class McpResponseError extends WeftError {
+  response;
+  constructor(response) {
+    super("McpResponseError", response.error?.message ?? "MCP response error");
+    this.response = response;
+  }
+  toResponse(_id) {
+    return this.response;
+  }
+}

package/dist/mcp/http.d.ts

@@ -0,0 +1,64 @@
+import type { Engine } from '../core/engine.ts';
+import { type Principal } from '../server/principal.ts';
+import { McpSessionManager } from './session.ts';
+/**
+ * Options for handling one Streamable HTTP MCP request.
+ *
+ * @example
+ * ```ts
+ * import { createMcpSessionManager, type McpHttpRequestOptions } from '@lostgradient/weft/mcp';
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ *
+ * await using storage = new MemoryStorage();
+ * await using engine = new Engine({ storage });
+ * await using sessionManager = createMcpSessionManager(engine);
+ *
+ * const request = new Request('http://localhost/mcp', { method: 'GET' });
+ * const options: McpHttpRequestOptions = {
+ *   request,
+ *   engine,
+ *   sessionManager,
+ *   authRequired: false,
+ * };
+ * void options;
+ * ```
+ */
+export type McpHttpRequestOptions = {
+    readonly request: Request;
+    readonly engine: Engine;
+    readonly sessionManager: McpSessionManager;
+    readonly principal?: Principal;
+    readonly authRequired: boolean;
+    readonly maxBodyBytes?: number;
+    readonly publicOrigin?: string;
+    readonly trustedHosts?: ReadonlyArray<string>;
+};
+/**
+ * Handle one MCP Streamable HTTP request.
+ *
+ * Most applications should use `serve({ engine })`, which mounts `/mcp`
+ * automatically. Use this helper when embedding the MCP transport in a custom
+ * Bun server.
+ *
+ * @example
+ * ```ts
+ * import { createMcpSessionManager, handleMcpHttpRequest } from '@lostgradient/weft/mcp';
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ *
+ * await using storage = new MemoryStorage();
+ * await using engine = new Engine({ storage });
+ * await using sessionManager = createMcpSessionManager(engine);
+ *
+ * Bun.serve({
+ *   fetch(request) {
+ *     return handleMcpHttpRequest({
+ *       request,
+ *       engine,
+ *       sessionManager,
+ *       authRequired: false,
+ *     });
+ *   },
+ * });
+ * ```
+ */
+export declare function handleMcpHttpRequest(options: McpHttpRequestOptions): Promise<Response>;

package/dist/mcp/http.js

@@ -0,0 +1,272 @@
+import { WeftError } from "../core/weft-error.js";
+import { anonymousPrincipal, isAuthenticated } from "../server/principal.js";
+import { dispatchMcpMessage } from "./dispatcher.js";
+import {
+  accepts,
+  DEFAULT_MCP_MAX_BODY_BYTES,
+  isJsonContentType,
+  isMcpRequest,
+  isNotification,
+  MCP_PROTOCOL_VERSION,
+  parseMcpMessage
+} from "./protocol.js";
+import { McpSessionLimitExceededError, McpSessionManager } from "./session.js";
+
+class McpBodyTooLargeError extends WeftError {
+  constructor() {
+    super("McpBodyTooLargeError", "body too large");
+  }
+}
+export async function handleMcpHttpRequest(options) {
+  const originFailure = validateOrigin(options.request, options.publicOrigin, options.trustedHosts);
+  if (originFailure !== null)
+    return originFailure;
+  switch (options.request.method) {
+    case "POST":
+      return handleMcpPost(options);
+    case "GET":
+      return handleMcpGet(options);
+    case "DELETE":
+      return handleMcpDelete(options);
+    default:
+      return new Response("Method Not Allowed", {
+        status: 405,
+        headers: { allow: "POST, GET, DELETE" }
+      });
+  }
+}
+async function handleMcpPost(options) {
+  const headerFailure = validatePostHeaders(options.request);
+  if (headerFailure !== null)
+    return headerFailure;
+  const parsed = await readMcpJsonBody(options);
+  if (parsed instanceof Response)
+    return parsed;
+  if (!parsed.ok)
+    return Response.json({
+      jsonrpc: "2.0",
+      id: null,
+      error: { code: -32700, message: "Parse error" }
+    }, { status: 200, headers: noStoreHeaders() });
+  const sessionResolution = resolvePostSession(options, parsed.value);
+  if (sessionResolution instanceof Response)
+    return sessionResolution;
+  const { session, createdSession, principal } = sessionResolution, result = await dispatchMcpMessage(parsed.value, {
+    engine: options.engine,
+    session,
+    principal,
+    authRequired: authRequiredFromOptions(options)
+  });
+  if (result.kind === "accepted")
+    return new Response(null, {
+      status: 202,
+      headers: maybeSessionHeaders(session, createdSession)
+    });
+  return Response.json(result.response, {
+    status: 200,
+    headers: maybeSessionHeaders(session, createdSession)
+  });
+}
+function validatePostHeaders(request) {
+  if (!accepts(request.headers.get("accept"), "application/json"))
+    return new Response("Not Acceptable", { status: 406 });
+  if (!isJsonContentType(request.headers.get("content-type") ?? ""))
+    return new Response("Unsupported Media Type", { status: 415 });
+  return null;
+}
+async function readMcpJsonBody(options) {
+  const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MCP_MAX_BODY_BYTES;
+  try {
+    const bytes = await readBodyBounded(options.request, maxBodyBytes);
+    return parseMcpMessage(new TextDecoder().decode(bytes));
+  } catch (error) {
+    return new Response(error instanceof McpBodyTooLargeError ? "Payload Too Large" : "Bad Request", {
+      status: error instanceof McpBodyTooLargeError ? 413 : 400
+    });
+  }
+}
+function resolvePostSession(options, message) {
+  const sessionHeader = sessionIdFromHeaders(options.request.headers), versionFailure = validateProtocolVersion(options.request.headers);
+  if (versionFailure !== null)
+    return versionFailure;
+  if (shouldCreateSessionForPost(message, sessionHeader)) {
+    const principal = principalFromOptions(options);
+    try {
+      return {
+        session: options.sessionManager.create(principal),
+        createdSession: !0,
+        principal
+      };
+    } catch (error) {
+      if (error instanceof McpSessionLimitExceededError)
+        return new Response(error.message, { status: 429, headers: noStoreHeaders() });
+      throw error;
+    }
+  }
+  if (sessionHeader === null)
+    return new Response("Missing Mcp-Session-Id", { status: 400 });
+  const session = options.sessionManager.get(sessionHeader);
+  if (session === void 0)
+    return new Response("MCP session not found", { status: 404 });
+  const principal = principalFromOptions(options);
+  if (!isSameSessionOwner(session.principal, principal))
+    return new Response("Forbidden", { status: 403, headers: noStoreHeaders() });
+  options.sessionManager.touch(session);
+  return { session, createdSession: !1, principal };
+}
+function shouldCreateSessionForPost(message, sessionHeader) {
+  if (sessionHeader !== null)
+    return !1;
+  if (!isMcpRequest(message))
+    return !1;
+  return message.method === "initialize" && !isNotification(message);
+}
+function handleMcpGet(options) {
+  if (!accepts(options.request.headers.get("accept"), "text/event-stream"))
+    return new Response("Not Acceptable", { status: 406 });
+  const versionFailure = validateProtocolVersion(options.request.headers);
+  if (versionFailure !== null)
+    return versionFailure;
+  const sessionId = sessionIdFromHeaders(options.request.headers);
+  if (sessionId === null)
+    return new Response("Missing Mcp-Session-Id", { status: 400 });
+  const session = options.sessionManager.get(sessionId);
+  if (session === void 0)
+    return new Response("MCP session not found", { status: 404 });
+  const principal = principalFromOptions(options);
+  if (!isSameSessionOwner(session.principal, principal))
+    return new Response("Forbidden", { status: 403, headers: noStoreHeaders() });
+  options.sessionManager.touch(session);
+  const stream = new ReadableStream({
+    start(controller) {
+      const encoder = new TextEncoder, write = (message) => {
+        controller.enqueue(encoder.encode(`event: message
+data: ${JSON.stringify(message)}
+
+`));
+      };
+      controller.enqueue(encoder.encode(`: connected
+
+`));
+      const remove = session.addTarget(write);
+      options.request.signal.addEventListener("abort", () => {
+        remove();
+        try {
+          controller.close();
+        } catch {}
+      }, { once: !0 });
+    }
+  });
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      ...noStoreHeaders(),
+      "content-type": "text/event-stream",
+      "Mcp-Session-Id": session.id
+    }
+  });
+}
+function handleMcpDelete(options) {
+  const sessionId = sessionIdFromHeaders(options.request.headers);
+  if (sessionId === null)
+    return new Response("Missing Mcp-Session-Id", { status: 400 });
+  const session = options.sessionManager.get(sessionId);
+  if (session === void 0)
+    return new Response("MCP session not found", { status: 404 });
+  if (!isSameSessionOwner(session.principal, principalFromOptions(options)))
+    return new Response("Forbidden", { status: 403, headers: noStoreHeaders() });
+  options.sessionManager.delete(sessionId);
+  return new Response(null, { status: 204, headers: noStoreHeaders() });
+}
+function sessionIdFromHeaders(headers) {
+  return headers.get("Mcp-Session-Id") ?? headers.get("MCP-Session-Id");
+}
+function validateProtocolVersion(headers) {
+  const version = headers.get("Mcp-Protocol-Version") ?? headers.get("MCP-Protocol-Version");
+  if (version === null)
+    return null;
+  if (version === MCP_PROTOCOL_VERSION)
+    return null;
+  return new Response("Unsupported MCP protocol version", { status: 400 });
+}
+function maybeSessionHeaders(session, includeSession) {
+  const headers = noStoreHeaders();
+  if (includeSession)
+    headers["Mcp-Session-Id"] = session.id;
+  return headers;
+}
+function noStoreHeaders() {
+  return { "cache-control": "no-store" };
+}
+function authRequiredFromOptions(options) {
+  return options.authRequired;
+}
+function principalFromOptions(options) {
+  return options.principal ?? anonymousPrincipal();
+}
+function isSameSessionOwner(left, right) {
+  if (left === right)
+    return !0;
+  if (left.method !== right.method)
+    return !1;
+  if (!isAuthenticated(left) || !isAuthenticated(right))
+    return left.method === right.method;
+  if (left.subject === void 0 || right.subject === void 0)
+    return !1;
+  return left.subject === right.subject && haveSameScopes(left.scopes, right.scopes);
+}
+function haveSameScopes(left, right) {
+  if (left.size !== right.size)
+    return !1;
+  for (const scope of left)
+    if (!right.has(scope))
+      return !1;
+  return !0;
+}
+async function readBodyBounded(request, maxBytes) {
+  const body = request.body;
+  if (body === null)
+    return new Uint8Array;
+  const reader = body.getReader(), chunks = [];
+  let total = 0;
+  try {
+    while (!0) {
+      const result = await reader.read();
+      if (result.done)
+        break;
+      total += result.value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel();
+        throw new McpBodyTooLargeError;
+      }
+      chunks.push(result.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bodyBytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bodyBytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bodyBytes;
+}
+function validateOrigin(request, publicOrigin, trustedHosts) {
+  const origin = request.headers.get("origin");
+  if (origin === null)
+    return null;
+  let originUrl;
+  try {
+    originUrl = new URL(origin);
+  } catch {
+    return new Response("Forbidden", { status: 403 });
+  }
+  if (publicOrigin !== void 0 && origin === publicOrigin)
+    return null;
+  if (trustedHosts?.includes(originUrl.host))
+    return null;
+  if (originUrl.host === new URL(request.url).host)
+    return null;
+  return new Response("Forbidden", { status: 403 });
+}

package/dist/mcp/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * MCP server support for Weft.
+ *
+ * This subpath is server/runtime-oriented. Browser-safe entry points remain
+ * under `@lostgradient/weft`, `@lostgradient/weft/client`, and `@lostgradient/weft/service-worker`.
+ *
+ * @module mcp
+ */
+export { anonymousPrincipal, principalFromApiKey, principalFromJwtClaims, principalFromMutualTls, principalFromStdioLocal, } from '../server/principal.ts';
+export type { AuthenticatedPrincipal, JwtClaims, Principal, UnauthenticatedPrincipal, } from '../server/principal.ts';
+export { handleMcpHttpRequest } from './http.ts';
+export type { McpHttpRequestOptions } from './http.ts';
+export { DEFAULT_MCP_MAX_BODY_BYTES, MCP_PROTOCOL_VERSION } from './protocol.ts';
+export { McpSession, McpSessionManager, createMcpSessionManager } from './session.ts';
+export type { McpSessionManagerOptions, McpSessionPhase } from './session.ts';
+export { runMcpStdioSession } from './stdio.ts';
+export type { McpStdioAdmission, McpStdioSessionOptions, McpStdioSessionResult } from './stdio.ts';

package/dist/mcp/index.js

@@ -0,0 +1,26 @@
+import {
+  anonymousPrincipal,
+  principalFromApiKey,
+  principalFromJwtClaims,
+  principalFromMutualTls,
+  principalFromStdioLocal,
+} from '../server/principal.js';
+import { handleMcpHttpRequest } from './http.js';
+import { DEFAULT_MCP_MAX_BODY_BYTES, MCP_PROTOCOL_VERSION } from './protocol.js';
+import { McpSession, McpSessionManager, createMcpSessionManager } from './session.js';
+import { runMcpStdioSession } from './stdio.js';
+
+export {
+  anonymousPrincipal,
+  createMcpSessionManager,
+  DEFAULT_MCP_MAX_BODY_BYTES,
+  handleMcpHttpRequest,
+  MCP_PROTOCOL_VERSION,
+  McpSession,
+  McpSessionManager,
+  principalFromApiKey,
+  principalFromJwtClaims,
+  principalFromMutualTls,
+  principalFromStdioLocal,
+  runMcpStdioSession,
+};

package/dist/mcp/list-filter.d.ts

@@ -0,0 +1,10 @@
+import type { ListFilter } from '../core/types.ts';
+export type McpListFilterParseResult = {
+    readonly ok: true;
+    readonly filter: ListFilter;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export declare function parseMcpListFilter(value: unknown): McpListFilterParseResult;
+export declare function parseMcpListFilterFromSearchParams(searchParams: URLSearchParams): McpListFilterParseResult;