# scitara-cto/dynamic-mcp-server architecture

> Architecture diagram of the GitHub repository scitara-cto/dynamic-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/scitara-cto/dynamic-mcp-server
- Repository: https://github.com/scitara-cto/dynamic-mcp-server

## Overview

##### Project Type and Purpose
- This is a backend framework—a Node.js/TypeScript server—for hosting Model Context Protocol (MCP) AI tools.
- It provides HTTP transport, API‐key authentication, user management, dynamic tool loading/sharing, and a MongoDB‐backed persistence layer.
- It is extensible: downstream projects can register new handler packages (i.e., plugin modules) and add custom HTTP routes or DB collections.

##### File Structure
- src/index.ts: entry point that wires up configuration, HTTP server, and MCP server.
- src/config: centralized config loader (e.g., environment, constants).
- src/http: custom HTTP server, routing (health, streamable‐HTTP/MCP endpoint), authentication middleware.
- src/handlers: three core handler packages—user, tool, prompt management—each organized by actions (add, delete, list, update, etc.).
- src/services: business‐logic layer (PromptService, ToolService, EmailService).
- src/db: repository + model layer (Mongoose or equivalent) for User, Tool, Prompt.
- src/mcp: MCP transport server implementation (streamable protocol).
- src/utils: cross‐cutting utilities (logger, etc.).

##### README for Additional Insights
- Authentication: API‐key lookup in MongoDB.
- Transport: legacy vs. streamable HTTP `/mcp` endpoint.
- Extensibility: handler packages register tools at runtime.
- Tool argument mapping: templated config.args resolved per invocation.

##### Main Components and Interactions
a. Components
– Configuration Loader (env, constants)
– HTTP Layer:
- HTTP Server
- Routing Module (health, MCP streams)
- Auth Middleware (API‐key verifier)
– MCP Server (streamable protocol implementation)
– Handler Packages (plugins):
- UserManagementHandler
- ToolManagementHandler
- PromptManagementHandler
- Custom downstream handlers
– Service Layer: PromptService, ToolService, EmailService
– Repository Layer: PromptRepository, ToolRepository, UserRepository
– Data Models: Prompt, Tool, User
– Persistence: MongoDB
– Utility Components: Logger
– External Integrations: e.g., external HTTP APIs for tools (weather, etc.)

b. Relationships / Data Flow
1. Client request → HTTP Server
2. Routing → API Key Auth Middleware
3. Authenticated request → `/mcp` handler or REST routes
4. `/mcp` handler dispatches to MCP Server
5. MCP Server invokes relevant Handler Package (based on tool namespace)
6. Handler executes one of its Actions → calls Service
7. Service applies business rules → calls Repository
8. Repository CRUDs MongoDB → returns Models to Service
9. Service returns result up to Handler → MCP Server → HTTP Server → Client
10. For email notifications, Service → EmailService → external SMTP/API

c. Architectural Patterns and Principles
– Layered Architecture (HTTP → Handlers → Services → Repositories → DB)
– Repository Pattern (abstract data access)
– Plugin / Extension Pattern (handler packages as first‐class modules)
– Dependency Injection (config & services wired at startup)
– Single‐Responsibility (each layer has distinct role)

