Data Models (Pydantic)
Relevant source files
The following files were used as context for generating this wiki page:
Stacklet MCP uses Pydantic models to define structured data for communication between the Model Context Protocol (MCP) server, the Stacklet Platform GraphQL API, and the AssetDB Redash API. These models ensure type safety, validate inputs for tools, and sanitize sensitive data before returning results to LLMs.
The models are organized into specific packages reflecting the project architecture: assetdb for SQL-related data, platform for GraphQL and dataset exports, and utils for server configuration profiles. Sources: CLAUDE.md:20-40, stacklet/mcp/assetdb/models.py
AssetDB Data Models
AssetDB models facilitate interactions with the Redash-based SQL warehouse. They manage query definitions, execution jobs, and result sets.
Query and User Definitions
The Query model represents a saved SQL query. It includes metadata such as tags, parameters, and ownership information. The model uses ConfigDict(extra="ignore") to prevent sensitive fields like api_key from being leaked during serialization.
The diagram shows the relationship between a saved query and its creator.
Sources: stacklet/mcp/assetdb/models.py:68-124
Query Execution and Results
Execution of queries is tracked via Job and JobStatus. Results are returned using ToolQueryResult, which provides a preview of data (first 20 rows) and handles full dataset delivery via file paths or embedded resources.
| Model | Purpose | Key Fields |
|---|---|---|
Job | Tracks async execution | id, status, query_result_id |
QueryResult | Raw data from API | data, runtime, columns |
ToolQueryResult | LLM-optimized result | some_rows, row_count, full_results_saved_to |
Sources: stacklet/mcp/assetdb/models.py:27-56, stacklet/mcp/assetdb/models.py:269-322
Job Lifecycle
Query execution follows a specific status flow until reaching a terminal state.
The diagram illustrates the job transitions from initiation to terminal states.
Sources: stacklet/mcp/assetdb/models.py:27-44
Platform Data Models
Platform models support GraphQL schema introspection, query execution, and large-scale dataset exports.
GraphQL Operations
Models like ListTypesResult and GetTypesResult allow LLMs to discover and understand the Stacklet Platform schema before executing queries. GraphQLQueryResult captures the response data or any errors returned by the API.
Sources: stacklet/mcp/platform/models.py:17-69
Dataset Export Configuration
Exporting large datasets requires defining columns and JMESPath transformations. The ExportRequest model structures these requirements for the server-side CSV generator.
This flow shows how an export request aggregates column and parameter definitions.
Sources: stacklet/mcp/platform/models.py:80-137
Export Status Tracking
The ConnectionExport model tracks the progress of asynchronous CSV generation.
| Field | Type | Description |
|---|---|---|
dataset_id | str | Unique ID for the export job |
processed_rows | int | Number of rows exported so far |
download_url | str | S3 URL for the finished CSV |
success | bool | Final completion status |
Sources: stacklet/mcp/platform/models.py:140-160
Server Configuration Models
The project uses Pydantic to manage server configuration and tool permission profiles.
Configuration Profiles
The MCPServerConfig model defines the structure of the .mcp.json file used by MCP clients. Profiles determine which features (mutations, saves, archives) are enabled.
class Profile(StrEnum):
DEFAULT = "default"
UNRESTRICTED = "unrestricted"
MCP_SETTINGS_PROFILES = {
Profile.DEFAULT: Settings(
assetdb_allow_archive=False,
assetdb_allow_save=False,
platform_allow_mutations=False,
),
Profile.UNRESTRICTED: Settings(
assetdb_allow_archive=True,
assetdb_allow_save=True,
platform_allow_mutations=True,
),
}
Sources: stacklet/mcp/utils/mcp_json.py:16-36
Summary
Data models in this project serve as the contract for all tool operations. They ensure that LLM-generated inputs conform to API requirements and that API outputs are sanitized and summarized for efficient context window usage. The separation into AssetDB and Platform models reflects the dual nature of Stacklet's data architecture, balancing warehouse-scale SQL analysis with granular GraphQL governance.