JauryAbreu/mcp-backend-server

MCP Backend Server

Overview

A professional Model Context Protocol (MCP) backend server built with TypeScript, implementing SOLID principles and Clean Architecture patterns. Features dual access modes: native MCP protocol for development and HTTP REST API for external integrations.

✨ Key Features

• 🏗️ SOLID Architecture: Full compliance with all 5 SOLID principles
• 🔧 Clean Architecture: Hexagonal (Ports & Adapters) pattern implementation
• 🚀 Dual Access: MCP protocol + HTTP REST API wrapper
• 🔍 Type Safety: Full TypeScript implementation with strict mode
• ✅ Comprehensive Testing: Unit tests with 100% coverage
• 📝 Domain-Driven: Rich domain models with validation
• 💉 Dependency Injection: IoC container for loose coupling
• 📊 Structured Logging: Centralized logging with different levels
• 🔒 Input Validation: Zod schema validation for all endpoints

🏛️ Architecture Overview

SOLID Principles Implementation

✅ Single Responsibility Principle (SRP)

• Controllers: Only handle HTTP requests/responses
• Services: Pure business logic implementation
• Repositories: Data access abstraction
• Validators: Input validation only
• Models: Domain entity representation

✅ Open/Closed Principle (OCP)

• Interface-based design allows extension without modification
• Plugin architecture for new tools and resources
• Strategy pattern for different implementations

✅ Liskov Substitution Principle (LSP)

• All implementations properly substitute their interfaces
• HttpClient can be replaced with any IHttpClient implementation
• Logger implementations are fully interchangeable

✅ Interface Segregation Principle (ISP)

• Focused interfaces (IHttpClient, ILogger, IResourceService)
• No forced dependencies on unused methods
• Client-specific interface design

✅ Dependency Inversion Principle (DIP)

• High-level modules don't depend on low-level modules
• Both depend on abstractions (interfaces)
• ServiceContainer manages all dependencies

🏗️ Layer Architecture

┌─────────────────────────────────────────────────────────────┐
│                    ADAPTERS LAYER                           │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │  HTTP REST API  │  │   MCP Protocol  │  │ Controllers  │ │
│  │   (Express)     │  │     (stdio)     │  │   Routes     │ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                  APPLICATION LAYER                          │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │    Services     │  │   Use Cases     │  │   Handlers   │ │
│  │ (Business Logic)│  │ (Orchestration) │  │ (MCP Tools)  │ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                    DOMAIN LAYER                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │    Entities     │  │  Value Objects  │  │  Interfaces  │ │
│  │ (User, Post,    │  │  (Validation)   │  │ (Contracts)  │ │
│  │  Comment)       │  │                 │  │              │ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                INFRASTRUCTURE LAYER                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │   HTTP Client   │  │     Logger      │  │   External   │ │
│  │ (node-fetch)    │  │   (Console)     │  │     APIs     │ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────────┘

📁 Project Structure

src/
├── adapters/                    # 🔌 External interfaces
│   ├── controllers/            # HTTP request handlers
│   │   ├── resourceController.ts
│   │   ├── toolController.ts
│   │   └── index.ts
│   ├── routes/                 # Route definitions
│   │   └── httpRoutes.ts
│   ├── validators/             # Input validation schemas
│   │   └── httpValidators.ts
│   ├── httpAdapter.ts          # Express server setup
│   ├── mcpAdapter.ts          # MCP SDK wrapper
│   └── mcpServerAdapter.ts    # MCP server configuration
├── application/                # 🎯 Business logic
│   ├── services/              # Core business services
│   │   ├── resourceService.ts # Resource operations
│   │   └── toolService.ts     # Tool operations
│   ├── interfaces/            # Dependency contracts
│   │   └── index.ts          # All interfaces
│   ├── container/             # Dependency injection
│   │   └── serviceContainer.ts
│   ├── resources/             # MCP resource handlers
│   │   └── resourceHandlers.ts
│   ├── tools/                 # MCP tool handlers
│   │   └── toolHandlers.ts
│   └── index.ts              # Layer exports
├── domain/                     # 🎭 Business entities
│   ├── user.ts               # User entity & validation
│   ├── post.ts               # Post entity & validation
│   ├── comment.ts            # Comment entity & validation
│   └── index.ts              # Domain exports
├── infrastructure/            # 🔧 Technical implementations
│   ├── httpClient.ts         # HTTP client implementation
│   ├── logger.ts             # Logging implementation
│   ├── fetchUtil.ts          # Legacy utility (deprecated)
│   └── index.ts              # Infrastructure exports
├── server.ts                 # MCP server entry point
└── httpServer.ts            # HTTP server entry point

🚀 Quick Start

Prerequisites

• Node.js ≥ 18.0.0
• npm or yarn

Installation

# Clone and install dependencies
git clone <repository-url>
cd mcp-example
npm install

Development Commands

# Build the project
npm run build

# Start MCP server (for MCP Inspector)
npm start

