code-engine-mcp-server 1.0.4 → 1.0.6

package/docs/MCP_INSPECTOR_TROUBLESHOOTING.md

@@ -0,0 +1,232 @@
+# Troubleshooting with the MCP Inspector
+
+The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is an interactive browser UI that lets you connect directly to any MCP server, browse its tools, run them manually, and inspect the raw JSON-RPC traffic. This is the fastest way to verify your `code-engine-mcp-server` is working correctly — without needing a full AI assistant session.
+
+---
+
+## Prerequisites
+
+| Requirement | Notes |
+|-------------|-------|
+| Node.js ≥ 18 | Required to run the server and the inspector |
+| Built server | Run `npm run build` in the repo root |
+| IBM Cloud API key | Set in your environment or passed directly to the inspector |
+
+---
+
+## Step 1 — Build the server
+
+```bash
+cd /path/to/code-engine-mcp-server
+npm install && npm run build
+```
+
+Verify the entry point exists:
+
+```bash
+ls -lh build/index.js
+```
+
+---
+
+## Step 2 — Launch the MCP Inspector
+
+The inspector runs the MCP server as a child process (STDIO transport), so **no manual server startup is needed**.
+
+```bash
+npx @modelcontextprotocol/inspector \
+  node build/index.js
+```
+
+The inspector prints two URLs:
+
+```
+MCP Inspector is up and running at http://localhost:6274 🚀
+```
+
+Open the URL it prints. If it adds a `?MCP_PROXY_AUTH_TOKEN=...` query parameter, use the full URL including that token — it is required to connect to the proxy.
+
+> If port 6274 or 6277 is already in use from a stale run, kill the old process first:
+> ```bash
+> lsof -ti :6274,:6277 | xargs kill -9
+> ```
+
+---
+
+## Step 3 — Connect with your API key
+
+The server requires `IBMCLOUD_API_KEY` (and optionally `IBMCLOUD_REGION`). Pass them as environment variables in the inspector's **Environment Variables** panel before connecting:
+
+| Key | Example value |
+|-----|---------------|
+| `IBMCLOUD_API_KEY` | `YOUR_IBM_CLOUD_API_KEY` |
+| `IBMCLOUD_REGION` | `us-south` |
+
+Or set them in your shell before launching the inspector:
+
+```bash
+export IBMCLOUD_API_KEY=your-key
+export IBMCLOUD_REGION=us-south
+
+npx @modelcontextprotocol/inspector node build/index.js
+```
+
+The inspector UI looks like this with the STDIO transport configured and `IBMCLOUD_API_KEY` / `IBMCLOUD_REGION` entered:
+
+![Inspector setup — STDIO mode with env vars](images/inspector-localhost-1-setup.png)
+
+Once variables are set, click **Connect**. The status indicator turns green and the server name (`code-engine-mcp-server`) appears with the tools list populated:
+
+![Inspector connected — STDIO, tools listed](images/inspector-localhost-2-connected.png)
+
+---
+
+## Step 4 — List all tools
+
+1. Click the **Tools** tab.
+2. Click **List Tools**.
+
+You should see all ~62 tools grouped by category:
+
+| Category prefix | Example tools |
+|-----------------|--------------|
+| `ce_` | `ce_list_projects`, `ce_create_application`, `ce_get_app_logs` |
+| `docker_` | `docker_build_image`, `docker_push_image` |
+| `icr_` | `icr_list_namespaces`, `icr_list_images` |
+| `proc_` | `proc_build_push_deploy`, `proc_build_run_and_deploy` |
+
+If the list is empty or an error appears, check [Common errors](#common-errors) below.
+
+---
+
+## Step 5 — Run a tool manually
+
+### 5a — List your Code Engine projects
+
+Select `ce_list_projects` from the tools list and click **Run Tool** (no parameters needed).
+
+The result panel shows **Tool Result: Success** in green:
+
+![Tool Result: Success — ce_list_projects](images/inspector-localhost-3-result.png)
+
+Scrolling down shows the full JSON response with your real projects:
+
+![Tool result JSON — projects list](images/inspector-localhost-4-result-detail.png)
+
+Expected response shape:
+```json
+{
+  "projects": [
+    {
+      "id": "7e131e87-e967-4e7f-a2f1-480957244eac",
+      "name": "markus-app-v2-toronto",
+      "region": "ca-tor",
+      "status": "active"
+    }
+  ],
+  "total": 3
+}
+```
+
+### 5b — Get app logs
+
+Select `ce_get_app_logs` and fill in:
+
+| Parameter | Value |
+|-----------|-------|
+| `project_id` | your project ID from step 5a |
+| `app_name` | an app deployed in that project |
+| `tail_lines` | `50` (optional, default 100) |
+
+Click **Run Tool**. The tool fetches logs via the Kubernetes proxy API (same mechanism as `ibmcloud ce app logs`).
+
+### 5c — List app instances
+
+Select `ce_list_app_instances`:
+
+| Parameter | Value |
+|-----------|-------|
+| `project_id` | your project ID |
+| `app_name` | an app name |
+
+This confirms running pods and their current state.
+
+---
+
+## Step 6 — Inspect the raw JSON-RPC traffic
+
+The **History** panel on the left shows every request and response in order:
+
+| # | Method | Purpose |
+|---|--------|---------|
+| 1 | `initialize` | Handshake — server returns its name, version, capabilities |
+| 2 | `notifications/initialized` | Client acknowledges capabilities |
+| 3 | `tools/list` | Client fetches all available tools |
+| 4 | `tools/call` | Client invokes a specific tool |
+
+Click any history entry to see the full JSON payload. This is useful for copying exact tool inputs/outputs into bug reports.
+
+> **Why does raw `curl` give "Method not found"?**
+> A bare `curl` to the server's STDIO stream sends data without going through the `initialize` handshake first. The server correctly rejects it. The inspector handles the full handshake automatically.
+
+---
+
+## Common errors
+
+### `IBMCLOUD_API_KEY` not set
+
+**Symptom:** Tools return `401 Unauthorized` or `Missing API key` errors.
+
+**Fix:** Set the environment variable before launching the inspector, or add it in the inspector's Environment Variables panel and reconnect.
+
+---
+
+### `ECONNREFUSED` / server won't start
+
+**Symptom:** Inspector shows "Connection failed" immediately after clicking Connect.
+
+**Fix:**
+1. Confirm the build exists: `ls build/index.js`
+2. Test the server directly: `node build/index.js` — it should print nothing and wait (STDIO mode).
+3. Check Node.js version: `node --version` (must be ≥ 18).
+
+---
+
+### Port already in use
+
+**Symptom:** Inspector fails to start with `EADDRINUSE :6274` or `:6277`.
+
+**Fix:**
+```bash
+lsof -ti :6274,:6277 | xargs kill -9
+```
+
+Then rerun `npx @modelcontextprotocol/inspector node build/index.js`.
+
+---
+
+### Tools list is empty
+
+**Symptom:** `tools/list` returns `[]` or the Tools tab shows nothing.
+
+**Fix:** The server may have exited during startup (e.g. missing dependency). Run `node build/index.js` directly and check stderr for stack traces.
+
+---
+
+### `ce_get_app_logs` returns no pods
+
+**Symptom:** Response says no pods found for the app.
+
+**Possible causes:**
+- The app has scaled to zero (Code Engine scales idle apps down). Send a request to the app URL first to wake it up, then retry.
+- The `app_name` doesn't match exactly — it's case-sensitive.
+- The `project_id` is wrong — use `ce_list_projects` to confirm.
+
+---
+
+## Tips
+
+- Use the inspector's **Copy value** button on any result to paste exact JSON into a GitHub issue.
+- The **History** panel persists across tool calls in the same session — useful for comparing before/after behaviour when debugging.
+- To test a freshly built change, kill the inspector, run `npm run build`, and relaunch.
+- All `ce_` tools that need a `project_id` can discover it first with `ce_list_projects` — the same workflow your AI assistant uses.

package/docs/SETUP_INSTRUCTIONS.md

@@ -1,220 +1,123 @@
-# Quick Setup Instructions for Bob/Cline
+# Setup Instructions for MCP Clients (VS Code, Antigravity, Bob, Cursor)
 
-Follow these steps to enable Bob to understand Docker and Code Engine commands.
+Follow these steps to enable your AI assistant to understand Docker and Code Engine commands across different IDEs and MCP clients.
 
-> **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: Verify the Build
 
-The MCP server has been built successfully. Verify it exists:
+The MCP server must be built before it can be used. Verify it exists:
 
 ```bash
 ls -la /Users/markusvankempen/projects/code-engine/code-engine-mcp-server/build/index.js
 ```
 
-You should see the compiled JavaScript file.
+If it doesn't exist, run `npm install && npm run build` in the server root.
 
-## Step 2: Configure Cline in VSCode
+---
 
-1. **Open VSCode Settings**
-   - Press `Cmd + ,` (Mac) or `Ctrl + ,` (Windows/Linux)
-   - Or go to: Code → Settings → Settings
+## ⚙️ Step 2: Configure Your Client
 
-2. **Search for MCP Settings**
-   - Type "Cline MCP" in the search bar
-   - Look for "Cline: MCP Settings"
+Choose your IDE/Client below and follow the specific configuration steps.
 
-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:
+### 1. VS Code + GitHub Copilot (Official Extension)
+If you are using the latest VS Code (**1.101+**) with GitHub Copilot, the easiest way is to use our pre-built extension:
+1. Go to the `vscode-extension/` folder in this repo.
+2. Install the `.vsix` file (**Command Palette** → **Extensions: Install from VSIX...**).
+3. Open **Settings** (**Cmd+,**) and search for **IBM Code Engine MCP**.
+4. Enter your **IBM Cloud API Key**.
 
+### 2. Antigravity IDE / Claude Desktop
+Antigravity uses a standard MCP configuration file.
+1. Open (or create) your MCP config file at:
+   `~/Library/Application Support/Claude/claude_desktop_config.json`
+2. Add the following entry:
    ```json
    {
-     "cline.mcpServers": {
+     "mcpServers": {
        "code-engine": {
          "command": "node",
-         "args": [
-           "/Users/markusvankempen/projects/code-engine/code-engine-mcp-server/build/index.js"
-         ],
+         "args": ["/Users/markusvankempen/projects/code-engine/code-engine-mcp-server/build/index.js"],
          "env": {
-           "IBMCLOUD_API_KEY": "YOUR_IBMCLOUD_API_KEY_HERE"
+           "IBMCLOUD_API_KEY": "YOUR_IBM_CLOUD_API_KEY",
+           "IBMCLOUD_REGION": "us-south"
          }
        }
      }
    }
    ```
 
-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)
-
-## Step 3: Restart Cline/Bob
-
-1. **Reload VSCode Window**
-   - Press `Cmd + Shift + P` (Mac) or `Ctrl + Shift + P` (Windows/Linux)
-   - Type "Reload Window"
-   - Press Enter
-
-2. **Or Restart Cline**
-   - Open Cline sidebar
-   - Look for restart/reload option
-
-## Step 4: Verify the Connection
-
-1. **Check MCP Status**
-   - Look at the Cline status bar
-   - You should see "MCP" indicator
-   - It should show "code-engine" as connected
-
-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.
-
-## Step 5: Test Docker/Podman Integration
-
-Ask Bob:
-```
-Can you list all my local Docker images?
-```
-
-Bob should execute the `list_local_images` tool and show your images.
-
-## Step 6: Test Code Engine Integration
-
-Ask Bob:
-```
-Can you list all my Code Engine projects?
-```
-
-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
+### 3. Bob / Cline (VS Code Extension)
+1. Open **VS Code Settings** and search for **Cline: MCP Settings**.
+2. Click **Edit in settings.json**.
+3. Add the server to the `cline.mcpServers` object:
+   ```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_IBM_CLOUD_API_KEY"
+       }
+     }
+   }
    ```
