@purplesquirrel/ibmz-mcp-server 1.0.0

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.
Files changed (12) hide show
  1. package/.github/dependabot.yml +21 -0
  2. package/.github/workflows/ci.yml +36 -0
  3. package/LICENSE +21 -0
  4. package/README.md +217 -0
  5. package/TROUBLESHOOTING.md +241 -0
  6. package/docs/index.html +761 -0
  7. package/docs/specs.html +646 -0
  8. package/index.js +681 -0
  9. package/linkedin-post.md +90 -0
  10. package/package.json +29 -0
  11. package/test-keyprotect.js +46 -0
  12. package/test-watsonx-generation.js +72 -0
package/docs/specs.html ADDED
@@ -0,0 +1,646 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>Technical Specifications - IBM Z MCP Server</title>
7
+ <meta name="description" content="Full technical specifications for the IBM Z MCP Server">
8
+ <link rel="stylesheet" href="https://unpkg.com/@carbon/styles@1.50.0/css/styles.min.css">
9
+ <style>
10
+ :root {
11
+ --ibm-blue: #0f62fe;
12
+ --ibm-gray-100: #161616;
13
+ --ibm-gray-90: #262626;
14
+ --ibm-gray-80: #393939;
15
+ --ibm-cyan: #1192e8;
16
+ --ibm-purple: #8a3ffc;
17
+ }
18
+
19
+ * {
20
+ margin: 0;
21
+ padding: 0;
22
+ box-sizing: border-box;
23
+ }
24
+
25
+ body {
26
+ font-family: 'IBM Plex Sans', -apple-system, sans-serif;
27
+ background: var(--ibm-gray-100);
28
+ color: #f4f4f4;
29
+ line-height: 1.6;
30
+ }
31
+
32
+ .header {
33
+ background: var(--ibm-gray-90);
34
+ border-bottom: 1px solid var(--ibm-gray-80);
35
+ padding: 1rem 2rem;
36
+ display: flex;
37
+ justify-content: space-between;
38
+ align-items: center;
39
+ }
40
+
41
+ .header a {
42
+ color: var(--ibm-cyan);
43
+ text-decoration: none;
44
+ }
45
+
46
+ .header a:hover {
47
+ text-decoration: underline;
48
+ }
49
+
50
+ .container {
51
+ max-width: 1000px;
52
+ margin: 0 auto;
53
+ padding: 3rem 2rem;
54
+ }
55
+
56
+ h1 {
57
+ font-size: 2.5rem;
58
+ font-weight: 400;
59
+ margin-bottom: 0.5rem;
60
+ }
61
+
62
+ h1 span {
63
+ color: var(--ibm-cyan);
64
+ }
65
+
66
+ .subtitle {
67
+ color: #a8a8a8;
68
+ font-size: 1.1rem;
69
+ margin-bottom: 3rem;
70
+ }
71
+
72
+ h2 {
73
+ font-size: 1.5rem;
74
+ font-weight: 500;
75
+ margin: 3rem 0 1.5rem;
76
+ padding-bottom: 0.5rem;
77
+ border-bottom: 1px solid var(--ibm-gray-80);
78
+ }
79
+
80
+ h3 {
81
+ font-size: 1.25rem;
82
+ font-weight: 500;
83
+ margin: 2rem 0 1rem;
84
+ color: var(--ibm-purple);
85
+ }
86
+
87
+ p {
88
+ margin-bottom: 1rem;
89
+ color: #c6c6c6;
90
+ }
91
+
92
+ table {
93
+ width: 100%;
94
+ border-collapse: collapse;
95
+ margin: 1.5rem 0;
96
+ background: var(--ibm-gray-90);
97
+ border-radius: 8px;
98
+ overflow: hidden;
99
+ }
100
+
101
+ th, td {
102
+ padding: 1rem;
103
+ text-align: left;
104
+ border-bottom: 1px solid var(--ibm-gray-80);
105
+ }
106
+
107
+ th {
108
+ background: var(--ibm-gray-80);
109
+ font-weight: 500;
110
+ font-size: 0.875rem;
111
+ text-transform: uppercase;
112
+ letter-spacing: 0.5px;
113
+ }
114
+
115
+ td:first-child {
116
+ font-family: 'IBM Plex Mono', monospace;
117
+ color: var(--ibm-cyan);
118
+ font-size: 0.9rem;
119
+ }
120
+
121
+ .code-block {
122
+ background: var(--ibm-gray-90);
123
+ border: 1px solid var(--ibm-gray-80);
124
+ border-radius: 8px;
125
+ padding: 1.5rem;
126
+ margin: 1rem 0;
127
+ overflow-x: auto;
128
+ }
129
+
130
+ .code-block pre {
131
+ font-family: 'IBM Plex Mono', monospace;
132
+ font-size: 0.9rem;
133
+ color: #78a9ff;
134
+ line-height: 1.6;
135
+ }
136
+
137
+ .code-block .comment {
138
+ color: #6f6f6f;
139
+ }
140
+
141
+ .code-block .string {
142
+ color: #42be65;
143
+ }
144
+
145
+ .code-block .key {
146
+ color: #be95ff;
147
+ }
148
+
149
+ .warning {
150
+ background: rgba(250, 77, 86, 0.1);
151
+ border-left: 4px solid #fa4d56;
152
+ padding: 1rem 1.5rem;
153
+ margin: 1rem 0;
154
+ border-radius: 0 8px 8px 0;
155
+ }
156
+
157
+ .warning p {
158
+ color: #fa4d56;
159
+ margin: 0;
160
+ }
161
+
162
+ .info {
163
+ background: rgba(17, 146, 232, 0.1);
164
+ border-left: 4px solid var(--ibm-cyan);
165
+ padding: 1rem 1.5rem;
166
+ margin: 1rem 0;
167
+ border-radius: 0 8px 8px 0;
168
+ }
169
+
170
+ .info p {
171
+ color: var(--ibm-cyan);
172
+ margin: 0;
173
+ }
174
+
175
+ ul {
176
+ margin: 1rem 0 1rem 1.5rem;
177
+ color: #c6c6c6;
178
+ }
179
+
180
+ li {
181
+ margin-bottom: 0.5rem;
182
+ }
183
+
184
+ code {
185
+ font-family: 'IBM Plex Mono', monospace;
186
+ background: var(--ibm-gray-80);
187
+ padding: 0.2rem 0.5rem;
188
+ border-radius: 4px;
189
+ font-size: 0.9em;
190
+ }
191
+
192
+ footer {
193
+ border-top: 1px solid var(--ibm-gray-80);
194
+ padding: 2rem;
195
+ text-align: center;
196
+ color: #6f6f6f;
197
+ margin-top: 3rem;
198
+ }
199
+
200
+ footer a {
201
+ color: var(--ibm-cyan);
202
+ text-decoration: none;
203
+ }
204
+ </style>
205
+ </head>
206
+ <body>
207
+ <div class="header">
208
+ <a href="index.html">&larr; Back to Home</a>
209
+ <a href="https://github.com/PurpleSquirrelMedia/ibmz-mcp-server">GitHub</a>
210
+ </div>
211
+
212
+ <div class="container">
213
+ <h1>Technical <span>Specifications</span></h1>
214
+ <p class="subtitle">IBM Z MCP Server v1.0.0</p>
215
+
216
+ <h2>Environment Variables</h2>
217
+
218
+ <h3>Key Protect Configuration</h3>
219
+ <table>
220
+ <thead>
221
+ <tr>
222
+ <th>Variable</th>
223
+ <th>Required</th>
224
+ <th>Description</th>
225
+ </tr>
226
+ </thead>
227
+ <tbody>
228
+ <tr>
229
+ <td>IBM_CLOUD_API_KEY</td>
230
+ <td>Yes</td>
231
+ <td>IBM Cloud API key with access to Key Protect</td>
232
+ </tr>
233
+ <tr>
234
+ <td>KEY_PROTECT_INSTANCE_ID</td>
235
+ <td>Yes</td>
236
+ <td>GUID of your Key Protect service instance</td>
237
+ </tr>
238
+ <tr>
239
+ <td>KEY_PROTECT_URL</td>
240
+ <td>No</td>
241
+ <td>Key Protect endpoint (default: https://us-south.kms.cloud.ibm.com)</td>
242
+ </tr>
243
+ </tbody>
244
+ </table>
245
+
246
+ <h3>z/OS Connect Configuration</h3>
247
+ <table>
248
+ <thead>
249
+ <tr>
250
+ <th>Variable</th>
251
+ <th>Required</th>
252
+ <th>Description</th>
253
+ </tr>
254
+ </thead>
255
+ <tbody>
256
+ <tr>
257
+ <td>ZOS_CONNECT_URL</td>
258
+ <td>Yes*</td>
259
+ <td>Base URL of z/OS Connect server (e.g., https://mainframe:9443)</td>
260
+ </tr>
261
+ <tr>
262
+ <td>ZOS_CONNECT_USERNAME</td>
263
+ <td>No</td>
264
+ <td>Username for basic authentication</td>
265
+ </tr>
266
+ <tr>
267
+ <td>ZOS_CONNECT_PASSWORD</td>
268
+ <td>No</td>
269
+ <td>Password for basic authentication</td>
270
+ </tr>
271
+ </tbody>
272
+ </table>
273
+ <p><em>* Required only if using z/OS Connect tools</em></p>
274
+
275
+ <h2>Key Protect Tool Specifications</h2>
276
+
277
+ <h3>key_protect_list_keys</h3>
278
+ <p>List encryption keys in your Key Protect instance.</p>
279
+ <table>
280
+ <thead>
281
+ <tr>
282
+ <th>Parameter</th>
283
+ <th>Type</th>
284
+ <th>Required</th>
285
+ <th>Description</th>
286
+ </tr>
287
+ </thead>
288
+ <tbody>
289
+ <tr>
290
+ <td>limit</td>
291
+ <td>number</td>
292
+ <td>No</td>
293
+ <td>Maximum keys to return (default: 100)</td>
294
+ </tr>
295
+ <tr>
296
+ <td>offset</td>
297
+ <td>number</td>
298
+ <td>No</td>
299
+ <td>Number of keys to skip (default: 0)</td>
300
+ </tr>
301
+ <tr>
302
+ <td>state</td>
303
+ <td>array</td>
304
+ <td>No</td>
305
+ <td>Filter by state: 1=Active, 2=Suspended, 3=Deactivated, 5=Destroyed</td>
306
+ </tr>
307
+ </tbody>
308
+ </table>
309
+
310
+ <h3>key_protect_create_key</h3>
311
+ <p>Create a new encryption key in the HSM.</p>
312
+ <table>
313
+ <thead>
314
+ <tr>
315
+ <th>Parameter</th>
316
+ <th>Type</th>
317
+ <th>Required</th>
318
+ <th>Description</th>
319
+ </tr>
320
+ </thead>
321
+ <tbody>
322
+ <tr>
323
+ <td>name</td>
324
+ <td>string</td>
325
+ <td>Yes</td>
326
+ <td>Unique name for the key</td>
327
+ </tr>
328
+ <tr>
329
+ <td>description</td>
330
+ <td>string</td>
331
+ <td>No</td>
332
+ <td>Description of key purpose</td>
333
+ </tr>
334
+ <tr>
335
+ <td>type</td>
336
+ <td>string</td>
337
+ <td>No</td>
338
+ <td>"root_key" or "standard_key" (default)</td>
339
+ </tr>
340
+ <tr>
341
+ <td>extractable</td>
342
+ <td>boolean</td>
343
+ <td>No</td>
344
+ <td>Allow key material export (default: false)</td>
345
+ </tr>
346
+ <tr>
347
+ <td>payload</td>
348
+ <td>string</td>
349
+ <td>No</td>
350
+ <td>Base64 key material for BYOK</td>
351
+ </tr>
352
+ </tbody>
353
+ </table>
354
+
355
+ <h3>key_protect_wrap_key</h3>
356
+ <p>Wrap (encrypt) a data encryption key with a root key.</p>
357
+ <table>
358
+ <thead>
359
+ <tr>
360
+ <th>Parameter</th>
361
+ <th>Type</th>
362
+ <th>Required</th>
363
+ <th>Description</th>
364
+ </tr>
365
+ </thead>
366
+ <tbody>
367
+ <tr>
368
+ <td>key_id</td>
369
+ <td>string</td>
370
+ <td>Yes</td>
371
+ <td>ID of the root key</td>
372
+ </tr>
373
+ <tr>
374
+ <td>plaintext</td>
375
+ <td>string</td>
376
+ <td>Yes</td>
377
+ <td>Base64-encoded DEK to wrap</td>
378
+ </tr>
379
+ <tr>
380
+ <td>aad</td>
381
+ <td>array</td>
382
+ <td>No</td>
383
+ <td>Additional authenticated data</td>
384
+ </tr>
385
+ </tbody>
386
+ </table>
387
+
388
+ <h3>key_protect_unwrap_key</h3>
389
+ <p>Unwrap (decrypt) a wrapped data encryption key.</p>
390
+ <table>
391
+ <thead>
392
+ <tr>
393
+ <th>Parameter</th>
394
+ <th>Type</th>
395
+ <th>Required</th>
396
+ <th>Description</th>
397
+ </tr>
398
+ </thead>
399
+ <tbody>
400
+ <tr>
401
+ <td>key_id</td>
402
+ <td>string</td>
403
+ <td>Yes</td>
404
+ <td>ID of the root key</td>
405
+ </tr>
406
+ <tr>
407
+ <td>ciphertext</td>
408
+ <td>string</td>
409
+ <td>Yes</td>
410
+ <td>Base64-encoded wrapped DEK</td>
411
+ </tr>
412
+ <tr>
413
+ <td>aad</td>
414
+ <td>array</td>
415
+ <td>No</td>
416
+ <td>AAD (must match wrap operation)</td>
417
+ </tr>
418
+ </tbody>
419
+ </table>
420
+
421
+ <h3>key_protect_rotate_key</h3>
422
+ <p>Rotate a root key to a new version.</p>
423
+ <table>
424
+ <thead>
425
+ <tr>
426
+ <th>Parameter</th>
427
+ <th>Type</th>
428
+ <th>Required</th>
429
+ <th>Description</th>
430
+ </tr>
431
+ </thead>
432
+ <tbody>
433
+ <tr>
434
+ <td>key_id</td>
435
+ <td>string</td>
436
+ <td>Yes</td>
437
+ <td>ID of the root key to rotate</td>
438
+ </tr>
439
+ <tr>
440
+ <td>payload</td>
441
+ <td>string</td>
442
+ <td>No</td>
443
+ <td>New key material for BYOK rotation</td>
444
+ </tr>
445
+ </tbody>
446
+ </table>
447
+
448
+ <h3>key_protect_delete_key</h3>
449
+ <div class="warning">
450
+ <p><strong>WARNING:</strong> Key deletion is irreversible. Data encrypted with deleted keys becomes permanently unrecoverable.</p>
451
+ </div>
452
+ <table>
453
+ <thead>
454
+ <tr>
455
+ <th>Parameter</th>
456
+ <th>Type</th>
457
+ <th>Required</th>
458
+ <th>Description</th>
459
+ </tr>
460
+ </thead>
461
+ <tbody>
462
+ <tr>
463
+ <td>key_id</td>
464
+ <td>string</td>
465
+ <td>Yes</td>
466
+ <td>ID of the key to delete</td>
467
+ </tr>
468
+ <tr>
469
+ <td>force</td>
470
+ <td>boolean</td>
471
+ <td>No</td>
472
+ <td>Force delete even with associated resources</td>
473
+ </tr>
474
+ </tbody>
475
+ </table>
476
+
477
+ <h2>z/OS Connect Tool Specifications</h2>
478
+
479
+ <div class="info">
480
+ <p><strong>Note:</strong> z/OS Connect requires access to an IBM mainframe with z/OS Connect EE installed. These tools will return configuration errors if ZOS_CONNECT_URL is not set.</p>
481
+ </div>
482
+
483
+ <h3>zos_connect_list_services</h3>
484
+ <p>List all deployed z/OS Connect services.</p>
485
+ <p>No parameters required.</p>
486
+
487
+ <h3>zos_connect_call_service</h3>
488
+ <p>Call a z/OS Connect service to interact with mainframe programs.</p>
489
+ <table>
490
+ <thead>
491
+ <tr>
492
+ <th>Parameter</th>
493
+ <th>Type</th>
494
+ <th>Required</th>
495
+ <th>Description</th>
496
+ </tr>
497
+ </thead>
498
+ <tbody>
499
+ <tr>
500
+ <td>service_name</td>
501
+ <td>string</td>
502
+ <td>Yes</td>
503
+ <td>Name of the z/OS Connect service</td>
504
+ </tr>
505
+ <tr>
506
+ <td>operation</td>
507
+ <td>string</td>
508
+ <td>No</td>
509
+ <td>API operation path (default: "/")</td>
510
+ </tr>
511
+ <tr>
512
+ <td>method</td>
513
+ <td>string</td>
514
+ <td>No</td>
515
+ <td>HTTP method: GET, POST, PUT, DELETE, PATCH</td>
516
+ </tr>
517
+ <tr>
518
+ <td>payload</td>
519
+ <td>object</td>
520
+ <td>No</td>
521
+ <td>JSON request body</td>
522
+ </tr>
523
+ <tr>
524
+ <td>path_params</td>
525
+ <td>object</td>
526
+ <td>No</td>
527
+ <td>Path parameter substitutions</td>
528
+ </tr>
529
+ <tr>
530
+ <td>query_params</td>
531
+ <td>object</td>
532
+ <td>No</td>
533
+ <td>Query string parameters</td>
534
+ </tr>
535
+ </tbody>
536
+ </table>
537
+
538
+ <h2>Dependencies</h2>
539
+ <div class="code-block">
540
+ <pre>{
541
+ <span class="key">"@modelcontextprotocol/sdk"</span>: <span class="string">"^1.0.0"</span>,
542
+ <span class="key">"@ibm-cloud/key-protect"</span>: <span class="string">"^0.12.0"</span>,
543
+ <span class="key">"ibm-cloud-sdk-core"</span>: <span class="string">"^5.1.0"</span>
544
+ }</pre>
545
+ </div>
546
+
547
+ <h2>Security Considerations</h2>
548
+
549
+ <h3>Key Protect</h3>
550
+ <ul>
551
+ <li>Keys are stored in FIPS 140-2 Level 3 certified HSMs</li>
552
+ <li>Root keys never leave the HSM hardware</li>
553
+ <li>All API calls use TLS 1.2+ encryption</li>
554
+ <li>IAM authentication required for all operations</li>
555
+ <li>Activity Tracker logs all key operations</li>
556
+ </ul>
557
+
558
+ <h3>z/OS Connect</h3>
559
+ <ul>
560
+ <li>Supports TLS/SSL for transport security</li>
561
+ <li>Basic authentication or SAF-based security</li>
562
+ <li>Credentials should be stored securely (not in code)</li>
563
+ <li>Network access typically requires VPN or private connection</li>
564
+ </ul>
565
+
566
+ <h2>Error Handling</h2>
567
+ <p>All tools return structured error messages:</p>
568
+ <div class="code-block">
569
+ <pre>{
570
+ <span class="key">"content"</span>: [{
571
+ <span class="key">"type"</span>: <span class="string">"text"</span>,
572
+ <span class="key">"text"</span>: <span class="string">"Error: Key Protect not configured. Set IBM_CLOUD_API_KEY and KEY_PROTECT_INSTANCE_ID environment variables."</span>
573
+ }]
574
+ }</pre>
575
+ </div>
576
+
577
+ <h2>Claude Code Configuration</h2>
578
+ <div class="code-block">
579
+ <pre><span class="comment">// ~/.claude.json</span>
580
+ {
581
+ <span class="key">"mcpServers"</span>: {
582
+ <span class="key">"ibmz"</span>: {
583
+ <span class="key">"type"</span>: <span class="string">"stdio"</span>,
584
+ <span class="key">"command"</span>: <span class="string">"node"</span>,
585
+ <span class="key">"args"</span>: [<span class="string">"/path/to/ibmz-mcp-server/index.js"</span>],
586
+ <span class="key">"env"</span>: {
587
+ <span class="key">"IBM_CLOUD_API_KEY"</span>: <span class="string">"your-ibm-cloud-api-key"</span>,
588
+ <span class="key">"KEY_PROTECT_INSTANCE_ID"</span>: <span class="string">"your-key-protect-instance-id"</span>,
589
+ <span class="key">"KEY_PROTECT_URL"</span>: <span class="string">"https://us-south.kms.cloud.ibm.com"</span>,
590
+ <span class="comment">// Optional: z/OS Connect configuration</span>
591
+ <span class="key">"ZOS_CONNECT_URL"</span>: <span class="string">"https://your-mainframe:9443"</span>,
592
+ <span class="key">"ZOS_CONNECT_USERNAME"</span>: <span class="string">"your-username"</span>,
593
+ <span class="key">"ZOS_CONNECT_PASSWORD"</span>: <span class="string">"your-password"</span>
594
+ }
595
+ }
596
+ }
597
+ }</pre>
598
+ </div>
599
+
600
+ <h2>Regional Endpoints</h2>
601
+ <h3>Key Protect</h3>
602
+ <table>
603
+ <thead>
604
+ <tr>
605
+ <th>Region</th>
606
+ <th>Endpoint</th>
607
+ </tr>
608
+ </thead>
609
+ <tbody>
610
+ <tr>
611
+ <td>us-south</td>
612
+ <td>https://us-south.kms.cloud.ibm.com</td>
613
+ </tr>
614
+ <tr>
615
+ <td>us-east</td>
616
+ <td>https://us-east.kms.cloud.ibm.com</td>
617
+ </tr>
618
+ <tr>
619
+ <td>eu-gb</td>
620
+ <td>https://eu-gb.kms.cloud.ibm.com</td>
621
+ </tr>
622
+ <tr>
623
+ <td>eu-de</td>
624
+ <td>https://eu-de.kms.cloud.ibm.com</td>
625
+ </tr>
626
+ <tr>
627
+ <td>jp-tok</td>
628
+ <td>https://jp-tok.kms.cloud.ibm.com</td>
629
+ </tr>
630
+ <tr>
631
+ <td>au-syd</td>
632
+ <td>https://au-syd.kms.cloud.ibm.com</td>
633
+ </tr>
634
+ </tbody>
635
+ </table>
636
+ </div>
637
+
638
+ <footer>
639
+ <p>
640
+ <a href="index.html">Home</a> |
641
+ <a href="https://github.com/PurpleSquirrelMedia/ibmz-mcp-server">GitHub</a> |
642
+ MIT License
643
+ </p>
644
+ </footer>
645
+ </body>
646
+ </html>