Skip to content

Commit 6d0b0e5

Browse files
kopkop
committed
docs: add design overview
Adds a document with detailed technical overview of the Firebolt MCP Server.
1 parent df81310 commit 6d0b0e5

File tree

1 file changed

+249
-0
lines changed

1 file changed

+249
-0
lines changed

‎docs/overview.md‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
# Firebolt MCP Server: Design Overview
2+
3+
This document provides a detailed technical overview of the Firebolt MCP Server, explaining its architecture, components, and how they interact to enable LLM integration with Firebolt Data Warehouse.
4+
5+
## What is the Firebolt MCP Server?
6+
7+
Firebolt MCP Server is an implementation of the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) that allows Large Language Models (LLMs) like Claude, GitHub Copilot, and others to directly interact with Firebolt cloud data warehouse. It serves as a bridge between AI assistants and Firebolt's data storage and query capabilities.
8+
9+
## Architecture Overview
10+
11+
```mermaid
12+
graph TD
13+
subgraph "Client Applications"
14+
Claude["Claude Desktop"]
15+
Copilot["GitHub Copilot"]
16+
Cursor["Cursor"]
17+
end
18+
19+
subgraph "Firebolt MCP Server"
20+
Server["MCP Server Core"]
21+
22+
subgraph "Tools"
23+
DocsT["firebolt_docs"]
24+
ConnectT["firebolt_connect"]
25+
QueryT["firebolt_query"]
26+
end
27+
28+
subgraph "Resources"
29+
DocsR["Documentation"]
30+
AccountsR["Accounts"]
31+
DatabasesR["Databases"]
32+
EnginesR["Engines"]
33+
end
34+
35+
subgraph "Prompts"
36+
FireboltExpert["Firebolt Expert"]
37+
end
38+
end
39+
40+
subgraph "Firebolt Services"
41+
DiscoveryAPI["Firebolt Discovery API"]
42+
FireboltDB["Firebolt Database"]
43+
end
44+
45+
Claude --> |MCP Protocol| Server
46+
Copilot --> |MCP Protocol| Server
47+
Cursor --> |MCP Protocol| Server
48+
49+
Server --> DocsT
50+
Server --> ConnectT
51+
Server --> QueryT
52+
Server --> DocsR
53+
Server --> AccountsR
54+
Server --> DatabasesR
55+
Server --> EnginesR
56+
Server --> FireboltExpert
57+
58+
ConnectT --> AccountsR
59+
ConnectT --> DatabasesR
60+
ConnectT --> EnginesR
61+
62+
AccountsR --> DiscoveryAPI
63+
DatabasesR --> FireboltDB
64+
EnginesR --> FireboltDB
65+
66+
QueryT --> FireboltDB
67+
```
68+
69+
## Core Components
70+
71+
### 1. MCP Server
72+
73+
The server component (`pkg/server/server.go`) is the central part of the application that manages communication with LLM clients and orchestrates interactions between tools, resources, and prompts. It implements the Model Context Protocol using the `mark3labs/mcp-go` library.
74+
75+
Key features:
76+
- Supports multiple transport methods (stdio, SSE)
77+
- Handles request routing to appropriate tools and resources
78+
- Manages lifecycle of connections and interactions
79+
80+
### 2. Tools
81+
82+
Tools are executable capabilities exposed to LLMs through the MCP interface:
83+
84+
1. **firebolt_docs** (`pkg/tools/docs.go`)
85+
- Provides access to Firebolt documentation
86+
- Returns embedded markdown content for various documentation articles
87+
- Helps LLMs understand Firebolt concepts, SQL syntax, and best practices
88+
89+
2. **firebolt_connect** (`pkg/tools/connect.go`)
90+
- Lists available Firebolt accounts, databases, and engines
91+
- Requires a "proof" from documentation to ensure the LLM has read basic Firebolt information
92+
- Enables discovery of resources before executing queries
93+
94+
3. **firebolt_query** (`pkg/tools/query.go`)
95+
- Executes SQL queries against Firebolt databases
96+
- Manages connections to the specified account, database, and engine
97+
- Returns query results in JSON format
98+
99+
### 3. Resources
100+
101+
Resources are information objects that can be accessed by the LLM:
102+
103+
1. **Documentation Resources** (`pkg/resources/docs.go`)
104+
- Provides markdown documentation about Firebolt
105+
- Includes an overview, detailed reference, and specialized articles
106+
107+
2. **Account Resources** (`pkg/resources/accounts.go`)
108+
- Represents Firebolt accounts the user has access to
109+
- Contains account metadata like name and region
110+
111+
3. **Database Resources** (`pkg/resources/databases.go`)
112+
- Represents databases within Firebolt accounts
113+
- Includes metadata about each database
114+
115+
4. **Engine Resources** (`pkg/resources/engines.go`)
116+
- Represents compute engines within Firebolt accounts
117+
- Contains information about engine type, status, and configuration
118+
119+
### 4. Clients
120+
121+
The MCP server includes specialized clients to interact with Firebolt services:
122+
123+
1. **Database Client** (`pkg/clients/database/`)
124+
- Manages connections to Firebolt databases
125+
- Handles connection pooling for different account/database/engine combinations
126+
- Executes SQL queries and formats results
127+
128+
2. **Discovery Client** (`pkg/clients/discovery/`)
129+
- Communicates with Firebolt API to discover available accounts
130+
- Handles OAuth2 authentication and API communication
131+
132+
## Data Flow and Interactions
133+
134+
```mermaid
135+
sequenceDiagram
136+
participant LLM as LLM Client
137+
participant Server as MCP Server
138+
participant Docs as firebolt_docs
139+
participant Connect as firebolt_connect
140+
participant Query as firebolt_query
141+
participant FireboltAPI as Firebolt API
142+
participant FireboltDB as Firebolt Database
143+
144+
LLM->>Server: Connect with MCP protocol
145+
Server->>LLM: Capabilities and instructions
146+
147+
Note over LLM, Server: Documentation Flow
148+
LLM->>Server: Request documentation
149+
Server->>Docs: Call firebolt_docs
150+
Docs->>Server: Return documentation resources
151+
Server->>LLM: Documentation content
152+
153+
Note over LLM, Server: Connection Flow
154+
LLM->>Server: Request resources
155+
Server->>Connect: Call firebolt_connect
156+
Connect->>FireboltAPI: List accounts
157+
FireboltAPI->>Connect: Account information
158+
Connect->>FireboltDB: Query databases
159+
Connect->>FireboltDB: Query engines
160+
FireboltDB->>Connect: Database and engine info
161+
Connect->>Server: Resource information
162+
Server->>LLM: Available accounts, databases, engines
163+
164+
Note over LLM, Server: Query Flow
165+
LLM->>Server: Execute SQL query
166+
Server->>Query: Call firebolt_query
167+
Query->>FireboltDB: Execute SQL
168+
FireboltDB->>Query: Query results
169+
Query->>Server: Formatted results
170+
Server->>LLM: SQL query results
171+
```
172+
173+
## Implementation Details
174+
175+
### Authentication and Security
176+
177+
The server authenticates with Firebolt using OAuth2 client credentials (client ID and client secret). It obtains a token from Firebolt's identity service and uses it for all API calls and database connections.
178+
179+
Security features:
180+
- No credential storage - credentials are passed as environment variables or command line arguments
181+
- Connection pool management to avoid credential leakage
182+
- Secure transport options (stdio, SSE)
183+
184+
### Connection Pooling
185+
186+
The server implements a connection pool for different Firebolt account/database/engine combinations. This optimizes for:
187+
- Reusing connections when possible
188+
- Properly managing resources across multiple requests
189+
- Handling concurrent queries efficiently
190+
191+
```mermaid
192+
graph TD
193+
subgraph "Connection Pool"
194+
Pool["pool.go"]
195+
Connections["Managed Connections"]
196+
end
197+
198+
subgraph "Connection Management"
199+
ConnParams["ConnectionParams"]
200+
ConnImpl["connectionImpl"]
201+
end
202+
203+
subgraph "Tools"
204+
QueryTool["firebolt_query"]
205+
ResourceTools["Resource Tools"]
206+
end
207+
208+
QueryTool --> Pool
209+
ResourceTools --> Pool
210+
Pool --> Connections
211+
Connections --> ConnImpl
212+
ConnParams --> ConnImpl
213+
ConnImpl --> FireboltDB["Firebolt Database"]
214+
```
215+
216+
### Documentation Integration
217+
218+
The server embeds Firebolt documentation directly in the binary, making it available offline and ensuring fast access:
219+
- Documentation is structured as markdown files
220+
- Special articles (overview, proof, reference) are embedded with the `go:embed` directive
221+
- Additional documentation is stored in the filesystem and can be updated independently
222+
223+
### Error Handling and Logging
224+
225+
The server implements comprehensive error handling and structured logging:
226+
- All errors are properly wrapped with context
227+
- Structured logging using `log/slog`
228+
- Unified error handling patterns across components
229+
230+
## Starting Points for Understanding the Code
231+
232+
1. **Main Application Entry Point**: `cmd/firebolt-mcp-server/main.go`
233+
2. **Server Core Implementation**: `pkg/server/server.go`
234+
3. **Tool Implementations**:
235+
- `pkg/tools/docs.go`
236+
- `pkg/tools/connect.go`
237+
- `pkg/tools/query.go`
238+
4. **Resource Handlers**:
239+
- `pkg/resources/docs.go`
240+
- `pkg/resources/accounts.go`
241+
- `pkg/resources/databases.go`
242+
- `pkg/resources/engines.go`
243+
5. **Database Connection**: `pkg/clients/database/pool.go` and `pkg/clients/database/connection.go`
244+
245+
## Conclusion
246+
247+
The Firebolt MCP Server provides a robust implementation of the Model Context Protocol that allows LLMs to interact with Firebolt Data Warehouse. By exposing tools, resources, and prompts through a standardized interface, it enables AI assistants to query data, understand documentation, and provide insights based on Firebolt's capabilities.
248+
249+
The modular architecture ensures clear separation of concerns, with distinct components handling server communication, resource discovery, documentation access, and query execution. This design facilitates maintenance, testing, and future expansion of the server's capabilities.

0 commit comments

Comments
 (0)