# Start HTTP REST API server
npm run start:http

# Run tests with coverage
npm test

# Lint and fix code
npm run lint
npm run format

🔌 API Endpoints

Base URL: http://localhost:3001

📊 Resources

• GET /api/users - Fetch all users
• GET /api/posts - Fetch all posts
• GET /api/comments?postId=<id> - Fetch comments (with optional filtering)

🔧 Tools

• POST /api/calculate - Mathematical operations
• POST /api/temperature - Temperature conversion

📖 Documentation

• GET /health - Health check
• GET /api/docs - Complete API documentation

Example Requests

Calculate

curl -X POST http://localhost:3001/api/calculate \
  -H "Content-Type: application/json" \
  -d '{"a": 10, "b": 5, "operation": "add"}'

Temperature Conversion

curl -X POST http://localhost:3001/api/temperature \
  -H "Content-Type: application/json" \
  -d '{"value": 25, "fromUnit": "celsius", "toUnit": "fahrenheit"}'

🧪 Testing

Test Coverage

• Unit Tests: All services, controllers, and utilities
• Integration Tests: Complete HTTP API workflow
• Domain Tests: Entity validation and transformation
• Infrastructure Tests: External integrations

# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run specific test file
npm test -- --testPathPattern=resourceController

🔧 Configuration

Environment Variables

# Copy example configuration
cp .env.example .env

# Available variables
NODE_ENV=development          # Environment mode
PORT=3001                    # HTTP server port
API_BASE_URL=https://...     # External API URL
LOG_LEVEL=debug              # Logging level

🚀 Deployment

Production Build

npm run build
NODE_ENV=production node dist/httpServer.js

Docker Support

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
EXPOSE 3001
CMD ["node", "dist/httpServer.js"]

🔧 Extension Guide

Adding New Resources

1. Create Domain Model (src/domain/)
2. Implement Service (src/application/services/)
3. Add Controller (src/adapters/controllers/)
4. Register Route (src/adapters/routes/)
5. Add Validation (src/adapters/validators/)
6. Write Tests (tests/)

Adding New Tools

1. Implement Service Logic (src/application/services/)
2. Create MCP Handler (src/application/tools/)
3. Add HTTP Controller (src/adapters/controllers/)
4. Define Validation Schema (src/adapters/validators/)
5. Register Routes (src/adapters/routes/)

Custom Implementations

// Example: Custom HTTP Client
export class CustomHttpClient implements IHttpClient {
  async fetch(url: string, options?: any): Promise<any> {
    // Your implementation
  }
}

// Register in ServiceContainer
const customClient = new CustomHttpClient();
container.register('httpClient', customClient);

📊 Monitoring & Logging

Log Levels

• DEBUG: Detailed execution information
• INFO: General operational messages
• WARN: Warning conditions
• ERROR: Error conditions

Sample Log Output

[INFO] Successfully fetched 10 users
[DEBUG] Processing GET /api/users request
[WARN] Invalid query parameters for comments request
[ERROR] Failed to fetch posts: HTTP 500

🤝 Contributing

1. Code Style: Follow existing TypeScript/ESLint configuration
2. Testing: Maintain 100% test coverage
3. Documentation: Update README for new features
4. Architecture: Follow SOLID principles and Clean Architecture
5. Commits: Use conventional commit messages

📋 Development Checklist

• SOLID Compliance: Each class has single responsibility
• Interface Segregation: No fat interfaces
• Dependency Injection: Use ServiceContainer
• Type Safety: Strict TypeScript mode
• Input Validation: Zod schemas for all inputs
• Error Handling: Proper error propagation
• Logging: Structured logging throughout
• Testing: Unit + integration tests
• Documentation: Comments in English

📚 Technology Stack

Core

• TypeScript 5.9.2 - Type-safe JavaScript
• Node.js 18+ - Runtime environment
• Zod 3.25.76 - Schema validation

MCP Integration

• @modelcontextprotocol/sdk 1.17.4 - MCP protocol support

HTTP Server

• Express 5.1.0 - Web application framework
• CORS 2.8.5 - Cross-origin resource sharing

Testing

• Jest 30.0.5 - Testing framework
• Supertest 7.1.4 - HTTP integration testing
• ts-jest 29.4.1 - TypeScript support for Jest

Development Tools

• ESLint 9.34.0 - Code linting
• Prettier 3.6.2 - Code formatting
• TypeScript ESLint - TypeScript-specific linting

👤 Author

Jaury Abreu
📧 abreuj03@thryv.com
🏢 Thryv, Inc.

📄 License

ISC License - see LICENSE file for details.

🔄 Version History

v1.0.0

• ✅ Initial release with SOLID architecture
• ✅ Clean Architecture implementation
• ✅ Dual MCP/HTTP access modes
• ✅ Comprehensive test coverage
• ✅ Full TypeScript implementation
• ✅ Dependency injection container
• ✅ Structured logging system