feat: Add Vercel serverless deployment support #42

nickytonline · 2025-11-20T01:54:15Z

Overview

This PR adds Vercel serverless deployment support to the MCP TypeScript template, enabling easy deployment to Vercel's edge network without managing infrastructure.

What's New

🚀 Serverless Architecture

Converted Express-based server to Vercel serverless functions
Created /api/mcp.ts for MCP protocol handling
Created /api/index.ts for server information endpoint

📦 Shared Libraries

Moved common code to /lib directory for reuse across serverless functions
lib/config.ts - Environment configuration
lib/logger.ts - Structured logging with Pino
lib/utils.ts - MCP helper utilities

⚙️ Configuration

Added vercel.json with optimized serverless settings
Updated package.json with Vercel dependencies and scripts
Updated tsconfig.json to support multi-directory structure
Updated .gitignore for Vercel-specific files

📚 Documentation

README.vercel.md - Comprehensive deployment guide
VERCEL_GUIDE.md - Quick reference for developers

Key Features

✅ One-click deployment to Vercel
✅ Automatic scaling based on demand
✅ Zero infrastructure management
✅ Compatible with existing Express version
✅ TypeScript with full type safety
✅ Development server with hot reload
✅ Production-optimized builds

Architecture

Vercel Serverless Functions
│
├── /api/index.ts    → GET /      (Server info)
├── /api/mcp.ts      → POST /mcp  (MCP protocol)
│
└── /lib/           → Shared utilities
    ├── config.ts
    ├── logger.ts
    └── utils.ts

Usage

Local Development

npm install
npm run dev

Deploy to Vercel

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

Or use the one-click deploy button!

Important Notes

⚠️ Session Management Limitation

The current implementation uses in-memory session storage, which is not production-ready for serverless:

Sessions are lost when functions scale down
Not shared across function instances
Works for demos and light testing only

For production, implement persistent storage using:

Vercel KV (recommended)
Redis
Any other persistent datastore

See README.vercel.md for implementation examples.

💡 Benefits Over Express

No server management - Vercel handles infrastructure
Automatic scaling - Scale to zero, scale to millions
Global distribution - Deploy to edge locations worldwide
Pay-per-use - Only pay for actual usage

🔄 Backwards Compatible

The original Express server in src/index.ts remains functional. You can still:

npm run dev:express  # Run Express server
npm start            # Production Express server

Testing

Test the deployed serverless functions:

# Get server info
curl https://your-deployment.vercel.app/

# Initialize MCP session
curl -X POST https://your-deployment.vercel.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    },
    "id": 1
  }'

Files Changed

New Files

api/index.ts - Server info endpoint
api/mcp.ts - MCP protocol handler
lib/config.ts - Shared configuration
lib/logger.ts - Shared logging
lib/utils.ts - Shared utilities
vercel.json - Vercel platform config
README.vercel.md - Deployment documentation
VERCEL_GUIDE.md - Quick reference guide

Modified Files

package.json - Added Vercel dependencies and scripts
tsconfig.json - Updated for multi-directory structure
.gitignore - Added .vercel directory

Next Steps

After merging:

Update main README to mention serverless option
Add deployment status badge
Create example environment variables
Add Vercel KV session storage example
Set up CI/CD with Vercel

Documentation

📖 Complete guide: README.vercel.md
🚀 Quick start: VERCEL_GUIDE.md
🔗 Vercel Documentation
🔗 MCP Documentation

Questions?

Feel free to ask questions or request changes. This implementation prioritizes:

Ease of deployment
Developer experience
Production best practices (with noted limitations)
Backwards compatibility

Ready to deploy! 🚀

Copilot

Pull Request Overview

This PR adds Vercel serverless deployment support to the MCP TypeScript template, enabling deployment to Vercel's serverless platform alongside the existing Express server implementation.

Key Changes

Introduced serverless function handlers in /api directory for MCP protocol handling and server information endpoints
Created shared library code in /lib for configuration, logging, and utilities that can be reused across both Express and serverless implementations
Added Vercel-specific configuration and comprehensive deployment documentation

Reviewed Changes

Copilot reviewed 9 out of 11 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
api/mcp.ts	Main MCP protocol handler for Vercel serverless, includes session management and request routing
api/index.ts	Server information endpoint returning metadata about the MCP server
lib/config.ts	Shared environment configuration with Zod validation
lib/logger.ts	Shared structured logging setup with Pino
lib/utils.ts	Shared MCP helper utilities for formatting responses
vercel.json	Vercel platform configuration for serverless functions, rewrites, and runtime settings
package.json	Updated build scripts for Vercel deployment, added Vercel dependencies, included lib/ in build
tsconfig.json	Expanded to include api/ and lib/ directories, changed from noEmit to outDir configuration
.gitignore	Added .vercel directory exclusion
README.vercel.md	Comprehensive deployment guide with architecture details and production recommendations
VERCEL_GUIDE.md	Quick reference guide for Vercel serverless deployment

