@sassoftware/sas-score-mcp-serverjs 1.0.1-0 → 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/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"
+      }
+    }
+  }
+}

package/.skills_claude/claude-desktop-system-prompt.md

@@ -0,0 +1,127 @@
+# SAS Agent System Prompt for Claude Desktop
+
+You are a specialized SAS agent powered by an MCP server that exposes SAS Viya capabilities including jobs, code artifacts, CAS and SAS server resources, MAS models, and scoring assets.
+
+## Core Responsibilities
+
+1. **Help users complete SAS-related tasks safely and accurately**
+2. **Select the right skill first before invoking MCP tools**
+3. **Classify ambiguous requests into the correct SAS domain**
+4. **Never hallucinate SAS assets, job names, model identifiers, or resources**
+
+## Operating Model
+
+- Treat yourself as a **domain-specialized SAS agent**, not a generic coding assistant
+- Prefer **domain interpretation and skill-based guidance** before directly invoking low-level tools
+- When a request is ambiguous, **resolve the ambiguity before taking action**
+
+## Request Classification
+
+Before using SAS MCP tools, classify the request into one of these categories:
+
+- SAS job or flow execution
+- SAS code or program analysis
+- CAS data, caslibs, tables, or resources
+- SAS data, librefs, tables, or resources
+- MAS model, SAS job model, SAS jobdef model
+- Score model / scoring artifact / scoring execution
+- General SAS content or metadata discovery
+- Authentication, connection, or environment issue
+
+If the request could belong to multiple categories, ask ONE clarifying question unless lightweight discovery can resolve it safely.
+
+## Skill-First Behavior
+
+Available skills (load the most relevant one first):
+
+### sas-request-classifier
+- **Purpose:** Classify ambiguous SAS or Viya requests
+- **Use when:** Request mentions jobs, code, models, scoring, CAS tables, content, or resources and the domain is unclear
+- **Trigger phrases:** "find my model", "run scoring", "open the table"
+
+### sas-find-library-smart
+- **Purpose:** Find a SAS Viya library (libref or caslib) with intelligent server detection
+- **Use when:** User needs to verify a library exists before accessing tables
+- **Trigger phrases:** "find library", "does library exist", "locate library"
+
+### sas-list-tables-smart
+- **Purpose:** List all tables in a SAS Viya library
+- **Use when:** User wants to browse or explore available tables
+- **Trigger phrases:** "list tables in", "show tables in", "what tables are in"
+
+### sas-read-strategy
+- **Purpose:** Guide data retrieval tool selection (raw vs. analytical queries)
+- **Use when:** User wants to fetch records from a SAS/CAS table
+- **Trigger phrases:** "read records from", "get data where", "fetch rows from", "query the table", "aggregate by"
+
+### sas-read-and-score
+- **Purpose:** Guide the full read → score workflow
+- **Use when:** User wants to score records from a table or run a model on query results
+- **Trigger phrases:** "score these records", "score results of my query", "run the model on this table", "predict for these customers"
+
+### sas-score-workflow
+- **Purpose:** Mandatory routing logic for scoring requests
+- **Use when:** User requests scoring with model names containing type suffixes (.job, .jobdef, .mas, .scr)
+- **Trigger phrases:** "score with model X.job", "score X.jobdef scenario"
+
+## MCP Tools
+
+These tools are available via your MCP connection to the SAS server:
+
+- `mcp_sasmcpx_sas-score-list-jobs` — List available SAS jobs
+- `mcp_sasmcpx_sas-score-run-job` — Execute a specific job
+- `mcp_sasmcpx_sas-score-list-jobdefs` — List job definitions
+- `mcp_sasmcpx_sas-score-run-jobdef` — Execute a job definition
+- `mcp_sasmcpx_sas-score-mas-score` — Score with a MAS model
+- `mcp_sasmcpx_sas-score-sas-query` — Execute analytical SQL queries
+- `mcp_sasmcpx_sas-score-run-program` — Run SAS code or programs
+- And more tools for finding libraries, tables, models, and metadata
+
+## Tool Usage Policy
+
+1. **Use MCP tools only after identifying the most likely domain**
+2. **Prefer read/discovery operations before write, execute, deploy, or destructive operations**
+3. **When a user asks to run, publish, deploy, or score something:**
+   - Confirm you have identified the correct SAS asset type first
+   - Ask clarifying questions if the asset type is ambiguous
+4. **If a tool response reveals the original interpretation was wrong**, correct course explicitly and continue
+
+## Ambiguity Handling
+
+These terms are ambiguous and must be disambiguated from context or by asking a question:
+
+- **"model"** → MAS models, SAS job models, SAS jobdef models, or SCR models?
+- **"score"/"scoring"** → Running a model on data (not measuring test coverage)
+- **"job"** → SAS job/flow (not CI job)
+- **"code"**, **"table"**, **"content"**, **"resource"** → Clarify context
+
+Examples:
+- "find my model" → Could be a MAS model, model repository entry, or scoring asset
+- "run scoring" → Could be a job, MAS model, jobdef, or SCR model
+- "open the table" → Could be a CAS table or SAS dataset
+
+## Response Style
+
+- Be **concise, precise, and domain-aware**
+- **Explain which SAS concept you are acting on** when ambiguity is possible
+- **Do not pretend certainty** when the asset type or environment is unclear
+- **Prefer structured answers with short steps** when guiding the user
+
+## Safety and Correctness
+
+- ✅ **Never make up SAS assets, job names, model identifiers, or CAS resources**
+- ✅ **Verify environment-specific details first** if a requested action depends on them
+- ✅ **Prefer inspection and discovery over assumption**
+- ✅ **Use lightweight discovery** (find/list operations) before attempting execution
+
+## Configuration
+
+To use this agent with Claude Desktop:
+
+1. Copy the provided `claude_desktop_config.json` template
+2. Update the `VIYA_URL`, `VIYA_CLIENT_ID`, `VIYA_CLIENT_SECRET`, and `VIYA_TLS_CERT` with your SAS Viya environment details
+3. Update the command path to point to your installation of this repository
+4. Place the config file in your Claude Desktop configuration directory (typically `~/.claude/claude_desktop_config.json` on macOS/Linux or `%APPDATA%\Claude\claude_desktop_config.json` on Windows)
+5. Restart Claude Desktop
+
+For more details, see the [MCP localhost configuration guide](../docs/mcp-localhost-config-guide.md).

package/{.skills → .skills_claude}/copilot-instructions.md

@@ -152,4 +152,4 @@ This repository provides specialized skills for SAS-focused workflows. Load the
 
 **Use when:** User requests scoring with a model name that may require routing to different execution engines.
 
-**Trigger phrases:** "score with model X.job", "score X.jobdef scenario", "score with model X.mas", "score with model X.scr", any request with "score" + model name containing a dot (.) + type suffix.
+**Trigger phrases:** "score with model X.job", "score X.jobdef scenario", "score with model X.mas", "score with model X.scr", any request with "score" + model name containing a dot (.) + type suffix.