# yanmxa/prometheus-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/yanmxa/prometheus-mcp-server
- Repository: https://github.com/yanmxa/prometheus-mcp-server

## Overview

##### Project Type and Purpose
- This is a **backend CLI-based MCP (Model Context Protocol) server** implemented in TypeScript.
- Its job is to expose a set of “tools” (prom_query, prom_range, prom_discover, etc.) over the MCP protocol and translate them into Prometheus HTTP API calls.

##### File Structure
- Top level: package.json, tsconfig.json, README.md, .env.example
- src/index.ts – CLI entrypoint & MCP protocol bootstrap
- src/tools.ts – Implements each MCP “tool” handler
- src/prometheus-client.ts – HTTP client wrapper for Prometheus endpoints

##### Core Architectural Components
a. **CLI / MCP Server (index.ts)**
- Reads environment variables (PROMETHEUS_URL, auth, timeouts)
- Registers MCP commands (tools) and dispatches calls
b. **Tools Layer (tools.ts)**
- Business logic for each “tool”: prom_query, prom_range, prom_discover, etc.
- Parses incoming MCP requests, calls the client, formats responses
c. **Prometheus HTTP Client (prometheus-client.ts)**
- Provides typed methods to hit Prometheus’s REST API (instant, range, metadata, targets)
- Handles authentication (basic, bearer token, TLS settings)
d. **Environment Configuration**
- .env or environment variables injected into startup
- Drives client behavior (URL, credentials, timeout, insecure TLS)
e. **External Service**
- Prometheus server (http://localhost:9090 or remote)

##### Relationships & Data Flow
1) Operator invokes `npx prometheus-mcp-server` (or global install).
2) MCP server (index.ts) starts, reads config, exposes MCP protocol endpoint.
3) AI assistant or client sends an MCP request to a specific tool (e.g., prom_query).
4) MPC server routes request → Tools Layer.
5) Tool handler calls Prometheus HTTP Client → makes REST API call to Prometheus.
6) HTTP Client returns JSON data → Tool formats result → MCP server returns response.

##### Architectural Patterns & Design Principles
- **Separation of Concerns**:
- index.ts only handles protocol registration & config
- tools.ts only handles tool-specific logic
- prometheus-client.ts only handles HTTP communication
- **Plug-in / Extensible Tools**: Each tool is a self-contained function; new tools can be added with minimal changes.
- **Type Safety**: End-to-end TypeScript types define all requests/responses.

##### Putting It All Together
- Layer 1 (left): **Client / AI assistant** talking over MCP protocol
- Layer 2: **MCP Server (index.ts)** reading **Env Config**
- Layer 5 (right): **Prometheus Server (HTTP API)**

## Diagram (Mermaid)

```mermaid
graph TB
    Client["Client / AI Assistant"]:::external

    subgraph "Project Configuration"
        Package["package.json"]:::config
        Tsconfig["tsconfig.json"]:::config
        Env["Env Config (.env)"]:::config
    end

    MCP["MCP Server (index.ts)"]:::internal

    subgraph "Tools Layer"
        Query["prom_query"]:::internal
        Range["prom_range"]:::internal
        Discover["prom_discover"]:::internal
    end

    HTTPClient["Prometheus HTTP Client (prometheus-client.ts)"]:::internal
    Types["Shared Types (types.ts)"]:::internal
    Prometheus["Prometheus Server"]:::external

    Client -->|"MCP RPC"| MCP
    Package --> MCP
    Tsconfig --> MCP
    Env -->|"Env Vars"| MCP
    MCP -->|"dispatch"| Query
    MCP -->|"dispatch"| Range
    MCP -->|"dispatch"| Discover
    Query -->|"calls HTTP Client"| HTTPClient
    Range -->|"calls HTTP Client"| HTTPClient
    Discover -->|"calls HTTP Client"| HTTPClient
    HTTPClient -->|"HTTP/JSON"| Prometheus
    Prometheus -->|"JSON"| HTTPClient
    Query -->|"formats response"| MCP
    Range -->|"formats response"| MCP
    Discover -->|"formats response"| MCP
    MCP -->|"MCP Response"| Client
    Query -->|"uses types"| Types
    Range -->|"uses types"| Types
    Discover -->|"uses types"| Types
    HTTPClient -->|"uses types"| Types

    click MCP "https://github.com/yanmxa/prometheus-mcp-server/blob/main/src/index.ts"
    click Query "https://github.com/yanmxa/prometheus-mcp-server/blob/main/src/tools.ts"
    click Range "https://github.com/yanmxa/prometheus-mcp-server/blob/main/src/tools.ts"
    click Discover "https://github.com/yanmxa/prometheus-mcp-server/blob/main/src/tools.ts"
    click HTTPClient "https://github.com/yanmxa/prometheus-mcp-server/blob/main/src/prometheus-client.ts"
    click Types "https://github.com/yanmxa/prometheus-mcp-server/blob/main/src/types.ts"
    click Env "https://github.com/yanmxa/prometheus-mcp-server/blob/main/.env.example"
    click Package "https://github.com/yanmxa/prometheus-mcp-server/blob/main/package.json"
    click Tsconfig "https://github.com/yanmxa/prometheus-mcp-server/blob/main/tsconfig.json"

    classDef internal fill:#cce5ff,stroke:#339,stroke-width:1px
    classDef config fill:#d4edda,stroke:#396,stroke-width:1px
    classDef external fill:#fff3cd,stroke:#993,stroke-width:1px
```
