Downloads & Storage Paths
Relevant source files
The following files were used as context for generating this wiki page:
The Stacklet MCP server manages query results and temporary data through a configurable storage system. It primarily handles the output of large AssetDB SQL queries, which often exceed the context window limits of Large Language Models (LLMs). The system provides two primary routes for data delivery: local file storage or embedded MCP resources.
Sources: CLAUDE.md:144-150, stacklet/mcp/assetdb/tools.py:307-315
Storage Configuration
The server uses pydantic-settings to manage storage paths and behavior via environment variables. The Settings class defines how and where files are persisted.
Key Configuration Variables
| Variable | Type | Default | Description |
|---|---|---|---|
STACKLET_MCP_DOWNLOADS_PATH | Path | System Temp Dir | Directory for storing query result files. |
STACKLET_MCP_DOWNLOADS_ENABLED | bool | True | Writes complete results to disk if true; otherwise attaches them as resources. |
Sources: stacklet/mcp/settings.py:16-29, README.md:65-66, tests/test_settings.py:22-26
Data Persistence Logic
The server determines the storage method based on the downloads_enabled flag. This logic prevents file accumulation in hosted environments where the client cannot access the server's local filesystem.
The diagram shows the decision flow for handling large result sets based on server configuration.
Sources: stacklet/mcp/assetdb/tools.py:307-315, stacklet/mcp/settings.py:20-27
File Naming Conventions
When files are written to disk, the server uses specific naming patterns to ensure traceability:
- Saved Queries:
assetdb_{query_id}_{result_id}.json - Ad-hoc Queries:
assetdb_{result_id}.json
Sources: CLAUDE.md:147-149, stacklet/mcp/assetdb/tools.py:305-306
File Utility Operations
The server implements utility functions to manage file lifecycle and directory structure safely.
Directory Creation
The system automatically creates parent directories for the configured downloads_path if they do not exist during the first write operation.
Sources: tests/test_settings.py:79-88
Result Serialization
The _write_rows function handles the physical writing of data to the filesystem. It uses asyncio.to_thread to ensure that blocking I/O operations do not stall the main event loop.
def _write_rows(rows: list[dict[str, Any]], identity: str) -> str:
"""Write rows to a JSON file in the downloads directory, returning its path."""
with download_file("w", f"assetdb_{identity}", ".json") as f:
json.dump(rows, f, ensure_ascii=False, default=str)
return f.name
Sources: stacklet/mcp/assetdb/tools.py:339-343, stacklet/mcp/assetdb/tools.py:309-311
Result Delivery Models
The ToolQueryResult model encapsulates the metadata and the reference to the full data set.
Metadata vs. Full Data
- Preview: The tool response includes the first 20 rows of a result set (
some_rows) for immediate LLM context. - Full Results Reference: The
full_results_saved_tofield contains the absolute path to the file on disk ifdownloads_enabledis true. - Resource URI: If
downloads_enabledis false, the data is identified by a URI matching the patternassetdb://query_results/{identity}.json.
Sources: stacklet/mcp/assetdb/models.py:220-229, stacklet/mcp/assetdb/tools.py:346-355
Conclusion
The storage system ensures that the Stacklet MCP server can handle high-volume data analytics without overwhelming the LLM's context window. By providing configurable paths and dual delivery modes (Filesystem vs. MCP Resource), it supports both local development and restricted hosted environments.