Agent Config Generation

Agent Config Generation provides a mechanism to create .mcp.json configuration files for Model Context Protocol (MCP) clients such as Claude Desktop. This system automates the setup of environment variables and execution commands required for the agent to interface with the Stacklet MCP server.

The generation process utilizes predefined profiles to control the level of access granted to the AI agent. These profiles determine feature flags for writing, archiving, and mutating data within the Stacklet platform and AssetDB.
Sources: CLAUDE.md:209-220, README.md:38-44, stacklet/mcp/utils/mcp_json.py:17-31

CLI Architecture and Commands

The command-line interface (CLI) exposes the config generation functionality through the agent-config subcommand. Users interact with these commands via the stacklet-mcp binary or uv run stacklet-mcp.

Available Commands

Sources: stacklet/mcp/cmdline.py:20-53, CLAUDE.md:209-220

Generation Flow

The following diagram illustrates the flow from a CLI request to the final JSON output.

The CLI uses Pydantic-based command models to parse arguments and execute the cli_cmd methods.
Sources: stacklet/mcp/cmdline.py:20-60, stacklet/mcp/utils/mcp_json.py:53-58

Configuration Profiles

The system defines profiles that group server settings into logical access levels. These profiles are mapped in the MCP_SETTINGS_PROFILES dictionary.

Profile Definitions

Sources: stacklet/mcp/utils/mcp_json.py:17-31, CLAUDE.md:222-226

Profile Settings Mapping

This diagram shows how profiles map to specific feature flags.

Environment Variable Resolution

The generation process converts Pydantic settings into environment variables using the STACKLET_MCP_ prefix.

1. Prefixing: The env_prefix defined in the Settings model (typically STACKLET_MCP_) is prepended to each setting name.
2. Formatting: Setting names are converted to uppercase.
3. OS Specifics: If generated on Windows (win32), the generator automatically adds PYTHONUTF8=1 to the environment to prevent encoding errors.
4. Serialization: Values are converted to strings for the JSON output.

Sources: stacklet/mcp/utils/mcp_json.py:73-82, README.md:79-84

JSON Structure

The output follows the standard MCP server configuration format. It includes the execution command, arguments, and the resolved environment variables.

Configuration Model

The MCPServerConfig class defines the structure of the resulting JSON.

class MCPServerConfig(BaseModel):
    """The .mcp.json file content."""

    command: str
    args: tuple[str, ...] | None = None
    env: dict[str, str] | None = None

    def file_content(self) -> dict[str, Any]:
        """Content of the mcp.json file."""
        config = self.model_dump(exclude_none=True)
        return {
            "mcpServers": {
                "stacklet": config,
            }
        }

Sources: stacklet/mcp/utils/mcp_json.py:34-49

Command Detection

The generator detects the execution environment to determine the command and args fields:

• If run via __main__.py, it uses the Python executable with the -m stacklet.mcp argument.
• Otherwise, it uses the path to the current script as the command.

Sources: stacklet/mcp/utils/mcp_json.py:61-70

Summary

Agent Config Generation simplifies the integration between the Stacklet MCP server and various AI agents. By providing pre-configured profiles, it ensures that users can easily deploy agents with appropriate security boundaries, ranging from read-only access to full administrative capabilities. The generated configuration handles environmental complexities, such as Windows encoding requirements and path resolution, automatically.
Sources: README.md:46-52, CLAUDE.md:209-220