# neondatabase-labs/mcp-server-neon architecture

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

- Interactive diagram: https://gitdiagram.com/neondatabase-labs/mcp-server-neon
- Repository: https://github.com/neondatabase-labs/mcp-server-neon

## Overview

##### Main Components
- Neon MCP Server Core: From the “src” folder, the key entry point is “src/index.ts”. This component handles the MCP protocol commands and routes them to the appropriate handlers.
- MCP Client: The “mcp-client” directory contains a separate command-line client (with its own entry points like “cli-client.ts”, “neon-cli-client.ts”, “bin.ts”) designed for rapid development and testing of the MCP server.
- Utilities & Configuration: Key shared components include logging (“src/logger.ts”), configuration, constants, and state management. In addition, configuration files like “.env.example”, “tsconfig.json”, and several root-level configuration files indicate how the project builds, tests, and deploys.
- External Integrations: The system depends on external systems such as Claude Desktop (for LLM interaction) and Neon’s API. The README details commands that trigger migration workflows and operations like “list_projects” and “create_project”. Also, the Dockerfile suggests containerization.

##### Out Relationships and Interactions
- Command Routing: Within the server, “src/index.ts” intercepts commands then routes them to specific “handlers” based on the command type (e.g., “neon-auth” for provisioning auth, “tools-evaluations/*” for migration evaluations).
- External API Interaction: The handlers further communicate with Neon’s external API endpoints using credentials (supplied via environment variables) to perform actions like creating or deleting projects, branches, and executing SQL queries.

##### Architectural Patterns and Key Technologies
- Modular Design: Different functional areas are separated across folders. The “src” directory holds the core server logic and handlers, while “mcp-client” acts as an isolated client application.
- Command and Handler Pattern: User commands received by the server are routed through a central entry point and handled by specific modules.
- Environment-driven Configuration: The use of .env, tsconfig, and Dockerfile shows that the project is designed for flexible deployment, containerization, and runtime environment configuration.
- TypeScript: Given the presence of tsconfig files in both the root and subdirectories, note that the system is built with TypeScript.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Client / LLM
    ExternalClient["MCP Client/External LLM (e.g., Claude Desktop)"]:::client

    %% Neon MCP Server Subgraph
    subgraph "Neon MCP Server"
        ServerCore["MCP Server Entry (src/index.ts)"]:::server

        %% Command Handlers Subgraph
        subgraph "Command Handlers"
            NeonAuth["Handler: neon-auth"]:::handler
            ToolsEval["Handler: tools-evaluations"]:::handler
        end

        %% Utilities & Configuration Subgraph
        subgraph "Utilities & Configuration"
            Constants["constants.ts"]:::util
            InitConfig["initConfig.ts"]:::util
            State["state.ts"]:::util
            Resources["resources.ts"]:::util
            Tools["tools.ts"]:::util
            Utils["utils.ts"]:::util
            Polyfills["polyfills.ts"]:::util
            DotEnv[".env.example"]:::util
            Tsconfig["tsconfig.json"]:::util
            TsconfigTest["tsconfig.test.json"]:::util
            Docker["Dockerfile"]:::util
            Smithery["smithery.yaml"]:::util
        end
    end

    %% MCP Client Subgraph
    subgraph "MCP Client"
        MClient_Entry["Client Entry (mcp-client/src/index.ts)"]:::client
        MClient_CLI["CLI Client (mcp-client/src/cli-client.ts)"]:::client
        MClient_NeonCLI["Neon CLI Client (mcp-client/src/neon-cli-client.ts)"]:::client
        MClient_Bin["Bin (mcp-client/src/bin.ts)"]:::client
    end

    %% External Systems
    NeonAPI["Neon API"]:::external

    %% Development & Deployment Subgraph
    subgraph "Development & Deployment"
        Dev_BeforePublish["Before Publish Script (scripts/before-publish.ts)"]:::deploy
        Dev_RootConfigs["Root Configs (package.json, package-lock.json)"]:::deploy
        Dev_ClientConfigs["Client Configs (mcp-client/package.json, package-lock.json)"]:::deploy
    end

    %% Connections
    ExternalClient -->|"SendsCommands"| ServerCore
    MClient_Entry -->|"SendsMCPCommands"| ServerCore

    ServerCore -->|"RoutesCommand"| NeonAuth
    ServerCore -->|"RoutesCommand"| ToolsEval

    NeonAuth -->|"APICall"| NeonAPI
    ToolsEval -->|"APICall"| NeonAPI

    Dev_BeforePublish ---|"Build/Deploy"| ServerCore
    Dev_BeforePublish ---|"Build/Deploy"| MClient_Entry

    %% Click Events
    click ServerCore "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/src/index.ts"
    click NeonAuth "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/src/handlers/neon-auth.ts"
    click ToolsEval "https://github.com/neondatabase-labs/mcp-server-neon/tree/main/src/tools-evaluations/"

    click Constants "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/src/constants.ts"
    click InitConfig "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/src/initConfig.ts"
    click State "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/src/state.ts"
    click Resources "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/src/resources.ts"
    click Tools "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/src/tools.ts"
    click Utils "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/src/utils.ts"
    click Polyfills "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/src/polyfills.ts"
    click DotEnv "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/.env.example"
    click Tsconfig "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/tsconfig.json"
    click TsconfigTest "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/tsconfig.test.json"
    click Docker "https://github.com/neondatabase-labs/mcp-server-neon/tree/main/Dockerfile"
    click Smithery "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/smithery.yaml"

    click MClient_Entry "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/mcp-client/src/index.ts"
    click MClient_CLI "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/mcp-client/src/cli-client.ts"
    click MClient_NeonCLI "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/mcp-client/src/neon-cli-client.ts"
    click MClient_Bin "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/mcp-client/src/bin.ts"

    click Dev_BeforePublish "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/scripts/before-publish.ts"
    click Dev_RootConfigs "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/package.json"
    click Dev_ClientConfigs "https://github.com/neondatabase-labs/mcp-server-neon/blob/main/mcp-client/package.json"

    %% Class Definitions for Colors
    classDef client fill:#ffe6e6,stroke:#ff3333,stroke-width:2px;
    classDef server fill:#e6ffe6,stroke:#33cc33,stroke-width:2px;
    classDef handler fill:#e6e6ff,stroke:#3333ff,stroke-width:2px;
    classDef util fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef external fill:#ccffff,stroke:#00cccc,stroke-width:2px;
    classDef deploy fill:#f0e68c,stroke:#b8860b,stroke-width:2px;
```
