# hatrigt/hana-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/hatrigt/hana-mcp-server
- Repository: https://github.com/hatrigt/hana-mcp-server

## Overview

##### Project Type and Purpose
- This is a standalone, modular MCP (Model Context Protocol) server written in Node.js.
- Purpose: Expose a set of “tools” (schema exploration, query execution, admin functions) over JSON-RPC via STDIO, integrating SAP HANA with AI agents (e.g., Claude Desktop).

##### File Structure
- Top-level:
- hana-mcp-server.js – thin wrapper / entrypoint
- setup.sh, package.json, .env.example – installation & config
- src/ – core source code
- tests/ – manual & automated test suites
- src/ subdivided by layer:
- server/ – protocol handling, lifecycle management
- tools/ – registry + individual tool implementations
- database/ – connection management, query execution, low-level client
- utils/ – logging, config, validation, formatting
- constants/ – protocol constants, tool definitions

##### README for Additional Insights
- Confirms a 4-layer architecture: Server Layer, Tools Layer, Database Layer, Utilities & Constants Layers.
- Emphasizes JSON-RPC 2.0 over STDIO, modularity, testability, and easy extensibility.

a. Main Components:
1. Client (Claude Desktop or other AI agent)
2. STDIO Transport / JSON-RPC Layer (in src/server/)
3. MCP Handler & Lifecycle Manager (in src/server/)
4. Tool Registry (src/tools/index.js)
5. Tools Modules (config-tools, schema-tools, table-tools, index-tools, query-tools)
6. Database Layer (connection-manager, query-executor, hana-client)
7. Utilities & Constants (shared across layers)
8. SAP HANA Database (external service)
b. Relationships & Data Flow:
- Client sends JSON-RPC requests → STDIO Transport
- STDIO Transport forwards to MCP Handler → Lifecycle Manager (startup/shutdown)
- Handler delegates “tools/list” or “tools/call” to Tool Registry
- Tool Registry locates specific tool module → executes tool logic
- Tool logic invokes Database Layer as needed → Connection Manager → HANA Client → Query Executor
- Responses bubble back through Tool Registry → MCP Handler → STDIO → Client
c. Architectural Patterns / Principles:
- Layered architecture (Separation of Concerns)
- Registry pattern for tool discovery
- Single Responsibility: each module does one thing
- JSON-RPC 2.0 protocol abstraction
- Environment-based configuration management
d. Key Technologies & Frameworks:
- Node.js 18+
- JSON-RPC 2.0 over STDIO
- SAP HANA database (hana-client wrapper)
- npm modules for logging, validation, formatting