-   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
+### 4. Cursor IDE
+Cursor supports MCP servers directly in its settings.
+1. Go to **Cursor Settings** → **General** → **MCP**.
+2. Click **+ Add New MCP Server**.
+3. **Name**: `code-engine`
+4. **Type**: `stdio`
+5. **Command**: `node /Users/markusvankempen/projects/code-engine/code-engine-mcp-server/build/index.js`
+6. **Environment Variables**: Add `IBMCLOUD_API_KEY` with your key value.
 
-### Docker Commands Not Working
+---
 
-1. **Verify Docker is installed**
-   ```bash
-   docker --version
-   ```
-
-2. **Check Docker daemon is running**
-   ```bash
-   docker ps
-   ```
+## 🚀 Step 3: Verify the Connection
 
-3. **Check permissions**
-   - You may need to add your user to the docker group
-   - Or use Podman instead
+Once configured, restart your IDE or reload the MCP server and test with a simple prompt:
 
-### Code Engine Commands Not Working
+> "Can you detect which container runtime I have installed?"
 
-1. **Verify IBM Cloud CLI**
-   ```bash
-   ibmcloud --version
-   ```
+The assistant should respond with your Docker or Podman version information.
 
-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
+## 🤖 Step 4: The Agentic Experience (No Docker/Code Engine Lingo Needed)
 
