Development Environment Setup

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• README.md
• pyproject.toml
• stacklet/mcp/settings.py
• stacklet/mcp/utils/mcp_json.py
• tests/test_settings.py

The Development Environment Setup provides the necessary steps to configure a local workspace for contributing to the Stacklet MCP server. It covers tool installation, dependency management, authentication workflows, and server configuration.

This project uses modern Python tooling including uv for package management and just for task automation. Following these steps ensures a consistent environment for developing tools that interact with Stacklet's Platform GraphQL API and AssetDB SQL warehouse.

Core Prerequisites

The project requires specific software versions and management tools for proper operation.

• Python 3.12+: The project specifies a minimum version of Python 3.12. Sources: [pyproject.toml:11](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/pyproject.toml#L11), [CLAUDE.md:166](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/CLAUDE.md#L166)
• uv: Used for fast dependency synchronization and environment management. Sources: [CLAUDE.md:83](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/CLAUDE.md#L83), [README.md:31](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/README.md#L31)
• just: A command runner used to execute development tasks like linting, testing, and installation. Sources: [README.md:103](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/README.md#L103), [CLAUDE.md:87](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/CLAUDE.md#L87)
• mise: Recommended tool for managing dev-tool versions. Sources: [README.md:94](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/README.md#L94)

Initial Installation

You must synchronize the environment and install dependencies before running the server or tests.

1. Install required tools using mise install.
2. Synchronize dependencies with uv sync or just install.
3. The just install command automatically generates a default .mcp.json configuration file if one does not exist.

Sources: [README.md:94-108](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/README.md#L94-L108), [CLAUDE.md:83-91](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/CLAUDE.md#L83-L91)

The diagram above shows the linear progression from tool installation to running the MCP inspector.

Authentication Setup

The MCP server requires valid Stacklet credentials to access Platform and AssetDB services. It follows the same credential resolution logic as the Stacklet Terraform provider.

Credential Resolution Order

1. Environment Variables: STACKLET_ENDPOINT, STACKLET_ACCESS_TOKEN, and STACKLET_IDENTITY_TOKEN.
2. Configuration Files: Files saved by the stacklet-admin CLI located in ~/.stacklet/ (config.json, credentials, and id).

Authentication Procedure

1. Install the platform client: uv tool install stacklet.client.platform.
2. Log in to your environment: stacklet-admin login.
3. The login remains valid for twelve hours.

Sources: [CLAUDE.md:65-72](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/CLAUDE.md#L65-L72), [README.md:46-60](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/README.md#L46-L60)

The sequence diagram illustrates how credentials flow from the login command to the MCP server's local environment.

Server Configuration

Configuration is managed through environment variables prefixed with STACKLET_MCP_.

Variable	Default Value	Description
STACKLET_MCP_DOWNLOADS_PATH	System Temp Dir	Directory for storing query result files.
STACKLET_MCP_DOWNLOADS_ENABLED	true	Whether to write result files to the filesystem.
STACKLET_MCP_ASSETDB_DATASOURCE_NAME	AssetDB	Name used to look up the Redash data source ID.
STACKLET_MCP_ASSETDB_DATASOURCE	None	Explicit Redash data source ID (overrides name lookup).
STACKLET_MCP_ASSETDB_ALLOW_SAVE	false	Enables query save/update tools.
STACKLET_MCP_ASSETDB_ALLOW_ARCHIVE	false	Enables query archiving tools.
STACKLET_MCP_PLATFORM_ALLOW_MUTATIONS	false	Enables GraphQL mutation operations.

Sources: [stacklet/mcp/settings.py:17-64](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/stacklet/mcp/settings.py#L17-L64), [README.md:66-77](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/README.md#L66-L77)

Agent Profiles and MCP Configuration

The project supports generating standardized .mcp.json files for agents using the agent-config command.

Configuration Profiles

• default: Restricted access. Disables write operations and mutations.
• unrestricted: Full access. Enables all tools including assetdb_query_save and platform_allow_mutations.

Sources: [stacklet/mcp/utils/mcp_json.py:23-35](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/stacklet/mcp/utils/mcp_json.py#L23-L35), [CLAUDE.md:154-162](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/CLAUDE.md#L154-L162)

Profile Definitions

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:23-35](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/stacklet/mcp/utils/mcp_json.py#L23-L35)

Development Tasks

Use just commands to maintain code quality and verify functionality.

• Linting: just lint runs pre-commit hooks, formatters, and linters (Ruff).
• Testing: just test runs pytest. Use just test-coverage for reports.
• Inspecting: just inspect launches the MCP inspector tool to peek at protocol details.
• CLI Entrypoint: uv run stacklet-mcp runs the server directly.

Sources: [CLAUDE.md:87-98](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/CLAUDE.md#L87-L98), [pyproject.toml:68-76](https://github.com/stacklet/mcp-server/blob/60b83c90ffebbb89b1917bde6a6638a48622fede/pyproject.toml#L68-L76)

Summary

Setting up the development environment involves installing Python 3.12, uv, and just, followed by authenticating via stacklet-admin. The system relies on a modular configuration strategy where environment variables and agent profiles determine the server's permission levels. Developers use the just command suite to ensure code conforms to project standards and to verify tool behavior through the MCP inspector.