Server Utility Libraries
Relevant source files
The following files were used as context for generating this wiki page:
Server Utility Libraries provide standardized functions for tool registration, configuration generation, and cross-component metadata management. These utilities ensure consistent behavior across the Documentation, Platform, and AssetDB packages by centralizing logic for tool annotations, JSON handling, and MCP protocol compliance.
The utility layer manages the transition between raw backend data and the Model Context Protocol (MCP) requirements. It handles essential tasks such as marking tools as read-only or destructive, generating client configurations, and injecting environment-specific settings.
Sources: CLAUDE.md:14-25, stacklet/mcp/utils/tool.py
Tool Registration and Metadata
The utility layer provides a standardized factory for creating MCP tools with appropriate behavioral hints. This ensures that LLM clients understand the risks associated with specific tool calls, such as data mutation or destructive operations.
Tool Factory Logic
The make_tool function wraps Python functions into FastMCP Tool objects. It assigns specific metadata labels that inform the client about the tool's side effects.
| Metadata Field | Description | Source |
|---|---|---|
read_only | Indicates the tool does not modify any state. | stacklet/mcp/utils/tool.py:35 |
destructive | Indicates the tool performs actions that may be irreversible. | stacklet/mcp/utils/tool.py:36 |
idempotent | Indicates multiple identical requests have the same effect as one. | stacklet/mcp/utils/tool.py:37 |
open_world | Indicates the tool may access data outside its immediate context. | stacklet/mcp/utils/tool.py:38 |
The diagram shows how the make_tool utility converts standard functions into annotated MCP tools based on provided flags and server settings.
Sources: stacklet/mcp/utils/tool.py:27-55, stacklet/mcp/platform/tools.py:22-38
Info Tool Generation
Specialized utilities generate "info" tools which provide essential guidance to LLMs. These tools return ToolsetInfo objects containing Markdown content from the repository.
Sources: stacklet/mcp/utils/tool.py:72-84, stacklet/mcp/platform/tools.py:53-64
Configuration Management
The mcp_json utility generates the .mcp.json configuration file required by MCP clients like Claude Desktop. It manages environment variables and execution profiles.
Execution Profiles
The system defines two primary profiles that dictate tool availability and permissions:
- DEFAULT: Restricts write operations. Disallows AssetDB archiving, saving, and Platform mutations.
- UNRESTRICTED: Enables all capabilities, including destructive and state-changing tools.
Sources: stacklet/mcp/utils/mcp_json.py:16-32
Configuration Data Flow
The sequence diagram illustrates the process of generating a client configuration file based on a selected security profile.
Sources: stacklet/mcp/utils/mcp_json.py:53-76, CLAUDE.md:129-140
AssetDB and Platform Integration Utilities
Utilities bridge the gap between specific package clients (Redash, GraphQL) and the FastMCP server context.
Tool Registration Patterns
Components use utility functions to conditionally register tools based on server configuration. For example, assetdb_query_save only registers if SETTINGS.assetdb_allow_save evaluates to true.
| Component | Utility Usage | Logic |
|---|---|---|
| AssetDB | _result_tool | Explicitly declares ToolQueryResult schema for SQL results. |
| Platform | _graphql_query_tool | Dynamically flips read_only flag based on mutation settings. |
| Common | json_guard | Validates input parameters for JSON-safe execution. |
Sources: stacklet/mcp/assetdb/tools.py:36-64, stacklet/mcp/platform/tools.py:30-48
Result Handling Utility
A shared logic in the AssetDB package manages large result sets. It decides whether to write rows to the filesystem or attach them as MCP resources.
- Downloads Enabled: Writes to
STACKLET_MCP_DOWNLOADS_PATH. - Downloads Disabled: Attaches data to the
ToolResultas anEmbeddedResource.
Sources: stacklet/mcp/assetdb/tools.py:293-330
Summary
Server Utility Libraries standardize the interface between Stacklet's cloud governance logic and the MCP protocol. By centralizing tool annotation logic, configuration generation, and result set management, these utilities ensure the server operates predictably across different security profiles and deployment environments.
Sources: CLAUDE.md:10-25, stacklet/mcp/utils/tool.py, stacklet/mcp/utils/mcp_json.py