code-engine-mcp-server 1.0.4 → 1.0.7

package/docs/SETUP_INSTRUCTIONS.md

@@ -1,220 +1,315 @@
-# Quick Setup Instructions for Bob/Cline
+# Setup Instructions for MCP Clients
 
-Follow these steps to enable Bob to understand Docker and Code Engine commands.
+Follow these steps to connect any AI assistant to IBM Code Engine and Docker/Podman via the MCP server.
 
-> **VS Code + Copilot (no Cline):** If you use GitHub Copilot’s built-in MCP support in VS Code **1.101+** and want the published server via `npx` without editing `mcp.json`, use the optional **IBM Code Engine MCP** extension instead. See [vscode-extension/README.md](../vscode-extension/README.md) and the **Configuration** section in the [main README](../README.md).
+---
 
-## Step 1: Verify the Build
+## 🔑 Step 1: Get an IBM Cloud API key
 
-The MCP server has been built successfully. Verify it exists:
+All Code Engine and ICR operations require an IBM Cloud API key.
+
+1. Go to **[IBM Cloud IAM → API keys](https://cloud.ibm.com/iam/apikeys)**
+2. Click **Create an IBM Cloud API key**
+3. Give it a name (e.g. `code-engine-mcp`) and copy the value — you won't see it again
+
+Keep it in a password manager. You'll use it in one of the options below.
+
+---
+
+## 🔐 Step 2: Decide how to store the API key
+
+Never paste your API key directly into a file you might commit to git. Three options are available — choose one and use it consistently across all client configs below.
+
+### Option A — Shell environment variable (most secure, recommended)
+
+Copy the template and fill in your key:
 
 ```bash
-ls -la /Users/markusvankempen/projects/code-engine/code-engine-mcp-server/build/index.js
+# from the repo root
+cp .env.example .env        # .env is already in .gitignore
+```
+
+Edit `.env`:
+```
+IBMCLOUD_API_KEY=your-ibm-cloud-api-key-here
+```
+
+Load it into your current shell (or add the `export` line to `~/.zshrc` / `~/.bash_profile` for permanence):
+
+```bash
+source .env
+# or permanently:
+echo 'export IBMCLOUD_API_KEY="your-key"' >> ~/.zshrc
+```
+
+In any MCP config file, reference it without embedding the value:
+```json
+"IBMCLOUD_API_KEY": "${env:IBMCLOUD_API_KEY}"
+```
+
+> `${env:VARIABLE}` is VS Code's input-substitution syntax — it reads the value from your shell environment when the server starts. The key never appears in the config file.
+
+---
+
+### Option B — VS Code input variable (prompted on connect)
+
+VS Code can ask you for the key each time it starts the MCP server. Good for shared or public machines.
+
+Add an `inputs` block at the top level of your `mcp.json` (or `.vscode/mcp.json`):
+
+```json
+{
+  "inputs": [
+    {
+      "id": "ibmcloud-api-key",
+      "type": "promptString",
+      "description": "IBM Cloud API key",
+      "password": true
+    }
+  ],
+  "servers": {
+    "code-engine": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "code-engine-mcp-server@latest"],
+      "env": {
+        "IBMCLOUD_API_KEY": "${input:ibmcloud-api-key}",
+        "IBMCLOUD_REGION": "us-south"
+      }
+    }
+  }
+}
 ```
 
-You should see the compiled JavaScript file.
+VS Code shows a masked password prompt when the server starts. The key is never written to disk.
+
+---
 
-## Step 2: Configure Cline in VSCode
+### Option C — Inline value (simplest, least secure)
 
-1. **Open VSCode Settings**
-   - Press `Cmd + ,` (Mac) or `Ctrl + ,` (Windows/Linux)
-   - Or go to: Code → Settings → Settings
+Paste the key directly into the config. Only do this on a personal machine and make sure the file is in `.gitignore`.
 
-2. **Search for MCP Settings**
-   - Type "Cline MCP" in the search bar
-   - Look for "Cline: MCP Settings"
+```json
+"IBMCLOUD_API_KEY": "your-ibm-cloud-api-key-here"
+```
+
+> **Security:** Add the config file to `.gitignore` and never commit it. Prefer Option A or B whenever possible.
 
-3. **Edit settings.json**
-   - Click "Edit in settings.json" link
-   - This will open your VSCode settings file
+---
 
-4. **Add the MCP Server Configuration**
-   
-   Copy and paste this configuration into your settings.json:
+## ⚙️ Step 3: Configure your client
 
-   ```json
-   {
-     "cline.mcpServers": {
-       "code-engine": {
-         "command": "node",
-         "args": [
-           "/Users/markusvankempen/projects/code-engine/code-engine-mcp-server/build/index.js"
-         ],
-         "env": {
-           "IBMCLOUD_API_KEY": "YOUR_IBMCLOUD_API_KEY_HERE"
-         }
-       }
-     }
-   }
-   ```
+Choose your IDE or client below. Each config uses the `${env:IBMCLOUD_API_KEY}` pattern (Option A). Swap in the Option B or C value if you prefer one of those approaches.
 
-5. **Replace YOUR_IBMCLOUD_API_KEY_HERE**
-   - Get your IBM Cloud API key from: https://cloud.ibm.com/iam/apikeys
-   - Replace the placeholder with your actual API key
-   - Keep the quotes around the key
+---
 
-6. **Save the file**
-   - Press `Cmd + S` (Mac) or `Ctrl + S` (Windows/Linux)
+### 1. VS Code + GitHub Copilot — extension (easiest)
 
-## Step 3: Restart Cline/Bob
+The official extension handles server startup, API key storage, and MCP registration automatically — no `mcp.json` editing required.
 
-1. **Reload VSCode Window**
-   - Press `Cmd + Shift + P` (Mac) or `Ctrl + Shift + P` (Windows/Linux)
-   - Type "Reload Window"
-   - Press Enter
+| Platform | Install |
+|---|---|
+| VS Code Marketplace | [MarkusvanKempen.code-engine-mcp](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.code-engine-mcp) |
+| Open VSX (Cursor / Theia / Gitpod / Codium) | [markusvankempen.code-engine-mcp](https://open-vsx.org/extension/markusvankempen/code-engine-mcp) |
 
-2. **Or Restart Cline**
-   - Open Cline sidebar
-   - Look for restart/reload option
+After installing:
 
-## Step 4: Verify the Connection
+1. Open the **IBM Code Engine MCP** sidebar panel (cloud icon in the Activity Bar)
+2. Paste your IBM Cloud API key and click **Save**
+3. Click **Configure MCP** — writes the server entry to the global `mcp.json`
+4. Click **Run Diagnostics** to confirm Node.js, the API key, and tool discovery are all ✅
 
-1. **Check MCP Status**
-   - Look at the Cline status bar
-   - You should see "MCP" indicator
-   - It should show "code-engine" as connected
+> The extension stores the key in VS Code global settings — encrypted by the OS keychain, never in a plaintext file.
 
-2. **Test with a Simple Command**
-   
-   Ask Bob:
-   ```
-   Can you detect which container runtime I have installed?
-   ```
+---
 
-   Bob should respond with Docker or Podman version information.
+### 2. VS Code + GitHub Copilot — manual `mcp.json`
 
-## Step 5: Test Docker/Podman Integration
+Use this if you prefer to manage the config yourself without the extension.
 
-Ask Bob:
+Create (or edit) `.vscode/mcp.json` in your workspace root, or the global config at `~/Library/Application Support/Code/User/mcp.json` (macOS):
+
+```bash
+# workspace-level (add to .gitignore)
+mkdir -p .vscode
+echo '.vscode/mcp.json' >> .gitignore
 ```
-Can you list all my local Docker images?
+
+```json
+{
+  "servers": {
+    "code-engine": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "code-engine-mcp-server@latest"],
+      "env": {
+        "IBMCLOUD_API_KEY": "${env:IBMCLOUD_API_KEY}",
+        "IBMCLOUD_REGION": "us-south"
+      }
+    }
+  }
+}
 ```
 
-Bob should execute the `list_local_images` tool and show your images.
+Restart the server after saving: **Cmd+Shift+P** → **MCP: Restart Server** → `code-engine`.
+
+---
 
-## Step 6: Test Code Engine Integration
+### 3. Claude Desktop
 
-Ask Bob:
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "code-engine": {
+      "command": "npx",
+      "args": ["-y", "code-engine-mcp-server@latest"],
+      "env": {
+        "IBMCLOUD_API_KEY": "${env:IBMCLOUD_API_KEY}",
+        "IBMCLOUD_REGION": "us-south"
+      }
+    }
+  }
+}
 ```
-Can you list all my Code Engine projects?
+
+> Claude Desktop does not support `${env:...}` substitution — use Option A (export the variable in your shell profile before launching Claude) or Option C (inline, with the file excluded from git).
+
+Restart Claude Desktop after saving.
+
+---
+
+### 4. Cline (VS Code Extension)
+
+1. Open **VS Code Settings** (`Cmd+,`)
+2. Search for **Cline: MCP Settings** → **Edit in settings.json**
+3. Add:
+
+```json
+{
+  "cline.mcpServers": {
+    "code-engine": {
+      "command": "npx",
+      "args": ["-y", "code-engine-mcp-server@latest"],
+      "env": {
+        "IBMCLOUD_API_KEY": "${env:IBMCLOUD_API_KEY}",
+        "IBMCLOUD_REGION": "us-south"
+      }
+    }
+  }
+}
 ```
 
-Bob should execute the `ce_list_projects` tool and show your projects.
-
-## Troubleshooting
-
-### MCP Server Not Showing as Connected
-
-1. **Check the path is correct**
-   ```bash
-   ls -la /Users/markusvankempen/projects/code-engine/code-engine-mcp-server/build/index.js
-   ```
-
-2. **Check Node.js is available**
-   ```bash
-   node --version
-   ```
-   Should show v18 or higher
-
-3. **Test the server manually**
-   ```bash
-   node /Users/markusvankempen/projects/code-engine/code-engine-mcp-server/build/index.js
-   ```
-   Should show: "Code Engine MCP Server running on stdio"
-   Press Ctrl+C to exit
-
-4. **Check VSCode Output**
-   - View → Output
-   - Select "Cline" from dropdown
-   - Look for MCP connection errors
-
-### Docker Commands Not Working
-
-1. **Verify Docker is installed**
-   ```bash
-   docker --version
-   ```
-
-2. **Check Docker daemon is running**
-   ```bash
-   docker ps
-   ```
-
-3. **Check permissions**
-   - You may need to add your user to the docker group
-   - Or use Podman instead
-
-### Code Engine Commands Not Working
-
-1. **Verify IBM Cloud CLI**
-   ```bash
-   ibmcloud --version
-   ```
-
-2. **Check Code Engine plugin**
-   ```bash
-   ibmcloud plugin list
-   ```
-   Should show "code-engine" plugin
-
-3. **Verify API key**
-   - Make sure you replaced the placeholder in settings.json
-   - Test manually:
-   ```bash
-   export IBMCLOUD_API_KEY="your-key-here"
-   ibmcloud ce project list
-   ```
-
-## What You Can Do Now
-
-Once configured, you can ask Bob to:
-
-### Docker/Podman Operations
-- "Detect my container runtime"
-- "Build a container from ./Dockerfile as myapp:latest"
-- "List all my local images"
-- "Test myapp:latest locally on port 8080"
-- "Get logs from container abc123"
-- "Stop and remove container abc123"
-- "List all running containers"
-
-### Code Engine Operations
-- "List all my Code Engine projects"
-- "List applications in project 'my-project'"
-- "Get details of application 'my-app' in project 'my-project'"
-- "Create an application named 'test-app' with image 'nginx:latest' in project 'my-project'"
-
-### Complete Workflows
+> If your shell exports `IBMCLOUD_API_KEY`, Cline inherits it automatically — the `${env:...}` reference will resolve without any extra config.
+
+---
+
+### 5. Cursor IDE
+
+Cursor supports MCP servers in its settings UI or via a `~/.cursor/mcp.json` file.
+
+**UI approach:**
+1. Go to **Cursor Settings** → **General** → **MCP**
+2. Click **+ Add New MCP Server**
+3. Fill in:
+   - **Name**: `code-engine`
+   - **Type**: `stdio`
+   - **Command**: `npx`
+   - **Args**: `-y code-engine-mcp-server@latest`
+   - **Environment Variables**: `IBMCLOUD_API_KEY` = your key value
+
+**File approach** (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "code-engine": {
+      "command": "npx",
+      "args": ["-y", "code-engine-mcp-server@latest"],
+      "env": {
+        "IBMCLOUD_API_KEY": "${env:IBMCLOUD_API_KEY}",
+        "IBMCLOUD_REGION": "us-south"
+      }
+    }
+  }
+}
 ```
