WIP: Initial code

.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(export:*)",
+      "Bash(make check-deps:*)",
+      "Bash(go get:*)",
+      "WebFetch(domain:github.com)",
+      "Bash(go list:*)",
+      "Bash(go mod:*)",
+      "Bash(go run:*)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(go build:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

.gitignore

@@ -0,0 +1,49 @@
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Go workspace file
+go.work
+
+# Build artifacts
+/out/
+mapt-mcp
+mapt-mcp-*
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Coverage files
+coverage.out
+coverage.html
+
+# Temporary files
+*.tmp
+*.temp
+
+# Local configuration files
+config.toml
+*.local.toml
+
+# Logs
+*.log
+
+# Don't ignore vendor directory since we want to commit vendored dependencies
+# vendor/

AGENTS.md

@@ -0,0 +1,237 @@
+# Agent Context: mapt-mcp
+
+## Project Overview
+
+This is an MCP (Model Context Protocol) server that provides programmatic access to [mapt](https://github.com/redhat-developer/mapt) - Red Hat's Multi Architecture Provisioning Tool. The server wraps mapt's CLI functionality as MCP tools, enabling AI agents to provision and manage cloud infrastructure across AWS and Azure.
+
+## Project Structure
+
+```
+mapt-mcp/
+├── main.go              # MCP server entry point and initialization
+├── tools.go             # All MCP tool implementations and input/output structures
+├── go.mod               # Go module definition with dependencies
+├── go.sum               # Go module checksums
+├── Makefile             # Build automation and common tasks
+├── README.md            # User documentation
+├── AGENTS.md            # This file - agent context and interaction guide
+└── LICENSE              # Project license
+```
+
+## Core Architecture
+
+### MCP Server (main.go)
+- Uses MCP Go SDK v1.0.0 for JSON-RPC over stdio transport
+- Initializes server with name "mapt-mcp" version "1.0.0"
+- Registers all mapt action tools via `addEnhancedMaptTools()`
+- Provides `execMapt()` helper function for CLI command execution
+
+### Tool Implementation (tools.go)
+- **Input Structures**: Strongly typed structs for each action with JSON schema validation
+- **Tool Functions**: Each tool maps directly to a mapt CLI command
+- **Output Structure**: Standardized `TextOutput` with command results
+- **Error Handling**: Comprehensive error wrapping with context
+
+## Available MCP Tools
+
+### Utility Tools
+- `mapt_version` - Get mapt version information
+- `mapt_help` - Get help for mapt commands (optional subcommand)
+- `mapt_destroy` - Destroy resources by prefix
+
+### AWS Action Tools
+Each tool creates infrastructure on AWS with the pattern `mapt_aws_{action}_create`:
+
+- `mapt_aws_eks_create` - EKS Kubernetes clusters
+- `mapt_aws_fedora_create` - Fedora Linux instances
+- `mapt_aws_kind_create` - Kind Kubernetes clusters
+- `mapt_aws_mac_create` - macOS instances (dedicated hosts)
+- `mapt_aws_mac_pool_create` - Pools of macOS instances
+- `mapt_aws_openshift_snc_create` - OpenShift Single Node Clusters
+- `mapt_aws_rhel_create` - Red Hat Enterprise Linux instances
+- `mapt_aws_rhel_ai_create` - RHEL AI instances with GPU support
+- `mapt_aws_windows_create` - Windows Server instances
+
+### Azure Action Tools
+Each tool creates infrastructure on Azure with the pattern `mapt_azure_{action}_create`:
+
+- `mapt_azure_aks_create` - AKS Kubernetes clusters
+- `mapt_azure_linux_create` - Generic Linux instances
+- `mapt_azure_rhel_create` - Red Hat Enterprise Linux instances
+- `mapt_azure_windows_create` - Windows Server instances
+
+## Tool Parameter Patterns
+
+### Universal Parameters
+All create tools require:
+- `prefix` (string, required) - Unique identifier for the resource group
+
+### AWS Common Parameters
+- `region` (string, optional) - AWS region (default: "us-east-1")
+- `spot` (bool, optional) - Use spot instances for cost optimization
+- `version` (string, optional) - Software/OS version to deploy
+- `architecture` (string, optional) - CPU architecture (default: "amd64")
+
+### Azure Common Parameters
+- `location` (string, optional) - Azure region (default: "eastus")
+- `spot` (bool, optional) - Use spot instances for cost optimization
+- `version` (string, optional) - Software/OS version to deploy
+- `architecture` (string, optional) - CPU architecture (default: "amd64")
+
+### Specialized Parameters
+- **Cluster Tools** (EKS/AKS): `node_count` (int) - Number of worker nodes
+- **Mac Pool**: `pool_size` (int) - Number of Mac instances in pool
+- **RHEL/Fedora**: `airgap` (bool) - Deploy in disconnected environment
+
+## How to Interact with this MCP Server
+
+### 1. Prerequisites
+Agents using this server should verify:
+- `mapt` CLI tool is installed and accessible in PATH
+- Appropriate cloud credentials are configured (AWS CLI, Azure CLI)
+- MCP client supports JSON-RPC over stdio
+
+### 2. Server Initialization
+```bash
+./mapt-mcp
+```
+The server communicates via stdin/stdout using JSON-RPC 2.0 protocol.
+
+### 3. Tool Discovery
+Use MCP's `tools/list` method to discover available tools:
+```json
+{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}
+```
+
+### 4. Tool Execution Pattern
+All tools follow this pattern:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/call",
+  "params": {
+    "name": "tool_name",
+    "arguments": {
+      "prefix": "unique-identifier",
+      "parameter": "value"
+    }
+  }
+}
+```
+
+### 5. Example Workflows
+
+#### Create AWS RHEL Instance
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "mapt_aws_rhel_create",
+    "arguments": {
+      "prefix": "demo-rhel-vm",
+      "version": "9.4",
+      "region": "us-west-2",
+      "spot": true,
+      "architecture": "amd64"
+    }
+  }
+}
+```
+
+#### Create Azure AKS Cluster
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/call",
+  "params": {
+    "name": "mapt_azure_aks_create",
+    "arguments": {
+      "prefix": "demo-k8s-cluster",
+      "version": "1.28",
+      "location": "eastus",
+      "node_count": 3
+    }
+  }
+}
+```
+
+#### Clean Up Resources
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "mapt_destroy",
+    "arguments": {
+      "prefix": "demo-rhel-vm"
+    }
+  }
+}
+```
+
+## Agent Best Practices
+
+### Resource Management
+- **Always use unique prefixes** to avoid resource conflicts
+- **Clean up resources** using `mapt_destroy` when done
+- **Monitor costs** when using non-spot instances
+
+### Error Handling
+- Tools return errors for invalid parameters or mapt CLI failures
+- Check tool responses for error conditions before proceeding
+- Use `mapt_help` for parameter validation if unsure
+
+### Workflow Patterns
+1. **Discovery**: Use `mapt_version` to verify mapt availability
+2. **Planning**: Use `mapt_help` to understand specific tool parameters
+3. **Provisioning**: Call appropriate create tools with required parameters
+4. **Cleanup**: Always destroy resources when finished
+
+### Security Considerations
+- This server executes mapt CLI commands with the permissions of the running user
+- Ensure appropriate cloud provider credentials and RBAC policies
+- Validate all input parameters before calling tools
+- Be cautious with spot instances in production workloads
+
+## Development and Extension
+
+### Adding New Tools
+1. Add input struct in `tools.go` with JSON schema tags
+2. Implement tool function following the pattern: `func ToolName(ctx, req, input) (*CallToolResult, TextOutput, error)`
+3. Register tool in `addEnhancedMaptTools()` with name and description
+4. Update this documentation
+
+### Build and Test
+```bash
+# Build the server
+make build
+
+# Run tests
+make test
+
+# Check dependencies
+make check-deps
+
+# Cross-platform build
+make build-all
+```
+
+### Debugging
+- Use `make smoke-test` for basic server functionality
+- Enable mapt debug logging with environment variables
+- Check mapt CLI directly if tools fail: `mapt --help`
+
+## Integration Notes
+
+This MCP server is designed to work with:
+- **Claude Code** and other MCP-enabled AI assistants
+- **Automation pipelines** requiring cloud infrastructure
+- **Development workflows** needing temporary compute resources
+- **CI/CD systems** with dynamic infrastructure needs
+
+The server abstracts mapt's complexity while preserving its full functionality through type-safe, well-documented MCP tools.