unplugin

unplugin-mcp provides a unified MCP server and a suite of built-in tools that integrate with common JavaScript build tools like Rollup and Vite through the unplugin framework. The server exposes an HTTP/SSE interface so MCP clients (including AI assistants) can query project structure, build configurations, dependencies, and control the build process. By wiring the plugin into a bundler workflow, you gain access to tools such as ModuleTool for dependency analysis, BuildConfigTool for inspecting build settings, BuildErrorTool for debugging, and optional custom tools you may develop with the UnpluginMcpTool interface. The server is designed to stay up in watch mode, enabling ongoing AI interaction during development.

To use it, start the MCP server alongside your project and connect an MCP client (like Cursor or your own client) to the server endpoint (for example, http://localhost:14514/mcp/sse). In your bundler config, install and enable the built-in MCP tools (ModuleTool, BuildConfigTool, BuildErrorTool) or create and register your own UnpluginMcpTool implementations. Once connected, the MCP client can request contextual information about your codebase, inspect build configurations, monitor dependencies, and even issue guidance or commands that influence the build process via the standard transport layer (HTTP/SSE).

Prerequisites

• Node.js (version 14+ recommended) and npm or pnpm
• A project using a JS build tool compatible with unplugin (e.g., Rollup, Vite, Webpack) if you plan to exercise the integration examples

Install the MCP package

• Using npm: npm install --save-dev unplugin-mcp

• Using pnpm: pnpm add -D unplugin-mcp

Basic usage in your project

1. Install the package as a development dependency (as shown above).
2. If you want to expose the MCP server via a node entry point, create a small launcher script that starts the server (see example below).
3. Start the MCP server and connect an MCP client (e.g., Cursor) to the server URL.

Example launcher (Node.js):

// start-mcp-server.js
const path = require('path');
// This script should initialize and start the MCP server provided by unplugin-mcp
// The exact initialization may vary depending on the version; this is a placeholder to show intent.
const { createMcpServer } = require('unplugin-mcp');

async function main() {
  const server = await createMcpServer({
    port: process.env.PORT ? parseInt(process.env.PORT, 10) : 14514,
    host: process.env.HOST || '0.0.0.0'
  });
  await server.start();
  console.log(`MCP server listening on ${server.host}:${server.port}`);
}

main().catch(err => {
  console.error(err);
  process.exit(1);
});

Run the launcher with:

node path/to/start-mcp-server.js

Note: The exact startup API may vary; refer to the library's current API for creating and starting the MCP server. If your project already uses a bundler plugin, you may rely on the plugin to initialize its internal MCP server during bundling as demonstrated in the README examples.

Tips and common considerations:

• The MCP server communicates over HTTP/SSE; ensure your environment allows cross-origin requests if you connect from a separate frontend or tool.
• The default port often used by MCP clients is 14514; adjust PORT in environment variables if needed.
• If you extend with custom UnpluginMcpTool implementations, you can expose project-specific data or control flows. Remember to register tools in the plugin configuration (provideUnpluginMcpTools).
• In watch mode, the server remains active after builds, enabling persistent AI interactions. If you restart your bundler, ensure the MCP server restarts cleanly as well.
• For Cursor integration, place your MCP server URL in ~/.config/cursor/mcp.json under mcpServers, using the URL that serves the SSE endpoint (e.g., http://localhost:14514/mcp/sse).
• If you upgrade to newer versions, verify compatibility for the built-in tools (ModuleTool, BuildConfigTool, BuildErrorTool, BundleSizeTool) across your current bundler (Rollup, Webpack, etc.).