@lovable.dev/mcp-js 0.5.0

package/dist/stacks/tanstack/index.d.cts

@@ -0,0 +1,38 @@
+import { M as McpRuntimeOptions } from '../../authorize-DpTEIFvs.js';
+import { d as McpDefinition } from '../../types-zMlr1mOK.js';
+import 'zod';
+
+interface TanStackRouteCtx {
+    request: Request;
+}
+interface TanStackParamRouteCtx<TParam extends string> {
+    request: Request;
+    params: Record<TParam, string>;
+}
+type TanStackMcpHandler = (ctx: TanStackRouteCtx) => Promise<Response>;
+type TanStackListToolsHandler = (ctx: TanStackRouteCtx) => Promise<Response>;
+type TanStackInvokeToolHandler = (ctx: TanStackParamRouteCtx<"tool">) => Promise<Response>;
+type TanStackOAuthProtectedResourceMetadataHandler = (ctx: TanStackRouteCtx) => Promise<Response>;
+/**
+ * Build a TanStack Start handler for the MCP protocol endpoint
+ * (`POST /mcp`). Assignable directly to a route's `ANY` handler.
+ */
+declare function createTanStackMcpHandler(mcp: McpDefinition, options?: McpRuntimeOptions): TanStackMcpHandler;
+/**
+ * Build a TanStack Start handler for `GET /.mcp/list-tools`. Returns the
+ * tool catalog (name, description, annotations, JSON Schemas) as JSON.
+ */
+declare function createTanStackListToolsHandler(mcp: McpDefinition, options?: McpRuntimeOptions): TanStackListToolsHandler;
+/**
+ * Build a TanStack Start handler for `POST /.mcp/invoke-tool/$tool`.
+ * Reads the tool name from `params.tool`, validates the JSON body, and
+ * dispatches to the matching `defineTool` handler.
+ */
+declare function createTanStackInvokeToolHandler(mcp: McpDefinition, options?: McpRuntimeOptions): TanStackInvokeToolHandler;
+/**
+ * Build a TanStack Start handler for `GET /.well-known/oauth-protected-resource`.
+ * When the MCP definition has no OAuth auth config the handler returns 404.
+ */
+declare function createTanStackOAuthProtectedResourceMetadataHandler(mcp: McpDefinition, options?: McpRuntimeOptions): TanStackOAuthProtectedResourceMetadataHandler;
+
+export { type TanStackInvokeToolHandler, type TanStackListToolsHandler, type TanStackMcpHandler, type TanStackOAuthProtectedResourceMetadataHandler, createTanStackInvokeToolHandler, createTanStackListToolsHandler, createTanStackMcpHandler, createTanStackOAuthProtectedResourceMetadataHandler };

package/dist/stacks/tanstack/index.d.ts

