code-engine-mcp-server 1.0.3 → 1.0.6

package/README.md

@@ -5,32 +5,40 @@
 Model Context Protocol (MCP) server for IBM Code Engine and Docker/Podman integration.
 It enables AI assistants to build, run, push, and deploy containerized workloads with a single MCP server.
 
-[![MCP](https://img.shields.io/badge/MCP-Server-blue)](#)
-[![IBM Cloud](https://img.shields.io/badge/IBM%20Cloud-Code%20Engine-1261FE)](#)
+[![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://github.com/markusvankempen/code-engine-mcp-server)
+[![IBM Cloud](https://img.shields.io/badge/IBM%20Cloud-Code%20Engine-1261FE)](https://cloud.ibm.com/codeengine/overview)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-339933?logo=nodedotjs&logoColor=white)](#prerequisites)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-## 📚 Table of Contents
-
-- [What You Get](#what-you-get)
-- [Quick Start](#quick-start)
-- [Deploy Your First App](#deploy-your-first-app)
-- [Documentation](#documentation)
-- [Project Structure](#project-structure)
-- [Features](#features)
-- [Configuration](#configuration)
-- [npm and MCP Registry](#npm-and-mcp-registry)
-- [Example Prompts](#example-prompts)
-- [Available Tools](#available-tools)
-- [Environment Variables](#environment-variables)
-- [Prerequisites](#prerequisites)
-- [Development](#development)
-- [Troubleshooting](#troubleshooting)
-- [Security](#security)
-- [License](#license)
-- [Contributing](#contributing)
-- [Author](#author)
-- [Support](#support)
+## How It Works
+
+```mermaid
+flowchart TD
+    A([AI Assistant\nCopilot / Claude / Cline]) -->|MCP JSON-RPC| B[Code Engine MCP Server]
+
+    B --> C{Tool Category}
+
+    C -->|Container Tools| D[Docker / Podman]
+    C -->|Registry Tools| E[IBM Container Registry\nus.icr.io]
+    C -->|Code Engine Tools| F[IBM Code Engine\nREST API]
+    C -->|Procedures| G[Multi-step Workflows]
+
+    D -->|build / push / validate| E
+    E -->|image reference| F
+
+    G -->|proc_build_push_deploy| D
+    G -->|proc_build_run_and_deploy| F
+
+    F --> H[(Projects\nApps\nBuilds\nJobs\nSecrets\nDomains)]
+
+    H -->|ready| I([Live App\nhttps://app.region.codeengine.appdomain.cloud])
+
+    style A fill:#1261FE,color:#fff
+    style B fill:#0f3460,color:#fff
+    style G fill:#7b2d8b,color:#fff
+    style I fill:#198038,color:#fff
+```
+
 
 ## ✨ What You Get
 
@@ -55,7 +63,29 @@ node build/index.js
 
 Then configure your MCP client using one of the examples in the Configuration section below.
 
-## � Deploy Your First App
+## 🤖 The Agentic Experience (No Docker/Code Engine Lingo Needed)
+
+The true power of this MCP server is that **you don't need to know Docker or Code Engine commands**. You can simply state your goal, and the LLM will discover the environment, run the pipeline, and fix issues autonomously. 
+
+Here is an example interaction from a real session:
+
+**User:**
+> "I have an app in the `developer-splash` folder. Deploy it to my Code Engine project."
+
+**Assistant's Autonomous Thought Process:**
+1. *Discovery:* "Let me check what projects and namespaces exist... Found project `markus-app-v2-toronto` and namespace `mvk-code-engine`."
+2. *Prerequisites:* "No pull secret in this project yet. I'll get the API key from the `.env` file and create the secret `icr-pull-secret`."
+3. *Execution:* "Now I'll run the full pipeline: build → push → deploy → wait."
+4. *Validation:* "It's deployed but stuck at 'deploying'. Let me check the logs... The container is running but the readiness probe is failing."
+5. *Self-Correction:* "Ah, the `sed` pattern in the Dockerfile didn't match nginx alpine's default config format for port 80. I'll fix the Dockerfile with a regex-safe `sed` and rebuild."
+6. *Completion:* "App is live! 🎉 Status: ready."
+
+**Assistant Response to User:**
+> "Your app is deployed and live at: `https://developer-splash.29m5mrru3s3n.ca-tor.codeengine.appdomain.cloud`. I had to fix a minor port configuration issue in your Dockerfile, but it is successfully running now!"
+
+With this MCP server, the AI acts as an expert DevOps engineer pairing with you.
+
+## Deploy Your First App
 
 This walks through deploying the included [Star Wars splash page example](./examples/starwars-splash/) — a static nginx container — entirely through the MCP server.
 
@@ -301,14 +331,216 @@ push it, then deploy it to Code Engine project <project-id> with pull secret icr
 Tell me the public URL and confirm the instance is running.
 ```
 
-## �📖 Documentation
+---
+
+## 🌐 Host Any MCP Server on Code Engine
+
+You can use **this** MCP server to deploy **another** MCP server to Code Engine — no CLI, no Dockerfile, no YAML. The key ingredient is [`supergateway`](https://github.com/supercorp-ai/supergateway): a tiny bridge that wraps any STDIO-based MCP server as an HTTP + SSE endpoint, making it accessible to any remote client.
+
+> Credit: [Jeremias Werner & Enrico Regge — IBM Cloud Code Engine](https://community.ibm.com/community/user/blogs/jeremias-werner/2025/04/30/code-engine-mcp-server)
+
+```
+Your AI Assistant
+    │  MCP JSON-RPC (STDIO, local)
+    ▼
+code-engine-mcp-server  ──► ce_create_application
+                                     │
+                                     ▼
+                         Code Engine App
+                         image: docker.io/supercorp/supergateway
+                         args:  --stdio "npx -y <any-mcp-server>"
+                                --outputTransport sse
+                                     │  HTTPS + SSE  (public URL)
+                                     ▼
+                         Any remote MCP client
+                         (Claude Desktop, Cursor, VS Code, …)
+```
+
+Any STDIO MCP server becomes a remotely accessible, auto-scaling cloud service — with no custom infrastructure.
+
+This example deploys [`@tokenizin/mcp-npx-fetch`](https://www.npmjs.com/package/@tokenizin/mcp-npx-fetch), an MCP server that lets an AI assistant fetch content from public URLs.
+
+The example files live in [examples/mcp-server-supergateway/](./examples/mcp-server-supergateway/).
+
+### Step 1 — Deploy the hosted MCP server
+
+Ask your assistant:
+```
+Deploy a hosted MCP fetch server to my Code Engine project <project-id>.
+Use image docker.io/supercorp/supergateway on port 8000.
+Startup args: --stdio "npx -y @tokenizin/mcp-npx-fetch" --outputTransport sse
+Name it "mcp-fetch-server". No pull secret needed.
+```
+
+This calls `ce_create_application`:
+```json
+{
+  "project_id": "<your-project-id>",
+  "name": "mcp-fetch-server",
+  "image": "docker.io/supercorp/supergateway",
+  "port": 8000,
+  "run_args": ["--stdio", "npx -y @tokenizin/mcp-npx-fetch", "--outputTransport", "sse"]
+}
+```
+
+**MCP response — `ce_create_application`:**
+```json
+{
+  "name": "mcp-fetch-server",
+  "resource_type": "app_v2",
+  "status": "deploying",
+  "image_reference": "docker.io/supercorp/supergateway",
+  "image_port": 8000,
+  "scale_min_instances": 0,
+  "scale_max_instances": 10,
+  "endpoint": "https://mcp-fetch-server.<subdomain>.<region>.codeengine.appdomain.cloud",
+  "status_details": {
+    "latest_created_revision": "mcp-fetch-server-00001",
+    "latest_ready_revision": null
+  }
+}
+```
+
+> No pull secret is needed — `docker.io/supercorp/supergateway` is a public image. Code Engine scales to zero when idle; you pay only for actual requests.
+
+### Step 2 — Wait for the app to be ready
+
+Ask your assistant:
+```
+Wait for mcp-fetch-server in project <project-id> to be ready
+```
+
+This calls `ce_wait_for_app_ready`:
+```json
+{
+  "project_id": "<your-project-id>",
+  "app_name": "mcp-fetch-server",
+  "timeout_seconds": 120
+}
+```
+
+**MCP response — `ce_wait_for_app_ready`:**
+```json
+{
+  "app_name": "mcp-fetch-server",
+  "status": "ready",
+  "endpoint": "https://mcp-fetch-server.<subdomain>.<region>.codeengine.appdomain.cloud",
+  "elapsed_seconds": 34,
+  "poll_history": [
+    { "attempt": 1, "status": "deploying", "elapsed_seconds": 10 },
+    { "attempt": 2, "status": "deploying", "elapsed_seconds": 20 },
+    { "attempt": 3, "status": "ready",     "elapsed_seconds": 34 }
+  ]
+}
+```
+
+### Step 3 — Verify the running instance
+
+Ask your assistant:
+```
+List the running instances of mcp-fetch-server in project <project-id>
+```
+
+This calls `ce_list_app_instances`:
+
+**MCP response — `ce_list_app_instances`:**
+```json
+{
+  "instances": [
+    {
+      "name": "mcp-fetch-server-00001-deployment-abc123",
+      "revision": "mcp-fetch-server-00001",
+      "status": "running",
+      "restart_count": 0,
+      "started_at": "2026-05-09T12:01:44Z"
+    }
+  ]
+}
+```
+
+### Step 4 — Connect your MCP client
 
+Use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) to bridge the HTTP+SSE endpoint back to STDIO for local clients.
+
+**VS Code `mcp.json`:**
+```json
+{
+  "servers": {
+    "fetch": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "https://mcp-fetch-server.<subdomain>.<region>.codeengine.appdomain.cloud/sse"
+      ]
+    }
+  }
+}
+```
+
+**Claude Desktop `claude_desktop_config.json`:**
+```json
+{
+  "mcpServers": {
+    "fetch": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "https://mcp-fetch-server.<subdomain>.<region>.codeengine.appdomain.cloud/sse"
+      ]
+    }
+  }
+}
+```
+
+### Step 5 — Test the endpoint
+
+Verify the server is live and streaming:
+```bash
+curl -N https://mcp-fetch-server.<subdomain>.<region>.codeengine.appdomain.cloud/sse
+```
+
+Or open it in the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
+```bash
+npx @modelcontextprotocol/inspector
+# Connect via SSE → paste the Code Engine URL
+```
+
+Once connected, you will see the `fetch` tool listed and can invoke it directly from the inspector.
+
+### Full one-shot prompt
+
+```
+Deploy a hosted MCP fetch server to my Code Engine project <project-id>.
+Use image docker.io/supercorp/supergateway on port 8000 with no pull secret.
+run_args: --stdio "npx -y @tokenizin/mcp-npx-fetch" --outputTransport sse
+Name it "mcp-fetch-server", wait for it to be ready, and give me the /sse URL
+so I can add it to my mcp.json.
+```
+
+See [examples/mcp-server-supergateway/](./examples/mcp-server-supergateway/) for the ready-to-use client config file.
+
+### Deploy any other STDIO MCP server
+
+The same pattern works for any `npx`-runnable MCP server — just swap the `--stdio` argument:
+
+| MCP Server | `--stdio` argument |
+|---|---|
+| Fetch | `npx -y @tokenizin/mcp-npx-fetch` |
+| Filesystem | `npx -y @modelcontextprotocol/server-filesystem /data` |
+| Brave Search | `npx -y @modelcontextprotocol/server-brave-search` |
+| Your own server | `node /app/server.js` |
+
+---
+
+## Documentation
+
+- [Setup Instructions](./docs/SETUP_INSTRUCTIONS.md)
+- [MCP Inspector Troubleshooting](./docs/MCP_INSPECTOR_TROUBLESHOOTING.md)
 - [Code Engine API Reference](./docs/CODE_ENGINE_API_REFERENCE.md)
 - [API Call Scenarios](./docs/API_CALL_SCENARIOS.md)
-- [Setup Instructions](./docs/SETUP_INSTRUCTIONS.md)
 - [Client README](./docs/CLIENT_README.md)
 - [Cline MCP Config Example](./docs/CLINE_CONFIG_EXAMPLE.json)
-- [VS Code MCP extension](./vscode-extension/README.md) (registers this server via settings; no `mcp.json` required for the default `npx` flow)
+- [VS Code MCP extension](./vscode-extension/README.md)
 - [Code of Conduct](./docs/CODE_OF_CONDUCT.md)
 - [Contributing Guide](./docs/CONTRIBUTING.md)
 - [Maintainers](./docs/MAINTAINERS.md)
@@ -317,20 +549,27 @@ Tell me the public URL and confirm the instance is running.
 
 ```text
 code-engine-mcp-server/
-├── api/
-│   └── code-engine-openapi.yaml      # OpenAPI reference used for API coverage
+├── api/                              # OpenAPI reference used for API coverage
 ├── build/                            # Compiled JavaScript output
-├── docs/                             # API references and setup guides
-├── internal/                         # Internal release/publishing notes
+├── docs/                             # API references, client guides, community files
+│   ├── API_CALL_SCENARIOS.md
+│   ├── CODE_ENGINE_API_REFERENCE.md
+│   ├── MCP_INSPECTOR_TROUBLESHOOTING.md
+│   ├── SETUP_INSTRUCTIONS.md
+│   ├── CODE_OF_CONDUCT.md
+│   ├── CONTRIBUTING.md
+│   └── MAINTAINERS.md
+├── examples/
+│   ├── developer-splash/             # nginx static container example
+│   ├── starwars-splash/              # nginx Star Wars crawl example
+│   └── mcp-server-supergateway/      # Host any MCP server on Code Engine via supergateway
+├── internal/                         # Internal release notes
 ├── src/                              # Main TypeScript source code
 ├── CHANGELOG.md                      # Release history
-├── CODE_OF_CONDUCT.md                # Community guidelines
-├── CONTRIBUTING.md                   # Contribution workflow
 ├── LICENSE                           # Project license
-├── MAINTAINERS.md                    # Maintainer list
 ├── README.md                         # Project overview and usage
 ├── mcp.example.json                  # Example MCP client configuration
-├── vscode-extension/                 # Optional VS Code extension (MCP definition provider)
+├── vscode-extension/                 # Optional VS Code extension
 ├── package.json                      # npm package metadata and scripts
 ├── server.json                       # MCP Registry metadata
 └── tsconfig.json                     # TypeScript configuration
@@ -468,7 +707,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
-## npm and MCP Registry
+## One-Click Install
 
 Use the published package from npm or browse the MCP Registry listing:
 
@@ -579,8 +818,8 @@ Tell me what CNAME value to set in DNS.
 |------|-------------|----------------|
 | `ce_list_applications` | List applications in a project | `project_id` |
 | `ce_get_application` | Get application details and public URL | `project_id`, `app_name` |
-| `ce_create_application` | Deploy a new application | `project_id`, `name`, `image`, `image_secret`, `port`, `env_vars` |
-| `ce_update_application` | Update image, scaling, env, pull secret | `project_id`, `app_name`, `image`, `image_secret`, `scale_*` |
+| `ce_create_application` | Deploy a new application | `project_id`, `name`, `image`, `image_secret`, `port`, `env_vars`, `run_args`, `run_commands` |
+| `ce_update_application` | Update image, scaling, env, pull secret, run args | `project_id`, `app_name`, `image`, `image_secret`, `scale_*`, `run_args`, `run_commands` |
 | `ce_delete_application` | Delete an application | `project_id`, `app_name` |
 | `ce_list_app_instances` | List all running instances with status | `project_id`, `app_name` |
 | `ce_get_app_instance` | Get status details for a specific instance | `project_id`, `app_name`, `instance_name` |

package/build/index.js

@@ -86,7 +86,7 @@ async function resolveProjectId(nameOrId, token) {
 // Create MCP server
 const server = new Server({
     name: 'code-engine-mcp-server',
-    version: '1.0.3',
+    version: '1.0.6',
 }, {
     capabilities: {
         tools: {},
@@ -322,6 +322,8 @@ const codeEngineTools = [
                 scale_cpu_limit: { type: 'string', description: 'CPU limit (e.g. 1, 0.5)' },
                 scale_memory_limit: { type: 'string', description: 'Memory limit (e.g. 4G, 2G)' },
                 env_vars: { type: 'object', description: 'Key/value environment variables' },
+                run_args: { type: 'array', items: { type: 'string' }, description: 'Arguments passed to the container entrypoint (run_arguments). Required for supergateway: ["--stdio", "npx -y <mcp-server>", "--outputTransport", "sse"]' },
+                run_commands: { type: 'array', items: { type: 'string' }, description: 'Override the container entrypoint (run_commands). Rarely needed — use run_args for passing flags.' },
             },
             required: ['project_id', 'name', 'image'],
         },
@@ -340,6 +342,8 @@ const codeEngineTools = [
                 scale_max_instances: { type: 'number' },
                 scale_cpu_limit: { type: 'string' },
                 scale_memory_limit: { type: 'string' },
+                run_args: { type: 'array', items: { type: 'string' }, description: 'Arguments passed to the container entrypoint (run_arguments)' },
+                run_commands: { type: 'array', items: { type: 'string' }, description: 'Override the container entrypoint (run_commands)' },
             },
             required: ['project_id', 'app_name'],
         },
@@ -383,15 +387,16 @@ const codeEngineTools = [
     },
     {
         name: 'ce_get_app_logs',
-        description: 'Get logs for a specific Code Engine application instance',
+        description: 'Get logs for a Code Engine application. Retrieves logs from all running pods (or a specific instance) via the Code Engine Kubernetes API proxy.',
         inputSchema: {
             type: 'object',
             properties: {
-                project_id: { type: 'string' },
-                app_name: { type: 'string' },
-                instance_name: { type: 'string', description: 'Instance name (e.g. my-app-00001-deployment-abcde)' },
+                project_id: { type: 'string', description: 'Project ID or name' },
+                app_name: { type: 'string', description: 'Application name' },
+                instance_name: { type: 'string', description: 'Optional: specific pod/instance name to filter to (e.g. my-app-00001-deployment-abcde). If omitted, logs from all pods are returned.' },
+                tail_lines: { type: 'number', description: 'Number of log lines to return per pod (default: 100)' },
             },
-            required: ['project_id', 'app_name', 'instance_name'],
+            required: ['project_id', 'app_name'],
         },
     },
     // --- Builds ---
@@ -1259,6 +1264,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         type: 'literal', name, value,
                     }));
                 }
+                if (args.run_args)
+                    body.run_arguments = args.run_args;
+                if (args.run_commands)
+                    body.run_commands = args.run_commands;
                 const response = await axios.post(`${base}/apps`, body, { headers });
                 return { content: [{ type: 'text', text: JSON.stringify(response.data, null, 2) }] };
             }
@@ -1283,6 +1292,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     patch.scale_cpu_limit = args.scale_cpu_limit;
                 if (args.scale_memory_limit)
                     patch.scale_memory_limit = args.scale_memory_limit;
+                if (args.run_args)
+                    patch.run_arguments = args.run_args;
+                if (args.run_commands)
+                    patch.run_commands = args.run_commands;
                 const response = await axios.patch(`${base}/apps/${args.app_name}`, patch, {
                     headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/merge-patch+json', 'If-Match': entityTag },
                 });
@@ -1313,22 +1326,46 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             case 'ce_get_app_logs': {
                 const token = await getIAMToken(getApiKey());
-                const { base, headers } = await ceApi(args.project_id, token);
-                try {
-                    const response = await axios.get(`${base}/apps/${args.app_name}/instances/${args.instance_name}/logs`, { headers });
-                    return { content: [{ type: 'text', text: JSON.stringify(response.data, null, 2) }] };
+                const projectId = await resolveProjectId(args.project_id, token);
+                const region = await getProjectRegion(projectId, token);
+                const ceHeaders = { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' };
+                // Get app details to extract namespace/subdomain from the endpoint URL
+                const appRes = await axios.get(`https://api.${region}.codeengine.cloud.ibm.com/v2/projects/${projectId}/apps/${args.app_name}`, { headers: ceHeaders });
+                // Endpoint pattern: https://{app}.{subdomain}.{region}.codeengine.appdomain.cloud
+                const endpoint = appRes.data.endpoint || '';
+                const subdomainMatch = endpoint.match(/https?:\/\/[^.]+\.([^.]+)\.[^.]+\.codeengine/);
+                if (!subdomainMatch) {
+                    return { content: [{ type: 'text', text: JSON.stringify({ error: 'Could not determine project namespace from app endpoint', endpoint }, null, 2) }] };
                 }
-                catch (err) {
-                    if (err.response?.status === 403) {
-                        return { content: [{ type: 'text', text: JSON.stringify({
-                                        note: 'App instance logs are not accessible via the Code Engine REST API v2. ' +
-                                            'Configure IBM Log Analysis (IBM Cloud Logging) for your project to retrieve logs via the IBM Cloud Logs API.',
-                                        docs: 'https://cloud.ibm.com/docs/codeengine?topic=codeengine-view-logs',
-                                        status: 403,
-                                    }, null, 2) }] };
+                const namespace = subdomainMatch[1];
+                const proxyBase = `https://proxy.${region}.codeengine.cloud.ibm.com`;
+                const tailLines = args.tail_lines ?? 100;
+                const kubeHeaders = { Authorization: `Bearer ${token}` };
+                // List pods for the app via Kubernetes API proxy
+                const labelSelector = encodeURIComponent(`serving.knative.dev/service=${args.app_name}`);
+                const podsRes = await axios.get(`${proxyBase}/api/v1/namespaces/${namespace}/pods?labelSelector=${labelSelector}`, { headers: kubeHeaders });
+                const pods = podsRes.data.items || [];
+                if (pods.length === 0) {
+                    return { content: [{ type: 'text', text: JSON.stringify({ message: `No pods found for app '${args.app_name}'`, namespace, app: args.app_name }, null, 2) }] };
+                }
+                // Filter to a specific instance if requested
+                const targetPods = args.instance_name
+                    ? pods.filter((p) => p.metadata.name === args.instance_name || p.metadata.name.startsWith(String(args.instance_name)))
+                    : pods;
+                // Fetch logs for each pod
+                const results = [];
+                for (const pod of targetPods) {
+                    const podName = pod.metadata.name;
+                    const podPhase = pod.status?.phase ?? 'Unknown';
+                    try {
+                        const logRes = await axios.get(`${proxyBase}/api/v1/namespaces/${namespace}/pods/${podName}/log?container=user-container&tailLines=${tailLines}`, { headers: kubeHeaders });
+                        results.push({ pod: podName, status: podPhase, logs: logRes.data });
+                    }
+                    catch (logErr) {
+                        results.push({ pod: podName, status: podPhase, error: logErr.response?.data?.message ?? logErr.message });
                     }
-                    throw err;
                 }
+                return { content: [{ type: 'text', text: JSON.stringify({ app: args.app_name, namespace, region, pods_found: pods.length, results }, null, 2) }] };
             }
             case 'ce_list_builds': {
                 const token = await getIAMToken(getApiKey());