Aiven Resource Management Utility (ARMU)

This package encapsulates a minimal Aiven service broker, packaged as a portable Docker artifact.

Deployment Guide

1. Provision a configuration file named .env containing necessary API credentials:

# Aiven API Connectivity Settings
API_ENDPOINT=https://api.aiven.io
TARGET_AIVEN_PROJECT=your-designated-project

# Authentication Credential
AUTH_SECRET_KEY=your-api-token-here

1. Initiate the service using Docker Compose:

docker compose up -d

1. The management service will be accessible via HTTP on port 8000 (e.g., http://localhost:8000).

Accessible HTTP Interface

• GET /: Displays the operational status of the broker and current environment settings.
• GET /api/projects: Returns a JSON payload enumerating all accessible Aiven projects.

Termination Procedure

To gracefully stop and dismantle the running environment:

docker compose down

Aiven Broker Functionality

This ARM utility exposes several functional routines:

Available Operations

• enumerate_projects

• Retrieves a catalog of all projects associated with the authenticated Aiven tenant.

• fetch_project_services

• Fetches the inventory of deployed services within a specified Aiven project context.

• retrieve_service_specs

• Obtains granular configuration specifications for a designated service residing in a target Aiven project.

• get_service_telemetry

• Extracts ancillary metadata for a specific Aiven service instance (currently optimized for Aiven PostgreSQL deployments).

• execute_sql_command

• Permits the execution of SQL statements against a provisioned Aiven service endpoint (currently limited to Aiven PostgreSQL).

Integration Setup for Claude Desktop

1. Modify the Claude Desktop configuration file located at:
2. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

3. Windows: %APPDATA%/Claude/claude_desktop_config.json

4. Incorporate the following structure under the mcpServers configuration block:

{
  "mcpServers": {
    "aiven-armu": {
      "command": "uv",
      "args": [
        "--directory",
        "$REPOSITORY_ROOT",
        "run",
        "--with-editable",
        "$REPOSITORY_ROOT",
        "--python",
        "3.13",
        "aiven_armu_package_name"
      ],
      "env": {
        "API_ENDPOINT": "https://api.aiven.io",
        "TARGET_AIVEN_PROJECT": "$DEFAULT_PROJECT_NAME",
        "AUTH_SECRET_KEY": "$AIVEN_API_TOKEN"
      }
    }
  }
}

Remember to substitute dynamic placeholders: * $REPOSITORY_ROOT with the local path to the repository source code. * TARGET_AIVEN_PROJECT with your primary project identifier. * $AIVEN_API_TOKEN with your valid access token found at Aiven Token Documentation.

1. Ensure the uv execution path is absolute within the command entry. Use which uv on Unix-like systems to determine the correct path for direct invocation.

2. Relaunch the Claude Desktop application to effectuate the configuration changes.

Integration Setup for Cursor IDE

1. Navigate to Cursor Application Settings -> Configuration Interface.

2. Access the 'MCP Servers' management section.

3. Establish a new server entry defining:

   • Identifier: aiven-armu
   • Protocol Type: command
   • Execution String: uv --directory $REPOSITORY_ROOT run --with-editable $REPOSITORY_ROOT --python 3.13 aiven_armu_package_name

Environment variables like API_ENDPOINT, TARGET_AIVEN_PROJECT, and AUTH_SECRET_KEY may need to be externally injected or defined within the IDE's environment settings.

Development Workflow

1. Establish the required environment settings in the repository's root .env file:

API_ENDPOINT=https://api.aiven.io
TARGET_AIVEN_PROJECT=$DEFAULT_PROJECT_NAME
AUTH_SECRET_KEY=$AIVEN_API_TOKEN

1. Synchronize package dependencies using uv sync. Refer to Astral UV documentation for installation guidance. Activate the virtual environment via source .venv/bin/activate.

2. For iterative testing, initiate the broker service using the development harness: mcp dev aiven_armu/main_broker.py

Configuration Parameters

These environment variables govern the connection parameters for the Aiven API interaction:

Mandatory Inputs

• API_ENDPOINT: The designated base Uniform Resource Locator for Aiven services.
• TARGET_AIVEN_PROJECT: The default project identifier for operations.
• AUTH_SECRET_KEY: The required security token for API authentication.