-Once configured, you can ask Bob to:
+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. 
 
-### 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"
+Here is an example interaction from a real session:
 
-### 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'"
+**User:**
+> "I have an app in the `developer-splash` folder. Deploy it to my Code Engine project."
 
-### Complete Workflows
-```
-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"
-```
+**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."
 
-Bob will execute all these steps automatically!
+**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!"
 
-## Next Steps
+---
 
-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!
+## 🛠️ Troubleshooting
 
-## Need Help?
+### "Cannot find module" or "MODULE_NOT_FOUND"
+Ensure you are using an **absolute path** in the `args` or `command` field. MCP clients usually do not resolve `${workspaceFolder}` or `~` correctly.
 
-- 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
+### "invalid character 'â'" or encoding errors
+Ensure your server is built using `npm run build`. This error often occurs if there are special characters in the source code that the `stdio` transport cannot handle.
 
-## Security Note
+### IBM Cloud API Key
+Get your key from: [https://cloud.ibm.com/iam/apikeys](https://cloud.ibm.com/iam/apikeys). Ensure it has the necessary permissions for Code Engine and Container Registry.
 
-⚠️ **Important**: Never commit your IBM Cloud API key to version control!
+---
 
-- Keep your API key in VSCode settings (not tracked by git)
-- Or use environment variables
-- Consider using IBM Cloud IAM for better security
+## 🔐 Security Note
+⚠️ **Important**: Never commit your `mcp_config.json` or any file containing your API key to version control. Always use `.gitignore` to protect your secrets.

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.6",
   "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"
   }