mcp-aiven 0.1.5

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "mcp-aiven",
+  "version": "0.1.5",
+  "description": "MCP server for Aiven cloud data platform - manage PostgreSQL, Kafka, and other services",
+  "type": "module",
+  "main": "dist/index.js",
+  "keywords": [
+    "mcp",
+    "aiven",
+    "postgresql",
+    "kafka",
+    "cloud",
+    "database",
+    "model-context-protocol"
+  ],
+  "author": "Aiven",
+  "license": "Apache-2.0",
+  "files": [
+    "dist",
+    "src/manifests",
+    "generator/schemas",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Aiven-Open/mcp-aiven.git"
+  },
+  "bugs": "https://github.com/Aiven-Open/mcp-aiven/issues",
+  "homepage": "https://github.com/Aiven-Open/mcp-aiven/blob/main/README.md",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "express": "^5.2.1",
+    "express-rate-limit": "^8.3.2",
+    "libpg-query": "^17.7.3",
+    "openapi-fetch": "^0.17.0",
+    "pg": "^8.18.0",
+    "yaml": "^2.4.0",
+    "zod": "^3.23.8"
+  },
+  "bin": {
+    "mcp-aiven": "dist/index.js"
+  },
+  "scripts": {
+    "generate": "tsx generator/src/cli.ts",
+    "build": "tsc && rm -rf dist/manifests && cp -r src/manifests dist/manifests",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "test": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm i && pnpm generate:api-types && pnpm generate && pnpm build && pnpm test --run",
+    "generate:api-types": "openapi-typescript https://api.aiven.io/doc/openapi.json -o src/generated/aiven-api.ts"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.10.0",
+    "@types/pg": "^8.16.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-security": "^3.0.0",
+    "globals": "^15.0.0",
+    "lint-staged": "^15.0.0",
+    "openapi-typescript": "^7.13.0",
+    "prettier": "^3.2.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/manifests/core.yaml

@@ -0,0 +1,206 @@
+# Core tools: projects, services, logs, events
+tools:
+  - name: aiven_project_list
+    method: GET
+    path: /project
+    category: core
+    append_list_picker_hint: true
+    response_filter:
+      key: projects
+      fields: [project_name, default_cloud, organization_id, tags]
+    description: |
+      List all Aiven projects. ALWAYS call this first to get valid `project` names — never guess project names.
+
+  - name: aiven_project_get
+    method: GET
+    path: /project/{project}
+    category: core
+
+  - name: aiven_list_project_clouds
+    method: GET
+    path: /project/{project}/clouds
+    category: core
+    append_list_picker_hint: true
+
+    response_filter:
+      key: clouds
+      fields: [cloud_name, cloud_description, provider, geo_region]
+
+  - name: aiven_service_list
+    method: GET
+    path: /project/{project}/service
+    category: core
+    append_list_picker_hint: true
+    exclude_params: [include_secrets]
+    response_filter:
+      key: services
+      fields: [service_name, service_type]
+    description: |
+      List services in a project. `project` must be a valid Aiven project name from `aiven_project_list`.
+
+  - name: aiven_service_type_plans
+    method: GET
+    path: /project/{project}/service-types/{service_type}/plans
+    category: core
+    append_list_picker_hint: true
+    response_filter:
+      key: service_plans
+      fields: [service_plan]
+    description: |
+      List available plans for a service type. Requires `project` — use `aiven_project_list` first if unknown.
+
+      Each plan may include **`regions`** (and sometimes **`clouds`**) describing where that plan can run. Use those fields to show the user **which cloud names** (e.g. `do-fra`, `aws-eu-central-1`) are valid for their chosen plan before calling `aiven_service_create`.
+
+      **Pricing is not included in this response.** Prices vary by cloud region. Use `aiven_service_plan_pricing` to get pricing for a specific plan and cloud.
+
+  - name: aiven_service_plan_pricing
+    method: GET
+    path: /project/{project}/pricing/service-types/{service_type}/plans/{service_plan}/clouds/{cloud}
+    category: core
+    readOnly: true
+    append_list_picker_hint: true
+    description: |
+      Get pricing for a specific service plan in a specific cloud region. Returns hourly USD price.
+
+      Use `aiven_service_type_plans` to list available plans, and `aiven_list_project_clouds` to list available clouds.
+
+  - name: aiven_service_create
+    method: POST
+    path: /project/{project}/service
+    category: core
+    append_list_picker_hint: true
+    defaults:
+      project_vpc_id: null
+    response_filter:
+      key: service
+      fields: [service_name, service_type, state, plan, cloud_name]
+    description: |
+      Create a new Aiven service. Always call `aiven_service_type_plans` first, present plans to the user, and let them choose before creating. Do not pick a plan yourself.
+
+      **Cloud (`cloud`) — never guess or silently default.** After the user picks a plan, show valid cloud names from that plan’s **`regions` / `clouds`** in the `aiven_service_type_plans` response and **ask which cloud they want**. Do not invent a region (e.g. do not assume `do-fra`). If per-plan clouds are unclear, call `aiven_list_project_clouds` and still require an **explicit user choice** unless they told you to use a specific cloud or the project’s default.
+
+      For PostgreSQL, set `user_config: {"pg_version": "17"}`. After creation, tell the user the service is provisioning (takes a few minutes) and ask them to tell you when to check the status. Do NOT poll `aiven_service_get` in a loop.
+
+      **Read replica:** set `service_to_fork_from` to the primary and `user_config.pg_read_replica: true`.
+
+  - name: aiven_service_get
+    method: GET
+    path: /project/{project}/service/{service_name}
+    category: core
+    exclude_params: [include_secrets]
+    description: |
+      Get service information. `project` must be a valid Aiven project name from `aiven_project_list`.
+      If the service `state` is not `RUNNING`, return the status to the user and stop. Do NOT call this tool again in a loop — let the user decide when to re-check.
+
+  - name: aiven_service_update
+    method: PUT
+    path: /project/{project}/service/{service_name}
+    category: core
+    destructive: true
+    defaults:
+      project_vpc_id: null
+    description: |
+      Update an existing Aiven service.
+
+      Can change: plan, cloud region, user configuration, power state.
+
+      **Warning:** Plan changes may cause brief service downtime during migration. Confirm with the user before changing plans.
+
+      **Common user_config changes:**
+
+      Enable Kafka Connect on a Kafka service:
+      ```
+      aiven_service_update(project="my-project", service_name="my-kafka",
+        user_config={"kafka_connect": true})
+      ```
+
+      Enable Schema Registry (Karapace) on a Kafka service:
+      ```
+      aiven_service_update(project="my-project", service_name="my-kafka",
+        user_config={"schema_registry": true})
+      ```
+
+      Enable tiered storage on a Kafka service:
+      ```
+      aiven_service_update(project="my-project", service_name="my-kafka",
+        user_config={"tiered_storage": {"enabled": true}})
+      ```
+
+      Set PostgreSQL version:
+      ```
+      aiven_service_update(project="my-project", service_name="my-pg",
+        user_config={"pg_version": "17"})
+      ```
+
+  - name: aiven_project_get_service_logs
+    method: POST
+    path: /project/{project}/service/{service_name}/logs
+    category: core
+    readOnly: true
+
+  - name: aiven_service_query_activity
+    method: POST
+    path: /project/{project}/service/{service_name}/query/activity
+    category: core
+    readOnly: true
+
+  - name: aiven_service_metrics_fetch
+    method: POST
+    path: /project/{project}/service/{service_name}/metrics
+    category: core
+    readOnly: true
+
+    description: |
+      Fetch metrics for **managed data services** (PostgreSQL, Kafka, OpenSearch, etc.) — i.e. not `service_type: application`.
+
+      **Do not use** for **application** services (custom apps deployed as an Aiven “application” service). For those, use **`aiven_service_application_metrics_get`** instead (GET `…/application/metrics`). If unsure, call `aiven_service_get` first and check `service_type`.
+
+      Use `period` to control the time window: `hour`, `day`, `week`, `month`, or `year`.
+      For Kafka services, optionally pass `kafka_topic_name` to get topic-level metrics.
+
+      **Display format:** Render ALL metrics as a single ASCII dashboard using box-drawing characters (┌─┐│└┘) and progress bars (█░). One section per metric group. Show every metric returned — do not summarize or omit. Do NOT use markdown tables or bullet points. Do NOT generate scripts. Render directly as text. Add a blank line between each metric row for readability.
+
+  # Not in public OpenAPI — schema is maintained here (see generator manual_schema).
+  - name: aiven_service_application_metrics_get
+    method: GET
+    path: /project/{project}/service/{service_name}/application/metrics
+    category: core
+    readOnly: true
+    manual_schema:
+      type: object
+      properties:
+        project:
+          type: string
+        service_name:
+          type: string
+      required:
+        - project
+        - service_name
+    manual_strict: true
+    description: |
+      **Preferred tool** when the user asks for **application** metrics, or the target is an **application** service (`service_type: application`).
+
+      Calls **`GET …/application/metrics`**. Do **not** use `aiven_service_metrics_fetch` for these — that tool targets **`POST …/metrics`** for managed data services only.
+
+      If the service type is unknown, call **`aiven_service_get`** first, then choose this tool if `service_type` is `application`.
+
+  - name: aiven_project_vpc_list
+    method: GET
+    path: /project/{project}/vpcs
+    category: core
+    readOnly: true
+    response_filter:
+      key: vpcs
+      fields: [project_vpc_id, cloud_name, state, network_cidr]
+    description: |
+      List VPCs for a project. Returns each VPC's ID, cloud, state, and network CIDR.
+
+      Use this when deploying an application service fails with "please specify project_vpc_id" (i.e. the project has multiple active VPCs). List them, show the user the options, and let them pick which VPC to deploy into.
+
+      VPCs with state `ACTIVE` are ready to use. Pass the chosen `project_vpc_id` to `aiven_application_deploy`.
+
+  - name: aiven_project_get_event_logs
+    method: GET
+    path: /project/{project}/events
+    category: core
+    append_list_picker_hint: true

package/src/manifests/integrations.yaml

@@ -0,0 +1,72 @@
+# Service integration tools: CRUD for integrations between Aiven services and external endpoints
+
+tools:
+  - name: aiven_service_integration_list
+    method: GET
+    path: /project/{project}/service/{service_name}/integration
+    category: integrations
+    readOnly: true
+    append_list_picker_hint: true
+    description: |
+      List all integrations for a specific service. Returns both integrations where this service is the source and where it is the destination.
+
+      Use this to see what metrics, logs, data pipeline, or replication integrations are active on a service.
+
+  - name: aiven_service_integration_create
+    method: POST
+    path: /project/{project}/integration
+    category: integrations
+    description: |
+      Create a service integration between two Aiven services, or between an Aiven service and an external integration endpoint.
+
+      **Before calling:** use `aiven_integration_types_list` to discover valid `integration_type` values and which source/destination service types each supports.
+
+      Provide `source_service`/`dest_service` for Aiven-to-Aiven integrations, or use `source_endpoint_id`/`dest_endpoint_id` for external endpoints.
+
+  - name: aiven_service_integration_get
+    method: GET
+    path: /project/{project}/integration/{integration_id}
+    category: integrations
+    readOnly: true
+    description: |
+      Get details for a specific service integration by ID. Returns the integration type, source and destination services, status, and configuration.
+
+  - name: aiven_service_integration_update
+    method: PUT
+    path: /project/{project}/integration/{integration_id}
+    category: integrations
+    description: |
+      Update the configuration of an existing service integration.
+
+      Only `user_config` can be updated — you cannot change the integration type, source, or destination after creation. To change those, delete and recreate the integration.
+
+  - name: aiven_service_integration_delete
+    method: DELETE
+    path: /project/{project}/integration/{integration_id}
+    category: integrations
+    description: |
+      Delete a service integration. This removes the connection between the source and destination services.
+
+      **Warning:** Deleting an integration may disrupt data flows (metrics, logs, replication). Confirm with the user before proceeding.
+
+  - name: aiven_integration_types_list
+    method: GET
+    path: /project/{project}/integration_types
+    category: integrations
+    readOnly: true
+    append_list_picker_hint: true
+    description: |
+      List all available service integration types for a project. Returns the integration type name along with the valid source and destination service types for each.
+
+      **Call this first** before creating an integration to understand which service types can be connected and in which direction.
+
+  - name: aiven_integration_endpoint_types_list
+    method: GET
+    path: /project/{project}/integration_endpoint_types
+    category: integrations
+    readOnly: true
+    append_list_picker_hint: true
+    description: |
+      List all available integration endpoint types for a project. Integration endpoints represent external services (e.g. Datadog, external Elasticsearch, Prometheus remote write, rsyslog, AWS CloudWatch, Google Cloud Logging).
+
+      Use this to discover what external endpoint types can be created, then use `aiven_service_integration_create` with the endpoint ID to wire an Aiven service to the external system.

package/src/manifests/kafka.yaml

@@ -0,0 +1,143 @@
+# Kafka tools: topics, connectors, schema registry
+
+kafka_connect_plan_gate: &kafka_connect_plan_gate |
+  **Kafka Connect plan gate — call `aiven_service_get` first.** Read `service.plan`. On **free** Kafka plans (e.g. `free-0`), Kafka Connect is usually **not** included: Connect REST calls may return **403** (e.g. "Kafka Connect API disabled"). Do **not** call this tool when `service.plan` is `free-*` or the tier is known not to include Connect; tell the user to upgrade instead of hitting the API.
+
+  **Typically no Kafka Connect:** `free-*` (e.g. `free-0`).
+
+  **Typically includes Kafka Connect:** `startup-*` (e.g. `startup-2`, `startup-4`), `business-*`, `premium-*`.
+
+  On supported plans you may still need `user_config.kafka_connect: true`. A **403** saying Kafka Connect is **disabled** is usually a **plan / product** limit, not missing token permissions.
+
+tools:
+  - name: aiven_kafka_topic_list
+    method: GET
+    path: /project/{project}/service/{service_name}/topic
+    category: kafka
+    append_list_picker_hint: true
+
+  - name: aiven_kafka_topic_create
+    method: POST
+    path: /project/{project}/service/{service_name}/topic
+    category: kafka
+
+    description: |
+      Create a Kafka topic.
+
+      **IMPORTANT:** Always include `partitions` and `replication` in the request. The API may accept them as optional but topics created without these fields may not work correctly.
+
+      Recommended defaults:
+      - `partitions`: 1 (or more depending on throughput needs)
+      - `replication`: 3 (must not exceed the number of brokers in the cluster)
+
+      After creation, do NOT immediately call `aiven_kafka_topic_get` or other tools on this topic. Tell the user the topic was created and will be available shortly.
+
+  - name: aiven_kafka_topic_get
+    method: GET
+    path: /project/{project}/service/{service_name}/topic/{topic_name}
+    category: kafka
+
+  - name: aiven_kafka_topic_update
+    method: PUT
+    path: /project/{project}/service/{service_name}/topic/{topic_name}
+    category: kafka
+
+  - name: aiven_kafka_topic_delete
+    method: DELETE
+    path: /project/{project}/service/{service_name}/topic/{topic_name}
+    category: kafka
+
+  - name: aiven_kafka_topic_message_list
+    method: POST
+    path: /project/{project}/service/{service_name}/kafka/rest/topics/{topic_name}/messages
+    category: kafka
+    readOnly: true
+
+    description: |
+      Consume messages from a Kafka topic.
+
+      **REQUIRED BEFORE CALLING THIS TOOL — follow these steps in order:**
+      1. Kafka REST API must be enabled. Call `aiven_service_update` with `user_config: {"kafka_rest": true}` if not already enabled.
+      2. Call `aiven_service_get` once to check if `components` contains `kafka_rest` with `state: "running"`. If not ready, tell the user to wait and ask them when to re-check. Do NOT poll in a loop.
+
+      **Format:** The `format` must match how messages were produced. Use `"binary"` for Debezium CDC or any schema-encoded messages (values are returned as base64). Use `"json"` only for plain JSON messages produced without a schema.
+
+      The `partitions` parameter is an object keyed by partition number (as a string), each with an `offset` value.
+
+      **Example:**
+      ```
+      aiven_kafka_topic_message_list(
+        project="my-project",
+        service_name="my-kafka",
+        topic_name="my-topic",
+        partitions={"0": {"offset": 0}},
+        format="binary"
+      )
+      ```
+
+  - name: aiven_kafka_topic_message_produce
+    method: POST
+    path: /project/{project}/service/{service_name}/kafka/rest/topics/{topic_name}/produce
+    category: kafka
+
+    description: |
+      Produce messages into a Kafka topic.
+
+      **REQUIRED BEFORE CALLING THIS TOOL — follow these steps in order:**
+      1. Kafka REST API must be enabled. Call `aiven_service_update` with `user_config: {"kafka_rest": true}` if not already enabled.
+      2. Call `aiven_service_get` once to check if `components` contains `kafka_rest` with `state: "running"`. If not ready, tell the user to wait and ask them when to re-check. Do NOT poll in a loop.
+
+  - name: aiven_kafka_connect_available_connectors
+    method: GET
+    path: /project/{project}/service/{service_name}/available-connectors
+    category: kafka
+    append_list_picker_hint: true
+    description: *kafka_connect_plan_gate
+
+  - name: aiven_kafka_connect_list
+    method: GET
+    path: /project/{project}/service/{service_name}/connectors
+    category: kafka
+    append_list_picker_hint: true
+    description: *kafka_connect_plan_gate
+
+  - name: aiven_kafka_connect_get_connector_status
+    method: GET
+    path: /project/{project}/service/{service_name}/connectors/{connector_name}/status
+    category: kafka
+    description: *kafka_connect_plan_gate
+
+  - name: aiven_kafka_connect_pause_connector
+    method: POST
+    path: /project/{project}/service/{service_name}/connectors/{connector_name}/pause
+    category: kafka
+    description: *kafka_connect_plan_gate
+
+  - name: aiven_kafka_connect_resume_connector
+    method: POST
+    path: /project/{project}/service/{service_name}/connectors/{connector_name}/resume
+    category: kafka
+    description: *kafka_connect_plan_gate
+
+  - name: aiven_kafka_connect_restart_connector
+    method: POST
+    path: /project/{project}/service/{service_name}/connectors/{connector_name}/restart
+    category: kafka
+    description: *kafka_connect_plan_gate
+
+  - name: aiven_kafka_connect_delete_connector
+    method: DELETE
+    path: /project/{project}/service/{service_name}/connectors/{connector_name}
+    category: kafka
+    description: *kafka_connect_plan_gate
+
+  - name: aiven_kafka_schema_registry_subjects
+    method: GET
+    path: /project/{project}/service/{service_name}/kafka/schema/subjects
+    category: kafka
+    append_list_picker_hint: true
+
+  - name: aiven_kafka_schema_registry_subject_version_get
+    method: GET
+    path: /project/{project}/service/{service_name}/kafka/schema/subjects/{subject_name}/versions/{version_id}
+    category: kafka

package/src/manifests/pg.yaml

@@ -0,0 +1,43 @@
+# PostgreSQL tools: extensions, query stats, connection pools
+
+pg_connection_pool_plan_gate: &pg_connection_pool_plan_gate |
+  **PgBouncer connection pools** — `aiven_pg_bouncer_create`, `aiven_pg_bouncer_update`, and `aiven_pg_bouncer_delete` call Aiven’s `connection_pool` API.
+
+  **Plan gate — call `aiven_service_get` first.** Read `service.plan` (string). Do **not** call these tools if the plan does not support connection pooling; tell the user they need a higher tier instead of attempting the API.
+
+  **Plans that do _not_ include connection pooling:** `free-1-1gb`, `free-1-5gb`, any `free-*` plan, and **`hobbyist`**.
+
+  **Plans that support connection pooling:** `startup-*`, `business-*`, and `premium-*` (e.g. `startup-4`, `business-8`).
+
+  If the API returns **403** with a message about the service plan not including connection pooling, interpret that as a **plan limitation**, not necessarily a missing token permission.
+
+tools:
+  - name: aiven_pg_service_available_extensions
+    method: GET
+    path: /project/{project}/service/{service_name}/pg/available-extensions
+    category: pg
+    append_list_picker_hint: true
+
+  - name: aiven_pg_service_query_statistics
+    method: POST
+    path: /project/{project}/service/{service_name}/pg/query/stats
+    category: pg
+    readOnly: true
+
+  - name: aiven_pg_bouncer_create
+    method: POST
+    path: /project/{project}/service/{service_name}/connection_pool
+    category: pg
+    description: *pg_connection_pool_plan_gate
+
+  - name: aiven_pg_bouncer_update
+    method: PUT
+    path: /project/{project}/service/{service_name}/connection_pool/{pool_name}
+    category: pg
+    description: *pg_connection_pool_plan_gate
+
+  - name: aiven_pg_bouncer_delete
+    method: DELETE
+    path: /project/{project}/service/{service_name}/connection_pool/{pool_name}
+    category: pg
+    description: *pg_connection_pool_plan_gate