@sassoftware/sas-score-mcp-serverjs 1.0.1-2 → 1.0.1-3

package/.skills_claude/README.md

@@ -0,0 +1,303 @@
+# Claude Desktop — SAS Agent Setup & Deployment Guide
+
+This guide explains how to set up the SAS agent in Claude Desktop using the `.claude` folder.
+
+## What's Included
+
+The `.claude` folder contains:
+- ✅ Complete SAS agent configuration (same as `.github/` but organized for Claude)
+- ✅ All 6 specialized SAS skills
+- ✅ MCP server configuration template
+- ✅ System prompt for Claude Desktop
+- ✅ Setup and usage documentation
+
+## Prerequisites
+
+Before you start:
+- ✅ Claude Desktop installed (latest version recommended)
+- ✅ Node.js installed and in your PATH
+- ✅ SAS Viya environment with OAuth credentials
+- ✅ Access to your SAS Viya server from your machine
+- ✅ (Optional) CA certificate file if using self-signed TLS
+
+## Setup Steps
+
+### Step 1: Gather Your SAS Viya Credentials
+
+You'll need:
+- **VIYA_URL** — Your SAS Viya server URL (e.g., `https://sas-viya.example.com`)
+- **VIYA_CLIENT_ID** — OAuth client ID
+- **VIYA_CLIENT_SECRET** — OAuth client secret
+- **VIYA_TLS_CERT** — (Optional) Path to CA certificate file
+
+### Step 2: Configure the MCP Server Connection
+
+1. Open `.claude/claude-desktop-config.json`
+2. Update the configuration with your credentials:
+
+```json
+{
+  "mcpServers": {
+    "sas-mcp-server": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/7-skill-integration/cli.js"
+      ],
+      "env": {
+        "VIYA_URL": "https://your-sas-viya-url.com",
+        "VIYA_CLIENT_ID": "your-client-id",
+        "VIYA_CLIENT_SECRET": "your-client-secret",
+        "VIYA_TLS_CERT": "/path/to/ca-cert.pem"
+      }
+    }
+  }
+}
+```
+
+**Important notes:**
+- Use **absolute paths** for both the CLI path and certificate
+- Ensure the path to `cli.js` is correct for your system
+- Include the leading `/` for Unix/Mac paths; for Windows, use `C:\path\to\...`
+
+### Step 3: Place Configuration in Claude Desktop Directory
+
+Copy the updated `claude_desktop_config.json` to your Claude Desktop config location:
+
+**macOS/Linux:**
+```bash
+cp /path/to/7-skill-integration/.claude/claude-desktop-config.json ~/.claude/claude_desktop_config.json
+```
+
+**Windows:**
+```powershell
+Copy-Item "C:\path\to\7-skill-integration\.claude\claude-desktop-config.json" "$env:APPDATA\Claude\claude_desktop_config.json"
+```
+
+**Note:** If you have other MCP servers configured, merge the `mcpServers` sections instead of replacing the entire file.
+
+### Step 4: Add System Prompt to Claude
+
+1. Open **Claude Desktop**
+2. Go to **Settings** → **Custom Instructions**
+3. Open `.claude/claude-desktop-system-prompt.md`
+4. Copy the entire contents
+5. Paste into the custom instructions field in Claude
+6. Save
+
+### Step 5: Restart Claude Desktop
+
+Restart Claude Desktop to activate the new configuration and system prompt.
+
+## Verification
+
+After setup, verify the connection works:
+
+1. Start a chat with Claude
+2. Ask: **"list jobs"**
+3. You should see available SAS jobs from your Viya environment
+4. If successful, the MCP connection is working ✅
+
+## Configuration Details
+
+### MCP Server Configuration (claude-desktop-config.json)
+
+The configuration tells Claude Desktop how to:
+- Start the SAS MCP server (using Node.js)
+- Connect to your SAS Viya environment
+- Pass credentials securely
+
+**Key fields:**
+- `command` — The Node.js interpreter
+- `args` — Path to the MCP server CLI
+- `env` — Environment variables for authentication and TLS
+
+### System Prompt (claude-desktop-system-prompt.md)
+
+The system prompt instructs Claude to:
+- Treat itself as a SAS domain specialist
+- Load skills before using MCP tools
+- Classify ambiguous SAS terms
+- Verify assets before execution
+- Never hallucinate SAS resources
+
+## Using the SAS Agent
+
+Once configured, you can start using the agent:
+
+### Basic Commands
+
+```
+You: "Find library Public"
+Agent: Loads sas-find-library-smart skill, checks CAS and SAS, returns result
+
+You: "List tables in Public"
+Agent: Loads sas-list-tables-smart skill, enumerates tables
+
+You: "Score customers in Public.customers with model churn.mas"
+Agent: Loads sas-read-and-score + sas-score-workflow, returns predictions
+```
+
+### Available Skills
+
+See `skills-index.md` for quick reference, or each skill's file for details:
+
+1. **sas-request-classifier** — Disambiguate SAS terms
+2. **sas-find-library-smart** — Find CAS or SAS libraries
+3. **sas-list-tables-smart** — List tables in a library
+4. **sas-read-strategy** — Choose right read tool (raw vs. analytical)
+5. **sas-read-and-score** — Read table data + score with model
+6. **sas-score-workflow** — Route scoring by model type (.job, .mas, etc.)
+
+## Troubleshooting
+
+### "MCP Server Not Found"
+
+**Symptom:** Claude says the MCP server can't be found.
+
+**Solutions:**
+1. Verify the path to `cli.js` is absolute and correct
+2. Check that Node.js is installed: `node --version`
+3. Ensure Node.js is in your PATH: `which node` (Mac/Linux) or `where node` (Windows)
+4. Restart Claude Desktop
+5. Check the file permissions on `cli.js`
+
+### "Authentication Failed"
+
+**Symptom:** Claude connects but SAS operations fail with auth errors.
+
+**Solutions:**
+1. Verify `VIYA_CLIENT_ID` and `VIYA_CLIENT_SECRET` are correct
+2. Ensure credentials are still valid (check if they've expired)
+3. Verify `VIYA_URL` is accessible from your machine: `curl https://your-viya-url`
+4. Check network connectivity and firewall rules
+5. If using a proxy, configure it in your environment
+
+### "TLS Certificate Error"
+
+**Symptom:** SSL/certificate verification fails.
+
+**Solutions:**
+1. Verify the path in `VIYA_TLS_CERT` is correct and absolute
+2. Ensure the certificate file is readable
+3. If using self-signed cert, try `VIYA_TLS_SKIP_VERIFY=true` (development only, not recommended for production)
+4. Request the correct CA certificate from your SAS administrator
+
+### "No Tools Available"
+
+**Symptom:** Claude says no SAS tools are available.
+
+**Solutions:**
+1. Restart Claude Desktop
+2. Check the MCP server logs for errors
+3. Verify the SAS Viya server is running and accessible
+4. Try a simple test: ask "list jobs"
+5. Check your custom instructions are loaded correctly
+
+### "Claude Doesn't Load Skills"
+
+**Symptom:** Claude doesn't automatically load the right skill for your request.
+
+**Solutions:**
+1. Explicitly reference the skill: "Use sas-find-library-smart to find library Public"
+2. Check that `claude-desktop-system-prompt.md` is loaded in custom instructions
+3. Restart Claude Desktop to reload the system prompt
+4. Verify the skill files exist in `.claude/skills/`
+
+## Advanced Configuration
+
+### Using Multiple MCP Servers
+
+If you have other MCP servers configured:
+
+```json
+{
+  "mcpServers": {
+    "sas-mcp-server": {
+      "command": "node",
+      "args": ["/path/to/cli.js"],
+      "env": { ... }
+    },
+    "other-server": {
+      "command": "...",
+      "args": [...],
+      "env": { ... }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+You can also set environment variables system-wide instead of in the config:
+
+```bash
+export VIYA_URL="https://your-sas-viya.com"
+export VIYA_CLIENT_ID="your-client-id"
+export VIYA_CLIENT_SECRET="your-client-secret"
+export VIYA_TLS_CERT="/path/to/ca-cert.pem"
+```
+
+Then simplify the config to just reference `cli.js`.
+
+### Debugging
+
+To debug MCP server issues, check:
+1. Claude Desktop logs: `~/Library/Logs/Claude Desktop` (Mac) or `%APPDATA%\Claude\logs` (Windows)
+2. MCP server output: Check if there are error messages from Node.js
+3. Test the CLI directly: `node /path/to/cli.js`
+
+## File Structure Reference
+
+```
+.claude/
+├── copilot-instructions.md              ← Core SAS instructions
+├── claude-desktop-system-prompt.md      ← Claude Desktop prompt
+├── claude-desktop-config.json           ← MCP config (customize this)
+├── README.md                             ← This file
+├── instructions.md                      ← Usage instructions
+├── skills-index.md                      ← Skills quick reference
+├── agents/
+│   └── sas-viya-scoring-expert.md       ← Agent definition
+└── skills/
+    ├── sas-request-classifier/SKILL.md
+    ├── sas-find-library-smart/SKILL.md
+    ├── sas-list-tables-smart/SKILL.md
+    ├── sas-read-and-score/SKILL.md
+    ├── sas-read-strategy/SKILL.md
+    └── sas-score-workflow/SKILL.md
+```
+
+## Deployment
+
+### Local Development
+
+For local development:
+1. Keep the `.claude` folder in the repository
+2. Update `claude-desktop-config.json` locally (don't commit credentials)
+3. Share setup steps with team members
+
+### Production Deployment
+
+For production use:
+1. Store credentials in environment variables, not in config file
+2. Use a secrets management system for OAuth credentials
+3. Commit only the `.claude` template without sensitive data
+4. Have users configure their own credentials locally
+
+## Support & Documentation
+
+- **Setup issues?** See "Troubleshooting" above
+- **Want to use a skill?** Open `.claude/skills-index.md`
+- **Need usage guidance?** See `.claude/instructions.md`
+- **SAS domain details?** See `.claude/copilot-instructions.md`
+- **Skill specifics?** Open the skill's file directly: `.claude/skills/<name>/SKILL.md`
+
+## Next Steps
+
+1. ✅ Complete the setup steps above
+2. ✅ Verify the connection ("list jobs" test)
+3. ✅ Read `instructions.md` for how to use the agent
+4. ✅ Try a simple task: "Find library Public"
+5. ✅ Explore skills: See `skills-index.md`
+
+Happy SAS Viya scoring! 🎯

package/.skills_claude/TESTING_GUIDE.md

@@ -0,0 +1,252 @@
+# Testing Guide: Local Claude Desktop Setup
+
+This guide explains how to test the SAS agent locally by placing configuration in your home directory (`~/.claude/`).
+
+## Quick Start
+
+### 1. Create the `.claude` directory in your home folder
+
+```bash
+mkdir -p ~/.claude
+```
+
+### 2. Copy the configuration file
+
+```bash
+cp /path/to/7-skill-integration/.claude/claude-desktop-config.json ~/.claude/
+```
+
+### 3. Edit the configuration with your credentials
+
+```bash
+nano ~/.claude/claude-desktop-config.json
+```
+
+Update the following fields with your SAS Viya environment details:
+
+```json
+{
+  "mcpServers": {
+    "sas-mcp-server": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/7-skill-integration/cli.js"
+      ],
+      "env": {
+        "VIYA_URL": "https://your-sas-viya.com",
+        "VIYA_CLIENT_ID": "your-client-id",
+        "VIYA_CLIENT_SECRET": "your-client-secret",
+        "VIYA_TLS_CERT": "/path/to/ca-cert.pem"
+      }
+    }
+  }
+}
+```
+
+**Important:**
+- Use the **absolute path** to `cli.js` in your repository
+- Include the leading `/` for Unix/Mac paths; for Windows, use `C:\path\to\...`
+
+### 4. Add the system prompt to Claude Desktop
+
+1. Open **Claude Desktop**
+2. Go to **Settings** → **Custom Instructions**
+3. Open `.claude/claude-desktop-system-prompt.md` from the repository
+4. Copy the entire contents
+5. Paste into the custom instructions field
+6. Save
+
+### 5. Restart Claude Desktop
+
+Close and reopen Claude Desktop to load the new configuration and system prompt.
+
+### 6. Test the connection
+
+In a chat with Claude, ask:
+
+```
+list jobs
+```
+
+You should see a list of available SAS jobs from your Viya environment. If successful, the MCP connection is working! ✅
+
+---
+
+## What Files Go Where?
+
+### Files that must go in `~/.claude/`:
+- ✅ `claude-desktop-config.json` — **Required** for MCP server connection
+
+### Files that don't need to be copied:
+- ❌ Skills files — They live in the repository and are referenced in documentation
+- ❌ Agent definitions — Documentation only
+- ❌ Skill markdown files — For reference, not needed for execution
+
+### System prompt:
+- **Option A** — Copy `claude-desktop-system-prompt.md` contents to Claude Desktop Settings → Custom Instructions (recommended)
+- **Option B** — Keep it in the repository and reference it
+
+---
+
+## Directory Structure After Setup
+
+Your home directory will look like this:
+
+```
+~/
+├── .claude/
+│   └── claude-desktop-config.json    ← Your configuration
+├── ... (other home directory files)
+```
+
+The repository stays intact:
+
+```
+/path/to/7-skill-integration/
+├── .claude/
+│   ├── README.md
+│   ├── instructions.md
+│   ├── skills-index.md
+│   ├── copilot-instructions.md
+│   ├── claude-desktop-system-prompt.md
+│   ├── claude-desktop-config.json    ← Template (not modified)
+│   ├── agents/
+│   └── skills/
+├── cli.js
+├── ... (other repo files)
+```
+
+---
+
+## How It Works
+
+1. Claude Desktop reads `~/.claude/claude-desktop-config.json`
+2. It starts the MCP server (Node.js process running `cli.js`)
+3. The MCP server connects to your SAS Viya environment using the credentials you provided
+4. Claude loads the system prompt from custom instructions
+5. You can now use the SAS agent with all skills available
+
+The repository's `.claude/` folder serves as the **template and documentation** — it doesn't need to be in your home directory.
+
+---
+
+## Troubleshooting
+
+### "MCP Server Not Found"
+
+**Check:**
+1. Verify the path to `cli.js` is absolute and correct
+2. Test Node.js is available: `node --version`
+3. Verify the file exists: `ls -la /path/to/cli.js`
+4. Restart Claude Desktop
+
+**Solution:**
+```bash
+# Verify the path works
+node /absolute/path/to/7-skill-integration/cli.js --help
+```
+
+### "Authentication Failed"
+
+**Check:**
+1. Verify credentials in `~/.claude/claude-desktop-config.json`
+2. Ensure SAS Viya is accessible: `curl https://your-viya-url`
+3. Verify credentials are still valid
+
+### "No SAS Tools Available"
+
+**Check:**
+1. System prompt is loaded in Claude Custom Instructions
+2. Restart Claude Desktop after adding the system prompt
+3. Try a simple test: "list jobs"
+
+---
+
+## Testing Different Configurations
+
+### Test with a local development environment:
+
+```json
+{
+  "mcpServers": {
+    "sas-mcp-server": {
+      "command": "node",
+      "args": ["/Users/yourname/projects/7-skill-integration/cli.js"],
+      "env": {
+        "VIYA_URL": "http://localhost:7480",
+        "VIYA_CLIENT_ID": "dev-client",
+        "VIYA_CLIENT_SECRET": "dev-secret"
+      }
+    }
+  }
+}
+```
+
+### Test with production environment:
+
+```json
+{
+  "mcpServers": {
+    "sas-mcp-server": {
+      "command": "node",
+      "args": ["/opt/7-skill-integration/cli.js"],
+      "env": {
+        "VIYA_URL": "https://sas-viya-prod.company.com",
+        "VIYA_CLIENT_ID": "prod-client-id",
+        "VIYA_CLIENT_SECRET": "prod-client-secret",
+        "VIYA_TLS_CERT": "/etc/ssl/certs/company-ca.pem"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Next Steps After Testing
+
+### If testing is successful:
+1. Document your setup
+2. Share the setup steps with your team (without credentials)
+3. Consider using environment variables instead of config file for production
+4. Document any team-specific customizations
+
+### If testing fails:
+1. Check troubleshooting section above
+2. Review MCP server logs
+3. Verify SAS Viya environment is accessible
+4. Check credentials are correct and current
+
+---
+
+## Important Notes
+
+### Security
+
+- ⚠️ **Never commit credentials** to version control
+- ⚠️ **Never share** your `~/.claude/claude-desktop-config.json` file
+- ✅ Use environment variables for sensitive data when possible
+- ✅ Use a secrets management system for team deployments
+
+### Paths
+
+- ✅ Use absolute paths (starting with `/` or `C:\`)
+- ❌ Don't use relative paths like `./cli.js`
+- ❌ Don't use `~` in the config file (Claude Desktop may not expand it correctly)
+
+### File Permissions
+
+Ensure the config file is readable:
+
+```bash
+chmod 600 ~/.claude/claude-desktop-config.json
+```
+
+---
+
+## Support
+
+- **Setup questions?** See the main `README.md` in `.claude/`
+- **How to use the agent?** See `instructions.md` in `.claude/`
+- **Which skill to use?** See `skills-index.md` in `.claude/`
+- **Domain guidance?** See `copilot-instructions.md` in `.claude/`

package/.skills_claude/agents/sas-viya-scoring-expert.md

@@ -0,0 +1,58 @@
+---
+name: SAS Viya Scoring Expert
+description: Specialized SAS and Viya agent that classifies requests, selects the right SAS skill, and uses MCP tools safely for jobs, CAS data, libraries, models, scoring, and content workflows.
+---
+
+# SAS Viya Scoring Expert
+
+You are a SAS Viya expert agent.
+
+Your job is to help users work with SAS and Viya resources through the SAS MCP server.
+Treat requests as domain-specific SAS tasks, not generic coding tasks.
+
+## Default behavior
+Before using MCP tools:
+- Determine whether the request is about jobs, code, CAS data, libraries, models, scoring, content, or environment issues.
+- If the request includes ambiguous terms such as model, score, scoring, read, query, job, code, table, content, asset, or resource, classify the request before acting.
+- Prefer loading the most relevant SAS skill before using low-level tools.
+- If confidence is low, ask one focused clarifying question.
+- Prefer discovery and inspection before execution, publish, scoring, deploy, write, or destructive actions.
+
+## Skill-first policy
+Use skills as the primary source of SAS workflow guidance.
+Load one or more relevant SAS skills before using tools when the request is ambiguous, cross-domain, or execution-oriented.
+Do not load unrelated skills.
+
+## Routing policy
+When a request is ambiguous or could map to more than one SAS domain:
+- Start with classification.
+- Identify the most likely SAS asset or workflow type.
+- Choose the best matching SAS skill.
+- Only then select MCP tools.
+
+## Ambiguity policy
+These terms are overloaded in SAS and Viya workflows and should not be interpreted casually:
+- model
+- score
+- scoring
+- read
+- query
+- job
+- code
+- table
+- content
+- asset
+- resource
+
+If the meaning is unclear, ask one targeted clarifying question or use discovery-oriented skills before any execution step.
+
+## Tool usage policy
+- Prefer read-only discovery before execution.
+- Confirm the target asset type before running jobs, scoring data, publishing models, or modifying content.
+- If tool results contradict the initial interpretation, correct course explicitly and continue.
+- Never invent asset names, identifiers, libraries, or model types.
+
+## Response style
+Be concise, explicit, and domain-aware.
+State which SAS concept or asset type you are acting on when ambiguity is possible.
+Prefer short structured answers when guiding the user.

package/.skills_claude/claude-desktop-config.json

@@ -0,0 +1,16 @@
+{
+  "mcpServers": {
+    "sas-mcp-server": {
+      "command": "node",
+      "args": [
+        "/path/to/7-skill-integration/cli.js"
+      ],
+      "env": {
+        "VIYA_URL": "https://your-sas-viya-url.com",
+        "VIYA_CLIENT_ID": "your-client-id",
+        "VIYA_CLIENT_SECRET": "your-client-secret",
+        "VIYA_TLS_CERT": "/path/to/ca-cert.pem"
+      }
+    }
+  }
+}