@@ -0,0 +1,38 @@
+import { M as McpRuntimeOptions } from '../../authorize-DpTEIFvs.js';
+import { d as McpDefinition } from '../../types-zMlr1mOK.js';
+import 'zod';
+
+interface TanStackRouteCtx {
+    request: Request;
+}
+interface TanStackParamRouteCtx<TParam extends string> {
+    request: Request;
+    params: Record<TParam, string>;
+}
+type TanStackMcpHandler = (ctx: TanStackRouteCtx) => Promise<Response>;
+type TanStackListToolsHandler = (ctx: TanStackRouteCtx) => Promise<Response>;
+type TanStackInvokeToolHandler = (ctx: TanStackParamRouteCtx<"tool">) => Promise<Response>;
+type TanStackOAuthProtectedResourceMetadataHandler = (ctx: TanStackRouteCtx) => Promise<Response>;
+/**
+ * Build a TanStack Start handler for the MCP protocol endpoint
+ * (`POST /mcp`). Assignable directly to a route's `ANY` handler.
+ */
+declare function createTanStackMcpHandler(mcp: McpDefinition, options?: McpRuntimeOptions): TanStackMcpHandler;
+/**
+ * Build a TanStack Start handler for `GET /.mcp/list-tools`. Returns the
+ * tool catalog (name, description, annotations, JSON Schemas) as JSON.
+ */
+declare function createTanStackListToolsHandler(mcp: McpDefinition, options?: McpRuntimeOptions): TanStackListToolsHandler;
+/**
+ * Build a TanStack Start handler for `POST /.mcp/invoke-tool/$tool`.
+ * Reads the tool name from `params.tool`, validates the JSON body, and
+ * dispatches to the matching `defineTool` handler.
+ */
+declare function createTanStackInvokeToolHandler(mcp: McpDefinition, options?: McpRuntimeOptions): TanStackInvokeToolHandler;
+/**
+ * Build a TanStack Start handler for `GET /.well-known/oauth-protected-resource`.
+ * When the MCP definition has no OAuth auth config the handler returns 404.
+ */
+declare function createTanStackOAuthProtectedResourceMetadataHandler(mcp: McpDefinition, options?: McpRuntimeOptions): TanStackOAuthProtectedResourceMetadataHandler;
+
+export { type TanStackInvokeToolHandler, type TanStackListToolsHandler, type TanStackMcpHandler, type TanStackOAuthProtectedResourceMetadataHandler, createTanStackInvokeToolHandler, createTanStackListToolsHandler, createTanStackMcpHandler, createTanStackOAuthProtectedResourceMetadataHandler };

package/dist/stacks/tanstack/index.js

@@ -0,0 +1,38 @@
+import {
+  createMcpProtocolHandler
+} from "../../chunk-GLG5RZGE.js";
+import {
+  createOAuthProtectedResourceMetadataHandler
+} from "../../chunk-DDF63QWG.js";
+import {
+  createInvokeToolHandler,
+  createListToolsHandler
+} from "../../chunk-VD6CS7Y6.js";
+import "../../chunk-MA5H6PSF.js";
+import "../../chunk-XEDRJFAR.js";
+import "../../chunk-QA3FWDUV.js";
+import "../../chunk-6DXGZZA4.js";
+
+// src/stacks/tanstack/handlers.ts
+function createTanStackMcpHandler(mcp, options = {}) {
+  const handler = createMcpProtocolHandler(mcp, options);
+  return ({ request }) => handler(request);
+}
+function createTanStackListToolsHandler(mcp, options = {}) {
+  const handler = createListToolsHandler(mcp, options);
+  return ({ request }) => handler(request);
+}
+function createTanStackInvokeToolHandler(mcp, options = {}) {
+  const handler = createInvokeToolHandler(mcp, options);
+  return ({ request, params }) => handler(request, params.tool);
+}
+function createTanStackOAuthProtectedResourceMetadataHandler(mcp, options = {}) {
+  const handler = createOAuthProtectedResourceMetadataHandler(mcp, options);
+  return ({ request }) => handler(request);
+}
+export {
+  createTanStackInvokeToolHandler,
+  createTanStackListToolsHandler,
+  createTanStackMcpHandler,
+  createTanStackOAuthProtectedResourceMetadataHandler
+};

package/dist/stacks/tanstack/vite.cjs

