code-engine-mcp-server 1.0.4 → 1.0.7

package/docs/API_CALL_SCENARIOS.md

@@ -1,594 +0,0 @@
-# Code Engine API Call Scenarios
-
-**Author:** Markus van Kempen | markus.van.kempen@gmail.com  
-**Research | Floor 7½ 🏢🤏**
-
-This document provides specific API call scenarios that Bob can execute through MCP tools. Each scenario includes the exact curl commands and expected responses.
-
----
-
-## Scenario 1: Deploy Application to Toronto
-
-**Goal:** Deploy MarkusAppV2 to Toronto region with public image
-
-### Step 1: Get IAM Token
-
-```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"
-```
-
-**Expected Response:**
-```json
-{
-  "access_token": "eyJhbGc...",
-  "expires_in": 3600
-}
-```
-
-**Store:** `TOKEN=<access_token>`
-
-### Step 2: List Projects in Toronto
-
-```bash
-curl -X GET https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects \
-  -H "Authorization: Bearer $TOKEN"
-```
-
-**Expected Response:**
-```json
-{
-  "projects": [
-    {
-      "id": "7e131e87-e967-4e7f-a2f1-480957244eac",
-      "name": "markus-app-v2-toronto",
-      "status": "active"
-    }
-  ]
-}
-```
-
-**Store:** `PROJECT_ID=<id>`
-
-### Step 3: Create Application
-
-```bash
-curl -X POST https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/apps \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "markus-app-v2",
-    "image_reference": "icr.io/codeengine/helloworld",
-    "image_port": 8080,
-    "scale_min_instances": 0,
-    "scale_max_instances": 1,
-    "scale_cpu_limit": "0.25",
-    "scale_memory_limit": "0.5G",
-    "run_env_variables": [
-      {
-        "type": "literal",
-        "name": "TARGET",
-        "value": "Toronto - Research Floor 7½"
-      }
-    ]
-  }'
-```
-
-**Expected Response:**
-```json
-{
-  "name": "markus-app-v2",
-  "status": "deploying",
-  "image_reference": "icr.io/codeengine/helloworld",
-  "endpoint": "markus-app-v2.xxx.ca-tor.codeengine.appdomain.cloud"
-}
-```
-
-### Step 4: Check Application Status
-
-```bash
-curl -X GET https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/apps/markus-app-v2 \
-  -H "Authorization: Bearer $TOKEN"
-```
-
-**Expected Response:**
-```json
-{
-  "name": "markus-app-v2",
-  "status": "ready",
-  "endpoint": "markus-app-v2.xxx.ca-tor.codeengine.appdomain.cloud"
-}
-```
-
-**Result:** Application URL: `https://<endpoint>`
-
----
-
-## Scenario 2: Update Application Image
-
-**Goal:** Update existing application with new image
-
-### Step 1: Get IAM Token (same as Scenario 1)
-
-### Step 2: Get Project ID (same as Scenario 1)
-
-### Step 3: Update Application
-
-```bash
-curl -X PATCH https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/apps/markus-app-v2 \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/merge-patch+json" \
-  -d '{
-    "image_reference": "icr.io/namespace/markus-app-v2:v2.0"
-  }'
-```
-
-**Expected Response:**
-```json
-{
-  "name": "markus-app-v2",
-  "status": "updating",
-  "image_reference": "icr.io/namespace/markus-app-v2:v2.0"
-}
-```
-
----
-
-## Scenario 3: Scale Application
-
-**Goal:** Adjust application scaling parameters
-
-### Update Scaling
-
-```bash
-curl -X PATCH https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/apps/markus-app-v2 \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/merge-patch+json" \
-  -d '{
-    "scale_min_instances": 1,
-    "scale_max_instances": 5,
-    "scale_cpu_limit": "1",
-    "scale_memory_limit": "2G"
-  }'
-```
-
----
-
-## Scenario 4: Build from Source
-
-**Goal:** Build container image from source code and deploy
-
-### Step 1-2: Get Token and Project ID (same as Scenario 1)
-
-### Step 3: Create Build Configuration
-
-```bash
-curl -X POST https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/builds \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "markus-app-v2-build",
-    "output_image": "private.ca-tor.icr.io/'$PROJECT_ID'/markus-app-v2",
-    "output_secret": "ce-auto-icr-private-ca-tor",
-    "source_type": "local",
-    "strategy_type": "dockerfile",
-    "strategy_spec_file": "Dockerfile",
-    "strategy_size": "medium"
-  }'
-```
-
-**Expected Response:**
-```json
-{
-  "name": "markus-app-v2-build",
-  "status": "ready",
-  "output_image": "private.ca-tor.icr.io/project-id/markus-app-v2"
-}
-```
-
-### Step 4: Create Build Run
-
-```bash
-curl -X POST https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/build_runs \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "build_name": "markus-app-v2-build",
-    "name": "markus-app-v2-build-run-'$(date +%s)'"
-  }'
-```
-
-**Expected Response:**
-```json
-{
-  "name": "markus-app-v2-build-run-1234567890",
-  "status": "pending",
-  "build_name": "markus-app-v2-build"
-}
-```
-
-**Store:** `BUILD_RUN_NAME=<name>`
-
-### Step 5: Upload Source Code
-
-```bash
-# First create ZIP of source code
-cd markus-app-v2
-zip -r ../markus-app-v2-source.zip .
-cd ..
-
-# Upload
-curl -X PUT https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/build_runs/$BUILD_RUN_NAME/source \
-  -H "Authorization: Bearer $TOKEN" \
-  -F "file=@markus-app-v2-source.zip"
-```
-
-### Step 6: Monitor Build Status
-
-```bash
-# Poll every 5 seconds
-while true; do
-  STATUS=$(curl -s -X GET https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/build_runs/$BUILD_RUN_NAME \
-    -H "Authorization: Bearer $TOKEN" | jq -r '.status')
-  
-  echo "Build status: $STATUS"
-  
-  if [ "$STATUS" = "succeeded" ]; then
-    break
-  elif [ "$STATUS" = "failed" ]; then
-    echo "Build failed"
-    exit 1
-  fi
-  
-  sleep 5
-done
-```
-
-### Step 7: Deploy with Built Image
-
-```bash
-# Get the built image reference
-IMAGE=$(curl -s -X GET https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/build_runs/$BUILD_RUN_NAME \
-  -H "Authorization: Bearer $TOKEN" | jq -r '.output_image')
-
-# Create/update application
-curl -X POST https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/apps \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "markus-app-v2",
-    "image_reference": "'$IMAGE'",
-    "image_port": 8080,
-    "scale_min_instances": 0,
-    "scale_max_instances": 1
-  }'
-```
-
----
-
-## Scenario 5: Create New Project
-
-**Goal:** Create a new Code Engine project in a region
-
-### Step 1: Get IAM Token (same as Scenario 1)
-
-### Step 2: Create Project
-
-```bash
-curl -X POST https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "my-new-project"
-  }'
-```
-
-**Expected Response:**
-```json
-{
-  "id": "new-project-id",
-  "name": "my-new-project",
-  "region": "ca-tor",
-  "status": "creating"
-}
-```
-
-### Step 3: Wait for Project to be Active
-
-```bash
-while true; do
-  STATUS=$(curl -s -X GET https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/new-project-id \
-    -H "Authorization: Bearer $TOKEN" | jq -r '.status')
-  
-  echo "Project status: $STATUS"
-  
-  if [ "$STATUS" = "active" ]; then
-    break
-  fi
-  
-  sleep 5
-done
-```
-
----
-
-## Scenario 6: Manage Secrets
-
-**Goal:** Create and use secrets for sensitive data
-
-### Create Secret
-
-```bash
-# Base64 encode values
-API_KEY_B64=$(echo -n "my-api-key" | base64)
-PASSWORD_B64=$(echo -n "my-password" | base64)
-
-curl -X POST https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/secrets \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "my-secrets",
-    "format": "generic",
-    "data": {
-      "api_key": "'$API_KEY_B64'",
-      "password": "'$PASSWORD_B64'"
-    }
-  }'
-```
-
-### Use Secret in Application
-
-```bash
-curl -X POST https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/apps \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "my-app",
-    "image_reference": "icr.io/namespace/image:tag",
-    "run_env_variables": [
-      {
-        "type": "secret_key_reference",
-        "name": "API_KEY",
-        "reference": "my-secrets.api_key"
-      }
-    ]
-  }'
-```
-
----
-
-## Scenario 7: Delete Resources
-
-**Goal:** Clean up Code Engine resources
-
-### Delete Application
-
-```bash
-curl -X DELETE https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/apps/markus-app-v2 \
-  -H "Authorization: Bearer $TOKEN"
-```
-
-**Expected Response:** HTTP 204 No Content
-
-### Delete Build Configuration
-
-```bash
-curl -X DELETE https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/builds/markus-app-v2-build \
-  -H "Authorization: Bearer $TOKEN"
-```
-
-### Delete Project
-
-```bash
-curl -X DELETE https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID \
-  -H "Authorization: Bearer $TOKEN"
-```
-
----
-
-## Scenario 8: Multi-Region Deployment
-
-**Goal:** Deploy same application to multiple regions
-
-### Deploy to Multiple Regions
-
-```bash
-REGIONS=("us-south" "eu-de" "ca-tor")
-
-for REGION in "${REGIONS[@]}"; do
-  echo "Deploying to $REGION..."
-  
-  # Get token (reuse if not expired)
-  TOKEN=$(curl -s -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" \
-    | jq -r '.access_token')
-  
-  # Get or create project
-  PROJECT_ID=$(curl -s -X GET https://api.$REGION.codeengine.cloud.ibm.com/v2/projects \
-    -H "Authorization: Bearer $TOKEN" \
-    | jq -r '.projects[0].id')
-  
-  # Deploy application
-  curl -X POST https://api.$REGION.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/apps \
-    -H "Authorization: Bearer $TOKEN" \
-    -H "Content-Type: application/json" \
-    -d '{
-      "name": "markus-app-v2",
-      "image_reference": "icr.io/codeengine/helloworld",
-      "image_port": 8080
-    }'
-  
-  echo "Deployed to $REGION"
-done
-```
-
----
-
-## Scenario 9: Run Job
-
-**Goal:** Execute a batch job
-
-### Create Job Definition
-
-```bash
-curl -X POST https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/jobs \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "data-processor",
-    "image_reference": "icr.io/namespace/processor:latest",
-    "run_mode": "task",
-    "scale_array_spec": "1-10",
-    "scale_cpu_limit": "1",
-    "scale_memory_limit": "4G"
-  }'
-```
-
-### Submit Job Run
-
-```bash
-curl -X POST https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/job_runs \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "job_name": "data-processor",
-    "name": "data-processor-run-'$(date +%s)'"
-  }'
-```
-
----
-
-## MCP Tool Integration
-
-### How Bob Uses These Scenarios
-
-1. **User Request:** "Deploy MarkusAppV2 to Toronto"
-
-2. **Bob Identifies Scenario:** Scenario 1 - Deploy Application to Toronto
-
-3. **Bob Executes via MCP:**
-   ```
-   execute_command: curl -X POST https://iam.cloud.ibm.com/...
-   execute_command: curl -X GET https://api.ca-tor.codeengine.cloud.ibm.com/...
-   execute_command: curl -X POST https://api.ca-tor.codeengine.cloud.ibm.com/...
-   ```
-
-4. **Bob Monitors Progress:**
-   - Checks response codes
-   - Parses JSON responses
-   - Waits for status changes
-   - Reports results to user
-
-5. **No Scripts Created:** All operations done through direct API calls
-
-### Benefits
-
-- ✅ No standalone scripts to maintain
-- ✅ Direct API execution through MCP
-- ✅ Real-time feedback and error handling
-- ✅ Flexible and adaptable to user needs
-- ✅ Knowledge embedded in skill documentation
-
----
-
-## Error Handling Examples
-
-### Handle 401 Unauthorized
-
-```bash
-RESPONSE=$(curl -s -w "\n%{http_code}" -X GET https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects \
-  -H "Authorization: Bearer $TOKEN")
-
-HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
-
-if [ "$HTTP_CODE" = "401" ]; then
-  echo "Token expired, refreshing..."
-  TOKEN=$(curl -s -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" \
-    | jq -r '.access_token')
-  # Retry request
-fi
-```
-
-### Handle 404 Not Found
-
-```bash
-RESPONSE=$(curl -s -w "\n%{http_code}" -X GET https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/apps/my-app \
-  -H "Authorization: Bearer $TOKEN")
-
-HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
-
-if [ "$HTTP_CODE" = "404" ]; then
-  echo "Application not found, creating new..."
-  # Create application
-fi
-```
-
-### Handle 409 Conflict
-
-```bash
-RESPONSE=$(curl -s -w "\n%{http_code}" -X POST https://api.ca-tor.codeengine.cloud.ibm.com/v2/projects/$PROJECT_ID/apps \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"name": "my-app", ...}')
-
-HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
-
-if [ "$HTTP_CODE" = "409" ]; then
-  echo "Application exists, updating instead..."
-  # Use PATCH instead
-fi
-```
-
----
-
-## Quick Reference
-
-### Common Variables
-
-```bash
-IBMCLOUD_API_KEY="your-api-key"
-TOKEN="eyJhbGc..."
-PROJECT_ID="7e131e87-e967-4e7f-a2f1-480957244eac"
-REGION="ca-tor"
-APP_NAME="markus-app-v2"
-```
-
-### Common Endpoints
-
-```bash
-# IAM
-https://iam.cloud.ibm.com/identity/token
-
-# Code Engine (replace {region})
-https://api.{region}.codeengine.cloud.ibm.com/v2/projects
-https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/apps
-https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/builds
-https://api.{region}.codeengine.cloud.ibm.com/v2/projects/{project_id}/build_runs
-```
-
-### Useful jq Queries
-
-```bash
-# Extract access token
-jq -r '.access_token'
-
-# Extract project ID
-jq -r '.projects[0].id'
-
-# Extract application endpoint
-jq -r '.endpoint'
-
-# Extract build status
-jq -r '.status'
-
-# Check if app exists
-jq -r '.apps[] | select(.name=="markus-app-v2") | .name'
-```
-
----
-
-This documentation enables Bob to execute any Code Engine operation through MCP tools without creating standalone scripts. The skill orchestrates the API calls based on user requests.