##### Step-by-Step Creation
3. Below that, stack the Tools Layer (green rectangles):
– Tool Registry (index-tools)
– config-tools, schema-tools, table-tools, index-tools, query-tools
– Connection Manager → hana-client → Query Executor
5. Underneath or aside, add Utilities & Constants (gray rectangles): logger, config, validators, formatters, mcp-constants, tool-definitions.
– Client → STDIO → MCP Handler
– MCP Handler → Tool Registry → Specific Tool
– Tool → Connection Manager → hana-client → Query Executor → HANA DB
– Responses back the same path

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Claude Desktop (AI Agent)"]:::external

    %% Server Layer
    subgraph "Server Layer"
        STDIO["STDIO Transport + JSON-RPC\n(src/server/index.js)"]:::transport
        Handler["MCP Handler\n(src/server/mcp-handler.js)"]:::transport
        Lifecycle["Lifecycle Manager\n(src/server/lifecycle-manager.js)"]:::transport
    end

    %% Tools Layer
    subgraph "Tools Layer"
        ToolRegistry["Tool Registry\n(src/tools/index.js)"]:::tools
        ConfigTools["Config Tools\n(src/tools/config-tools.js)"]:::tools
        SchemaTools["Schema Tools\n(src/tools/schema-tools.js)"]:::tools
        TableTools["Table Tools\n(src/tools/table-tools.js)"]:::tools
        IndexTools["Index Tools\n(src/tools/index-tools.js)"]:::tools
        QueryTools["Query Tools\n(src/tools/query-tools.js)"]:::tools
    end

    %% Database Layer
    subgraph "Database Layer"
        ConnMgr["Connection Manager\n(src/database/connection-manager.js)"]:::database
        HanaClient["HANA Client Wrapper\n(src/database/hana-client.js)"]:::database
        QueryExec["Query Executor\n(src/database/query-executor.js)"]:::database
        HANA_DB[(SAP HANA Database)]:::external_db
    end

    %% Utilities & Constants
    subgraph "Utilities & Constants"
        ConfigUtil["Config Utility\n(src/utils/config.js)"]:::utils
        Logger["Logging Utility\n(src/utils/logger.js)"]:::utils
        Formatters["Formatting Utilities\n(src/utils/formatters.js)"]:::utils
        Validators["Validation Utilities\n(src/utils/validators.js)"]:::utils
        MCPConstants["Protocol Constants\n(src/constants/mcp-constants.js)"]:::utils
        ToolDefs["Tool Definitions\n(src/constants/tool-definitions.js)"]:::utils
    end

    %% Test Harness
    subgraph "Test Harness" style dashed
        AutoTests["Automated Tests\n(tests/)"]:::test
        ManualTests["Manual CLI Tests\n(tests/manual)"]:::test
    end

    %% Connections
    Client -->|"JSON-RPC Requests"| STDIO
    STDIO -->|"dispatch"| Handler
    Handler -->|"startup/shutdown"| Lifecycle
    Lifecycle -->|"lifecycle events"| Handler
    Handler -->|"tools/list, tools/call"| ToolRegistry
    ToolRegistry -->|selects| ConfigTools
    ToolRegistry -->|selects| SchemaTools
    ToolRegistry -->|selects| TableTools
    ToolRegistry -->|selects| IndexTools
    ToolRegistry -->|selects| QueryTools

    ConfigTools -->|"db call"| ConnMgr
    SchemaTools -->|"db call"| ConnMgr
    TableTools -->|"db call"| ConnMgr
    IndexTools -->|"db call"| ConnMgr
    QueryTools -->|"db call"| ConnMgr

    ConnMgr -->|"connect/query"| HanaClient
    HanaClient -->|"execute SQL"| QueryExec
    QueryExec -->|"run query"| HANA_DB

    HANA_DB -->|"results"| QueryExec
    QueryExec -->|"results"| HanaClient
    HanaClient -->|"results"| ConnMgr
    ConnMgr -->|"results"| ToolRegistry
    ToolRegistry -->|"results"| Handler
    Handler -->|"JSON-RPC Response"| STDIO
    STDIO -->|"response"| Client

    %% Test connections
    AutoTests -.->|uses STDIO| STDIO
    ManualTests -.->|uses STDIO| STDIO

    %% Click Events
    click STDIO "https://github.com/hatrigt/hana-mcp-server/blob/main/src/server/index.js"
    click Handler "https://github.com/hatrigt/hana-mcp-server/blob/main/src/server/mcp-handler.js"
    click Lifecycle "https://github.com/hatrigt/hana-mcp-server/blob/main/src/server/lifecycle-manager.js"
    click ToolRegistry "https://github.com/hatrigt/hana-mcp-server/blob/main/src/tools/index.js"
    click ConfigTools "https://github.com/hatrigt/hana-mcp-server/blob/main/src/tools/config-tools.js"
    click SchemaTools "https://github.com/hatrigt/hana-mcp-server/blob/main/src/tools/schema-tools.js"
    click TableTools "https://github.com/hatrigt/hana-mcp-server/blob/main/src/tools/table-tools.js"
    click IndexTools "https://github.com/hatrigt/hana-mcp-server/blob/main/src/tools/index-tools.js"
    click QueryTools "https://github.com/hatrigt/hana-mcp-server/blob/main/src/tools/query-tools.js"
    click ConnMgr "https://github.com/hatrigt/hana-mcp-server/blob/main/src/database/connection-manager.js"
    click HanaClient "https://github.com/hatrigt/hana-mcp-server/blob/main/src/database/hana-client.js"
    click QueryExec "https://github.com/hatrigt/hana-mcp-server/blob/main/src/database/query-executor.js"
    click MCPConstants "https://github.com/hatrigt/hana-mcp-server/blob/main/src/constants/mcp-constants.js"
    click ToolDefs "https://github.com/hatrigt/hana-mcp-server/blob/main/src/constants/tool-definitions.js"
    click ConfigUtil "https://github.com/hatrigt/hana-mcp-server/blob/main/src/utils/config.js"
    click Logger "https://github.com/hatrigt/hana-mcp-server/blob/main/src/utils/logger.js"
    click Formatters "https://github.com/hatrigt/hana-mcp-server/blob/main/src/utils/formatters.js"
    click Validators "https://github.com/hatrigt/hana-mcp-server/blob/main/src/utils/validators.js"

    %% Styles
    classDef transport fill:#a0c4ff,stroke:#0366d6,color:#000;
    classDef tools fill:#caffbf,stroke:#2b9348,color:#000;
    classDef database fill:#ffd6a5,stroke:#d15a24,color:#000;
    classDef utils fill:#d3d3d3,stroke:#6e6e6e,color:#000;
    classDef external fill:#d0bdf4,stroke:#6a0dad,color:#000;
    classDef external_db fill:#f4c2c2,stroke:#b22222,color:#000;
    classDef test fill:none,stroke:#999,stroke-dasharray: 5 5,color:#999;
```