@@ -0,0 +1,291 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/stacks/tanstack/vite.ts
+var vite_exports = {};
+__export(vite_exports, {
+  assertUrlPathShape: () => assertUrlPathShape,
+  default: () => vite_default,
+  deriveRouteFileName: () => deriveRouteFileName,
+  mcpPlugin: () => mcpPlugin
+});
+module.exports = __toCommonJS(vite_exports);
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+
+// src/auth/metadata-path.ts
+var OAUTH_PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
+
+// src/stacks/tanstack/vite.ts
+var GENERATED_BANNER = "// AUTO-GENERATED by @lovable.dev/mcp-js \u2014 do not edit. Regenerated by the Vite plugin.\n// To take ownership, delete this banner line; the plugin then leaves the file alone.";
+function isFileMissing(err) {
+  return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+}
+function normalizePath(p) {
+  return p.split(import_node_path.sep).join("/");
+}
+function assertContains(parent, child, label) {
+  if (child !== parent && !child.startsWith(parent + import_node_path.sep)) {
+    throw new Error(`@lovable.dev/mcp-js: ${label} must resolve under ${parent}, got ${child}`);
+  }
+}
+function wellKnownRouteFile(routesDir, urlPath) {
+  const segments = urlPath.replace(/^\//, "").split("/");
+  const fileSegments = segments.map((segment, index) => {
+    const escaped = segment.startsWith(".") ? `[${segment}]` : segment;
+    return index === segments.length - 1 ? `${escaped}.ts` : escaped;
+  });
+  return (0, import_node_path.resolve)(routesDir, ...fileSegments);
+}
+function resolveAllRoutes(projectRoot, routesDirOption, routeFileName) {
+  const routesDir = (0, import_node_path.resolve)(projectRoot, routesDirOption);
+  assertContains(projectRoot, routesDir, `routesDir "${routesDirOption}"`);
+  const mcpRouteFile = (0, import_node_path.resolve)(routesDir, routeFileName);
+  assertContains(routesDir, mcpRouteFile, `routeFileName "${routeFileName}"`);
+  return {
+    routesDir,
+    mcpRouteFile,
+    metadataRouteFile: wellKnownRouteFile(routesDir, OAUTH_PROTECTED_RESOURCE_METADATA_PATH),
+    listToolsRouteFile: (0, import_node_path.resolve)(routesDir, "[.mcp]", "list-tools.ts"),
+    invokeToolRouteFile: (0, import_node_path.resolve)(routesDir, "[.mcp]", "invoke-tool", "$tool.ts")
+  };
+}
+function assertUrlPathShape(urlPath) {
+  if (!urlPath.startsWith("/")) {
+    throw new Error(`@lovable.dev/mcp-js: path must start with "/", got "${urlPath}"`);
+  }
+  if (/\/{2,}/.test(urlPath)) {
+    throw new Error(`@lovable.dev/mcp-js: path "${urlPath}" contains empty segments ("//")`);
+  }
+  const trimmed = urlPath.replace(/^\/+/, "").replace(/\/+$/, "");
+  if (!trimmed) {
+    throw new Error(`@lovable.dev/mcp-js: path "${urlPath}" has no route segment`);
+  }
+  if (!/^[a-zA-Z0-9_\-/]+$/.test(trimmed)) {
+    throw new Error(`@lovable.dev/mcp-js: path "${urlPath}" contains unsupported characters`);
+  }
+  return trimmed;
+}
+function deriveRouteFileName(urlPath) {
+  return `${assertUrlPathShape(urlPath)}.ts`;
+}
+function canonicalUrlPath(urlPath) {
+  return `/${urlPath.replace(/^\/+/, "").replace(/\/+$/, "")}`;
+}
+function relativeImportSpecifier(routeFile, target) {
+  const rel = normalizePath((0, import_node_path.relative)((0, import_node_path.dirname)(routeFile), target));
+  const withoutExt = rel.replace(/\.ts$/, "");
+  return withoutExt.startsWith(".") ? withoutExt : `./${withoutExt}`;
+}
+function buildRouteSource(route, resourcePath, mcpEntry, projectRoot) {
+  const mcpImport = relativeImportSpecifier(route.file, mcpEntry);
+  const routeRel = normalizePath((0, import_node_path.relative)(projectRoot, route.file));
+  const note = route.spaFallbackNote ? "      // ANY: TanStack returns SPA HTML for methods not in `handlers`; the SDK 405s instead.\n" : "";
+  return `${GENERATED_BANNER}
+// route: ${route.routeLiteral}
+// emitted to: ${routeRel}
+
+import { createFileRoute } from "@tanstack/react-router";
+
+import { ${route.handlerFactory} } from "@lovable.dev/mcp-js/stacks/tanstack";
+
+import mcp from "${mcpImport}";
+
+export const Route = createFileRoute("${route.routeLiteral}")({
+  server: {
+    handlers: {
+${note}      ANY: ${route.handlerFactory}(mcp, { resourcePath: "${resourcePath}" }),
+    },
+  },
+});
+`;
+}
+function hasGeneratedBanner(content) {
+  return content.replace(/\r\n/g, "\n").startsWith(GENERATED_BANNER);
+}
+function writeIfChanged(file, content) {
+  let existing;
+  try {
+    existing = (0, import_node_fs.readFileSync)(file, "utf8");
+  } catch (err) {
+    if (!isFileMissing(err))
+      throw err;
+  }
+  if (existing !== void 0) {
+    if (!hasGeneratedBanner(existing)) {
+      throw new Error(
+        `@lovable.dev/mcp-js: refusing to overwrite user-authored route at ${file}. Delete it or move it first.`
+      );
+    }
+    if (existing === content)
+      return false;
+  }
+  (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(file), { recursive: true });
+  (0, import_node_fs.writeFileSync)(file, content, "utf8");
+  return true;
+}
+function fileStartsWithBanner(file) {
+  try {
+    return hasGeneratedBanner((0, import_node_fs.readFileSync)(file, "utf8"));
+  } catch (err) {
+    if (isFileMissing(err))
+      return false;
+    throw err;
+  }
+}
+function findAdoptedFiles(routesDir) {
+  const adopted = [];
+  const visit = (dir) => {
+    let entries;
+    try {
+      entries = (0, import_node_fs.readdirSync)(dir);
+    } catch (err) {
+      if (isFileMissing(err))
+        return;
+      throw err;
+    }
+    for (const entry of entries) {
+      const full = (0, import_node_path.join)(dir, entry);
+      let stat;
+      try {
+        stat = (0, import_node_fs.lstatSync)(full);
+      } catch (err) {
+        if (isFileMissing(err))
+          continue;
+        throw err;
+      }
+      if (stat.isDirectory()) {
+        visit(full);
+      } else if (entry.endsWith(".ts") && fileStartsWithBanner(full)) {
+        adopted.push(full);
+      }
+    }
+  };
+  visit(routesDir);
+  return adopted;
+}
+function mcpPlugin(options = {}) {
+  const mcpEntryOption = options.mcpEntry ?? "src/lib/mcp/index.ts";
+  const routesDirOption = options.routesDir ?? "src/routes";
+  const rawUrlPath = options.path ?? "/mcp";
+  assertUrlPathShape(rawUrlPath);
+  const routeFileName = options.routeFileName ?? deriveRouteFileName(rawUrlPath);
+  const urlPath = canonicalUrlPath(rawUrlPath);
+  const emitRestRoutes = options.restRoutes !== false;
+  const emitProtectedResourceMetadataRoute = options.protectedResourceMetadataRoute !== false;
+  let projectRoot = process.cwd();
+  let mcpEntry = (0, import_node_path.resolve)(projectRoot, mcpEntryOption);
+  let { routesDir, mcpRouteFile, metadataRouteFile, listToolsRouteFile, invokeToolRouteFile } = resolveAllRoutes(
+    projectRoot,
+    routesDirOption,
+    routeFileName
+  );
+  const regenerate = () => {
+    let mcpEntryExists = true;
+    try {
+      (0, import_node_fs.lstatSync)(mcpEntry);
+    } catch (err) {
+      if (!isFileMissing(err))
+        throw err;
+      mcpEntryExists = false;
+    }
+    const expected = /* @__PURE__ */ new Set();
+    if (mcpEntryExists) {
+      const routes = [
+        { file: mcpRouteFile, routeLiteral: urlPath, handlerFactory: "createTanStackMcpHandler" }
+      ];
+      if (emitProtectedResourceMetadataRoute) {
+        routes.push({
+          file: metadataRouteFile,
+          routeLiteral: OAUTH_PROTECTED_RESOURCE_METADATA_PATH,
+          handlerFactory: "createTanStackOAuthProtectedResourceMetadataHandler"
+        });
+      }
+      if (emitRestRoutes) {
+        routes.push(
+          {
+            file: listToolsRouteFile,
+            routeLiteral: "/.mcp/list-tools",
+            handlerFactory: "createTanStackListToolsHandler",
+            spaFallbackNote: true
+          },
+          {
+            file: invokeToolRouteFile,
+            routeLiteral: "/.mcp/invoke-tool/$tool",
+            handlerFactory: "createTanStackInvokeToolHandler",
+            spaFallbackNote: true
+          }
+        );
+      }
+      for (const route of routes) {
+        expected.add(route.file);
+        writeIfChanged(route.file, buildRouteSource(route, urlPath, mcpEntry, projectRoot));
+      }
+    }
+    for (const file of findAdoptedFiles(routesDir)) {
+      if (!expected.has(file)) {
+        try {
+          (0, import_node_fs.unlinkSync)(file);
+        } catch (err) {
+          if (!isFileMissing(err))
+            throw err;
+        }
+      }
+    }
+  };
+  return {
+    name: "@lovable.dev/mcp-js",
+    configResolved(config) {
+      projectRoot = config.root;
+      mcpEntry = (0, import_node_path.resolve)(projectRoot, mcpEntryOption);
+      ({ routesDir, mcpRouteFile, metadataRouteFile, listToolsRouteFile, invokeToolRouteFile } = resolveAllRoutes(
+        projectRoot,
+        routesDirOption,
+        routeFileName
+      ));
+      regenerate();
+    },
+    configureServer(server) {
+      const watchedEntry = mcpEntry;
+      const onEntryChange = (file) => {
+        if (normalizePath(file) === normalizePath(watchedEntry)) {
+          regenerate();
+        }
+      };
+      server.watcher.on("add", onEntryChange);
+      server.watcher.on("change", onEntryChange);
+      server.watcher.on("unlink", onEntryChange);
+      server.watcher.once("close", () => {
+        server.watcher.off("add", onEntryChange);
+        server.watcher.off("change", onEntryChange);
+        server.watcher.off("unlink", onEntryChange);
+      });
+    },
+    buildStart() {
+      regenerate();
+    }
+  };
+}
+var vite_default = mcpPlugin;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assertUrlPathShape,
+  deriveRouteFileName,
+  mcpPlugin
+});

