code-engine-mcp-server 1.0.6 β 1.0.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +165 -44
- package/build/index.js +1216 -66
- package/build/index.js.map +1 -1
- package/docs/MCP_INSPECTOR_TROUBLESHOOTING.md +70 -1
- package/docs/SETUP_INSTRUCTIONS.md +279 -87
- package/package.json +1 -1
|
@@ -1,123 +1,315 @@
|
|
|
1
|
-
# Setup Instructions for MCP Clients
|
|
1
|
+
# Setup Instructions for MCP Clients
|
|
2
2
|
|
|
3
|
-
Follow these steps to
|
|
3
|
+
Follow these steps to connect any AI assistant to IBM Code Engine and Docker/Podman via the MCP server.
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## π Step 1: Get an IBM Cloud API key
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
All Code Engine and ICR operations require an IBM Cloud API key.
|
|
10
|
+
|
|
11
|
+
1. Go to **[IBM Cloud IAM β API keys](https://cloud.ibm.com/iam/apikeys)**
|
|
12
|
+
2. Click **Create an IBM Cloud API key**
|
|
13
|
+
3. Give it a name (e.g. `code-engine-mcp`) and copy the value β you won't see it again
|
|
14
|
+
|
|
15
|
+
Keep it in a password manager. You'll use it in one of the options below.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## π Step 2: Decide how to store the API key
|
|
20
|
+
|
|
21
|
+
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.
|
|
22
|
+
|
|
23
|
+
### Option A β Shell environment variable (most secure, recommended)
|
|
24
|
+
|
|
25
|
+
Copy the template and fill in your key:
|
|
10
26
|
|
|
11
27
|
```bash
|
|
12
|
-
|
|
28
|
+
# from the repo root
|
|
29
|
+
cp .env.example .env # .env is already in .gitignore
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Edit `.env`:
|
|
33
|
+
```
|
|
34
|
+
IBMCLOUD_API_KEY=your-ibm-cloud-api-key-here
|
|
13
35
|
```
|
|
14
36
|
|
|
15
|
-
|
|
37
|
+
Load it into your current shell (or add the `export` line to `~/.zshrc` / `~/.bash_profile` for permanence):
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
source .env
|
|
41
|
+
# or permanently:
|
|
42
|
+
echo 'export IBMCLOUD_API_KEY="your-key"' >> ~/.zshrc
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
In any MCP config file, reference it without embedding the value:
|
|
46
|
+
```json
|
|
47
|
+
"IBMCLOUD_API_KEY": "${env:IBMCLOUD_API_KEY}"
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
> `${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.
|
|
16
51
|
|
|
17
52
|
---
|
|
18
53
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
### 3. Bob / Cline (VS Code Extension)
|
|
51
|
-
1. Open **VS Code Settings** and search for **Cline: MCP Settings**.
|
|
52
|
-
2. Click **Edit in settings.json**.
|
|
53
|
-
3. Add the server to the `cline.mcpServers` object:
|
|
54
|
-
```json
|
|
55
|
-
"cline.mcpServers": {
|
|
56
|
-
"code-engine": {
|
|
57
|
-
"command": "node",
|
|
58
|
-
"args": ["/Users/markusvankempen/projects/code-engine/code-engine-mcp-server/build/index.js"],
|
|
59
|
-
"env": {
|
|
60
|
-
"IBMCLOUD_API_KEY": "YOUR_IBM_CLOUD_API_KEY"
|
|
61
|
-
}
|
|
62
|
-
}
|
|
63
|
-
}
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
### 4. Cursor IDE
|
|
67
|
-
Cursor supports MCP servers directly in its settings.
|
|
68
|
-
1. Go to **Cursor Settings** β **General** β **MCP**.
|
|
69
|
-
2. Click **+ Add New MCP Server**.
|
|
70
|
-
3. **Name**: `code-engine`
|
|
71
|
-
4. **Type**: `stdio`
|
|
72
|
-
5. **Command**: `node /Users/markusvankempen/projects/code-engine/code-engine-mcp-server/build/index.js`
|
|
73
|
-
6. **Environment Variables**: Add `IBMCLOUD_API_KEY` with your key value.
|
|
54
|
+
### Option B β VS Code input variable (prompted on connect)
|
|
55
|
+
|
|
56
|
+
VS Code can ask you for the key each time it starts the MCP server. Good for shared or public machines.
|
|
57
|
+
|
|
58
|
+
Add an `inputs` block at the top level of your `mcp.json` (or `.vscode/mcp.json`):
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{
|
|
62
|
+
"inputs": [
|
|
63
|
+
{
|
|
64
|
+
"id": "ibmcloud-api-key",
|
|
65
|
+
"type": "promptString",
|
|
66
|
+
"description": "IBM Cloud API key",
|
|
67
|
+
"password": true
|
|
68
|
+
}
|
|
69
|
+
],
|
|
70
|
+
"servers": {
|
|
71
|
+
"code-engine": {
|
|
72
|
+
"type": "stdio",
|
|
73
|
+
"command": "npx",
|
|
74
|
+
"args": ["-y", "code-engine-mcp-server@latest"],
|
|
75
|
+
"env": {
|
|
76
|
+
"IBMCLOUD_API_KEY": "${input:ibmcloud-api-key}",
|
|
77
|
+
"IBMCLOUD_REGION": "us-south"
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
VS Code shows a masked password prompt when the server starts. The key is never written to disk.
|
|
74
85
|
|
|
75
86
|
---
|
|
76
87
|
|
|
77
|
-
|
|
88
|
+
### Option C β Inline value (simplest, least secure)
|
|
78
89
|
|
|
79
|
-
|
|
90
|
+
Paste the key directly into the config. Only do this on a personal machine and make sure the file is in `.gitignore`.
|
|
80
91
|
|
|
81
|
-
|
|
92
|
+
```json
|
|
93
|
+
"IBMCLOUD_API_KEY": "your-ibm-cloud-api-key-here"
|
|
94
|
+
```
|
|
82
95
|
|
|
83
|
-
|
|
96
|
+
> **Security:** Add the config file to `.gitignore` and never commit it. Prefer Option A or B whenever possible.
|
|
84
97
|
|
|
85
98
|
---
|
|
86
99
|
|
|
87
|
-
##
|
|
100
|
+
## βοΈ Step 3: Configure your client
|
|
88
101
|
|
|
89
|
-
|
|
102
|
+
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.
|
|
90
103
|
|
|
91
|
-
|
|
104
|
+
---
|
|
92
105
|
|
|
93
|
-
|
|
94
|
-
|
|
106
|
+
### 1. VS Code + GitHub Copilot β extension (easiest)
|
|
107
|
+
|
|
108
|
+
The official extension handles server startup, API key storage, and MCP registration automatically β no `mcp.json` editing required.
|
|
109
|
+
|
|
110
|
+
| Platform | Install |
|
|
111
|
+
|---|---|
|
|
112
|
+
| VS Code Marketplace | [MarkusvanKempen.code-engine-mcp](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.code-engine-mcp) |
|
|
113
|
+
| Open VSX (Cursor / Theia / Gitpod / Codium) | [markusvankempen.code-engine-mcp](https://open-vsx.org/extension/markusvankempen/code-engine-mcp) |
|
|
114
|
+
|
|
115
|
+
After installing:
|
|
116
|
+
|
|
117
|
+
1. Open the **IBM Code Engine MCP** sidebar panel (cloud icon in the Activity Bar)
|
|
118
|
+
2. Paste your IBM Cloud API key and click **Save**
|
|
119
|
+
3. Click **Configure MCP** β writes the server entry to the global `mcp.json`
|
|
120
|
+
4. Click **Run Diagnostics** to confirm Node.js, the API key, and tool discovery are all β
|
|
121
|
+
|
|
122
|
+
> The extension stores the key in VS Code global settings β encrypted by the OS keychain, never in a plaintext file.
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
### 2. VS Code + GitHub Copilot β manual `mcp.json`
|
|
127
|
+
|
|
128
|
+
Use this if you prefer to manage the config yourself without the extension.
|
|
129
|
+
|
|
130
|
+
Create (or edit) `.vscode/mcp.json` in your workspace root, or the global config at `~/Library/Application Support/Code/User/mcp.json` (macOS):
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
# workspace-level (add to .gitignore)
|
|
134
|
+
mkdir -p .vscode
|
|
135
|
+
echo '.vscode/mcp.json' >> .gitignore
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
```json
|
|
139
|
+
{
|
|
140
|
+
"servers": {
|
|
141
|
+
"code-engine": {
|
|
142
|
+
"type": "stdio",
|
|
143
|
+
"command": "npx",
|
|
144
|
+
"args": ["-y", "code-engine-mcp-server@latest"],
|
|
145
|
+
"env": {
|
|
146
|
+
"IBMCLOUD_API_KEY": "${env:IBMCLOUD_API_KEY}",
|
|
147
|
+
"IBMCLOUD_REGION": "us-south"
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Restart the server after saving: **Cmd+Shift+P** β **MCP: Restart Server** β `code-engine`.
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
### 3. Claude Desktop
|
|
159
|
+
|
|
160
|
+
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
161
|
+
|
|
162
|
+
```json
|
|
163
|
+
{
|
|
164
|
+
"mcpServers": {
|
|
165
|
+
"code-engine": {
|
|
166
|
+
"command": "npx",
|
|
167
|
+
"args": ["-y", "code-engine-mcp-server@latest"],
|
|
168
|
+
"env": {
|
|
169
|
+
"IBMCLOUD_API_KEY": "${env:IBMCLOUD_API_KEY}",
|
|
170
|
+
"IBMCLOUD_REGION": "us-south"
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
```
|
|
95
176
|
|
|
96
|
-
|
|
97
|
-
1. *Discovery:* "Let me check what projects and namespaces exist... Found project `markus-app-v2-toronto` and namespace `mvk-code-engine`."
|
|
98
|
-
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`."
|
|
99
|
-
3. *Execution:* "Now I'll run the full pipeline: build β push β deploy β wait."
|
|
100
|
-
4. *Validation:* "It's deployed but stuck at 'deploying'. Let me check the logs... The container is running but the readiness probe is failing."
|
|
101
|
-
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."
|
|
102
|
-
6. *Completion:* "App is live! π Status: ready."
|
|
177
|
+
> 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).
|
|
103
178
|
|
|
104
|
-
|
|
105
|
-
|
|
179
|
+
Restart Claude Desktop after saving.
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
### 4. Cline (VS Code Extension)
|
|
184
|
+
|
|
185
|
+
1. Open **VS Code Settings** (`Cmd+,`)
|
|
186
|
+
2. Search for **Cline: MCP Settings** β **Edit in settings.json**
|
|
187
|
+
3. Add:
|
|
188
|
+
|
|
189
|
+
```json
|
|
190
|
+
{
|
|
191
|
+
"cline.mcpServers": {
|
|
192
|
+
"code-engine": {
|
|
193
|
+
"command": "npx",
|
|
194
|
+
"args": ["-y", "code-engine-mcp-server@latest"],
|
|
195
|
+
"env": {
|
|
196
|
+
"IBMCLOUD_API_KEY": "${env:IBMCLOUD_API_KEY}",
|
|
197
|
+
"IBMCLOUD_REGION": "us-south"
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
> If your shell exports `IBMCLOUD_API_KEY`, Cline inherits it automatically β the `${env:...}` reference will resolve without any extra config.
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
### 5. Cursor IDE
|
|
209
|
+
|
|
210
|
+
Cursor supports MCP servers in its settings UI or via a `~/.cursor/mcp.json` file.
|
|
211
|
+
|
|
212
|
+
**UI approach:**
|
|
213
|
+
1. Go to **Cursor Settings** β **General** β **MCP**
|
|
214
|
+
2. Click **+ Add New MCP Server**
|
|
215
|
+
3. Fill in:
|
|
216
|
+
- **Name**: `code-engine`
|
|
217
|
+
- **Type**: `stdio`
|
|
218
|
+
- **Command**: `npx`
|
|
219
|
+
- **Args**: `-y code-engine-mcp-server@latest`
|
|
220
|
+
- **Environment Variables**: `IBMCLOUD_API_KEY` = your key value
|
|
221
|
+
|
|
222
|
+
**File approach** (`~/.cursor/mcp.json`):
|
|
223
|
+
|
|
224
|
+
```json
|
|
225
|
+
{
|
|
226
|
+
"mcpServers": {
|
|
227
|
+
"code-engine": {
|
|
228
|
+
"command": "npx",
|
|
229
|
+
"args": ["-y", "code-engine-mcp-server@latest"],
|
|
230
|
+
"env": {
|
|
231
|
+
"IBMCLOUD_API_KEY": "${env:IBMCLOUD_API_KEY}",
|
|
232
|
+
"IBMCLOUD_REGION": "us-south"
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
Cursor also supports the Open VSX extension: [markusvankempen.code-engine-mcp](https://open-vsx.org/extension/markusvankempen/code-engine-mcp)
|
|
240
|
+
|
|
241
|
+
---
|
|
242
|
+
|
|
243
|
+
## π Step 4: Verify the connection
|
|
244
|
+
|
|
245
|
+
Once configured, restart your IDE or reload the MCP server and test with:
|
|
246
|
+
|
|
247
|
+
> *"Can you detect which container runtime I have installed?"*
|
|
248
|
+
|
|
249
|
+
The assistant should respond with your Docker or Podman version. If it fails, see the Troubleshooting section below.
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
## π€ Step 5: The agentic experience
|
|
254
|
+
|
|
255
|
+
You don't need to know Docker or Code Engine commands. State your goal and the AI handles discovery, execution, and self-correction autonomously.
|
|
256
|
+
|
|
257
|
+
**Example from a real session:**
|
|
258
|
+
|
|
259
|
+
**User:** *"I have an app in the `developer-splash` folder. Deploy it to my Code Engine project."*
|
|
260
|
+
|
|
261
|
+
**Assistant's thought process:**
|
|
262
|
+
1. *Discovery:* "Let me check what projects and namespaces exist⦠Found project `markus-app-v2-toronto` and namespace `mvk-code-engine`."
|
|
263
|
+
2. *Prerequisites:* "No pull secret in this project yet. I'll create `icr-pull-secret` using the current API key."
|
|
264
|
+
3. *Execution:* "Running the full pipeline: build β push β deploy β wait."
|
|
265
|
+
4. *Validation:* "Stuck at 'deploying'. Checking logs⦠readiness probe failing."
|
|
266
|
+
5. *Self-correction:* "The `sed` pattern in the Dockerfile used `\s*` which Alpine BusyBox doesn't support. Fixing to `[[:space:]]*` and rebuilding."
|
|
267
|
+
6. *Completion:* "App is live! Status: ready."
|
|
268
|
+
|
|
269
|
+
**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."*
|
|
106
270
|
|
|
107
271
|
---
|
|
108
272
|
|
|
109
273
|
## π οΈ Troubleshooting
|
|
110
274
|
|
|
111
|
-
###
|
|
112
|
-
|
|
275
|
+
### `IBMCLOUD_API_KEY` not set / `401 Unauthorized`
|
|
276
|
+
|
|
277
|
+
The server requires the key at startup. Verify it is exported in the shell that launches your IDE:
|
|
278
|
+
|
|
279
|
+
```bash
|
|
280
|
+
echo $IBMCLOUD_API_KEY # should print your key, not empty
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
If empty, run `source .env` (from the repo root after filling in `.env`) or add the export to your shell profile.
|
|
284
|
+
|
|
285
|
+
### Tools show `undefined` or AI can't use them
|
|
113
286
|
|
|
114
|
-
|
|
115
|
-
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.
|
|
287
|
+
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.
|
|
116
288
|
|
|
117
|
-
###
|
|
118
|
-
|
|
289
|
+
### `Cannot find module` / `MODULE_NOT_FOUND`
|
|
290
|
+
|
|
291
|
+
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`.
|
|
292
|
+
|
|
293
|
+
### Port / permission errors on macOS
|
|
294
|
+
|
|
295
|
+
If `npx` can't find Node.js, ensure `node` and `npx` are on your `PATH`:
|
|
296
|
+
|
|
297
|
+
```bash
|
|
298
|
+
node --version # must be β₯ 18
|
|
299
|
+
npx --version
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
Install from [nodejs.org](https://nodejs.org) if missing.
|
|
303
|
+
|
|
304
|
+
### App revision stuck in `no_revision_ready`
|
|
305
|
+
|
|
306
|
+
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.
|
|
119
307
|
|
|
120
308
|
---
|
|
121
309
|
|
|
122
|
-
## π Security
|
|
123
|
-
|
|
310
|
+
## π Security checklist
|
|
311
|
+
|
|
312
|
+
- [ ] `.env` is in `.gitignore` (already set in this repo β verify with `git check-ignore .env`)
|
|
313
|
+
- [ ] `.vscode/mcp.json` is in `.gitignore` if it contains inline credentials
|
|
314
|
+
- [ ] API key uses `${env:IBMCLOUD_API_KEY}` or `${input:...}` rather than an inline value
|
|
315
|
+
- [ ] API key has only the minimum required IAM permissions (Code Engine Editor + Container Registry Reader)
|
package/package.json
CHANGED