code-engine-mcp-server 1.0.4 → 1.0.6

package/docs/CODE_ENGINE_API_REFERENCE.md

@@ -1,764 +0,0 @@
-# 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={IBMCLOUD_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=$IBMCLOUD_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.