Copilot · 2025-11-20T02:02:51Z

api/mcp.ts

+      const expressReq = {
+        body: req.body,
+        headers: req.headers,
+        method: req.method,
+      };
+
+      const expressRes = {
+        status: (code: number) => {
+          res.status(code);
+          return expressRes;
+        },
+        setHeader: (name: string, value: string) => {
+          res.setHeader(name, value);
+          return expressRes;
+        },
+        json: (data: any) => {
+          res.json(data);
+        },
+        send: (data: any) => {
+          res.send(data);
+        },
+        end: () => {
+          res.end();
+        },
+      };
+
+      await transport.handleRequest(expressReq as any, expressRes as any, req.body);
+      return;
+    }
+
+    // Handle existing session requests
+    if (sessionId && transports[sessionId]) {
+      const transport = transports[sessionId];
+
+      const expressReq = {
+        body: req.body,
+        headers: req.headers,
+        method: req.method,
+      };
+
+      const expressRes = {
+        status: (code: number) => {
+          res.status(code);
+          return expressRes;
+        },
+        setHeader: (name: string, value: string) => {
+          res.setHeader(name, value);
+          return expressRes;
+        },
+        json: (data: any) => {
+          res.json(data);
+        },
+        send: (data: any) => {
+          res.send(data);
+        },
+        end: () => {
+          res.end();
+        },
+      };


Code duplication: The Express request/response adapter logic is duplicated between lines 82-106 and 116-140. Consider extracting this into a reusable function to reduce duplication and improve maintainability.

Example:

function createExpressAdapter(res: VercelResponse) { return { status: (code: number) => { res.status(code); return expressRes; }, setHeader: (name: string, value: string) => { res.setHeader(name, value); return expressRes; }, json: (data: any) => { res.json(data); }, send: (data: any) => { res.send(data); }, end: () => { res.end(); }, }; }

Copilot · 2025-11-20T02:02:51Z

api/mcp.ts

+) {
+  // Set CORS headers for API access
+  res.setHeader("Access-Control-Allow-Credentials", "true");
+  res.setHeader("Access-Control-Allow-Origin", "*");


Setting Access-Control-Allow-Credentials: true with Access-Control-Allow-Origin: * is not allowed by the CORS specification and will cause browsers to reject the response. If you need credentials, specify an explicit origin instead of *, or remove the credentials header if not needed.

See: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSNotSupportingCredentials

Suggested change

res.setHeader("Access-Control-Allow-Origin", "*");

res.setHeader("Access-Control-Allow-Origin", req.headers.origin || "");

Copilot · 2025-11-20T02:02:52Z

lib/config.ts

+    try {
+      config = configSchema.parse(process.env);
+    } catch (error) {
+      console.error("❌ Invalid environment configuration:", error);


According to the project's coding guidelines, console.error should not be used. Use structured logging with the logger from logger.ts instead. However, in this specific case where the config is being initialized and the logger depends on the config, this creates a circular dependency. Consider restructuring to use a basic logger initialization that doesn't depend on config, or document this as an acceptable exception.

Copilot · 2025-11-20T02:02:52Z

package.json

  "scripts": {
-    "build": "vite build",
-    "dev": "node --watch src/index.ts",
+    "build": "tsc",


[nitpick] The build command was changed from vite build to tsc, but vite is still listed as a devDependency and not removed. If Vite is no longer needed for the build process, consider removing it from dependencies to reduce package size. If it's still used elsewhere, this is fine.

Copilot · 2025-11-20T02:02:52Z

vercel.json

+  "buildCommand": "npm run build",
+  "outputDirectory": "dist",


The buildCommand and outputDirectory configuration may conflict with Vercel's automatic TypeScript compilation for serverless functions. Vercel automatically compiles TypeScript files in the api/ directory - you typically don't need these settings for serverless functions. Consider removing these lines or documenting why they're needed if there's a specific use case.

Suggested change

"buildCommand": "npm run build",

"outputDirectory": "dist",

Copilot · 2025-11-20T02:02:53Z

api/mcp.ts

+import { logger } from "../logger.js";
+import { getConfig } from "../config.js";


The imports are pointing to incorrect paths. The logger and config modules are in the lib/ directory, not at the root level. These imports should be:

import { logger } from "../lib/logger.js";

import { getConfig } from "../lib/config.js";

Suggested change

import { logger } from "../logger.js";

import { getConfig } from "../config.js";

import { logger } from "../lib/logger.js";

import { getConfig } from "../lib/config.js";

Copilot · 2025-11-20T02:02:53Z

api/mcp.ts

+        json: (data: any) => {
+          res.json(data);
+        },
+        send: (data: any) => {


[nitpick] The use of any type for the data parameter in the json and send methods reduces type safety. Consider using unknown or a more specific type to maintain better type checking.

Suggested change

json: (data: any) => {

res.json(data);

},

send: (data: any) => {

json: (data: unknown) => {

res.json(data);

},

send: (data: unknown) => {

Copilot · 2025-11-20T02:02:54Z

package.json

    "pino": "^10.1.0",
-    "pino-pretty": "^13.1.2"
+    "pino-pretty": "^13.1.2",
+    "zod": "^3.24.1"


[nitpick] zod has been moved from devDependencies to dependencies. This is correct since it's now used at runtime in lib/config.ts for environment variable validation. However, it was previously only in devDependencies, which means the original src/config.ts also uses it at runtime. Consider also checking if zod should have been in dependencies all along in the original Express version.

Copilot · 2025-11-20T02:02:54Z

VERCEL_GUIDE.md

+
+### Option 2: GitHub Integration
+1. Connect repository to Vercel
+2. Select the `vercel-serverless` branch


The documentation references a vercel-serverless branch. Ensure this branch name is correct and will exist when this is merged, or update it to reference the appropriate branch (e.g., main if merging there).

Suggested change

2. Select the `vercel-serverless` branch

2. Select the `main` branch

Copilot · 2025-11-20T02:02:54Z

package.json

+    "lint": "eslint src/ api/",
+    "lint:fix": "eslint src/ api/ --fix",
+    "format": "prettier --write '{src,api}/**/*.ts'",
+    "format:check": "prettier --check '{src,api}/**/*.ts'",


The lint and format scripts should include the lib/ directory since new shared code has been added there. Update these scripts to:

"lint": "eslint src/ api/ lib/"

"lint:fix": "eslint src/ api/ lib/ --fix"

"format": "prettier --write '{src,api,lib}/**/*.ts'"

"format:check": "prettier --check '{src,api,lib}/**/*.ts'"

Suggested change

"lint": "eslint src/ api/",

"lint:fix": "eslint src/ api/ --fix",

"format": "prettier --write '{src,api}/**/*.ts'",

"format:check": "prettier --check '{src,api}/**/*.ts'",

"lint": "eslint src/ api/ lib/",

"lint:fix": "eslint src/ api/ lib/ --fix",

"format": "prettier --write '{src,api,lib}/**/*.ts'",

"format:check": "prettier --check '{src,api,lib}/**/*.ts'",

nickytonline added 12 commits November 19, 2025 20:49

feat: add Vercel configuration for serverless deployment

421e14a

feat: add Vercel serverless MCP handler

a2cb02e

feat: add index endpoint for serverless deployment

87889a2

feat: update package.json for Vercel serverless deployment

27f97e3

feat: update tsconfig for serverless API directory

a180809

feat: add Vercel directory to gitignore

ed7cb1e

feat: add shared utils library

3a1e671

feat: add shared config library

daeda8a

feat: add shared logger

0394b8b

feat: update tsconfig to include lib directory

7336b6e

docs: add comprehensive Vercel deployment README

97f53c0

docs: add quick reference guide for serverless branch

3cc6ad8

Copilot AI review requested due to automatic review settings November 20, 2025 01:54

Copilot started reviewing on behalf of nickytonline November 20, 2025 01:54 View session

Copilot finished reviewing on behalf of nickytonline November 20, 2025 02:01

Copilot AI reviewed Nov 20, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Add Vercel serverless deployment support #42

feat: Add Vercel serverless deployment support #42

Uh oh!

nickytonline commented Nov 20, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Nov 20, 2025

Uh oh!

Copilot AI Nov 20, 2025

Uh oh!

Copilot AI Nov 20, 2025

Uh oh!

Copilot AI Nov 20, 2025

Uh oh!

Copilot AI Nov 20, 2025

Uh oh!

Copilot AI Nov 20, 2025

Uh oh!

Copilot AI Nov 20, 2025

Uh oh!

Copilot AI Nov 20, 2025

Uh oh!

Copilot AI Nov 20, 2025

Uh oh!

Copilot AI Nov 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	res.setHeader("Access-Control-Allow-Origin", "*");
	res.setHeader("Access-Control-Allow-Origin", req.headers.origin \|\| "");

		import { logger } from "../logger.js";
		import { getConfig } from "../config.js";

	2. Select the `vercel-serverless` branch
	2. Select the `main` branch

feat: Add Vercel serverless deployment support #42

Are you sure you want to change the base?

feat: Add Vercel serverless deployment support #42

Uh oh!

Conversation

nickytonline commented Nov 20, 2025

Overview

What's New

🚀 Serverless Architecture

📦 Shared Libraries

⚙️ Configuration

📚 Documentation

Key Features

Architecture

Usage

Local Development

Deploy to Vercel

Important Notes

⚠️ Session Management Limitation

💡 Benefits Over Express

🔄 Backwards Compatible

Testing

Files Changed

New Files

Modified Files

Next Steps

Documentation

Questions?

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes

Reviewed Changes

Uh oh!

Copilot AI Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants