Architecture Overview

System Architecture

The Express REST API and MCP Server Framework is a TypeScript-based development framework that provides both REST API endpoints and MCP (Model Context Protocol) server interfaces for LLMs.

Core Components

  1. Application Layer
  2. Express.js REST API server
  3. Route versioning system
  4. Middleware pipeline (authentication, validation, caching, rate limiting)
  5. Health check endpoints (/health, /health/ready, /health/live)
  6. MCP configuration endpoints (/mcp/config, /mcp/info)

  7. Graceful shutdown handlers

  8. Business Logic Layer

  9. Controllers (request handlers with MCP exposure support)
  10. Services (reusable business logic)

  11. Models (Mongoose/Sequelize with schema descriptions)

  12. MCP Layer

  13. Models MCP Server (exposes data as resources and tools)
  14. Controllers MCP Server (exposes controller methods as tools)
  15. Services MCP Server (exposes service methods as tools)
  16. Unified MCP Server (combines all MCP servers)
  17. Streamable HTTP transport at GET/POST /mcp/http for Cursor and other MCP clients (when config.enableMcp is true)
  18. Per-model tools: create_<model>, create_many_<model>, update_<model>, delete_<model>; resources: <model>://list, <model>://{id}, <model>://search
  19. Auto-registration system for generated services

  20. Configuration generation endpoints (/mcp/config, /mcp/info) for LLM client setup

  21. Queue System

  22. Bull queue for background job processing
  23. Job processors for async operations
  24. Scheduled jobs with cron support

  25. Graceful queue shutdown

  26. Data Layer

  27. MongoDB (via Mongoose) - Main and Log databases
  28. SQL databases (via Sequelize) - Optional
  29. Redis (caching and queue)
  30. Connection retry logic with exponential backoff

  31. Centralized database initialization

  32. Infrastructure Layer

  33. Database initialization service
  34. Connection health monitoring
  35. Retry logic with exponential backoff
  36. Graceful shutdown service

Execution Order

The application follows a strict initialization sequence:

  1. Module Load: Configuration, database objects, queues, models
  2. Database Initialization: All connections awaited with retry logic
  3. Express App: Created and configured
  4. Routes: Loaded dynamically using ES modules
  5. Server: Starts listening
  6. MCP: Initialized after databases ready

MCP Integration

The framework automatically exposes: - Model data as MCP resources (read-only access) - Controller methods as MCP tools (with selective exposure via JSDoc annotations) - Schema field descriptions for LLM context understanding - Auto-registration of generated services

TypeScript Migration

All code has been migrated to TypeScript with: - Strict type checking - Type definitions for all modules - Path aliases for cleaner imports - Source maps for debugging - ES module imports (dynamic route loading)

Queue System (Bull)

Replaced Kue with Bull for: - Better Redis integration - Improved job processing - Repeatable jobs for scheduling - Better error handling and retry logic - Graceful shutdown support

Reliability Features

  • Connection Retry: Exponential backoff for database connections
  • Health Checks: Comprehensive health monitoring endpoints
  • Graceful Shutdown: Proper resource cleanup on termination
  • Error Handling: Comprehensive error handling throughout
  • Execution Order: Guaranteed correct initialization sequence