mcp-backend-server

JauryAbreu/mcp-backend-server

3.1

If you are the rightful owner of mcp-backend-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A professional Model Context Protocol (MCP) backend server built with TypeScript, implementing SOLID principles and Clean Architecture patterns.

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