MCP Server Core + Adapter Framework

[prosdev]

Description

Build the foundation of the MCP server: the core protocol handler and the adapter framework. This establishes the extensibility system that all future adapters (built-in and custom) will use.

Goal: Create a robust, testable foundation that proves the adapter pattern works before building specific adapters.

Scope

MCP Server Core

• JSON-RPC 2.0 protocol implementation
• Message routing and request/response handling
• Error handling with structured error types
• Server lifecycle management (start, stop, health check)

Transport Layer

• Stdio transport (primary for v1)
• Transport interface for future HTTP support
• Message serialization/deserialization
• Process communication via stdin/stdout

Adapter Framework

• Base adapter interfaces (Adapter, ToolAdapter, ResourceAdapter)
• Adapter lifecycle hooks (initialize, shutdown, healthCheck)
• Adapter metadata system (name, version, description)
• Tool definition schema (JSON Schema based)
• Execution context (logger, config, formatter)

Adapter Registry

• Adapter registration and management
• Tool execution routing
• Adapter discovery from directory (basic)
• Error handling and validation

Acceptance Criteria

• MCP server correctly implements JSON-RPC 2.0 protocol
• Stdio transport sends/receives messages correctly
• Adapter interfaces are well-defined and documented
• Registry can register, initialize, and execute adapters
• Structured error handling throughout
• Unit tests for all core components (>80% coverage)
• Integration test with mock adapter
• TypeScript types are strict and comprehensive

Technical Requirements

JSON-RPC 2.0 Implementation

Handle standard MCP methods:

• initialize - Server capabilities and configuration
• tools/list - List available tools
• tools/call - Execute a tool
• resources/list - List available resources (future)
• prompts/list - List available prompts (future)

Adapter Interface

export abstract class Adapter {
  abstract readonly metadata: AdapterMetadata;
  abstract initialize(context: AdapterContext): Promise<void>;
  abstract shutdown?(): Promise<void>;
  abstract healthCheck?(): Promise<boolean>;
}

export abstract class ToolAdapter extends Adapter {
  abstract getToolDefinition(): ToolDefinition;
  abstract execute(args: Record<string, unknown>, context: ToolExecutionContext): Promise<ToolResult>;
  validate?(args: Record<string, unknown>): ValidationResult;
  estimateTokens?(args: Record<string, unknown>): number;
}

Error Types

interface AdapterError {
  code: string;           // e.g., 'NOT_INITIALIZED', 'INVALID_ARGS'
  message: string;        // Human-readable error
  details?: unknown;      // Additional context
  recoverable?: boolean;  // Can the AI retry?
  suggestion?: string;    // How to fix
}

Package Structure

packages/integrations/mcp-server/
├── src/
│   ├── index.ts                      # Entry point (stdio mode)
│   ├── server/
│   │   ├── MCPServer.ts              # Main server class
│   │   ├── transport/
│   │   │   ├── Transport.ts          # Interface
│   │   │   └── StdioTransport.ts     # Implementation
│   │   └── protocol/
│   │       ├── jsonrpc.ts            # JSON-RPC 2.0
│   │       └── types.ts              # MCP types
│   ├── adapters/
│   │   ├── Adapter.ts                # Base class
│   │   ├── ToolAdapter.ts            # Tool adapter base
│   │   ├── ResourceAdapter.ts        # Resource adapter base
│   │   ├── AdapterRegistry.ts        # Registry
│   │   └── types.ts
│   └── utils/
│       ├── logger.ts
│       ├── errors.ts
│       └── config.ts
├── tests/
│   ├── server/
│   │   ├── MCPServer.test.ts
│   │   ├── StdioTransport.test.ts
│   │   └── jsonrpc.test.ts
│   ├── adapters/
│   │   ├── AdapterRegistry.test.ts
│   │   ├── ToolAdapter.test.ts
│   │   └── MockAdapter.ts           # Test helper
│   └── integration/
│       └── server.integration.test.ts
├── package.json
├── tsconfig.json
└── README.md

Testing Strategy

Unit Tests

• JSON-RPC message parsing and generation
• Transport message send/receive
• Adapter registration and lifecycle
• Tool execution routing
• Error handling

Integration Tests

• Create mock adapter
• Register with server
• Send MCP messages via stdio
• Verify tool execution
• Test error scenarios

Edge Cases

• Invalid JSON-RPC messages
• Adapter initialization failures
• Tool execution errors
• Concurrent requests
• Graceful shutdown

Definition of Done

• All code passes linting, formatting, and type checking
• All tests passing with >= 80% coverage
• Mock adapter proves framework works
• Can send/receive JSON-RPC messages via stdio
• Error handling tested and documented
• README documents architecture and usage
• Code reviewed and approved

Success Metrics

• Mock adapter executes successfully
• Clean separation: protocol vs. adapter logic
• Easy to add new adapters (proven in Issue First Adapter + Formatters (SearchAdapter) #28)
• Zero TypeScript errors with strict mode
• Test suite runs in < 5 seconds

Branch: feat/mcp-server-core
Priority: High (blocks all other Epic #3 issues)
Estimate: 3 days
Parent Epic: #26 (Epic: MCP Integration)