vite-plugin-mcp-builder 0.0.1

package/README.md

@@ -0,0 +1,166 @@
+# Vite Plugin: MCP Build
+
+This Vite plugin helps develop and build Model Context Protocol (MCP) handlers.
+
+Key features:
+
+- Development server that mounts an MCP handler under `/mcp`.
+- Production build that produces a single bundle at `dist/app.js`.
+- Scans configured directories for `*.tool`, `*.prompt` and `*.resource` files to include in the bundle.
+
+## Overview
+
+The plugin scans the project files defined by the `dirs` option and exposes a development endpoint at `/mcp` that serves those definitions dynamically. For production it bundles the detected definitions into a single output file `dist/app.js`.
+
+## Installation
+
+Install with your package manager:
+
+```bash
+yarn add -D vite-plugin-mcp-build
+# or
+npm install -D vite-plugin-mcp-build
+```
+
+## Usage (example `vite.config.ts`)
+
+```ts
+import { defineConfig } from 'vite'
+import mcpPlugin from 'vite-plugin-mcp-build'
+
+export default defineConfig({
+  plugins: [
+    mcpPlugin({
+      // optional plugin properties shown below
+      server: './src/createServer.js',
+      main: './src/main.js',
+      dirs: [
+        { dir: './src/calculadora' }
+      ]
+    })
+  ]
+})
+```
+
+## Plugin options
+
+All options are optional. Defaults are shown where applicable.
+
+- `root?: string` — Project root used to resolve relative paths. Defaults to `process.cwd()`.
+- `cacheDir?: string` — Directory where generated helper files are written (e.g. `createInstance.js`). Default: `.mcp`.
+- `server?: string` — Path to the server factory module used in production. Default: internal `src-dev/createServer.js` (resolved relative to `root`).
+- `devHandler?: string` — Path to the development handler module used by the Vite dev server. Default: internal `src-dev/devHandler.js` (resolved relative to `root`).
+- `main?: string` — The main production entry module used for SSR build. Default: internal `src-dev/main.js` (resolved relative to `root`).
+- `include?: string[]` — Glob patterns used to match tool/prompt/resource files inside each `dirs` entry. Default patterns (the plugin supports both `.ts` and `.js`):
+
+  ```
+  [
+    "**/*.tool.ts",
+    "**/*.prompt.ts",
+    "**/*.resource.ts",
+    "**/*.tool.js",
+    "**/*.prompt.js",
+    "**/*.resource.js"
+  ]
+  ```
+
+  Note: the original source contained a typo (`promt`). The plugin's intended pattern is `prompt`.
+
+- `dirs?: { dir: string; include?: string[]; skip?: boolean }[]` — Array of directories to scan. Each entry:
+  - `dir` (required): directory path (relative to `root`) to scan.
+  - `include` (optional): per-dir globs overriding the global `include` list.
+  - `skip` (optional): if `true` the directory is ignored.
+
+  Default: `[{ dir: 'src', include: [], skip: false }]` — the plugin will scan `src` by default.
+
+## Development mode
+
+Run Vite in dev mode (e.g. `yarn dev`). The plugin configures the dev server and mounts the MCP handler under `/mcp` (the path is registered by the plugin's middleware).
+
+By default Vite's dev server will include the plugin's middleware under the `/mcp` route. Example local URL:
+
+```
+http://localhost:5173/mcp
+```
+
+Register this URL in your agent during development, e.g.:
+
+```json
+{
+  "servers": {
+    "my-mcp-dev": {
+      "type": "http",
+      "url": "http://localhost:5173/mcp"
+    }
+  }
+}
+```
+
+## Production build
+
+Run your normal Vite build (e.g. `yarn build`). The plugin configures the build to produce a single SSR entry output named `app.js` (written under the `dist` directory by default). That file is suitable to load in a production process that creates the server instance and starts transports.
+
+Example `main.js` (production runner):
+
+```ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import createInstance from "@mcp/createInstance.js";
+
+const server = await createInstance();
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+## Defining tools, prompts and resources
+
+Tools, prompts and resources are defined with the helper registrations (see `src/define.ts`). Typical usage registers a tool with a title, description, input schema and an implementation function. Example (TypeScript):
+
+```ts
+import { z } from 'zod';
+import { defineRegisterTool } from '@mcp/define';
+
+export default defineRegisterTool(
+  'divide',
+  {
+    title: 'Divide two numbers',
+    description: 'Divides two given numbers.',
+    inputSchema: {
+      number1: z.number(),
+      number2: z.number(),
+    },
+  },
+  async ({ number1, number2 }: any) => {
+    if (typeof number1 !== 'number' || typeof number2 !== 'number') {
+      throw new Error('Parameters must be numbers.');
+    }
+    return {
+      content: [{ type: 'text', text: String(number1 / number2) }]
+    };
+  }
+);
+```
+
+The registration helpers (`defineRegisterTool`, `defineRegisterPrompt`, `defineRegisterResource`) allow describing handlers without requiring a server instance at definition time.
+
+## Example project layout
+
+```bash
+packages/example/src/
+  server.ts
+  calculadora/
+    dividir.tool.ts
+    multiplicar.tool.ts
+    nombre.resource.ts
+```
+
+With the configuration above, the plugin will find `dividir.tool.ts`, `multiplicar.tool.ts` and `nombre.resource.ts` and include them in the production bundle.
+
+## Troubleshooting
+
+- If files are not detected, verify your `dirs` entries and `include` globs, and ensure file extensions (`.ts`/`.js`) match your build.
+- Inspect Vite's console output for plugin scan and build messages.
+
+---
+
+If you want, I can also add concrete type signatures for the `defineRegister*` helpers and a small example that consumes `dist/app.js` in a production process.
+

package/dist/define.d.ts

@@ -0,0 +1,22 @@
+import { PromptCallback, McpServer, ResourceMetadata, ReadResourceCallback, ResourceTemplate, ReadResourceTemplateCallback, ToolCallback } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ZodRawShapeCompat, AnySchema } from '@modelcontextprotocol/sdk/server/zod-compat.js';
+import { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+
+type PromptArgsRawShape = ZodRawShapeCompat;
+declare const defineRegisterTool: <OutputArgs extends ZodRawShapeCompat | AnySchema, InputArgs extends undefined | ZodRawShapeCompat | AnySchema = undefined>(name: string, config: {
+    title?: string;
+    description?: string;
+    inputSchema?: InputArgs;
+    outputSchema?: OutputArgs;
+    annotations?: ToolAnnotations;
+    _meta?: Record<string, unknown>;
+}, cb: ToolCallback<InputArgs>) => (server: McpServer) => void;
+declare const defineRegisterPrompt: <Args extends PromptArgsRawShape>(name: string, config: {
+    title?: string;
+    description?: string;
+    argsSchema?: Args;
+}, cb: PromptCallback<Args>) => (server: McpServer) => void;
+declare const defineRegisterResource: (name: string, uriOrTemplate: string, config: ResourceMetadata, readCallback: ReadResourceCallback) => (server: McpServer) => void;
+declare const defineRegisterResourceV2: (name: string, uriOrTemplate: ResourceTemplate, config: ResourceMetadata, readCallback: ReadResourceTemplateCallback) => (server: McpServer) => void;
+
+export { defineRegisterPrompt, defineRegisterResource, defineRegisterResourceV2, defineRegisterTool };

package/dist/define.js

@@ -0,0 +1,46 @@
+const defineRegisterTool = (name, config, cb) => {
+  return (server) => {
+    try {
+      console.log("RegisterTool:", name);
+      server.registerTool(name, config, cb);
+    } catch (error) {
+      console.error("RegisterTool:", error);
+    }
+  };
+};
+const defineRegisterPrompt = (name, config, cb) => {
+  return (server) => {
+    try {
+      console.log("RegisterPrompt:", name);
+      server.registerPrompt(name, config, cb);
+    } catch (error) {
+      console.error("RegisterPrompt:", error);
+    }
+  };
+};
+const defineRegisterResource = (name, uriOrTemplate, config, readCallback) => {
+  return (server) => {
+    try {
+      console.log("RegisterResource:", name);
+      server.registerResource(name, uriOrTemplate, config, readCallback);
+    } catch (error) {
+      console.error("RegisterResource:", error);
+    }
+  };
+};
+const defineRegisterResourceV2 = (name, uriOrTemplate, config, readCallback) => {
+  return (server) => {
+    try {
+      console.log("RegisterResource:", name);
+      server.registerResource(name, uriOrTemplate, config, readCallback);
+    } catch (error) {
+      console.error("RegisterResourceV2:", error);
+    }
+  };
+};
+export {
+  defineRegisterPrompt,
+  defineRegisterResource,
+  defineRegisterResourceV2,
+  defineRegisterTool
+};

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { Plugin } from 'vite';
+
+type PluginOpts = {
+    root?: string;
+    cacheDir?: string;
+    server?: string;
+    devHandler?: string;
+    main?: string;
+    include?: string[];
+    dirs?: {
+        dir: string;
+        include?: string[];
+        skip?: boolean;
+    }[];
+};
+
+declare const mcpPlugin: (opts: PluginOpts) => Plugin[];
+
+export { mcpPlugin as default, mcpPlugin };

package/dist/index.js

@@ -0,0 +1,100 @@
+import express from "express";
+import { assertConfig } from "./model";
+import { writeCreateInstance } from "./createInstanceFile";
+const mcpPlugin = (opts) => {
+  const conf = assertConfig(opts);
+  writeCreateInstance(conf);
+  const isReload = (file) => {
+    return conf.hmrDirs.find((it) => file.startsWith(it));
+  };
+  return [
+    {
+      name: "vite-plugin-mcp-alias",
+      enforce: "pre",
+      config: () => {
+        return {
+          resolve: {
+            alias: {
+              [`${conf.moduleId}/main.js`]: conf.mainFile,
+              [`${conf.moduleId}/createServer.js`]: conf.serverFile,
+              [`${conf.moduleId}/createInstance.js`]: conf.createInstanceFile
+            }
+          }
+        };
+      }
+    },
+    {
+      name: "vite-plugin-mcp-server",
+      enforce: "pre",
+      apply: "serve",
+      config: () => {
+        return {
+          appType: "custom",
+          server: {
+            cors: true
+          }
+        };
+      },
+      configureServer: async (devServer) => {
+        const {
+          //
+          watcher,
+          restart,
+          middlewares,
+          ssrLoadModule,
+          ssrFixStacktrace
+        } = devServer;
+        var appServer = express();
+        const onReload = async (file) => {
+          if (isReload(file)) {
+            writeCreateInstance(conf);
+            restart();
+          }
+        };
+        watcher.on("all", (_, file) => onReload(file));
+        console.log("Load devHandlerFile!");
+        const { createHandler } = await ssrLoadModule(conf.devHandlerFile, {
+          fixStacktrace: true
+        });
+        const handler = await createHandler({});
+        appServer.use("/", async (req, res, next) => {
+          try {
+            handler(req, res, next);
+          } catch (error) {
+            ssrFixStacktrace(error);
+            process.exitCode = 1;
+            next(error);
+          }
+        });
+        middlewares.use("/mcp", appServer);
+      }
+    },
+    {
+      name: "vite-plugin-mcp-build",
+      enforce: "pre",
+      config: () => {
+        return {
+          appType: "custom",
+          target: "esnext",
+          emptyOutDir: true,
+          build: {
+            ssr: conf.mainFile,
+            rollupOptions: {
+              output: {
+                format: "es",
+                entryFileNames: "app.js",
+                chunkFileNames: "bin/[name].js",
+                assetFileNames: "assets/[name].[ext]"
+              }
+            }
+          }
+        };
+      }
+    }
+  ];
+};
+var src_default = mcpPlugin;
+export {
+  src_default as default,
+  mcpPlugin
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "vite-plugin-mcp-builder",
+  "version": "0.0.1",
+  "description": "Vite plugin to build and serve MCP (Model Context Protocol) servers",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./define": {
+      "import": "./dist/define.js",
+      "types": "./dist/define.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src-dev",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepublish": "yarn build",
+    "prepack": "yarn build"
+  },
+  "keywords": [
+    "vite",
+    "plugin",
+    "mcp",
+    "model-context-protocol",
+    "build-tool"
+  ],
+  "author": "Willyams Yujra <yracnet@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/yracnet/vite-plugin-mcp-builder",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yracnet/vite-plugin-mcp-builder"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "vite": "^3 || ^4 || ^5 || ^6 || ^7",
+    "glob": "^13.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "glob": "^13.0.1",
+    "globals": "^16.5.0",
+    "tsup": "^8.5.1",
+    "typescript": "~5.9.3",
+    "vite": "^7.2.4"
+  }
+}

package/src-dev/createServer.js

@@ -0,0 +1,10 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+export default () => {
+  const servidor = new McpServer({
+    name: "mcp-example",
+    version: "1.0.0",
+  });
+  return servidor;
+}
+

package/src-dev/devHandler.js

@@ -0,0 +1,33 @@
+import express from "express"
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import createInstance from "@mcp/createInstance.js"
+import cors from 'cors';
+import { randomUUID } from 'node:crypto';
+
+export const createHandler = async ({
+    stateless = true
+}) => {
+    const handler = express();
+    handler.use(express.json());
+    handler.use(cors({
+        origin: '*',
+        methods: ['GET', 'POST', 'DELETE', 'OPTIONS'],
+        allowedHeaders: ['Content-Type', 'mcp-session-id', 'Last-Event-ID', 'mcp-protocol-version'],
+        exposedHeaders: ['mcp-session-id', 'mcp-protocol-version']
+    }));
+
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: stateless ? undefined : randomUUID,
+        retryInterval: 2000,
+    });
+    const server = await createInstance();
+    server.connect(transport);
+
+    handler.all('/', async (req, res) => {
+        const sessionId = req.headers['mcp-session-id'];
+        console.log(`\n${req.method} ${req.originalUrl}`, req.body, sessionId);
+        await transport.handleRequest(req, res, req.body);
+    });
+    return handler;
+}
+

package/src-dev/main.js

@@ -0,0 +1,6 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import createInstance from "@mcp/createInstance.js"
+
+const server = await createInstance();
+const transport = new StdioServerTransport();
+await server.connect(transport);