package/dist/stacks/tanstack/vite.d.cts

@@ -0,0 +1,64 @@
+import { Plugin } from 'vite';
+
+interface McpPluginOptions {
+    /**
+     * Path to the MCP entry file (default export = `defineMcp(...)` result),
+     * relative to the project root.
+     * @default "src/lib/mcp/index.ts"
+     */
+    mcpEntry?: string;
+    /**
+     * Where TanStack route files live, relative to the project root.
+     * The plugin emits `<routesDir>/<routeFileName>` plus the REST companion
+     * routes here.
+     * @default "src/routes"
+     */
+    routesDir?: string;
+    /**
+     * Public URL path for the MCP-protocol route only.
+     *
+     * The REST companion routes are fixed at `/.mcp/list-tools` and
+     * `/.mcp/invoke-tool/$tool` and are not affected by this option — the
+     * `[.mcp]` namespace exists to keep them from colliding with
+     * user-defined URLs, so making them follow `path` would defeat the
+     * purpose. Set `restRoutes: false` to drop the companions entirely.
+     *
+     * Must start with `/` and use only `/mcp`-style segments; anything more
+     * exotic doesn't map cleanly to a TanStack file name.
+     * @default "/mcp"
+     */
+    path?: string;
+    /**
+     * Filename to emit for the main MCP route, relative to `routesDir`.
+     * Defaults to a name derived from `path` (e.g. `/mcp` → `mcp.ts`,
+     * `/api/mcp` → `api/mcp.ts`).
+     */
+    routeFileName?: string;
+    /**
+     * Set to `false` to skip emitting the REST companion routes at
+     * `/.mcp/list-tools` and `/.mcp/<tool>`. Set
+     * `protectedResourceMetadataRoute: false` as well if you want the MCP
+     * protocol route to be the only emitted surface.
+     * @default true
+     */
+    restRoutes?: boolean;
+    /**
+     * Set to `false` to skip emitting the OAuth protected-resource metadata
+     * route at `/.well-known/oauth-protected-resource`.
+     * @default true
+     */
+    protectedResourceMetadataRoute?: boolean;
+}
+declare function assertUrlPathShape(urlPath: string): string;
+declare function deriveRouteFileName(urlPath: string): string;
+/**
+ * Generate the TanStack route(s) that mount the MCP server.
+ *
+ * Place this in your `vite.config.ts` plugins array. Emits during
+ * `configResolved` (so dev-server boot and the TanStack file-router both
+ * see the routes on the first request) and re-emits when the MCP entry
+ * file changes during dev.
+ */
+declare function mcpPlugin(options?: McpPluginOptions): Plugin;
+
+export { type McpPluginOptions, assertUrlPathShape, mcpPlugin as default, deriveRouteFileName, mcpPlugin };

