watsonx-mcp-server 1.0.1

package/README.md

@@ -0,0 +1,240 @@
+# 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)