MCP Server Rollup — dual ESM/CJS output, tree-shaking, npm library bundling

When to use Rollup vs esbuild for MCP server packages

Rollup is the conventional choice when your MCP server is a reusable library — a package that other projects install via npm rather than deploy directly. Its strengths for library distribution are tree-shaking (unused exports are dropped from consumer bundles), clean dual ESM/CJS output, and first-class support for generating declaration files via plugins.

For a self-contained MCP server that runs as a process (stdio, SSE, or HTTP), esbuild is simpler: one entry point, one output file, done. Rollup adds complexity that pays off only when downstream consumers import named exports from your package.

rollup.config.js with dual ESM and CJS output

// rollup.config.js
import { defineConfig } from 'rollup';
import esbuild from 'rollup-plugin-esbuild';        // fast TS transform
import nodeExternals from 'rollup-plugin-node-externals'; // auto-externals
import dts from 'rollup-plugin-dts';                // .d.ts bundle

const src = 'src/index.ts';

export default defineConfig([
  // --- JavaScript output (ESM) ---
  {
    input: src,
    output: {
      dir: 'dist/esm',
      format: 'esm',
      preserveModules: true,      // one output file per input file (better tree-shaking)
      preserveModulesRoot: 'src', // strip 'src/' prefix from output paths
      sourcemap: true,
    },
    plugins: [
      nodeExternals(),   // marks everything in node_modules as external automatically
      esbuild({
        target: 'node22',
        // esbuild handles TS transpilation; Rollup handles module graph + tree-shaking
      }),
    ],
  },

  // --- JavaScript output (CJS) ---
  {
    input: src,
    output: {
      dir: 'dist/cjs',
      format: 'cjs',
      preserveModules: true,
      preserveModulesRoot: 'src',
      sourcemap: true,
      exports: 'named',  // required for CJS: tells consumers how exports are structured
    },
    plugins: [
      nodeExternals(),
      esbuild({ target: 'node22' }),
    ],
  },

  // --- TypeScript declarations (.d.ts) ---
  {
    input: src,
    output: {
      file: 'dist/index.d.ts',
      format: 'esm',   // format doesn't matter for .d.ts — pick either
    },
    plugins: [
      nodeExternals(),
      dts(),   // bundles all .d.ts into a single declaration file
    ],
  },
]);

preserveModules: true is preferred over single-file bundling for library output: it preserves the module structure so bundlers used by downstream consumers (webpack, Rollup, esbuild) can tree-shake individual exports. A single-file bundle prevents tree-shaking because all exports are in one file.

package.json exports map for dual-format MCP packages

The exports field in package.json tells Node.js and bundlers which file to use for each import condition. A correctly structured exports map ensures that ESM consumers get .js files from dist/esm/, CJS consumers get files from dist/cjs/, and TypeScript consumers find the declaration file.

// package.json — for a dual-format MCP server library
{
  "name": "@myorg/mcp-server-search",
  "version": "1.0.0",
  "type": "module",         // default module system for .js files
  "exports": {
    ".": {
      "import": {
        "types":   "./dist/index.d.ts",
        "default": "./dist/esm/index.js"
      },
      "require": {
        "types":   "./dist/index.d.ts",
        "default": "./dist/cjs/index.js"
      }
    }
  },
  "main":  "./dist/cjs/index.js",   // fallback for old bundlers that ignore exports
  "module": "./dist/esm/index.js",  // unofficial but understood by some bundlers
  "types": "./dist/index.d.ts",     // fallback for TypeScript <4.7 (no exports resolution)
  "files": ["dist"],

  "peerDependencies": {
    "@modelcontextprotocol/sdk": "^1.4.0"
    // Declared as peer — consumers provide their own copy.
    // rollup-plugin-node-externals reads peerDependencies and marks them external.
  },
  "devDependencies": {
    "@modelcontextprotocol/sdk": "^1.4.0",
    "rollup": "^4.0.0",
    "rollup-plugin-esbuild": "^6.0.0",
    "rollup-plugin-node-externals": "^7.0.0",
    "rollup-plugin-dts": "^6.0.0",
    "typescript": "^5.5.0"
  },

  "scripts": {
    "build":     "rollup -c",
    "typecheck": "tsc --noEmit",
    "prepublishOnly": "npm run typecheck && npm run build"
  }
}

The types condition inside exports must come before default within each block — TypeScript resolves conditions in order and stops at the first match. If default appears first, TypeScript never sees the types pointer and falls back to the top-level "types" field, which works but produces worse IDE autocomplete in monorepos.

Manual external array vs rollup-plugin-node-externals

Without rollup-plugin-node-externals, you must list every package that should not be bundled. For MCP server packages with many dependencies this becomes error-prone — a missing entry means that package gets bundled, which can cause version conflicts at runtime.

// Without the plugin — manual, fragile:
export default {
  external: [
    '@modelcontextprotocol/sdk',
    'zod',
    'undici',
    // ...must be kept in sync with package.json manually
  ],
  // ...
};

// With rollup-plugin-node-externals — automatic:
import nodeExternals from 'rollup-plugin-node-externals';
export default {
  plugins: [
    nodeExternals({
      // By default, marks dependencies, peerDependencies, and optionalDependencies
      // as external. devDependencies are bundled unless include: 'devDependencies'.
      // Pass devDeps: true to also exclude devDependencies (rarely needed).
    }),
  ],
  // ...
};

One exception: if your MCP server depends on a pure-ESM package that doesn't ship CJS output, you may need to bundle it into the CJS build rather than marking it external. In that case, use the include option of rollup-plugin-node-externals to exclude specific packages from the auto-external list, allowing Rollup to bundle them.

Common failure modes