-I have a Node.js app in ./my-app with a Dockerfile. Can you:
-1. Build it as myapp:v1.0.0
-2. Test it locally on port 3000
-3. Push it to icr.io/my-namespace/myapp:v1.0.0
-4. Deploy it to my Code Engine project "production"
+
+Cursor also supports the Open VSX extension: [markusvankempen.code-engine-mcp](https://open-vsx.org/extension/markusvankempen/code-engine-mcp)
+
+---
+
+## 🚀 Step 4: Verify the connection
+
+Once configured, restart your IDE or reload the MCP server and test with:
+
+> *"Can you detect which container runtime I have installed?"*
+
+The assistant should respond with your Docker or Podman version. If it fails, see the Troubleshooting section below.
+
+---
+
+## 🤖 Step 5: The agentic experience
+
+You don't need to know Docker or Code Engine commands. State your goal and the AI handles discovery, execution, and self-correction autonomously.
+
+**Example from a real session:**
+
+**User:** *"I have an app in the `developer-splash` folder. Deploy it to my Code Engine project."*
+
+**Assistant's 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 create `icr-pull-secret` using the current API key."
+3. *Execution:* "Running the full pipeline: build → push → deploy → wait."
+4. *Validation:* "Stuck at 'deploying'. Checking logs… readiness probe failing."
+5. *Self-correction:* "The `sed` pattern in the Dockerfile used `\s*` which Alpine BusyBox doesn't support. Fixing to `[[:space:]]*` and rebuilding."
+6. *Completion:* "App is live! Status: ready."
+
+**Response to user:** *"Your app is deployed at `https://developer-splash.29m5mrru3s3n.ca-tor.codeengine.appdomain.cloud`. I fixed a minor port config issue in the Dockerfile along the way."*
+
+---
+
+## 🛠️ Troubleshooting
+
+### `IBMCLOUD_API_KEY` not set / `401 Unauthorized`
+
+The server requires the key at startup. Verify it is exported in the shell that launches your IDE:
+
+```bash
+echo $IBMCLOUD_API_KEY    # should print your key, not empty
 ```
 
-Bob will execute all these steps automatically!
+If empty, run `source .env` (from the repo root after filling in `.env`) or add the export to your shell profile.
+
+### Tools show `undefined` or AI can't use them
 
-## Next Steps
+Run **Diagnostics** (extension sidebar) or check `tools/list` in the [MCP Inspector](https://github.com/modelcontextprotocol/inspector). If the tool list is empty, the server exited at startup — run `node build/index.js` directly to see any error output.
+
+### `Cannot find module` / `MODULE_NOT_FOUND`
+
+Use `npx -y code-engine-mcp-server@latest` instead of a local path, or ensure the repo is built with `npm install && npm run build` and use the absolute path to `build/index.js`.
+
+### Port / permission errors on macOS
+
+If `npx` can't find Node.js, ensure `node` and `npx` are on your `PATH`:
+
+```bash
+node --version   # must be ≥ 18
+npx --version
+```
 
-1. ✅ MCP server is built and ready
-2. ✅ Configuration example is provided
-3. ⏳ Add configuration to VSCode settings
-4. ⏳ Restart VSCode/Cline
-5. ⏳ Test with simple commands
-6. ⏳ Start using Bob for Docker and Code Engine tasks!
+Install from [nodejs.org](https://nodejs.org) if missing.
 
-## Need Help?
+### App revision stuck in `no_revision_ready`
 
-- Check the README.md for detailed documentation
-- Review MCP_SERVER_SETUP_GUIDE.md for comprehensive setup
-- Look at CLINE_CONFIG_EXAMPLE.json for configuration reference
-- Open an issue if you encounter problems
+See [MCP_INSPECTOR_TROUBLESHOOTING.md](./MCP_INSPECTOR_TROUBLESHOOTING.md) — the two most common causes are a stale ICR pull secret and an nginx port not rewritten in the Dockerfile.
 
-## Security Note
+---
 
-⚠️ **Important**: Never commit your IBM Cloud API key to version control!
+## 🔐 Security checklist
 
-- Keep your API key in VSCode settings (not tracked by git)
-- Or use environment variables
-- Consider using IBM Cloud IAM for better security
+- [ ] `.env` is in `.gitignore` (already set in this repo — verify with `git check-ignore .env`)
+- [ ] `.vscode/mcp.json` is in `.gitignore` if it contains inline credentials
+- [ ] API key uses `${env:IBMCLOUD_API_KEY}` or `${input:...}` rather than an inline value
+- [ ] API key has only the minimum required IAM permissions (Code Engine Editor + Container Registry Reader)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "code-engine-mcp-server",
   "mcpName": "io.github.markusvankempen/code-engine-mcp-server",
-  "version": "1.0.4",
+  "version": "1.0.7",
   "description": "MCP server for IBM Code Engine and Docker/Podman integration",
   "repository": {
     "type": "git",
@@ -23,7 +23,9 @@
     "deploy": "tsx src/deploy-cli.ts",
     "start": "node build/simple-client.js",
     "prepare": "npm run build",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --experimental-vm-modules node_modules/.bin/jest",
+    "test:watch": "node --experimental-vm-modules node_modules/.bin/jest --watch",
+    "test:coverage": "node --experimental-vm-modules node_modules/.bin/jest --coverage"
   },
   "keywords": [
     "mcp",
@@ -56,7 +58,10 @@
     "dotenv": "^17.4.2"
   },
   "devDependencies": {
+    "@types/jest": "^30.0.0",
     "@types/node": "^20.0.0",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.9",
     "tsx": "^4.7.0",
     "typescript": "^5.3.0"
   }