Building Custom MCP Servers with TypeScript: Complete Architecture & Deployment Guide

mkdir mcp-server-ts
cd mcp-server-ts
npm init -y
npm install typescript @types/node ts-node zod @modelcontextprotocol/sdk express @types/express @modelcontextprotocol/zod
npm install --save-dev @types/ws ws
npx tsc --init

// tsconfig.json
{
  "compilerOptions": {
    "target": "es2021",
    "module": "commonjs",
    "rootDir": "./src",
    "outDir": "./dist",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules"]
}

// src/schemas.ts
import {
  MCPRequestSchema,
  MCPResponseSchema,
  ToolDefinitionSchema,
  ResourceDefinitionSchema,
  PromptTemplateDefinitionSchema,
  ToolCallSchema,
  ToolResultSchema,
  ResourceFetchSchema,
  ResourceDataSchema,
  PromptTemplateRenderSchema,
  PromptTemplateOutputSchema,
} from '@modelcontextprotocol/zod';

// Export all necessary schemas for use throughout the server
export {
  MCPRequestSchema,
  MCPResponseSchema,
  ToolDefinitionSchema,
  ResourceDefinitionSchema,
  PromptTemplateDefinitionSchema,
  ToolCallSchema,
  ToolResultSchema,
  ResourceFetchSchema,
  ResourceDataSchema,
  PromptTemplateRenderSchema,
  PromptTemplateOutputSchema,
};

// Define custom tool/resource schemas if needed, extending base MCP types
// Example: A custom tool that takes a 'query' string
import { z } from 'zod';

export const SearchToolInputSchema = z.object({
  query: z.string().describe("The search query to execute."),
});

export const SearchToolOutputSchema = z.object({
  results: z.array(z.string()).describe("A list of search results."),
});

export const SearchToolDefinition = ToolDefinitionSchema.extend({
  name: z.literal("search"),
  description: z.literal("A tool for performing web searches."),
  input_schema: SearchToolInputSchema,
  output_schema: SearchToolOutputSchema,
});

export type SearchToolInput = z.infer<typeof SearchToolInputSchema>;
export type SearchToolOutput = z.infer<typeof SearchToolOutputSchema>;

// src/handlers.ts
import {
  MCPRequest,
  MCPResponse,
  ToolCall,
  ResourceFetch,
  PromptTemplateRender,
  ToolDefinition,
  ResourceDefinition,
  PromptTemplateDefinition,
} from '@modelcontextprotocol/sdk';
import {
  SearchToolInput,
  SearchToolOutput,
  SearchToolDefinition,
} from './schemas';

// --- Tool Implementations ---
async function executeSearchTool(input: SearchToolInput): Promise<SearchToolOutput> {
  console.log(`Executing search for: ${input.query}`);
  // Simulate an external API call
  await new Promise(resolve => setTimeout(resolve, 500));
  const results = [
    `Result 1 for "${input.query}"`,
    `Result 2 for "${input.query}"`,
  ];
  return { results };
}

// Map tool names to their execution functions
const toolExecutors: Record<string, (input: any) => Promise<any>> = {
  'search': executeSearchTool,
};

// --- Resource Implementations ---
async function fetchDocumentationResource(id: string): Promise<string> {
  console.log(`Fetching documentation for ID: ${id}`);
  // Simulate fetching from a database or file system
  await new Promise(resolve => setTimeout(resolve, 300));
  switch (id) {
    case 'mcp-overview':
      return "The Model Context Protocol (MCP) standardizes AI model interaction with external systems.";
    case 'sdk-usage':
      return "The @modelcontextprotocol/sdk provides utilities for building MCP clients and servers.";
    default:
      throw new Error(`Resource with ID '${id}' not found.`);
  }
}

// Map resource names to their fetch functions
const resourceFetchers: Record<string, (id: string) => Promise<any>> = {
  'documentation': fetchDocumentationResource,
};

// --- Prompt Template Implementations ---
async function renderSummaryTemplate(variables: Record<string, any>): Promise<string> {
  console.log(`Rendering summary template with variables: ${JSON.stringify(variables)}`);
  const { document, length } = variables;
  if (!document) throw new Error("Missing 'document' variable for summary template.");
  // Simulate a complex templating engine
  await new Promise(resolve => setTimeout(resolve, 100));
  return `Here is a ${length || 'brief'} summary of the document: "${document.substring(0, 50)}..."`;
}

// Map prompt template names to their render functions
const promptTemplateRenderers: Record<string, (variables: Record<string, any>) => Promise<string>> = {
  'summary': renderSummaryTemplate,
};

// --- MCP Request Handler ---
export async function handleMCPRequest(request: MCPRequest): Promise<MCPResponse> {
  const response: MCPResponse = {
    request_id: request.request_id,
    tool_results: [],
    resource_data: [],
    prompt_template_outputs: [],
    error: undefined,
  };

  try {
    // Handle tool calls
    if (request.tool_calls) {
      for (const call of request.tool_calls) {
        const executor = toolExecutors[call.name];
        if (!executor) {
          response.tool_results.push({
            call_id: call.call_id,
            error: `Tool '${call.name}' not found.`,
          });
          continue;
        }
        try {
          const output = await executor(call.input);
          response.tool_results.push({
            call_id: call.call_id,
            output: output,
          });
        } catch (toolError: any) {
          response.tool_results.push({
            call_id: call.call_id,
            error: toolError.message || 'Tool execution failed.',
          });
        }
      }
    }

    // Handle resource fetches
    if (request.resource_fetches) {
      for (const fetch of request.resource_fetches) {
        const fetcher = resourceFetchers[fetch.name];
        if (!fetcher) {
          response.resource_data.push({
            fetch_id: fetch.fetch_id,
            error: `Resource '${fetch.name}' not found.`,
          });
          continue;
        }
        try {
          const data = await fetcher(fetch.id);
          response.resource_data.push({
            fetch_id: fetch.fetch_id,
            data: data,
          });
        } catch (resourceError: any) {
          response.resource_data.push({
            fetch_id: fetch.fetch_id,
            error: resourceError.message || 'Resource fetch failed.',
          });
        }
      }
    }

    // Handle prompt template renders
    if (request.prompt_template_renders) {
      for (const render of request.prompt_template_renders) {
        const renderer = promptTemplateRenderers[render.name];
        if (!renderer) {
          response.prompt_template_outputs.push({
            render_id: render.render_id,
            error: `Prompt template '${render.name}' not found.`,
          });
          continue;
        }
        try {
          const output = await renderer(render.variables);
          response.prompt_template_outputs.push({
            render_id: render.render_id,
            output: output,
          });
        } catch (templateError: any) {
          response.prompt_template_outputs.push({
            render_id: render.render_id,
            error: templateError.message || 'Prompt template rendering failed.',
          });
        }
      }
    }

  } catch (e: any) {
    console.error("Unhandled error in MCP request handler:", e);
    response.error = e.message || 'Internal server error.';
  }

  return response;
}

// --- Server Capabilities (for /mcp/capabilities endpoint) ---
export const serverCapabilities = {
  tools: [
    SearchToolDefinition.parse({
      name: 'search',
      description: 'A tool for performing web searches.',
      input_schema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
      output_schema: { type: 'object', properties: { results: { type: 'array', items: { type: 'string' } } }, required: ['results'] },
    }),
  ] as ToolDefinition[],
  resources: [
    ResourceDefinition.parse({
      name: 'documentation',
      description: 'Provides access to internal documentation articles.',
      id_schema: { type: 'string' },
      data_schema: { type: 'string' },
    }),
  ] as ResourceDefinition[],
  prompt_templates: [
    PromptTemplateDefinition.parse({
      name: 'summary',
      description: 'Generates a summary of a given document.',
      variables_schema: {
        type: 'object',
        properties: {
          document: { type: 'string', description: 'The document content to summarize.' },
          length: { type: 'string', enum: ['brief', 'detailed'], description: 'Desired length of the summary.' }
        },
        required: ['document']
      },
      output_schema: { type: 'string' },
    }),
  ] as PromptTemplateDefinition[],
};

// src/stdioServer.ts
import { MCPRequestSchema, MCPResponseSchema } from './schemas';
import { handleMCPRequest } from './handlers';
import {
  readMCPMessage,
  writeMCPMessage,
  MCPMessage,
} from '@modelcontextprotocol/sdk/stdio';

async function startStdioServer() {
  console.log("MCP stdio server started. Waiting for input...");

  process.stdin.on('data', async (chunk) => {
    try {
      const messages = readMCPMessage(chunk);
      for (const message of messages) {
        if (message.type === 'request') {
          const parsedRequest = MCPRequestSchema.parse(message.payload);
          console.log(`Received MCP Request: ${parsedRequest.request_id}`);
          const response = await handleMCPRequest(parsedRequest);
          writeMCPMessage(process.stdout, { type: 'response', payload: response });
        } else {
          console.warn(`Received unexpected MCP message type: ${message.type}`);
        }
      }
    } catch (error: any) {
      console.error("Error processing stdio input:", error);
      // Attempt to send an error response if possible
      if (error.request_id) { // If we can extract request_id from a partially parsed request
        writeMCPMessage(process.stdout, {
          type: 'response',
          payload: {
            request_id: error.request_id,
            error: `Invalid MCP request: ${error.message}`,
          },
        });
      } else {
        // Fallback for unparseable requests
        console.error("Failed to parse incoming MCP request. Cannot send specific error response.");
      }
    }
  });

  process.stdin.on('end', () => {
    console.log("MCP stdio server stdin ended.");
  });

  process.stdin.on('error', (err) => {
    console.error("MCP stdio server stdin error:", err);
  });
}

if (require.main === module) {
  startStdioServer();
}

// src/sseServer.ts
import express from 'express';
import { v4 as uuidv4 } from 'uuid';
import { MCPRequestSchema, MCPResponseSchema } from './schemas';
import { handleMCPRequest, serverCapabilities } from './handlers';
import {
  MCPRequest,
  MCPResponse,
  MCPCapabilities,
} from '@modelcontextprotocol/sdk';

const app = express();
app.use(express.json()); // For parsing application/json

const PORT = process.env.PORT || 8080;

// Middleware to set SSE headers
const setSSEHeaders = (res: express.Response) => {
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');
  res.setHeader('X-Accel-Buffering', 'no'); // Disable Nginx buffering
};

// Endpoint for server capabilities
app.get('/mcp/capabilities', (req, res) => {
  res.json(serverCapabilities);
});

// SSE endpoint for MCP requests
app.post('/mcp/stream', async (req, res) => {
  setSSEHeaders(res);

  const requestId = uuidv4(); // Generate a unique ID for this request stream

  try {
    // Validate incoming request body
    const mcpRequest: MCPRequest = MCPRequestSchema.parse({
      request_id: requestId, // Override or ensure request_id is present
      ...req.body,
    });

    console.log(`Received SSE MCP Request: ${mcpRequest.request_id}`);

    // Send initial "request_received" event
    res.write(`event: request_received\n`);
    res.write(`data: ${JSON.stringify({ request_id: mcpRequest.request_id })}\n\n`);

    // Process the request
    const mcpResponse = await handleMCPRequest(mcpRequest);

    // Send the final "response" event
    res.write(`event: response\n`);
    res.write(`data: ${JSON.stringify(mcpResponse)}\n\n`);

  } catch (error: any) {
    console.error("Error processing SSE MCP request:", error);
    const errorResponse: MCPResponse = {
      request_id: requestId,
      error: `Invalid MCP request or internal server error: ${error.message}`,
    };
    res.write(`event: error\n`);
    res.write(`data: ${JSON.stringify(errorResponse)}\n\n`);
  } finally {
    res.end(); // Close the connection after sending response or error
  }
});

// Health check endpoint
app.get('/healthz', (req, res) => {
  res.status(200).send('OK');
});

export function startSseServer() {
  app.listen(PORT, () => {
    console.log(`MCP SSE server listening on port ${PORT}`);
  });
}

if (require.main === module) {
  startSseServer();
}

// src/index.ts
import { startStdioServer } from './stdioServer';
import { startSseServer } from './sseServer';

const SERVER_TYPE = process.env.MCP_SERVER_TYPE || 'sse'; // Default to SSE

if (SERVER_TYPE === 'stdio') {
  startStdioServer();
} else if (SERVER_TYPE === 'sse') {
  startSseServer();
} else {
  console.error(`Unknown MCP_SERVER_TYPE: ${SERVER_TYPE}. Must be 'stdio' or 'sse'.`);
  process.exit(1);
}

# Dockerfile
# Use a slim Node.js image for smaller size
FROM node:20-slim AS builder

WORKDIR /app

# Copy package.json and package-lock.json first to leverage Docker cache
COPY package*.json ./
RUN npm install --omit=dev

# Copy source code
COPY . .

# Build TypeScript code
RUN npm run build

# --- Production Stage ---
FROM node:20-slim

WORKDIR /app

# Copy only necessary files from the builder stage
COPY --from=builder /app/package*.json ./
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist

# Expose the port for the SSE server
EXPOSE 8080

# Set environment variable for SSE server type
ENV MCP_SERVER_TYPE=sse

# Command to run the SSE server
CMD ["node", "dist/index.js"]

docker build -t mcp-server-ts .

docker run -p 8080:8080 mcp-server-ts

curl -X POST -H "Content-Type: application/json" \
     -d '{
           "tool_calls": [
             { "call_id": "call-1", "name": "search", "input": { "query": "latest AI research" } }
           ],
           "resource_fetches": [
             { "fetch_id": "fetch-1", "name": "documentation", "id": "mcp-overview" }
           ],
           "prompt_template_renders": [
             { "render_id": "render-1", "name": "summary", "variables": { "document": "This is a very long document about the history of computing.", "length": "brief" } }
           ]
         }' \
     http://localhost:8080/mcp/stream

event: request_received
data: {"request_id":"<uuid>"}

event: response
data: {"request_id":"<uuid>","tool_results":[{"call_id":"call-1","output":{"results":["Result 1 for \"latest AI research\"","Result 2 for \"latest AI research\""]}}],"resource_data":[{"fetch_id":"fetch-1","data":"The Model Context Protocol (MCP) standardizes AI model interaction with external systems."}],"prompt_template_outputs":[{"render_id":"render-1","output":"Here is a brief summary of the document: \"This is a very long document about the history of compu...\""}]}