@purplesquirrel/watsonx-mcp-server 1.0.0

package/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "chore(deps)"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "github-actions"
+    commit-message:
+      prefix: "chore(ci)"

package/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run linter
+        run: npm run lint --if-present
+
+      - name: Run tests
+        run: npm test --if-present
+
+      - name: Build
+        run: npm run build --if-present

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Purple Squirrel Media
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,245 @@
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io)
+[![watsonx](https://img.shields.io/badge/IBM-watsonx-052FAD)](https://www.ibm.com/watsonx)
+[![CI](https://github.com/PurpleSquirrelMedia/watsonx-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/PurpleSquirrelMedia/watsonx-mcp-server/actions/workflows/ci.yml)
+
+# watsonx MCP Server
+
+MCP server for IBM watsonx.ai integration with Claude Code. Enables Claude to delegate tasks to IBM's foundation models (Granite, Llama, Mistral, etc.).
+
+## Features
+
+- **Text Generation** - Generate text using watsonx.ai foundation models
+- **Chat** - Have conversations with watsonx.ai chat models
+- **Embeddings** - Generate text embeddings
+- **Model Listing** - List all available foundation models
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `watsonx_generate` | Generate text using watsonx.ai models |
+| `watsonx_chat` | Chat with watsonx.ai models |
+| `watsonx_embeddings` | Generate text embeddings |
+| `watsonx_list_models` | List available models |
+
+## Setup
+
+### 1. Install Dependencies
+
+```bash
+cd ~/watsonx-mcp-server
+npm install
+```
+
+### 2. Configure Environment
+
+Set these environment variables:
+
+```bash
+WATSONX_API_KEY=your-ibm-cloud-api-key
+WATSONX_URL=https://us-south.ml.cloud.ibm.com
+WATSONX_SPACE_ID=your-deployment-space-id  # Recommended: deployment space
+WATSONX_PROJECT_ID=your-project-id          # Alternative: project ID
+```
+
+**Note**: Either `WATSONX_SPACE_ID` or `WATSONX_PROJECT_ID` is required for text generation, embeddings, and chat. Deployment spaces are recommended as they have Watson Machine Learning (WML) pre-configured.
+
+### 3. Add to Claude Code
+
+The MCP server is already configured in `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "watsonx": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/Users/matthewkarsten/watsonx-mcp-server/index.js"],
+      "env": {
+        "WATSONX_API_KEY": "your-api-key",
+        "WATSONX_URL": "https://us-south.ml.cloud.ibm.com",
+        "WATSONX_SPACE_ID": "your-deployment-space-id"
+      }
+    }
+  }
+}
+```
+
+## Usage
+
+Once configured, Claude can use watsonx.ai tools:
+
+```
+User: Use watsonx to generate a haiku about coding
+
+Claude: [Uses watsonx_generate tool]
+Result: Code flows like water
+       Bugs arise, then disappear
+       Programs come alive
+```
+
+## Available Models
+
+Some notable models available:
+
+- `ibm/granite-3-3-8b-instruct` - IBM Granite 3.3 8B (recommended)
+- `ibm/granite-13b-chat-v2` - IBM Granite chat model
+- `ibm/granite-3-8b-instruct` - Granite 3 instruct model
+- `meta-llama/llama-3-70b-instruct` - Meta's Llama 3 70B
+- `mistralai/mistral-large` - Mistral AI large model
+- `ibm/slate-125m-english-rtrvr-v2` - Embedding model
+
+Use `watsonx_list_models` to see all available models.
+
+## Architecture
+
+```
+Claude Code (Opus 4.5)
+         │
+         └──▶ watsonx MCP Server
+                    │
+                    └──▶ IBM watsonx.ai API
+                              │
+                              ├── Granite Models
+                              ├── Llama Models
+                              ├── Mistral Models
+                              └── Embedding Models
+```
+
+## Two-Agent System
+
+This enables a two-agent architecture where:
+
+1. **Claude (Opus 4.5)** - Primary reasoning agent, handles complex tasks
+2. **watsonx.ai** - Secondary agent for specific workloads
+
+Claude can delegate tasks to watsonx.ai when:
+- IBM-specific model capabilities are needed
+- Running batch inference on enterprise data
+- Using specialized Granite models
+- Generating embeddings for RAG pipelines
+
+## IBM Cloud Resources
+
+This MCP server uses:
+- **Service**: watsonx.ai Studio (data-science-experience)
+- **Plan**: Lite (free tier)
+- **Region**: us-south
+
+Create your own watsonx.ai project and deployment space in IBM Cloud.
+
+## Integration with IBM Z MCP Server
+
+This watsonx MCP server works alongside the IBM Z MCP server:
+
+```
+Claude Code (Opus 4.5)
+         │
+         ├──▶ watsonx MCP Server
+         │         └── Text generation, embeddings, chat
+         │
+         └──▶ ibmz MCP Server
+                   └── Key Protect HSM, z/OS Connect
+```
+
+Demo scripts in the ibmz-mcp-server:
+- `demo-full-stack.js` - Full 5-service pipeline
+- `demo-rag.js` - RAG with watsonx embeddings + Granite
+
+## Document Analyzer
+
+The document analyzer (`document-analyzer.js`) provides powerful tools for analyzing your external drive data using watsonx.ai:
+
+### Commands
+
+```bash
+# View document catalog (9,168 documents)
+node document-analyzer.js catalog
+
+# Summarize a document
+node document-analyzer.js summarize 1002519.txt
+
+# Analyze document type, topics, entities
+node document-analyzer.js analyze 1002519.txt
+
+# Ask questions about a document
+node document-analyzer.js question 1002519.txt 'What AWS credentials are needed?'
+
+# Generate embeddings for documents
+node document-analyzer.js embed
+
+# Semantic search across documents
+node document-analyzer.js search 'IBM Cloud infrastructure'
+```
+
+### Features
+
+- **Summarization**: Generate concise summaries of any document
+- **Analysis**: Extract document type, topics, entities, and sentiment
+- **Q&A**: Ask natural language questions about document content
+- **Embeddings**: Generate 768-dimensional vectors for semantic search
+- **Semantic Search**: Find similar documents using vector similarity
+
+### Demo
+
+Run the full demo:
+```bash
+./demo-external-drive.sh
+```
+
+## Embedding Index & RAG
+
+The `embedding-index.js` tool provides semantic search and RAG (Retrieval Augmented Generation):
+
+```bash
+# Build an embedding index (50 documents)
+node embedding-index.js build 50
+
+# Semantic search
+node embedding-index.js search 'cloud infrastructure'
+
+# RAG query - retrieves relevant docs and generates answer
+node embedding-index.js rag 'How do I set up AWS for Satellite?'
+
+# Show index statistics
+node embedding-index.js stats
+```
+
+## Batch Processor
+
+The `batch-processor.js` tool processes multiple documents at once:
+
+```bash
+# Classify documents into categories
+node batch-processor.js classify 20
+
+# Extract topics from documents
+node batch-processor.js topics 15
+
+# Generate one-line summaries
+node batch-processor.js summarize 10
+
+# Full analysis (classify + topics + summary)
+node batch-processor.js full 10
+```
+
+Categories: technical, business, creative, personal, code, legal, marketing, educational, other
+
+## Files
+
+- `index.js` - MCP server implementation
+- `document-analyzer.js` - Document analysis CLI tool
+- `embedding-index.js` - Embedding index and RAG tool
+- `batch-processor.js` - Batch document processor
+- `demo-external-drive.sh` - Demo script
+- `package.json` - Dependencies
+- `README.md` - This file
+
+## Author
+
+Matthew Karsten
+
+## License
+
+MIT

package/TROUBLESHOOTING.md

@@ -0,0 +1,176 @@
+# Troubleshooting Guide
+
+Common issues and solutions for the watsonx MCP Server.
+
+## Authentication Errors
+
+### `WATSONX_API_KEY not set`
+
+**Cause**: The API key environment variable is missing or empty.
+
+**Solution**:
+```bash
+# Set your IBM Cloud API key
+export WATSONX_API_KEY="your-ibm-cloud-api-key"
+
+# Or add to your Claude Code MCP config in ~/.claude.json
+```
+
+### `401 Unauthorized`
+
+**Cause**: Invalid or expired API key.
+
+**Solutions**:
+1. Verify your API key is correct in IBM Cloud console
+2. Generate a new API key if expired
+3. Ensure the API key has access to watsonx.ai services
+
+### `403 Forbidden`
+
+**Cause**: API key lacks permissions for watsonx.ai.
+
+**Solutions**:
+1. Check IAM permissions in IBM Cloud
+2. Ensure your account has watsonx.ai service enabled
+3. Verify the API key is associated with the correct account
+
+## Configuration Errors
+
+### `Space ID or Project ID required`
+
+**Cause**: Neither `WATSONX_SPACE_ID` nor `WATSONX_PROJECT_ID` is set.
+
+**Solution**:
+```bash
+# Use a deployment space (recommended)
+export WATSONX_SPACE_ID="your-deployment-space-id"
+
+# OR use a project
+export WATSONX_PROJECT_ID="your-project-id"
+```
+
+**Finding your Space/Project ID**:
+1. Go to [IBM watsonx.ai](https://dataplatform.cloud.ibm.com)
+2. Open your deployment space or project
+3. Go to Settings/Manage tab
+4. Copy the Space ID or Project ID
+
+### `Invalid region URL`
+
+**Cause**: `WATSONX_URL` points to wrong region or is malformed.
+
+**Valid regions**:
+```bash
+# US South (Dallas)
+WATSONX_URL=https://us-south.ml.cloud.ibm.com
+
+# EU Germany (Frankfurt)
+WATSONX_URL=https://eu-de.ml.cloud.ibm.com
+
+# EU Great Britain (London)
+WATSONX_URL=https://eu-gb.ml.cloud.ibm.com
+
+# Asia Pacific (Tokyo)
+WATSONX_URL=https://jp-tok.ml.cloud.ibm.com
+```
+
+## Model Errors
+
+### `Model not found`
+
+**Cause**: The specified model ID doesn't exist or isn't available.
+
+**Solution**:
+1. Use `watsonx_list_models` to see available models
+2. Check model ID spelling (case-sensitive)
+3. Some models require specific deployment space types
+
+**Common model IDs**:
+- `ibm/granite-3-3-8b-instruct`
+- `ibm/granite-13b-chat-v2`
+- `meta-llama/llama-3-70b-instruct`
+- `mistralai/mistral-large`
+
+### `Token limit exceeded`
+
+**Cause**: Input or output exceeds model's maximum token limit.
+
+**Solutions**:
+1. Reduce input text length
+2. Set `max_new_tokens` to a lower value
+3. Use a model with higher token limits
+
+**Token limits by model**:
+| Model | Max Input | Max Output |
+|-------|-----------|------------|
+| granite-3-3-8b-instruct | 8192 | 8192 |
+| granite-13b-chat-v2 | 8192 | 4096 |
+| llama-3-70b-instruct | 8192 | 4096 |
+
+## Connection Errors
+
+### `ECONNREFUSED` or `ETIMEDOUT`
+
+**Cause**: Cannot reach IBM Cloud endpoints.
+
+**Solutions**:
+1. Check internet connectivity
+2. Verify no firewall blocking IBM Cloud IPs
+3. Check IBM Cloud status page for outages
+4. Try a different region endpoint
+
+### `Rate limit exceeded`
+
+**Cause**: Too many API requests in a short period.
+
+**Solutions**:
+1. Add delays between requests
+2. Implement exponential backoff
+3. Check your service plan limits
+4. Upgrade to higher tier if needed
+
+## MCP Server Errors
+
+### Server not appearing in Claude Code
+
+**Solutions**:
+1. Verify `~/.claude.json` syntax is valid JSON
+2. Check the path to `index.js` is correct
+3. Restart Claude Code after config changes
+4. Check server logs: `node /path/to/index.js`
+
+### `Cannot find module` errors
+
+**Cause**: Dependencies not installed.
+
+**Solution**:
+```bash
+cd ~/watsonx-mcp-server
+npm install
+```
+
+## Debugging
+
+### Enable verbose logging
+
+```bash
+# Run server directly to see errors
+node /Users/matthewkarsten/watsonx-mcp-server/index.js
+
+# Check for syntax errors
+node --check /Users/matthewkarsten/watsonx-mcp-server/index.js
+```
+
+### Test API connection
+
+```bash
+# Test with curl
+curl -X GET "https://us-south.ml.cloud.ibm.com/ml/v1/foundation_model_specs?version=2024-01-01" \
+  -H "Authorization: Bearer $(ibmcloud iam oauth-tokens | grep IAM | awk '{print $4}')"
+```
+
+## Getting Help
+
+- [IBM watsonx.ai Documentation](https://cloud.ibm.com/docs/watsonx-ai)
+- [IBM Cloud Status](https://cloud.ibm.com/status)
+- [GitHub Issues](https://github.com/PurpleSquirrelMedia/watsonx-mcp-server/issues)