ionoscloud-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Model Context Protocol (MCP) server that enables LLMs to interact with IONOS CLOUD infrastructure. Built with the official MCP Go SDK and the IONOS CLOUD Go SDK.

Build Commands

make build      # Build the binary (outputs ./ionoscloud-mcp)
make install    # Install the binary to $GOBIN so MCP clients on PATH pick it up
make test       # Run unit tests
make test-e2e   # Binary-over-stdio (mocked API) + read-only live API checks
make fmt        # Format code with gofmt
make vet        # Run go vet
make lint       # Run golangci-lint (read-only)
make lintfix    # Run golangci-lint with --fix
make vuln       # Run govulncheck against all packages
make docker     # Build local Docker image (IMAGE= to override tag)

Pass VERSION=<tag> to make build or make docker to override the version string (defaults to dev).

Architecture

main.go             # Entry point: arg parsing, load-mode resolution, SDK clients init, MCP server, stdio transport
server_config.go    # Version resolution (ldflags > go install > vcs), resolveLoadMode()
resources.go        # MCP resources (embedded docs served to LLM clients)
tools/
├── helpers.go      # Shared helpers (TextResult)
├── inputs.go       # Shared input structs with json/jsonschema tags
├── ionosclient/    # User-Agent string builder
├── loader/         # Lazy loaders for compute and object storage
├── dynamic/        # 'dynamic' load mode: catalog + search/describe/call meta-tools
├── compute/        # Compute Engine tools (servers, datacenters, volumes, NICs, etc.)
├── k8s/            # Managed Kubernetes tools (clusters, node pools, nodes, versions)
├── dns/            # DNS tools (zones, records, reverse records, secondary zones, DNSSEC, quota)
├── billing/        # Billing tools (invoices, usage, utilization, traffic, EVN)
├── cert/           # Certificate Manager tools (certificates, auto-certs, providers)
├── activitylog/    # Activity Log tools (contracts, events)
└── objectstorage/  # Object Storage tools (buckets, objects, access keys, regions)
docs/
├── billing/        # One doc per tool group + focus-v1.3.md (embedded as MCP resource)
├── compute/        # One doc per resource
├── k8s/            # Managed Kubernetes docs
├── dns/            # One doc per resource
├── cert/           # Certificate Manager docs
├── activitylog/    # Activity Log docs
└── objectstorage/  # Object Storage docs