# sparesparrow/mcp-prompts architecture

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

- Interactive diagram: https://gitdiagram.com/sparesparrow/mcp-prompts
- Repository: https://github.com/sparesparrow/mcp-prompts

## Overview

- MCP Prompts Server – This is the core service which handles API requests, prompt management (CRUD operations, variable substitution/template processing), and SSE events.
○ File Storage (JSON files on disk)
○ PostgreSQL Adapter (database-driven storage, including vector search aspects)
○ MDC Adapter (managing prompts in Cursor Rules Marker Down Code (.mdc) files)
- Template and Prompt Processing – A module (or set of modules) inside the MCP Prompts Server that is responsible for converting prompt formats, variable extraction, and applying templates.
- External Interfaces:
○ API/SSE Endpoint – Representing how clients (e.g., Claude Desktop or AI Clients) interact via HTTP and SSE.
○ Docker Deployment Components – Containers running for different environments (development, production, testing) with docker-compose and management scripts.
- CI/CD and Development Tools – Optionally include the GitHub workflows, Dockerfiles, test directories, and scripts that drive the build, test, release, and deployment flows.

##### Relationships and Interactions
- That Docker Compose deployments act as an orchestration mechanism, connecting various containers (the prompts container, PostgreSQL, and integration service containers) via a network, with volumes for persistence.

##### Architectural Patterns and Key Design Principles
- A modular, layered design where the core MCP Prompts Server is decoupled from storage specifics (via the adapter pattern) and from external integrations (using resource routing or integration service patterns).
- That the design supports multiple configurations (e.g., file-based vs. PostgreSQL vs. MDC storage) determined at runtime by environment variables.
- Use deployment patterns with Docker and CI/CD workflows – which help in iterative delivery, testing (unit and integration tests), and versioning/release pipelines.
- Acknowledge the use of SSE (for low-latency updates) and a clear separation of concerns between prompt management, template transformation, and external service integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Layer
    Client["External Clients"]:::external
    API["API/SSE Endpoint"]:::interface

    %% Main MCP Server and its Modules
    subgraph "Backend Server"
        MCP["MCP Prompts Server"]:::server
        Template["Template Engine"]:::internal

        subgraph "Storage Adapters"
            FileStorage["File Storage Adapter"]:::storage
            PostgreSQL["PostgreSQL Adapter"]:::storage
            MDC["MDC Adapter"]:::storage
            PostgreSQLConfig["PostgreSQL Config"]:::storage
        end

        subgraph "Resource Integration Layer"
            Resource["Resource Integration"]:::integration
            CustomIntegration["Custom Integration"]:::integration
        end
    end

    %% Deployment and CI/CD
    Docker["Docker Deployment Environment"]:::docker
    CICD["CI/CD & Dev Tools"]:::cicd

    %% Connections between External Clients and Server
    Client -->|"API_Request&SSE"| API
    API -->|"Forwards_To"| MCP

    %% Internal connections within MCP
    MCP -->|"HandlesTemplates"| Template
    MCP -->|"CRUD_Operations"| FileStorage
    MCP -->|"CRUD_Operations"| PostgreSQL
    MCP -->|"CRUD_Operations"| MDC
    MCP -->|"CallsIntegrations"| Resource
    Resource -->|"CustomHooks"| CustomIntegration

    %% Additional connection for PostgreSQL Adapter config
    PostgreSQL -->|"Uses_Config"| PostgreSQLConfig

    %% Deployment and CI/CD orchestration
    Docker -->|"Orchestrates"| MCP
    Docker -->|"Orchestrates"| PostgreSQL
    CICD -->|"Automates_Build_Test_Deploy"| MCP

    %% Click Events for MCP Prompts Server components
    click MCP "https://github.com/sparesparrow/mcp-prompts/blob/main/src/index.ts"
    click Template "https://github.com/sparesparrow/mcp-prompts/blob/main/src/prompts.ts"
    click FileStorage "https://github.com/sparesparrow/mcp-prompts/tree/main/data/prompts"
    click PostgreSQL "https://github.com/sparesparrow/mcp-prompts/blob/main/tests/integration/postgres-adapter.integration.test.ts"
    click PostgreSQLConfig "https://github.com/sparesparrow/mcp-prompts/blob/main/docker/compose/docker-compose.postgres.yml"
    click MDC "https://github.com/sparesparrow/mcp-prompts/blob/main/.cursor/rules/mdc-adapter-implementation.mdc"
    click API "https://github.com/sparesparrow/mcp-prompts/blob/main/src/http-server.ts"
    click Resource "https://github.com/sparesparrow/mcp-prompts/blob/main/.cursor/rules/mcp-integration.mdc"
    click CustomIntegration "https://github.com/sparesparrow/mcp-prompts/blob/main/custom-mcp/custom-server.js"
    click Docker "https://github.com/sparesparrow/mcp-prompts/tree/main/docker/"
    click CICD "https://github.com/sparesparrow/mcp-prompts/tree/main/.github/workflows/"

    %% Styles
    classDef server fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef internal fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef storage fill:#ffeb99,stroke:#000,stroke-width:1px;
    classDef integration fill:#ffc0cb,stroke:#000,stroke-width:1px;
    classDef external fill:#ffd700,stroke:#000,stroke-width:1px;
    classDef docker fill:#d3d3d3,stroke:#000,stroke-width:1px;
    classDef cicd fill:#f4a460,stroke:#000,stroke-width:1px;
    classDef interface fill:#87cefa,stroke:#000,stroke-width:1px;
```