package/dist/stacks/tanstack/vite.d.ts

@@ -0,0 +1,64 @@
+import { Plugin } from 'vite';
+
+interface McpPluginOptions {
+    /**
+     * Path to the MCP entry file (default export = `defineMcp(...)` result),
+     * relative to the project root.
+     * @default "src/lib/mcp/index.ts"
+     */
+    mcpEntry?: string;
+    /**
+     * Where TanStack route files live, relative to the project root.
+     * The plugin emits `<routesDir>/<routeFileName>` plus the REST companion
+     * routes here.
+     * @default "src/routes"
+     */
+    routesDir?: string;
+    /**
+     * Public URL path for the MCP-protocol route only.
+     *
+     * The REST companion routes are fixed at `/.mcp/list-tools` and
+     * `/.mcp/invoke-tool/$tool` and are not affected by this option — the
+     * `[.mcp]` namespace exists to keep them from colliding with
+     * user-defined URLs, so making them follow `path` would defeat the
+     * purpose. Set `restRoutes: false` to drop the companions entirely.
+     *
+     * Must start with `/` and use only `/mcp`-style segments; anything more
+     * exotic doesn't map cleanly to a TanStack file name.
+     * @default "/mcp"
+     */
+    path?: string;
+    /**
+     * Filename to emit for the main MCP route, relative to `routesDir`.
+     * Defaults to a name derived from `path` (e.g. `/mcp` → `mcp.ts`,
+     * `/api/mcp` → `api/mcp.ts`).
+     */
+    routeFileName?: string;
+    /**
+     * Set to `false` to skip emitting the REST companion routes at
+     * `/.mcp/list-tools` and `/.mcp/<tool>`. Set
+     * `protectedResourceMetadataRoute: false` as well if you want the MCP
+     * protocol route to be the only emitted surface.
+     * @default true
+     */
+    restRoutes?: boolean;
+    /**
+     * Set to `false` to skip emitting the OAuth protected-resource metadata
+     * route at `/.well-known/oauth-protected-resource`.
+     * @default true
+     */
+    protectedResourceMetadataRoute?: boolean;
+}
+declare function assertUrlPathShape(urlPath: string): string;
+declare function deriveRouteFileName(urlPath: string): string;
+/**
+ * Generate the TanStack route(s) that mount the MCP server.
+ *
+ * Place this in your `vite.config.ts` plugins array. Emits during
+ * `configResolved` (so dev-server boot and the TanStack file-router both
+ * see the routes on the first request) and re-emits when the MCP entry
+ * file changes during dev.
+ */
+declare function mcpPlugin(options?: McpPluginOptions): Plugin;
+
+export { type McpPluginOptions, assertUrlPathShape, mcpPlugin as default, deriveRouteFileName, mcpPlugin };