# renzoreccio/nestjs-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/renzoreccio/nestjs-mcp
- Repository: https://github.com/renzoreccio/nestjs-mcp

## Overview

##### Project Type and Purpose
- Type: A backend service built with NestJS, showcasing a Model Context Protocol implementation.
- Purpose:
– Expose “create-weather” and “get-weathers” operations via a prompt/tool layer.
– Demonstrate a layered (DDD + CQRS) architecture.
– Integrate with external tools (MCP Inspector) and persist weather data via a repository.

##### File Structure
Top-level files
- Configuration: nest-cli.json, tsconfig.json, dockerfile
- Package management: package.json, package-lock.json
src/
- presentation/ – Prompts and tools (interfaces to the outside world, e.g., CLI or MCP inspector)
- application/ – Application layer: commands & queries, handlers, DTOs (CQRS)
- domain/ – Core business model and repository interface (Weather entity & WeatherRepository interface)
- infrastructure/ – Concrete implementations (e.g., weather.repository.ts), global error handler
- main.ts – NestJS bootstrap

##### README for Additional Insights
- Confirms MCP focus and NestJS backbone.
- Mentions the “MCP Playground” (external inspector tool that interacts with the presentation layer).
- Docker support for deployment.

a. Main Components
1. Presentation Layer
– WeatherPrompt (src/presentation/prompts/weather.prompt.ts)
– WeatherTool (src/presentation/tools/weather.tool.ts)
– Exposes an interface (CLI or MCP Inspector)
2. Application Layer
– Command Bus and Query Bus (commands.ts & queries.ts)
– Handlers for CreateWeatherCommand & GetWeathersQuery
– DTOs: command.request/response, query.request/response
3. Domain Layer
– Weather entity (weather.ts)
– WeatherRepository interface (weather.repository.ts)
4. Infrastructure Layer
– WeatherRepository implementation (infrastructure/repositories/weather.repository.ts)
– GlobalErrorHandler (infrastructure/global-error-handler)
5. External Services & Tools
– MCP Inspector (external)
– Underlying database or persistence (not shown in code but implied by repository)
b. Relationships & Data Flow
– Presentation → Application: user input or MCP Inspector triggers a command/query
– Application → Domain: handlers invoke domain entities & repository interface
– Domain → Infrastructure: repository interface is bound to concrete implementation to read/write data
– Infrastructure → Database: actual persistence (e.g., PostgreSQL, MongoDB)
– Errors bubble up through GlobalErrorHandler back to Presentation
c. Architectural Patterns
– Layered Architecture: Presentation / Application / Domain / Infrastructure
– CQRS: Separate command handlers from query handlers
– DDD: Domain entities and repository abstractions
d. Key Technologies
– NestJS framework (modules, providers, controllers – here lean on prompts/tools instead of HTTP controllers)
– TypeScript, Node.js
– Docker containerization
– External MCP Inspector for live protocol validation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External"
        style External fill:#f0f0f0,stroke:#999
        Inspector["MCP Inspector"]:::external
        Database["Database"]:::external
    end

    %% Docker Container Boundary
    subgraph "Docker Container\n(NestJS Service)"
        style Docker fill:none,stroke:#333,stroke-dasharray: 5 5

        %% Bootstrap
        Main["NestJS Bootstrap\nmain.ts"]:::bootstrap

        %% Presentation Layer
        subgraph "Presentation Layer" 
            style Presentation fill:#dae8fc,stroke:#6c8ebf
            Prompt["WeatherPrompt"]:::presentation
            Tool["WeatherTool"]:::presentation
        end

        %% Application Layer
        subgraph "Application Layer"
            style Application fill:#e1d5e7,stroke:#9673a6
            CommandBus["CommandBus"]:::application
            QueryBus["QueryBus"]:::application
            CWC["CreateWeatherCommand"]:::application
            CWH["CreateWeatherHandler"]:::application
            CWR["CreateWeatherResponseDTO"]:::application
            GWCQ["GetWeathersQuery"]:::application
            GWH["GetWeathersHandler"]:::application
            GWR["GetWeathersResponseDTO"]:::application
        end

        %% Domain Layer
        subgraph "Domain Layer"
            style Domain fill:#d5e8d4,stroke:#82b366
            Entity["Weather Entity"]:::domain
            RepoIntf["WeatherRepository Interface"]:::domain
        end

        %% Infrastructure Layer
        subgraph "Infrastructure Layer"
            style Infrastructure fill:#ffe6cc,stroke:#d79b00
            RepoImpl["WeatherRepository Implementation"]:::infrastructure
            ErrorHandler["GlobalErrorHandler"]:::infrastructure
        end

        %% NestJS Bootstrap Connections
        Main --> Prompt
        Main --> Tool
        Main --> CommandBus
        Main --> QueryBus

        %% Presentation to Application
        Inspector --> Prompt
        Inspector --> Tool
        Prompt -->|trigger command| CommandBus
        Tool -->|trigger query| QueryBus

        %% CQRS Flows
        CommandBus -->|dispatch| CWC
        CWC -->|handled by| CWH
        CWH -->|returns| CWR

        QueryBus -->|dispatch| GWCQ
        GWCQ -->|handled by| GWH
        GWH -->|returns| GWR

        %% Domain Interactions
        CWH -->|uses| Entity
        CWH -->|calls| RepoIntf
        GWH -->|uses| Entity
        GWH -->|calls| RepoIntf

        %% Infrastructure Binding & Persistence
        RepoIntf -->|implemented by| RepoImpl
        RepoImpl -->|persists| Database

        %% Error Handling
        CWH -->|errors| ErrorHandler
        GWH -->|errors| ErrorHandler
        ErrorHandler -->|notifies| Prompt
        ErrorHandler -->|notifies| Tool
    end

    %% Click Events
    click Prompt "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/presentation/prompts/weather.prompt.ts"
    click Tool "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/presentation/tools/weather.tool.ts"
    click Main "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/main.ts"
    click Presentation "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/presentation/presentation.module.ts"
    click CommandBus "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/application/config/commands.ts"
    click QueryBus "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/application/config/queries.ts"
    click CWC "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/application/weather/commands/create-weather/create-weather.command.ts"
    click CWH "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/application/weather/commands/create-weather/create-weather.handler.ts"
    click CWR "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/application/weather/commands/create-weather/create-weather.response.ts"
    click GWCQ "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/application/weather/queries/get-weathers/get-weathers.query.ts"
    click GWH "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/application/weather/queries/get-weathers/get-weathers.handler.ts"
    click GWR "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/application/weather/queries/get-weathers/get-weathers.response.ts"
    click Application "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/application/application.module.ts"
    click Entity "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/domain/weather/weather.ts"
    click RepoIntf "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/domain/weather/weather.repository.ts"
    click Infrastructure "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/infrastructure/infrastructure.module.ts"
    click RepoImpl "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/infrastructure/repositories/weather.repository.ts"
    click ErrorHandler "https://github.com/renzoreccio/nestjs-mcp/blob/main/src/infrastructure/global-error-handler/global-error-handler.error.ts"
    click Database "https://github.com/renzoreccio/nestjs-mcp/tree/main/dockerfile"

    %% Styles
    classDef external fill:#eeeeee,stroke:#666,stroke-width:1px
    classDef bootstrap fill:#ffffff,stroke:#333,stroke-width:1px
    classDef presentation fill:#dae8fc,stroke:#6c8ebf,stroke-width:1px
    classDef application fill:#f8cecc,stroke:#b85450,stroke-width:1px
    classDef domain fill:#d5e8d4,stroke:#82b366,stroke-width:1px
    classDef infrastructure fill:#ffe6cc,stroke:#d79b00,stroke-width:1px
```
