How the MCP Server Integrates with the McpServer Framework: A Deep Dive into deepwiki-mcp

The deepwiki-mcp repository implements a thin wrapper around the Model Context Protocol (MCP) SDK, providing factory functions to instantiate McpServer instances and connect them to STDIO, HTTP, or SSE transports through a unified CLI interface.

The regenrek/deepwiki-mcp project demonstrates how to build a production-ready MCP server by leveraging the official @modelcontextprotocol/sdk. This article examines how the codebase integrates with the McpServer framework, handles transport layer abstraction, and exposes a developer-friendly command-line interface for running the server in multiple modes.

Core Integration Architecture

The integration layer resides primarily in src/server.ts, which acts as a bridge between the MCP SDK and the application-specific logic. This file exports two critical functions: createServer for instantiation and startServer for transport binding.

Instantiating the McpServer

The createServer factory function wraps the SDK's McpServer class to enforce consistent initialization patterns. Located at lines 9-13 in src/server.ts, this function imports the concrete implementation from @modelcontextprotocol/sdk/server/mcp.js and returns it as the canonical McpServer type:

import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { McpServer as Server } from '@modelcontextprotocol/sdk/server/mcp.js'

export function createServer(options: { name: string, version: string }): McpServer {
  const { name, version } = options
  return new Server({ name, version })
}

This abstraction allows the rest of the application to remain agnostic about SDK version changes while maintaining strict type safety through the imported McpServer interface.

Transport Selection and Connection

The startServer function (lines 25-70 in src/server.ts) handles the second integration phase: connecting the instantiated server to a transport layer. This async function accepts a McpServer instance and StartOptions, then selects between three transport implementations based on the type parameter:

export async function startServer(
  server: McpServer,
  options: StartOptions = { type: 'stdio' },
): Promise<void> {
  if (options.type === 'stdio') { 
    // STDIO transport logic
  }
  if (options.type === 'http') { 
    // HTTP transport logic
  }
  // SSE case handling
}

Each transport branch instantiates its respective class (StdioServerTransport, RestServerTransport, or SSEServerTransport) and binds it to the server via await server.connect(transport). This unified connection pattern ensures consistent error handling and cleanup regardless of transport type.

CLI Entry Point and Tool Registration

The integration extends beyond the server core into the command-line interface defined in src/index.ts. This file bridges user input to the server framework using the citty CLI library.

The citty Command Interface

The CLI entry point defines a command named mcp-instruct that orchestrates the integration workflow. It parses command-line arguments to determine the transport mode, instantiates the server via createServer, and invokes startServer with the appropriate configuration:

const mode = args.http ? 'http' : args.sse ? 'sse' : 'stdio'
const mcp = createServer({ name: 'my-mcp-server', version })
deepwikiTool({ mcp } as McpToolContext)

if (mode === 'http') await startServer(mcp, { type: 'http', … })
else if (mode === 'sse') await startServer(mcp, { type: 'sse', … })
else await startServer(mcp, { type: 'stdio' })

This pattern allows developers to switch between STDIO, HTTP, and SSE modes using simple flags without modifying the underlying server implementation.

Registering Custom Tools

The integration supports extensibility through tool registration. The deepwikiTool function in src/tools/deepwiki.ts demonstrates how to augment the McpServer with custom capabilities. Tools receive the server instance through the McpToolContext interface and register themselves using the SDK's tool registration methods, keeping the core integration layer clean while allowing domain-specific functionality.

Transport Implementation Details

Each transport option in startServer addresses specific deployment scenarios, from local command-line piping to web-based event streaming.

STDIO Transport for Command-Line Pipelines

The STDIO transport uses StdioServerTransport to read from process.stdin and write to process.stdout. This mode is ideal for local development and piping scenarios where the MCP server acts as a subprocess to a host application.

HTTP Transport with RestServerTransport

The HTTP transport instantiates RestServerTransport, binding to a configurable port and endpoint. It starts a raw Node.js HTTP server that exposes the MCP protocol over RESTful endpoints, suitable for containerized deployments and direct API integration.

SSE Transport with EventSource Support

The SSE transport leverages SSEServerTransport to create an H3 router handling /sse and /messages endpoints. It runs a raw Node HTTP server that forwards Server-Sent Events compatible requests, enabling real-time streaming communication with web clients.

Code Examples

Starting a STDIO-based MCP Server

Useful for command-line pipelines and local development:

import { createServer, startServer } from './server'

const mcp = createServer({ name: 'demo', version: '1.0.0' })
await startServer(mcp, { type: 'stdio' })

Running an HTTP MCP Server on Port 8080

Ideal for containerized deployments and REST API integration:

import { createServer, startServer } from './server'

const mcp = createServer({ name: 'demo', version: '1.0.0' })
await startServer(mcp, { type: 'http', port: 8080, endpoint: '/mcp' })

Launching the SSE Variant for Real-Time Streaming

Enables EventSource-based communication with web clients:

import { createServer, startServer } from './server'

const mcp = createServer({ name: 'demo', version: '1.0.0' })
await startServer(mcp, { type: 'sse', port: 8000 })

Summary

• The deepwiki-mcp repository wraps the @modelcontextprotocol/sdk to provide a simplified interface for creating MCP servers.
• Integration occurs in three phases: instantiation via createServer in src/server.ts, transport selection via startServer, and CLI orchestration in src/index.ts.
• Three transport modes are supported: STDIO for pipelines, HTTP for REST APIs, and SSE for real-time streaming.
• Tool registration remains decoupled from the core integration, allowing domain-specific tools like deepwikiTool to extend functionality without modifying server infrastructure.

Frequently Asked Questions

How does the MCP server handle different transport protocols?

The startServer function in src/server.ts uses a conditional branching strategy to instantiate the appropriate transport class based on the type option. It supports StdioServerTransport for STDIO, RestServerTransport for HTTP, and SSEServerTransport for SSE, connecting each to the McpServer instance via the connect method.

What is the purpose of the createServer factory function?

The createServer function abstracts the instantiation of the SDK's McpServer class, enforcing consistent initialization parameters like name and version. This factory pattern insulates the application from SDK implementation changes while providing type-safe server creation through the imported McpServer interface from @modelcontextprotocol/sdk/server/mcp.js.

Can I register custom tools without modifying the core server files?

Yes, the architecture decouples tool registration from the integration layer. Tools like deepwikiTool in src/tools/deepwiki.ts receive the server instance through the McpToolContext interface and register themselves using SDK methods. This allows you to add domain-specific capabilities by creating new tool files without touching src/server.ts or src/index.ts.

Which file serves as the main entry point for running the server?

The src/index.ts file serves as the CLI entry point, defining the mcp-instruct command using the citty library. It parses command-line arguments to determine the transport mode, invokes createServer to build the server instance, registers available tools, and calls startServer to initiate the selected transport and begin accepting connections.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}