How hatrigt/hana-mcp-server works
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