How skanga/dbchat works
Project type and purpose
• DBChat is a standalone Java-based MCP (Model Context Protocol) server that exposes a natural-language interface to arbitrary JDBC databases.
• It is not a typical multi-tier full-stack app; rather, it’s a backend service (“MCP server”) that you run as a JAR, which your MCP-aware client (e.g., Claude Desktop) connects to over STDIN/STDOUT or HTTP.
File structure
• Top-level: pom.xml (Maven), build & release scripts, documentation (INSTALL.md, VISUALIZATION.md, MCP-SETUP.md).
• src/main/java/com/skanga/init – configuration and CLI parsing.
• src/main/java/com/skanga/mcp – core server bootstrap (McpServer), protocol handlers (HealthCheckHandler), HTTP adapter (McpHttpHandler), security utilities.
• src/main/java/com/skanga/mcp/config – parameter definitions (ConfigParams), CLI utilities, ResourceManager (registers MCP resources).
• src/main/java/com/skanga/mcp/db – data-access layer: DatabaseService (JDBC pooling), DatabaseResource (exposes SQL endpoints), QueryResult.
• Modules under mcp/demo, mcp/insights, mcp/prompts, mcp/workflow – each providing a specialized service and registering MCP handlers.
• src/main/resources – application.properties and per-DB YAML configs.
README
• Confirms architecture: a single JAR that implements MCP protocol handlers for prompts, workflows, insights, demo data, and SQL operations.
• Supports both STDIN/STDOUT MCP clients and an optional HTTP listener.
• Emphasizes modular “prompt” and “workflow” subsystems, dynamic discovery of resources via MCP protocol.
Main components
a. Entry points:
• MCP Client (e.g., Claude Desktop) – STDIN/STDOUT or HTTP
• CLI args / Environment variables – initial configuration
b. Core server:
• ClientConfig & CliUtils – parse args, load config file, env vars
• McpServer – main loop, routes incoming MCP requests to handlers
• McpHttpHandler – optional HTTP adapter forwarding HTTP calls into MCP pipeline
• ResourceManager – registry of available MCP resource endpoints
c. Protocol handlers (registered in ResourceManager):
• HealthCheckHandler
• McpHttpHandler (if HTTP_MODE=true)
• Prompts module – PromptService, PromptTemplate
• Workflow module – WorkflowManager, WorkflowService
• Demo module – DemoDataGenerator, DemoDataService, BusinessScenario
• Insights module – InsightsService, InsightsMemo, BusinessInsight
• Database module – DatabaseResource, DatabaseService, QueryResult
d. External dependencies:
• JDBC driver (MySQL, PostgreSQL, SQLite, etc)
• Underlying database(s)
• File system – YAML configs, JSON persistence for insights/demo state
Relationships & interactions
1. MCP Client → (STDIN/STDOUT or HTTP) → McpServer / McpHttpHandler
2. McpServer looks up resource in ResourceManager → invokes appropriate Handler
3. Handler uses one or more Services:
• DatabaseResource calls DatabaseService → JDBC → Database
• PromptService loads PromptTemplate → returns prompt metadata or content
• WorkflowService / WorkflowManager manage state machine for interactive workflows
• DemoDataService / DemoDataGenerator populate database with scenario data
• InsightsService / InsightsMemo accumulate and persist business insights
4. Service returns domain object (QueryResult, BusinessInsight, PromptTemplate, WorkflowState) → Handler serializes to JSON/MCP protocol → McpServer → MCP Client
Architectural patterns & design principles
• Layered/hexagonal architecture: separation of transport (MCP/HTTP), handler layer, service/domain layer, and infrastructure (DB, file system).
• Plugin-style modules: each feature (prompts, workflow, insights, demo) registers itself via ResourceManager.
• Configuration priority: CLI args → config file → environment vars → system properties → defaults.
• Stateless request handling in services except the workflow state manager, which persists JSON state.
• Clean separation of concerns: protocol parsing vs. business logic vs. persistence.
Essential architectural elements to capture
• Dual transport: STDIN/STDOUT MCP protocol and optional HTTP
• ResourceManager as the registry
• Modular handlers for prompts, workflows, insights, demos, SQL
• DatabaseService as the unified data-access component
• Configuration hierarchy
• External dependencies (JDBC drivers, target databases)