mcp-server

Entrypoint — mcp-server

This file is consumed by Step 8 of the rewrite process. Apply when AUDIT_MANIFEST.projectType === "mcp-server".

Architecture Overview

src/stdio.ts          ← process entry; connects StdioServerTransport; never imported by tests
src/server.ts         ← McpServer factory; registers all tools; importable with no side effects
src/tools/<module>/   ← one folder per logical tool group (module)
src/lib/
  container.ts        ← wires HTTP client → services; exports service instances
  http-client.ts      ← axios/got client with auth interceptors + error normalization
src/config/           ← zod-validated env (from Step 2)
src/errors/           ← AppError hierarchy (from Step 4)

---

src/server.ts — McpServer Factory

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { config } from './config/index.js';
import { register<Module>Tools } from './tools/<module>/<module>.tool.js';
// one import per module in AUDIT_MANIFEST.mcpTools[*].module (deduplicated)

export function createServer(): McpServer {
  const server = new McpServer({
    name: config.app?.name ?? '<projectName>',
    version: process.env['npm_package_version'] ?? '0.0.0',
  });

  // Register tools in alphabetical module order
  register<Module>Tools(server);
  // ...

  return server;
}

server.ts must NOT call server.connect() — that is stdio.ts's job. This makes server.ts testable without side effects.

---

src/stdio.ts — Process Entry

import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { createServer } from './server.js';
import { logger } from './lib/logger.js';
import { config } from './config/index.js';

async function main(): Promise<void> {
  const server = createServer();
  const transport = new StdioServerTransport();

  await server.connect(transport);

  logger.info(
    {
      app: config.app?.name ?? 'mcp-server',
      env: config.env,
      profile: config.mcp?.activeProfile ?? 'default',
    },
    'MCP stdio server started',
  );
}

process.on('SIGTERM', () => {
  logger.info('SIGTERM received — shutting down');
  process.exit(0);
});

process.on('SIGINT', () => {
  logger.info('SIGINT received — shutting down');
  process.exit(0);
});

process.on('unhandledRejection', (reason) => {
  logger.fatal({ reason }, 'Unhandled promise rejection');
  process.exit(1);
});

void main().catch((err) => {
  logger.fatal({ err }, 'Failed to start MCP server');
  process.exit(1);
});