code-engine-mcp-server 1.0.0

package/docs/CODE_ENGINE_API_REFERENCE.md

@@ -0,0 +1,764 @@
+# Code Engine API Reference for MCP
+
+**Author:** Markus van Kempen | markus.van.kempen@gmail.com  
+**Research | Floor 7½ 🏢🤏**
+
+**Official API Documentation:** https://cloud.ibm.com/apidocs/codeengine/v2
+
+This document provides comprehensive API procedures that MCP tools can execute directly without creating standalone scripts.
+
+---
+
+## Table of Contents
+
+1. [Authentication](#authentication)
+2. [Projects](#projects)
+3. [Applications](#applications)
+4. [Builds](#builds)
+5. [Build Runs](#build-runs)
+6. [Jobs](#jobs)
+7. [Secrets & ConfigMaps](#secrets--configmaps)
+8. [Common Workflows](#common-workflows)
+
+---
+
+## Authentication
+
+### Get IAM Token
+
+**Purpose:** Authenticate with IBM Cloud to get access token for API calls
+
+**Endpoint:** `POST https://iam.cloud.ibm.com/identity/token`
+
+**Headers:**
+```
+Content-Type: application/x-www-form-urlencoded
+```
+
+**Body:**
+```
+grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey={IBM_CLOUD_API_KEY}
+```
+
+**Response:**
+```json
+{
+  "access_token": "eyJhbGc...",
+  "refresh_token": "...",
+  "token_type": "Bearer",
+  "expires_in": 3600
+}
+```
+
+**MCP Tool:** Use `execute_command` to call via curl or implement as MCP tool
+
+**Example:**
+```bash
+curl -X POST https://iam.cloud.ibm.com/identity/token \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$IBM_CLOUD_API_KEY"
+```
+
+---
+
+## Projects
+
+### List Projects
+
+**Purpose:** Get all Code Engine projects in a region
+
+**Endpoint:** `GET https://api.{region}.codeengine.cloud.ibm.com/v2/projects`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+```
+
+**Query Parameters:**
+- `limit` (optional): Number of projects to return (default: 100)
+- `start` (optional): Token for pagination
+
+**Response:**
+```json
+{
+  "projects": [
+    {
+      "id": "7e131e87-e967-4e7f-a2f1-480957244eac",
+      "name": "markus-app-v2-toronto",
+      "region": "ca-tor",
+      "status": "active",
+      "created_at": "2026-05-07T18:39:19Z",
+      "resource_group_id": "..."
+    }
+  ],
+  "limit": 100
+}
+```
+
+**Regions:**
+- `us-south` - Dallas
+- `us-east` - Washington DC
+- `eu-de` - Frankfurt
+- `eu-gb` - London
+- `jp-tok` - Tokyo
+- `jp-osa` - Osaka
+- `au-syd` - Sydney
+- `ca-tor` - Toronto
+- `br-sao` - São Paulo
+
+### Create Project
+
+**Purpose:** Create a new Code Engine project
+
+**Endpoint:** `POST https://api.{region}.codeengine.cloud.ibm.com/v2/projects`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+  "name": "my-project",
+  "resource_group_id": "default"
+}
+```
+
+**Response:**
+```json
+{
+  "id": "project-id",
+  "name": "my-project",
+  "region": "ca-tor",
+  "status": "creating",
+  "created_at": "2026-05-07T18:39:19Z"
+}
+```
+
+### Get Project
+
+**Purpose:** Get details of a specific project
+
+**Endpoint:** `GET https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+```
+
+### Delete Project
+
+**Purpose:** Delete a Code Engine project
+
+**Endpoint:** `DELETE https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+```
+
+---
+
+## Applications
+
+### List Applications
+
+**Purpose:** Get all applications in a project
+
+**Endpoint:** `GET https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/apps`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+```
+
+**Query Parameters:**
+- `limit` (optional): Number of apps to return
+- `start` (optional): Token for pagination
+
+**Response:**
+```json
+{
+  "apps": [
+    {
+      "name": "markus-app-v2",
+      "status": "ready",
+      "image_reference": "icr.io/codeengine/helloworld",
+      "image_port": 8080,
+      "endpoint": "markus-app-v2.29m5mrru3s3n.ca-tor.codeengine.appdomain.cloud",
+      "scale_min_instances": 0,
+      "scale_max_instances": 1,
+      "scale_cpu_limit": "0.25",
+      "scale_memory_limit": "0.5G"
+    }
+  ]
+}
+```
+
+### Create Application
+
+**Purpose:** Create a new application
+
+**Endpoint:** `POST https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/apps`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+  "name": "my-app",
+  "image_reference": "icr.io/namespace/image:tag",
+  "image_port": 8080,
+  "scale_min_instances": 0,
+  "scale_max_instances": 10,
+  "scale_cpu_limit": "1",
+  "scale_memory_limit": "4G",
+  "run_env_variables": [
+    {
+      "type": "literal",
+      "name": "ENV_VAR",
+      "value": "value"
+    }
+  ]
+}
+```
+
+**Scaling Options:**
+- `scale_min_instances`: Minimum instances (0 for scale-to-zero)
+- `scale_max_instances`: Maximum instances
+- `scale_cpu_limit`: CPU limit (0.125, 0.25, 0.5, 1, 2, 4, 6, 8)
+- `scale_memory_limit`: Memory limit (0.25G, 0.5G, 1G, 2G, 4G, 8G, 16G, 32G)
+- `scale_concurrency`: Requests per instance (default: 100)
+- `scale_concurrency_target`: Target concurrency for scaling
+
+**Environment Variables:**
+- `type: "literal"` - Plain text value
+- `type: "config_map_key_reference"` - Reference to ConfigMap
+- `type: "secret_key_reference"` - Reference to Secret
+
+### Get Application
+
+**Purpose:** Get details of a specific application
+
+**Endpoint:** `GET https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/apps/{app_name}`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+```
+
+### Update Application
+
+**Purpose:** Update an existing application
+
+**Endpoint:** `PATCH https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/apps/{app_name}`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+Content-Type: application/merge-patch+json
+```
+
+**Body:** (only include fields to update)
+```json
+{
+  "image_reference": "icr.io/namespace/image:new-tag",
+  "scale_max_instances": 5
+}
+```
+
+### Delete Application
+
+**Purpose:** Delete an application
+
+**Endpoint:** `DELETE https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/apps/{app_name}`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+```
+
+---
+
+## Builds
+
+### List Builds
+
+**Purpose:** Get all build configurations in a project
+
+**Endpoint:** `GET https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/builds`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+```
+
+### Create Build
+
+**Purpose:** Create a build configuration
+
+**Endpoint:** `POST https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/builds`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+  "name": "my-build",
+  "output_image": "private.{region}.icr.io/{project_id}/my-image",
+  "output_secret": "ce-auto-icr-private-{region}",
+  "source_type": "local",
+  "strategy_type": "dockerfile",
+  "strategy_spec_file": "Dockerfile",
+  "strategy_size": "medium"
+}
+```
+
+**Source Types:**
+- `local` - Upload source code directly
+- `git` - Build from Git repository
+
+**Strategy Types:**
+- `dockerfile` - Use Dockerfile
+- `buildpacks` - Use Cloud Native Buildpacks
+
+**Strategy Sizes:**
+- `small` - 2 vCPU, 4 GB memory
+- `medium` - 4 vCPU, 8 GB memory
+- `large` - 8 vCPU, 16 GB memory
+- `xlarge` - 16 vCPU, 32 GB memory
+
+### Get Build
+
+**Purpose:** Get details of a build configuration
+
+**Endpoint:** `GET https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/builds/{build_name}`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+```
+
+### Delete Build
+
+**Purpose:** Delete a build configuration
+
+**Endpoint:** `DELETE https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/builds/{build_name}`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+```
+
+---
+
+## Build Runs
+
+### List Build Runs
+
+**Purpose:** Get all build runs in a project
+
+**Endpoint:** `GET https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/build_runs`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+```
+
+### Create Build Run
+
+**Purpose:** Start a new build
+
+**Endpoint:** `POST https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/build_runs`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+  "build_name": "my-build",
+  "name": "my-build-run-123"
+}
+```
+
+**Response:**
+```json
+{
+  "name": "my-build-run-123",
+  "status": "pending",
+  "build_name": "my-build",
+  "created_at": "2026-05-07T18:42:19Z"
+}
+```
+
+### Upload Source Code
+
+**Purpose:** Upload source code for a build run
+
+**Endpoint:** `PUT https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/build_runs/{build_run_name}/source`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+Content-Type: multipart/form-data
+```
+
+**Body:** (multipart form data)
+```
+file: <source_code.zip>
+```
+
+**Note:** Source code must be a ZIP archive
+
+### Get Build Run
+
+**Purpose:** Get status of a build run
+
+**Endpoint:** `GET https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/build_runs/{build_run_name}`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+```
+
+**Response:**
+```json
+{
+  "name": "my-build-run-123",
+  "status": "succeeded",
+  "output_image": "private.ca-tor.icr.io/project-id/my-image:latest",
+  "status_details": {
+    "completion_time": "2026-05-07T18:45:00Z",
+    "reason": "Succeeded"
+  }
+}
+```
+
+**Status Values:**
+- `pending` - Build queued
+- `running` - Build in progress
+- `succeeded` - Build completed successfully
+- `failed` - Build failed
+
+### Delete Build Run
+
+**Purpose:** Delete a build run
+
+**Endpoint:** `DELETE https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/build_runs/{build_run_name}`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+```
+
+---
+
+## Jobs
+
+### List Jobs
+
+**Purpose:** Get all jobs in a project
+
+**Endpoint:** `GET https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/jobs`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+```
+
+### Create Job
+
+**Purpose:** Create a job definition
+
+**Endpoint:** `POST https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/jobs`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+  "name": "my-job",
+  "image_reference": "icr.io/namespace/image:tag",
+  "run_mode": "task",
+  "scale_array_spec": "1-5",
+  "scale_cpu_limit": "1",
+  "scale_memory_limit": "4G",
+  "scale_max_execution_time": 7200
+}
+```
+
+### Submit Job Run
+
+**Purpose:** Run a job
+
+**Endpoint:** `POST https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/job_runs`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+  "job_name": "my-job",
+  "name": "my-job-run-123"
+}
+```
+
+---
+
+## Secrets & ConfigMaps
+
+### Create Secret
+
+**Purpose:** Store sensitive data
+
+**Endpoint:** `POST https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/secrets`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+  "name": "my-secret",
+  "format": "generic",
+  "data": {
+    "key1": "base64_encoded_value",
+    "key2": "base64_encoded_value"
+  }
+}
+```
+
+**Secret Formats:**
+- `generic` - Generic secret
+- `ssh_auth` - SSH authentication
+- `basic_auth` - Basic authentication
+- `tls` - TLS certificate
+- `service_access` - Service credentials
+- `registry` - Container registry credentials
+
+### Create ConfigMap
+
+**Purpose:** Store non-sensitive configuration
+
+**Endpoint:** `POST https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/config_maps`
+
+**Headers:**
+```
+Authorization: Bearer {access_token}
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+  "name": "my-config",
+  "data": {
+    "config_key": "config_value"
+  }
+}
+```
+
+---
+
+## Common Workflows
+
+### Workflow 1: Deploy Application with Public Image
+
+**Steps:**
+1. Get IAM token
+2. List projects to find project ID
+3. Create/update application with image reference
+
+**MCP Tool Sequence:**
+```
+1. execute_command: Get IAM token
+2. execute_command: List projects
+3. execute_command: Create application
+4. execute_command: Get application status
+```
+
+### Workflow 2: Build and Deploy from Source
+
+**Steps:**
+1. Get IAM token
+2. Get project ID
+3. Create build configuration
+4. Create build run
+5. Upload source code ZIP
+6. Wait for build to complete
+7. Create/update application with built image
+
+**MCP Tool Sequence:**
+```
+1. execute_command: Get IAM token
+2. execute_command: Get project ID
+3. execute_command: Create build
+4. execute_command: Create build run
+5. execute_command: Upload source (multipart)
+6. execute_command: Poll build run status
+7. execute_command: Create/update application
+```
+
+### Workflow 3: Update Application Image
+
+**Steps:**
+1. Get IAM token
+2. Get project ID
+3. Update application with new image
+
+**MCP Tool Sequence:**
+```
+1. execute_command: Get IAM token
+2. execute_command: Get project ID
+3. execute_command: PATCH application
+```
+
+### Workflow 4: Scale Application
+
+**Steps:**
+1. Get IAM token
+2. Get project ID
+3. Update application scaling parameters
+
+**MCP Tool Sequence:**
+```
+1. execute_command: Get IAM token
+2. execute_command: Get project ID
+3. execute_command: PATCH application with new scale settings
+```
+
+### Workflow 5: Deploy to New Region
+
+**Steps:**
+1. Get IAM token
+2. List projects in target region
+3. Create project if needed
+4. Create application in new region
+
+**MCP Tool Sequence:**
+```
+1. execute_command: Get IAM token
+2. execute_command: List projects in region
+3. execute_command: Create project (if needed)
+4. execute_command: Create application
+```
+
+---
+
+## Error Handling
+
+### Common HTTP Status Codes
+
+- `200 OK` - Success
+- `201 Created` - Resource created
+- `204 No Content` - Success with no response body
+- `400 Bad Request` - Invalid request
+- `401 Unauthorized` - Invalid or expired token
+- `403 Forbidden` - Insufficient permissions
+- `404 Not Found` - Resource not found
+- `409 Conflict` - Resource already exists
+- `429 Too Many Requests` - Rate limit exceeded
+- `500 Internal Server Error` - Server error
+
+### Error Response Format
+
+```json
+{
+  "errors": [
+    {
+      "code": "error_code",
+      "message": "Error description",
+      "target": {
+        "type": "field",
+        "name": "field_name"
+      }
+    }
+  ],
+  "trace": "trace-id",
+  "status_code": 400
+}
+```
+
+---
+
+## Best Practices
+
+1. **Token Management**
+   - Cache IAM tokens (valid for 1 hour)
+   - Refresh before expiration
+   - Don't request new token for every API call
+
+2. **Polling**
+   - Use reasonable intervals (5-10 seconds)
+   - Implement timeout limits
+   - Check status before proceeding
+
+3. **Error Handling**
+   - Always check HTTP status codes
+   - Parse error messages for details
+   - Implement retry logic for transient errors
+
+4. **Resource Naming**
+   - Use lowercase letters, numbers, hyphens
+   - Start with letter
+   - Max 63 characters
+   - Must be unique within project
+
+5. **Image References**
+   - Use specific tags, not `latest`
+   - Include full registry path
+   - Verify image exists before deployment
+
+---
+
+## MCP Integration
+
+All these API calls can be executed through MCP tools:
+
+1. **execute_command** - For curl-based API calls
+2. **Custom MCP Tools** - Implement dedicated Code Engine tools
+3. **Skill Orchestration** - Bob skill coordinates the workflow
+
+**Example MCP Tool Implementation:**
+```typescript
+{
+  name: "code_engine_api",
+  description: "Execute Code Engine API calls",
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: { type: "string", enum: ["list_projects", "create_app", ...] },
+      region: { type: "string" },
+      project_id: { type: "string" },
+      parameters: { type: "object" }
+    }
+  }
+}
+```
+
+This allows Bob to execute any Code Engine operation through MCP without creating standalone scripts.