refactor: make Server class framework-agnostic by moving express to separate module

[cytle]

refactor: make Server class framework-agnostic by moving express to separate module

• Move createMcpExpressApp and CreateMcpExpressAppOptions to src/server/express.ts
• Remove express import from src/server/index.ts to make Server class usable in browser environments
• Update all imports to use server/express.js instead of server/index.js for createMcpExpressApp
• Update documentation and comments to reference the new import path

This allows Server class to be used without forcing express dependency, making it framework-agnostic and browser-compatible.

Summary

This PR refactors the Server class to be framework-agnostic by moving Express-related functionality to a separate module. The createMcpExpressApp function and CreateMcpExpressAppOptions interface have been moved from src/server/index.ts to src/server/express.ts, and the express import has been removed from the main server module.

Motivation and Context

The Server class was previously importing express at the top level of src/server/index.ts, which created an unnecessary coupling to the Express framework. This prevented the Server class from being used in browser environments, as bundlers would attempt to resolve the Node.js-only express dependency.

Problem:

• Server class cannot be used in browser environments due to express dependency
• Unnecessary framework coupling limits usage with other frameworks (Fastify, Koa, Cloudflare Workers, etc.)
• All code importing Server was forced to include express even if not needed

Solution:

• Move Express-related functionality to src/server/express.ts
• Remove express import from src/server/index.ts
• Update all imports to use server/express.js for createMcpExpressApp
• This makes Server class framework-agnostic and browser-compatible

How Has This Been Tested?

• ✅ Updated all example files to import createMcpExpressApp from the new location
• ✅ Updated test files to use the new import path
• ✅ Verified that Server class no longer imports express directly
• ✅ Updated documentation and comments to reference the new import path
• ✅ Type checking passes (no TypeScript errors)
• ✅ All linting checks pass

Files updated:

• 11 example files in src/examples/server/
• 1 test file (src/server/index.test.ts)
• 2 transport files (src/server/sse.ts, src/server/streamableHttp.ts)
• Documentation (docs/server.md)

Breaking Changes

Yes, this is a breaking change for users importing createMcpExpressApp.

Users who were importing createMcpExpressApp from @modelcontextprotocol/sdk/server or @modelcontextprotocol/sdk/server/index.js need to update their imports to:
cript
// Before
import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server';
// or
import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/index.js';

// After
import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';Migration guide:

• All examples and tests have been updated to demonstrate the new import path
• The Server class itself remains unchanged and can still be imported from @modelcontextprotocol/sdk/server
• Only Express-related functionality (createMcpExpressApp, CreateMcpExpressAppOptions) has moved

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Design decisions:

1. Separate module approach: Instead of using conditional imports or making express optional, we chose to completely separate Express functionality into its own module. This provides the cleanest separation of concerns and makes it explicit when Express is being used.

2. No re-exports: We intentionally did not re-export createMcpExpressApp from index.ts to avoid any possibility of the express dependency being pulled in when importing Server. Users must explicitly import from server/express.js if they need Express functionality.

3. Backward compatibility: While this is a breaking change, the migration is straightforward - users just need to update their import path. The functionality itself remains identical.

Benefits:

• ✅ Server class can now be used in browser environments
• ✅ No forced express dependency when using Server class
• ✅ Framework-agnostic design allows use with any HTTP framework
• ✅ Clear separation between core server functionality and Express-specific utilities

Related issue: This addresses the concern raised in the GitHub issue about making Server class framework-agnostic.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/sdk@1223

commit: 8265db1

[cytle]

Related commit: 09623e2

[cytle]

Related issue: #1222

[pcarleton]

LGTM

I double checked we didn't miss any references.