d. Key Technologies
– Node.js with TypeScript
– Custom HTTP server (in `src/http`)
– Streamable HTTP MCP protocol (`src/mcp`)
– MongoDB (via Mongoose‐style models)
– Jest for testing
– EmailService for notifications

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Bootstrap and Config
    Entry["Application Bootstrap\n(src/index.ts)"]:::business
    Config["Configuration Loader\n(src/config/index.ts)"]:::util

    Entry -->|loads| Config
    Entry -->|wires| HTTPServer
    Entry -->|wires| MCPServer
    Entry -->|registers| HandlerRegistration

    %% HTTP Transport Layer
    subgraph "HTTP Layer"
        direction TB
        HTTPServer["HTTP Server\n(src/http/http-server.ts)"]:::transport
        RoutingHealth["Health Route\n(src/http/routes/health.ts)"]:::transport
        RoutingStream["Streamable MCP Route\n(src/http/routes/streamable-http.ts)"]:::transport
        AuthMiddleware["Auth Middleware\n(src/http/services/auth.ts)"]:::transport
        HTTPTypes["HTTP Types\n(src/http/types.ts)"]:::transport

        HTTPServer -->|uses| HTTPTypes
        HTTPServer -->|routes to| RoutingHealth
        HTTPServer -->|routes to| RoutingStream
        RoutingHealth -->|passes through| AuthMiddleware
        RoutingStream -->|passes through| AuthMiddleware
        AuthMiddleware -->|authenticates| Entry
    end

    %% MCP Transport Layer
    subgraph "MCP Layer"
        direction TB
        MCPServer["MCP Server\n(src/mcp/server.ts)"]:::transport
        MCPTypes["MCP Types\n(src/mcp/types.ts)"]:::transport

        RoutingStream -->|invokes| MCPServer
        MCPServer -->|uses| MCPTypes
    end

    %% Handler Layer
    subgraph "Handler Packages"  
        direction TB
        HandlerRegistration["Handler Registration\n(server.registerHandler)"]:::business
        UserHandler["UserManagementHandler\n(src/handlers/userManagementHandler/index.ts)"]:::business
        ToolHandler["ToolManagementHandler\n(src/handlers/toolManagementHandler/index.ts)"]:::business
        PromptHandler["PromptManagementHandler\n(src/handlers/promptManagementHandler/index.ts)"]:::business
        CustomHandlers["Custom Handlers\n(downstream)"]:::business

        HandlerRegistration -->|loads at runtime| UserHandler
        HandlerRegistration -->|loads at runtime| ToolHandler
        HandlerRegistration -->|loads at runtime| PromptHandler
        HandlerRegistration -->|loads at runtime| CustomHandlers

        MCPServer -->|dispatches to| UserHandler
        MCPServer -->|dispatches to| ToolHandler
        MCPServer -->|dispatches to| PromptHandler
        MCPServer -->|dispatches to| CustomHandlers
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        PromptService["PromptService\n(src/services/PromptService.ts)"]:::business
        ToolService["ToolService\n(src/services/ToolService.ts)"]:::business
        EmailService["EmailService\n(src/services/EmailService.ts)"]:::business
    end

    UserHandler -->|calls| PromptService
    UserHandler -->|calls| ToolService
    UserHandler -->|calls| EmailService
    ToolHandler -->|calls| ToolService
    PromptHandler -->|calls| PromptService

    %% Repository and Models Layer
    subgraph "Data Access Layer"
        direction TB
        PromptRepo["PromptRepository\n(src/db/repositories/PromptRepository.ts)"]:::data
        ToolRepo["ToolRepository\n(src/db/repositories/ToolRepository.ts)"]:::data
        UserRepo["UserRepository\n(src/db/repositories/UserRepository.ts)"]:::data
        DBConnection["DB Connection\n(src/db/connection.ts)"]:::data

        PromptRepo -->|CRUD| PromptModel
        ToolRepo -->|CRUD| ToolModel
        UserRepo -->|CRUD| UserModel
        DBConnection -->|connects| MongoDB
    end

    subgraph "Data Models"
        direction TB
        PromptModel["Prompt Model\n(src/db/models/Prompt.ts)"]:::data
        ToolModel["Tool Model\n(src/db/models/Tool.ts)"]:::data
        UserModel["User Model\n(src/db/models/User.ts)"]:::data
    end

    PromptService -->|calls| PromptRepo
    ToolService -->|calls| ToolRepo
    EmailService -->|calls| UserRepo

    %% Utilities and External Integrations
    Logger["Logger Utility\n(src/utils/logger.ts)"]:::util
    MongoDB["MongoDB"]:::external
    EmailAPI["External Email API/SMTP"]:::external

    Entry -->|uses| Logger
    EmailService -->|sends via| EmailAPI
    DBConnection -->|to| MongoDB

    %% Click Events
    click Entry "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/index.ts"
    click Config "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/config/index.ts"
    click HTTPServer "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/http/http-server.ts"
    click RoutingHealth "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/http/routes/health.ts"
    click RoutingStream "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/http/routes/streamable-http.ts"
    click AuthMiddleware "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/http/services/auth.ts"
    click HTTPTypes "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/http/types.ts"
    click MCPServer "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/mcp/server.ts"
    click MCPTypes "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/mcp/types.ts"
    click UserHandler "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/handlers/userManagementHandler/index.ts"
    click ToolHandler "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/handlers/toolManagementHandler/index.ts"
    click PromptHandler "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/handlers/promptManagementHandler/index.ts"
    click PromptService "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/services/PromptService.ts"
    click ToolService "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/services/ToolService.ts"
    click EmailService "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/services/EmailService.ts"
    click PromptRepo "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/db/repositories/PromptRepository.ts"
    click ToolRepo "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/db/repositories/ToolRepository.ts"
    click UserRepo "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/db/repositories/UserRepository.ts"
    click DBConnection "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/db/connection.ts"
    click PromptModel "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/db/models/Prompt.ts"
    click ToolModel "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/db/models/Tool.ts"
    click UserModel "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/db/models/User.ts"
    click Logger "https://github.com/scitara-cto/dynamic-mcp-server/blob/main/src/utils/logger.ts"

    %% Styles
    classDef transport fill:#cce5ff,stroke:#0366d6,color:#0366d6
    classDef business fill:#d4edda,stroke:#28a745,color:#155724
    classDef data fill:#fff3cd,stroke:#d39e00,color:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#343a40
    classDef util fill:#f8f9fa,stroke:#adb5bd,color:#495057
```
