@purplesquirrel/watsonx-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 (17) 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 +245 -0
  5. package/TROUBLESHOOTING.md +176 -0
  6. package/batch-processor.js +345 -0
  7. package/batch-results/classify-1765765720041.json +106 -0
  8. package/batch-results/full-analysis-1765765676586.json +193 -0
  9. package/docs/index.html +572 -0
  10. package/docs/specs.html +613 -0
  11. package/document-analyzer.js +353 -0
  12. package/embedding-index.js +318 -0
  13. package/embeddings-index.json +38761 -0
  14. package/index.js +551 -0
  15. package/linkedin-post.md +92 -0
  16. package/package.json +28 -0
  17. package/test-watsonx.js +29 -0
package/docs/specs.html ADDED
@@ -0,0 +1,613 @@
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 - watsonx MCP Server</title>
7
+ <link rel="preconnect" href="https://fonts.googleapis.com">
8
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
9
+ <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500&display=swap" rel="stylesheet">
10
+ <style>
11
+ :root {
12
+ --ibm-blue: #0f62fe;
13
+ --carbon-gray-100: #161616;
14
+ --carbon-gray-90: #262626;
15
+ --carbon-gray-80: #393939;
16
+ --carbon-gray-70: #525252;
17
+ --carbon-gray-50: #8d8d8d;
18
+ --carbon-gray-30: #c6c6c6;
19
+ --carbon-gray-10: #f4f4f4;
20
+ --purple: #8a3ffc;
21
+ --teal: #009d9a;
22
+ --green: #24a148;
23
+ }
24
+
25
+ * { margin: 0; padding: 0; box-sizing: border-box; }
26
+
27
+ body {
28
+ font-family: 'IBM Plex Sans', sans-serif;
29
+ background: var(--carbon-gray-100);
30
+ color: var(--carbon-gray-10);
31
+ line-height: 1.7;
32
+ }
33
+
34
+ .container {
35
+ max-width: 900px;
36
+ margin: 0 auto;
37
+ padding: 4rem 2rem;
38
+ }
39
+
40
+ nav {
41
+ background: var(--carbon-gray-90);
42
+ border-bottom: 1px solid var(--carbon-gray-80);
43
+ padding: 1rem 2rem;
44
+ position: sticky;
45
+ top: 0;
46
+ z-index: 100;
47
+ }
48
+
49
+ nav a {
50
+ color: var(--carbon-gray-30);
51
+ text-decoration: none;
52
+ margin-right: 2rem;
53
+ font-size: 0.875rem;
54
+ }
55
+
56
+ nav a:hover, nav a.active {
57
+ color: var(--ibm-blue);
58
+ }
59
+
60
+ h1 {
61
+ font-size: 2.5rem;
62
+ margin-bottom: 0.5rem;
63
+ }
64
+
65
+ h1 span { color: var(--ibm-blue); }
66
+
67
+ .tagline {
68
+ color: var(--carbon-gray-50);
69
+ font-size: 1.125rem;
70
+ margin-bottom: 3rem;
71
+ }
72
+
73
+ h2 {
74
+ font-size: 1.5rem;
75
+ margin: 3rem 0 1.5rem;
76
+ padding-bottom: 0.5rem;
77
+ border-bottom: 1px solid var(--carbon-gray-80);
78
+ }
79
+
80
+ h3 {
81
+ font-size: 1.125rem;
82
+ margin: 2rem 0 1rem;
83
+ color: var(--ibm-blue);
84
+ }
85
+
86
+ p { margin-bottom: 1rem; }
87
+
88
+ code {
89
+ font-family: 'IBM Plex Mono', monospace;
90
+ background: var(--carbon-gray-90);
91
+ padding: 0.2em 0.4em;
92
+ border-radius: 3px;
93
+ font-size: 0.875em;
94
+ }
95
+
96
+ pre {
97
+ background: var(--carbon-gray-90);
98
+ border: 1px solid var(--carbon-gray-80);
99
+ padding: 1.5rem;
100
+ overflow-x: auto;
101
+ margin: 1rem 0;
102
+ font-family: 'IBM Plex Mono', monospace;
103
+ font-size: 0.875rem;
104
+ line-height: 1.6;
105
+ }
106
+
107
+ table {
108
+ width: 100%;
109
+ border-collapse: collapse;
110
+ margin: 1rem 0;
111
+ }
112
+
113
+ th, td {
114
+ text-align: left;
115
+ padding: 0.75rem 1rem;
116
+ border-bottom: 1px solid var(--carbon-gray-80);
117
+ }
118
+
119
+ th {
120
+ background: var(--carbon-gray-90);
121
+ font-weight: 600;
122
+ }
123
+
124
+ tr:hover {
125
+ background: var(--carbon-gray-90);
126
+ }
127
+
128
+ .spec-grid {
129
+ display: grid;
130
+ grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
131
+ gap: 1rem;
132
+ margin: 1rem 0;
133
+ }
134
+
135
+ .spec-card {
136
+ background: var(--carbon-gray-90);
137
+ border: 1px solid var(--carbon-gray-80);
138
+ padding: 1.5rem;
139
+ }
140
+
141
+ .spec-card h4 {
142
+ font-size: 0.875rem;
143
+ color: var(--carbon-gray-50);
144
+ margin-bottom: 0.5rem;
145
+ text-transform: uppercase;
146
+ letter-spacing: 0.05em;
147
+ }
148
+
149
+ .spec-card .value {
150
+ font-size: 1.25rem;
151
+ font-weight: 600;
152
+ }
153
+
154
+ .badge {
155
+ display: inline-block;
156
+ background: var(--carbon-gray-80);
157
+ padding: 0.25rem 0.5rem;
158
+ border-radius: 2px;
159
+ font-size: 0.75rem;
160
+ margin-right: 0.5rem;
161
+ margin-bottom: 0.5rem;
162
+ }
163
+
164
+ .badge.blue { background: var(--ibm-blue); }
165
+ .badge.green { background: var(--green); }
166
+ .badge.purple { background: var(--purple); }
167
+
168
+ ul {
169
+ margin: 1rem 0;
170
+ padding-left: 1.5rem;
171
+ }
172
+
173
+ li { margin-bottom: 0.5rem; }
174
+
175
+ .callout {
176
+ background: var(--carbon-gray-90);
177
+ border-left: 4px solid var(--ibm-blue);
178
+ padding: 1rem 1.5rem;
179
+ margin: 1.5rem 0;
180
+ }
181
+
182
+ .callout.warning {
183
+ border-color: #f1c21b;
184
+ }
185
+
186
+ a { color: var(--ibm-blue); }
187
+ a:hover { text-decoration: none; }
188
+ </style>
189
+ </head>
190
+ <body>
191
+ <nav>
192
+ <a href="index.html">Home</a>
193
+ <a href="specs.html" class="active">Specifications</a>
194
+ <a href="https://github.com/PurpleSquirrelMedia/watsonx-mcp-server">GitHub</a>
195
+ </nav>
196
+
197
+ <div class="container">
198
+ <h1>Technical <span>Specifications</span></h1>
199
+ <p class="tagline">Complete documentation for the watsonx MCP Server integration</p>
200
+
201
+ <h2>System Overview</h2>
202
+
203
+ <div class="spec-grid">
204
+ <div class="spec-card">
205
+ <h4>Protocol</h4>
206
+ <div class="value">MCP 1.0</div>
207
+ <p style="font-size: 0.875rem; color: var(--carbon-gray-50); margin-top: 0.5rem;">Model Context Protocol</p>
208
+ </div>
209
+ <div class="spec-card">
210
+ <h4>Transport</h4>
211
+ <div class="value">stdio</div>
212
+ <p style="font-size: 0.875rem; color: var(--carbon-gray-50); margin-top: 0.5rem;">Standard I/O streams</p>
213
+ </div>
214
+ <div class="spec-card">
215
+ <h4>Runtime</h4>
216
+ <div class="value">Node.js 18+</div>
217
+ <p style="font-size: 0.875rem; color: var(--carbon-gray-50); margin-top: 0.5rem;">ES Modules</p>
218
+ </div>
219
+ <div class="spec-card">
220
+ <h4>Region</h4>
221
+ <div class="value">us-south</div>
222
+ <p style="font-size: 0.875rem; color: var(--carbon-gray-50); margin-top: 0.5rem;">Dallas, TX</p>
223
+ </div>
224
+ </div>
225
+
226
+ <h2>Architecture</h2>
227
+
228
+ <p>The watsonx MCP Server implements a <strong>two-agent architecture</strong> where Claude (Opus 4.5) acts as the primary reasoning agent and can delegate specific tasks to IBM watsonx.ai foundation models.</p>
229
+
230
+ <pre>
231
+ ┌─────────────────────────────────────────────────────────────────┐
232
+ │ CLIENT LAYER │
233
+ │ ┌─────────────────────────────────────────────────────────┐ │
234
+ │ │ Claude Code CLI / Desktop │ │
235
+ │ │ (Claude Opus 4.5) │ │
236
+ │ └───────────────────────┬─────────────────────────────────┘ │
237
+ └──────────────────────────│──────────────────────────────────────┘
238
+ │ MCP Protocol (JSON-RPC over stdio)
239
+ ▼
240
+ ┌─────────────────────────────────────────────────────────────────┐
241
+ │ MCP SERVER LAYER │
242
+ │ ┌─────────────────────────────────────────────────────────┐ │
243
+ │ │ watsonx-mcp-server (Node.js) │ │
244
+ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
245
+ │ │ │ generate │ │ chat │ │ embeddings │ │ │
246
+ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
247
+ │ └───────────────────────┬─────────────────────────────────┘ │
248
+ └──────────────────────────│──────────────────────────────────────┘
249
+ │ HTTPS + IAM Authentication
250
+ ▼
251
+ ┌─────────────────────────────────────────────────────────────────┐
252
+ │ IBM CLOUD LAYER │
253
+ │ ┌─────────────────────────────────────────────────────────┐ │
254
+ │ │ watsonx.ai (us-south.ml.cloud.ibm.com) │ │
255
+ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
256
+ │ │ │ Granite │ │ Llama 3 │ │ Mistral │ │ Slate │ │ │
257
+ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
258
+ │ └─────────────────────────────────────────────────────────┘ │
259
+ └─────────────────────────────────────────────────────────────────┘
260
+ </pre>
261
+
262
+ <h2>Tool Specifications</h2>
263
+
264
+ <h3>watsonx_generate</h3>
265
+ <p>Generate text completions using foundation models.</p>
266
+
267
+ <table>
268
+ <tr>
269
+ <th>Parameter</th>
270
+ <th>Type</th>
271
+ <th>Required</th>
272
+ <th>Default</th>
273
+ <th>Description</th>
274
+ </tr>
275
+ <tr>
276
+ <td><code>prompt</code></td>
277
+ <td>string</td>
278
+ <td>Yes</td>
279
+ <td>-</td>
280
+ <td>Input text prompt</td>
281
+ </tr>
282
+ <tr>
283
+ <td><code>model_id</code></td>
284
+ <td>string</td>
285
+ <td>No</td>
286
+ <td>ibm/granite-13b-chat-v2</td>
287
+ <td>Foundation model identifier</td>
288
+ </tr>
289
+ <tr>
290
+ <td><code>max_new_tokens</code></td>
291
+ <td>number</td>
292
+ <td>No</td>
293
+ <td>500</td>
294
+ <td>Maximum tokens to generate</td>
295
+ </tr>
296
+ <tr>
297
+ <td><code>temperature</code></td>
298
+ <td>number</td>
299
+ <td>No</td>
300
+ <td>0.7</td>
301
+ <td>Sampling temperature (0-2)</td>
302
+ </tr>
303
+ <tr>
304
+ <td><code>top_p</code></td>
305
+ <td>number</td>
306
+ <td>No</td>
307
+ <td>1.0</td>
308
+ <td>Nucleus sampling probability</td>
309
+ </tr>
310
+ <tr>
311
+ <td><code>top_k</code></td>
312
+ <td>number</td>
313
+ <td>No</td>
314
+ <td>50</td>
315
+ <td>Top-k sampling</td>
316
+ </tr>
317
+ </table>
318
+
319
+ <h3>watsonx_chat</h3>
320
+ <p>Multi-turn conversation with chat models.</p>
321
+
322
+ <table>
323
+ <tr>
324
+ <th>Parameter</th>
325
+ <th>Type</th>
326
+ <th>Required</th>
327
+ <th>Description</th>
328
+ </tr>
329
+ <tr>
330
+ <td><code>messages</code></td>
331
+ <td>array</td>
332
+ <td>Yes</td>
333
+ <td>Array of {role, content} objects</td>
334
+ </tr>
335
+ <tr>
336
+ <td><code>model_id</code></td>
337
+ <td>string</td>
338
+ <td>No</td>
339
+ <td>Chat model to use</td>
340
+ </tr>
341
+ <tr>
342
+ <td><code>max_new_tokens</code></td>
343
+ <td>number</td>
344
+ <td>No</td>
345
+ <td>Maximum response length</td>
346
+ </tr>
347
+ <tr>
348
+ <td><code>temperature</code></td>
349
+ <td>number</td>
350
+ <td>No</td>
351
+ <td>Response randomness</td>
352
+ </tr>
353
+ </table>
354
+
355
+ <p>Message roles:</p>
356
+ <ul>
357
+ <li><code>system</code> - System instructions</li>
358
+ <li><code>user</code> - User input</li>
359
+ <li><code>assistant</code> - Model response</li>
360
+ </ul>
361
+
362
+ <h3>watsonx_embeddings</h3>
363
+ <p>Generate vector embeddings for semantic search and RAG.</p>
364
+
365
+ <table>
366
+ <tr>
367
+ <th>Parameter</th>
368
+ <th>Type</th>
369
+ <th>Required</th>
370
+ <th>Description</th>
371
+ </tr>
372
+ <tr>
373
+ <td><code>texts</code></td>
374
+ <td>array[string]</td>
375
+ <td>Yes</td>
376
+ <td>Texts to embed</td>
377
+ </tr>
378
+ <tr>
379
+ <td><code>model_id</code></td>
380
+ <td>string</td>
381
+ <td>No</td>
382
+ <td>Embedding model (default: slate-125m)</td>
383
+ </tr>
384
+ </table>
385
+
386
+ <h3>watsonx_list_models</h3>
387
+ <p>List all available foundation models.</p>
388
+ <p>No parameters required. Returns array of model objects with id, name, provider, and tasks.</p>
389
+
390
+ <h2>Available Models</h2>
391
+
392
+ <h3>Text Generation Models</h3>
393
+ <table>
394
+ <tr>
395
+ <th>Model ID</th>
396
+ <th>Provider</th>
397
+ <th>Parameters</th>
398
+ <th>Use Case</th>
399
+ </tr>
400
+ <tr>
401
+ <td><code>ibm/granite-13b-chat-v2</code></td>
402
+ <td>IBM</td>
403
+ <td>13B</td>
404
+ <td>General chat, instruction following</td>
405
+ </tr>
406
+ <tr>
407
+ <td><code>ibm/granite-3-8b-instruct</code></td>
408
+ <td>IBM</td>
409
+ <td>8B</td>
410
+ <td>Latest Granite, fast inference</td>
411
+ </tr>
412
+ <tr>
413
+ <td><code>meta-llama/llama-3-70b-instruct</code></td>
414
+ <td>Meta</td>
415
+ <td>70B</td>
416
+ <td>Complex reasoning, high quality</td>
417
+ </tr>
418
+ <tr>
419
+ <td><code>meta-llama/llama-3-8b-instruct</code></td>
420
+ <td>Meta</td>
421
+ <td>8B</td>
422
+ <td>Fast, efficient generation</td>
423
+ </tr>
424
+ <tr>
425
+ <td><code>mistralai/mistral-large</code></td>
426
+ <td>Mistral AI</td>
427
+ <td>-</td>
428
+ <td>Multilingual, reasoning</td>
429
+ </tr>
430
+ <tr>
431
+ <td><code>mistralai/mixtral-8x7b-instruct-v01</code></td>
432
+ <td>Mistral AI</td>
433
+ <td>8x7B MoE</td>
434
+ <td>Efficient, high quality</td>
435
+ </tr>
436
+ </table>
437
+
438
+ <h3>Embedding Models</h3>
439
+ <table>
440
+ <tr>
441
+ <th>Model ID</th>
442
+ <th>Dimensions</th>
443
+ <th>Use Case</th>
444
+ </tr>
445
+ <tr>
446
+ <td><code>ibm/slate-125m-english-rtrvr</code></td>
447
+ <td>768</td>
448
+ <td>English semantic search, RAG</td>
449
+ </tr>
450
+ <tr>
451
+ <td><code>ibm/slate-30m-english-rtrvr</code></td>
452
+ <td>384</td>
453
+ <td>Lightweight embedding</td>
454
+ </tr>
455
+ </table>
456
+
457
+ <h2>Configuration</h2>
458
+
459
+ <h3>Environment Variables</h3>
460
+ <table>
461
+ <tr>
462
+ <th>Variable</th>
463
+ <th>Required</th>
464
+ <th>Description</th>
465
+ </tr>
466
+ <tr>
467
+ <td><code>WATSONX_API_KEY</code></td>
468
+ <td>Yes</td>
469
+ <td>IBM Cloud API key</td>
470
+ </tr>
471
+ <tr>
472
+ <td><code>WATSONX_URL</code></td>
473
+ <td>No</td>
474
+ <td>Service URL (default: us-south)</td>
475
+ </tr>
476
+ <tr>
477
+ <td><code>WATSONX_PROJECT_ID</code></td>
478
+ <td>No</td>
479
+ <td>Project ID for scoped operations</td>
480
+ </tr>
481
+ </table>
482
+
483
+ <h3>Claude Code Configuration</h3>
484
+ <pre>
485
+ // ~/.claude.json
486
+ {
487
+ "mcpServers": {
488
+ "watsonx": {
489
+ "type": "stdio",
490
+ "command": "node",
491
+ "args": ["/path/to/watsonx-mcp-server/index.js"],
492
+ "env": {
493
+ "WATSONX_API_KEY": "your-api-key",
494
+ "WATSONX_URL": "https://us-south.ml.cloud.ibm.com"
495
+ }
496
+ }
497
+ }
498
+ }
499
+ </pre>
500
+
501
+ <h2>Dependencies</h2>
502
+
503
+ <table>
504
+ <tr>
505
+ <th>Package</th>
506
+ <th>Version</th>
507
+ <th>Purpose</th>
508
+ </tr>
509
+ <tr>
510
+ <td><code>@modelcontextprotocol/sdk</code></td>
511
+ <td>^1.24.3</td>
512
+ <td>MCP server framework</td>
513
+ </tr>
514
+ <tr>
515
+ <td><code>@ibm-cloud/watsonx-ai</code></td>
516
+ <td>^1.7.5</td>
517
+ <td>IBM watsonx.ai SDK</td>
518
+ </tr>
519
+ <tr>
520
+ <td><code>ibm-cloud-sdk-core</code></td>
521
+ <td>^5.4.5</td>
522
+ <td>IAM authentication</td>
523
+ </tr>
524
+ </table>
525
+
526
+ <h2>Use Cases</h2>
527
+
528
+ <div class="callout">
529
+ <strong>When to delegate to watsonx:</strong>
530
+ <ul style="margin-top: 0.5rem;">
531
+ <li>IBM-specific model capabilities (Granite enterprise features)</li>
532
+ <li>Batch inference on large datasets</li>
533
+ <li>Embedding generation for RAG pipelines</li>
534
+ <li>Cost optimization with smaller models</li>
535
+ <li>Regulatory compliance requiring IBM infrastructure</li>
536
+ </ul>
537
+ </div>
538
+
539
+ <h3>Example: RAG Pipeline</h3>
540
+ <pre>
541
+ // 1. Generate embeddings with watsonx
542
+ User: "Embed these documents for search"
543
+ Claude: [calls watsonx_embeddings with document texts]
544
+
545
+ // 2. Store in vector database
546
+ // 3. Query with user question embedding
547
+ // 4. Claude synthesizes final answer
548
+ </pre>
549
+
550
+ <h3>Example: Multi-Model Reasoning</h3>
551
+ <pre>
552
+ // Claude handles complex reasoning
553
+ // Delegates specific tasks to specialized models
554
+
555
+ User: "Analyze this legal document"
556
+
557
+ Claude (Opus 4.5):
558
+ → Understands context, plans analysis
559
+ → Calls watsonx_generate with Granite for compliance check
560
+ → Synthesizes results with own analysis
561
+ </pre>
562
+
563
+ <h2>Free Tier Limits</h2>
564
+
565
+ <div class="callout warning">
566
+ <strong>watsonx.ai Lite Plan:</strong>
567
+ <ul style="margin-top: 0.5rem;">
568
+ <li>Limited inference tokens per month</li>
569
+ <li>Access to select foundation models</li>
570
+ <li>Single user/project</li>
571
+ <li>No SLA guarantees</li>
572
+ </ul>
573
+ </div>
574
+
575
+ <h2>Error Handling</h2>
576
+
577
+ <p>The server returns structured error messages:</p>
578
+ <pre>
579
+ {
580
+ "content": [{
581
+ "type": "text",
582
+ "text": "Error calling watsonx.ai: [error message]"
583
+ }]
584
+ }
585
+ </pre>
586
+
587
+ <p>Common errors:</p>
588
+ <ul>
589
+ <li><code>401 Unauthorized</code> - Invalid API key</li>
590
+ <li><code>403 Forbidden</code> - Insufficient permissions</li>
591
+ <li><code>429 Too Many Requests</code> - Rate limit exceeded</li>
592
+ <li><code>Model not found</code> - Invalid model_id</li>
593
+ </ul>
594
+
595
+ <h2>Security</h2>
596
+
597
+ <ul>
598
+ <li>API keys stored in environment variables, not code</li>
599
+ <li>IAM token-based authentication</li>
600
+ <li>All traffic over HTTPS</li>
601
+ <li>No data persistence in MCP server</li>
602
+ </ul>
603
+
604
+ <hr style="margin: 3rem 0; border: none; border-top: 1px solid var(--carbon-gray-80);">
605
+
606
+ <p style="text-align: center; color: var(--carbon-gray-50);">
607
+ <a href="https://github.com/PurpleSquirrelMedia/watsonx-mcp-server">View Source</a> |
608
+ <a href="https://www.ibm.com/watsonx">IBM watsonx.ai</a> |
609
+ <a href="https://modelcontextprotocol.io">MCP Protocol</a>
610
+ </p>
611
+ </div>
612
+ </body>
613
+ </html>