@sassoftware/sas-score-mcp-serverjs 1.0.1-8 → 1.1.1

package/.skills/.claude-plugin/plugin.json

@@ -0,0 +1,59 @@
+{
+  "name": "sas-score-mcp-serverjs",
+  "displayName": "SAS Viya Score MCP",
+  "version": "0.0.6",
+  "description": "Skills, agent, and MCP server for reading and scoring data via SAS Viya",
+  "author": {
+    "name": "Deva Kumar",
+    "email": "deva.kumar@sas.com"
+  },
+  "repository": "https://github.com/sassoftware/sas-score-mcp-serverjs",
+  "license": "Apache-2.0",
+  "keywords": [
+    "sas",
+    "viya",
+    "scoring",
+    "mcp",
+    "analytics"
+  ],
+  "skills": "./skills/",
+  "agents": [
+    "./agents/sas-score-mcp-serverjs-agent.md"
+  ],
+  "mcpServers": {
+    "sas-score-mcp-serverjs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@sassoftware/sas-score-mcp-serverjs"
+      ],
+      "env": {
+        "VIYA_SERVER": "${VIYA_SERVER}",
+        "AUTHFLOW": "${AUTHFLOW:-sascli}",
+        "CLIENTID": "${CLIENTID:-vscodemcp}",
+        "AGENT": "${AGENT:-TRUE}"
+      }
+    }
+  },
+  "userConfig": {
+    "VIYA_SERVER": {
+      "type": "string",
+      "title": "SAS Viya server URL",
+      "description": "Base URL of your SAS Viya server, e.g. https://my-viya.example.com",
+      "required": true
+    },
+    "AUTHFLOW": {
+      "type": "string",
+      "title": "Auth flow",
+      "description": "Authentication flow: oauth, code, sascli, token, or bearer",
+      "default": "sascli"
+    },
+
+      "AGENT": {
+        "type": "string",
+        "title": "Agent mode",
+        "description": "If TRUE, the skills must be deployed",
+        "default": "TRUE"
+      }
+    }
+  }

package/.skills/agents/sas-score-mcp-serverjs-agent.md

@@ -0,0 +1,26 @@
+---
+name: sas-score-mcp-serverjs-agent
+description: >
+  Unified orchestration agent for scoring in SAS Viya.
+  Follow the canonical SKILL at [skills/request-routing/SKILL.md](skills/request-routing/SKILL.md).
+---
+
+# SAS Viya Unified Router
+
+**Default Agent Mode**: Use the request-routing strategy for all requests.
+
+Agent defaults
+- Append the **Strategy Summary** to every response.
+
+Behavior (high-level)
+- Classification → Verification → Execution → Formatting (Strategy Summary appended).
+- For Read+Score flows, follow the SKILL's Combined Read+Score steps.
+
+Implementation checklist (agent-level)
+- Classify request and consult SKILL for decision-making.
+- Invoke find-* tools for verification
+- Call execution tools mapped in the SKILL.
+- Surface errors verbatim and ask targeted clarification questions when needed.
+
+See the canonical router for the full mapping, rules, examples, and Strategy Summary template: [skills/request-routing/SKILL.md](skills/request-routing/SKILL.md)
+

package/.skills/copilot-instructions.md

@@ -0,0 +1,62 @@
+# GitHub Copilot — SAS Viya (concise agent guide)
+
+This file is a short, agent-facing reference. It delegates routing and detailed decision logic to the canonical SKILLs in the `skills/` folder (especially `skills/request-routing/SKILL.md`). Keep this file minimal — use the SKILLs for examples and edge cases.
+
+**Core principle (single sentence):** Verify resources, execute with the mapped tool, and format results.
+
+## Canonical workflow
+- Verify: confirm resources exist using `find-*` tools 
+- Execute: call the execution tool mapped by the router (read/query/score/describe/list).
+- Format: merge outputs, present results, and append a short Strategy Summary.
+
+Note: the five-step phrasing (Identify → Verify → Select → Execute → Format) maps to the same implementation; prefer the three-step mental model when implementing.
+
+## Agent defaults
+- Default model type: MAS (unless user specifies `.job`, `.jobdef`, `.scr`, `.sas`, or `.casl`).
+- Append a **Strategy Summary** to every response.
+- Always determine table server (CAS vs SAS) during verification; ask if ambiguous.
+- Do not invent resource names, servers, or model types — verify or ask.
+- Pagination: always pass `start=1` and `limit=10` when calling any tool that accepts these parameters, unless the user specifies different values.
+
+## Model types
+All of the following are treated as **models** that can be scored:
+- **MAS** (`.mas`) — Micro Analytic Score: `sas-score-mas-score`
+- **SCR** (`.scr`) — Score Code Runtime: `sas-score-scr-score`
+- **Job** (`.job`) — SAS Viya Job model: `sas-score-job-score`
+- **JobDef** (`.jobdef`) — SAS Viya Job Definition model: `sas-score-jobdef-score`
+- **Program** (`.sas`) — SAS Program model: `sas-score-program-score`
+- **CAS Program** (`.casl`) — CASL Program model: `sas-score-cas-program-score`
+- **Macro** — SAS macro by name: `sas-score-macro-score`
+
+## Canonical tool mappings (short)
+- Find: `sas-score-find-library`, `sas-score-find-table`, `sas-score-find-mas`, `sas-score-find-job`, `sas-score-find-jobdef`
+- Read / Query: `sas-score-read-table`, `sas-score-sas-query`
+- Score models: `sas-score-mas-score`, `sas-score-scr-score`, `sas-score-job-score`, `sas-score-jobdef-score`, `sas-score-program-score`, `sas-score-cas-program-score`, `sas-score-macro-score`
+- List: `sas-score-list-libraries`, `sas-score-list-tables`, `sas-score-list-mas`, `sas-score-list-jobs`, `sas-score-list-jobdefs`
+- Detail: `sas-score-mas-describe`, `sas-score-job-describe`, `sas-score-jobdef-describe`, `sas-score-scr-describe`, `sas-score-table-describe`
+
+## Strategy Summary (append to replies)
+---
+**Strategy Summary:**
+- **Classification**: [Find / Read / Score / List / Describe]
+- **Verification**: [Resources verified / skipped]
+- **Tool(s)**: [Primary tool(s) invoked]
+- **Decision**: [Server chosen, model type, mapping]
+- **Next steps**: [Follow-ups or clarifications]
+
+## When to ask a clarification (one focused question)
+- Missing or ambiguous resource name
+- Model type not specified (`.mas` / `.job` / `.jobdef` / `.scr` / `.sas` / `.casl`)
+- Table library or server not specified
+- Column-to-model-input mapping is unclear
+
+## References
+- Canonical router, examples, and Strategy Summary template: `skills/request-routing/SKILL.md`
+- Find/verify resources: `skills/find-resources/SKILL.md`
+- List/browse resources: `skills/list-resource/SKILL.md`
+- Read/query data: `skills/read-strategy/SKILL.md`
+- Scoring workflows: `skills/score-strategy/SKILL.md`
+- Describe/detail resources: `skills/detail-strategy/SKILL.md`
+- Decision trees (machine-readable): `decision-trees/`
+
+Keep this file short. Use the SKILLs for decision trees, examples, and edge-case rules.

package/.skills/skills/README.md

@@ -0,0 +1,204 @@
+# SAS Viya Unified Strategy - Quick Reference
+
+This folder contains simplified, consolidated strategies for working with SAS Viya through the MCP server.
+
+> **Claude Code Plugin**: The parent `.skills/` directory is a Claude Code plugin. See [Plugin Usage](#plugin-usage) at the bottom of this file for installation instructions.
+
+## Files
+
+### Core Strategies
+
+1. **request-routing** — Universal three-step workflow
+   - Step 1: Verify resources exist
+   - Step 2: Execute the request
+   - Step 3: Merge results
+
+2. **find-library-server** — Library existence and server verification
+   - Verifies a library exists in CAS or SAS
+   - Returns confirmed `{ lib, server }` pair
+   - Called by find-resources and list-tables before any library-scoped operation
+
+3. **find-resources** — Resource verification strategy
+   - How to find/verify libraries, tables, models, jobs, jobdefs
+   - Delegates library checks to find-library-server
+   - Server determination logic
+
+3. **list-library** — List SAS Viya libraries
+   - Calls sas-score-list-libraries with server parameter
+
+4. **list-tables** — List tables in a library
+   - Verifies library exists (CAS first, then SAS) before listing
+   - Passes confirmed lib and server to sas-score-list-tables
+
+5. **list-mas-job-jobdef** — List MAS models, Jobs, and JobDefs
+   - Routes to sas-score-list-mas, sas-score-list-jobs, or sas-score-list-jobdefs
+
+6. **read-strategy** — Data reading strategy
+   - Raw row reads (sas-score-read-table)
+   - Analytical queries (sas-score-sas-query)
+   - Decision tree for choosing the right tool
+
+7. **score-strategy** — Scoring workflow
+   - All model types: MAS, SCR, Job, JobDef, Program, CAS Program
+   - Inline scenarios vs table rows
+   - Result formatting and merging
+
+### Agent
+
+8. **sas-score-mcp-serverjs-agent** — Main agent instructions
+   - Orchestration logic
+   - Decision trees
+   - Implementation checklist
+
+---
+
+## Key Principles
+
+### 1. Three-Step Workflow (Always)
+
+Every request follows the same pattern:
+```
+Verify → Execute → Format
+```
+
+### 2. No Ambiguity
+
+- Clear classification of request type
+- Explicit server determination for tables (CAS vs SAS)
+- Explicit model type determination (MAS / SCR / Job / JobDef / Program / CAS Program)
+
+### 3. Verification Before Execution
+
+Always verify resources exist before executing (except SCR which has no pre-check).
+
+### 4. Simplified Tool Mapping
+
+| Resource | Tool |
+|---|---|
+| Find library | sas-score-find-library |
+| Find table | sas-score-find-table |
+| Find model (MAS) | sas-score-find-mas |
+| Find job | sas-score-find-job |
+| Find jobdef | sas-score-find-jobdef |
+| Read table | sas-score-read-table |
+| Query table | sas-score-sas-query |
+| Score (MAS) | sas-score-mas-score |
+| Score (SCR) | sas-score-scr-score |
+| Score (Job model) | sas-score-job-score |
+| Score (JobDef model) | sas-score-jobdef-score |
+| Score (Program model) | sas-score-program-score |
+| Score (CAS Program model) | sas-score-cas-program-score |
+
+---
+
+## Using These Strategies
+
+1. **Start with request-routing** to understand the three-step workflow
+2. **Use find-resources** when verifying resources
+3. **Use read-strategy** when reading data
+4. **Use score-strategy** when scoring/predicting
+5. **Reference agent sas-score-mcp-serverjs-agent.md** for orchestration
+
+---
+
+## Why Simplified?
+
+The original `.skills` folder had multiple overlapping strategies that caused confusion:
+- Multiple ways to find the same resource
+- Unclear when to use read vs query
+- Ambiguous model type inference
+- Complex decision trees
+
+This simplified system:
+- **One way to find each resource** (not multiple smart strategies)
+- **Clear read vs query decision** (raw rows vs aggregations)
+- **Explicit model type handling** (default MAS, allow .job/.jobdef/.scr suffixes)
+- **Consistent three-step workflow** (verify → execute → format)
+
+---
+
+## Migration Path
+
+If you were using the old `.skills` folder:
+
+| Old Skill | New Location |
+|---|---|
+| sas-find-resources-strategy | FIND-RESOURCE.md |
+| sas-list-resource-strategy (libraries) | list-library/SKILL.md |
+| sas-list-resource-strategy (tables) | list-tables/SKILL.md |
+| sas-list-resource-strategy (models/jobs) | list-mas-job-jobdef/SKILL.md |
+| sas-find-library-smart | FIND-RESOURCE.md (library section) |
+| sas-list-tables-smart | READ-STRATEGY.md + list-tables tool |
+| sas-read-strategy | READ-STRATEGY.md |
+| sas-read-and-score-strategy | SCORE-STRATEGY.md (Option B) |
+| sas-score-workflow-strategy | SCORE-STRATEGY.md |
+| sas-request-classifier | REQUEST-ROUTING.md (classification section) |
+
+---
+
+## Questions?
+
+Each strategy file has detailed examples, decision trees, and error handling guidance. Start with the strategy that matches your request type.
+
+---
+
+## Plugin Usage
+
+The `.skills/` directory (one level up from here) is a Claude Code plugin. It bundles these skills, the agent instructions, and the MCP server configuration.
+
+### Plugin structure
+
+```
+.skills/
+├── .claude-plugin/plugin.json   ← plugin manifest
+├── .mcp.json                    ← MCP server config (stdio, npx)
+├── agents/
+│   └── sas-score-mcp-serverjs-agent.md
+└── skills/
+    ├── request-routing/SKILL.md
+    ├── find-library-server/SKILL.md
+    ├── find-resources/SKILL.md
+    ├── list-library/SKILL.md
+    ├── list-tables/SKILL.md
+    ├── list-mas-job-jobdef/SKILL.md
+    ├── read-strategy/SKILL.md
+    ├── score-strategy/SKILL.md
+    └── detail-strategy/SKILL.md
+```
+
+### Install (after npm install)
+
+```bash
+# Point Claude Code at the plugin directory inside the installed package
+/plugin install ./node_modules/@sassoftware/sas-score-mcp-serverjs/.skills
+
+# Or from the git repo directly
+/plugin install https://github.com/sassoftware/sas-score-mcp-serverjs --subdir .skills
+```
+
+### Required environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `VIYA_SERVER` | *(required)* | SAS Viya server URL, e.g. `https://my-viya.example.com` |
+| `AUTHFLOW` | `oauth` | Auth flow: `oauth`, `code`, `sascli`, `token`, `bearer` |
+| `CLIENTID` | `vscodemcp` | OAuth client ID registered on the Viya server |
+| `CASSERVER` | `cas-shared-default` | CAS server name |
+| `COMPUTECONTEXT` | `SAS Job Execution compute context` | Compute context name |
+
+Set these in your shell or a `.env` file before starting Claude Code.
+
+### HTTP transport (remote/production deployments)
+
+The default `.mcp.json` uses stdio (local npx). For a remotely deployed server (e.g. Docker on Azure), replace the entry in `.mcp.json` with:
+
+```json
+{
+  "mcpServers": {
+    "sas-score-mcp-serverjs": {
+      "type": "http",
+      "url": "https://<your-deployed-host>/mcp"
+    }
+  }
+}
+```

package/.skills/skills/detail-strategy/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: detail-strategy
+description: >
+  Use this strategy when the user requests information about a resource. This is a  
+  Unified detail/information/describe retrieval strategy. Handles MAS models, Job models, JobDef models, SCR models, and tables. Verify resources exist using find-resources skill before retrieving details 
+---
+
+# Detail Strategy
+
+Use this strategy when the user requests information about a resource.
+
+**Supported resource types**: MAS model, Job model, JobDef model, SCR model,  or table.
+
+If the specified resource is ambiguous, ask the user for clarification (e.g. "Are you asking about a MAS model, a Job model, a JobDef model, a SCR model or a table?").
+
+**Model**: If user just says "model X" without specifying type, default to MAS model (this is an explicit exception to the 'never invent' rule, but it is a predefined convention in SAS).
+
+Verification rules
+- Always verify the target resource exists using the appropriate `find-*` tool before attempting retrieval, except for SCR models (see Exceptions below).
+- For tables, determine server (CAS vs SAS) during verification; if ambiguous, ask the user for the full `lib.table` or server.
+- For models, strip suffixes such as `.mas`, `.job`, `.jobdef`,`.scr`, `.cas`,  before lookup to avoid lookup failures.
+
+Defaults & exceptions
+- Default model type: MAS when the user says `model X` without specifying a type.
+- If verification fails, inform the user and ask for corrected or more specific identifiers.
+
+---
+
+## Classification & Verification Process
+
+### Phase 1: Classify the Resource Type
+
+Determine resource type from context/naming conventions.
+
+**Dotted `a.b` notation rule**: parse `b` to determine type. If `b` is not in `{mas, job, jobdef, scr, sas, casl}`, treat `a.b` as a table where lib=`a`, table=`b`.
+
+| Pattern                  | Resource Type |
+|--------------------------|---------------|
+| `X.mas` or `mas X` or `mas model X` | MAS model, name=X |
+| `X.job` or `job X` or `job model X` | Job model, name=X |
+| `X.jobdef` or `jobdef X` or `jobdef model X` | JobDef model, name=X |
+| `X.scr` or `scr X` or `scr model X` | SCR model, name=X |
+| `a.b` where b ∉ {mas,job,jobdef,scr,sas,casl} | **Table**: lib=a, name=b |
+| `table X in library Y`   | Table X in library Y |
+| `model X` (no suffix)    | Default to MAS model (explicit convention) |
+
+If resource is ambiguous, ask user for clarification.
+
+### Phase 2: Verify Resource Exists 
+
+**IMPORTANT**: Strip the suffix if user included it, use base name for lookup (e.g. "churnRisk.mas" → "churnRisk") to avoid lookup failures.
+
+Use find-resources skill to verify the resource exists
+
+If verification fails, inform the user and ask for additional details or corrections.
+
+---
+
+
+### Phase 3: Get Details
+
+### Option A: MAS Model Details
+
+**Trigger phrases**: "what inputs does mas model X need", "describe mas X", "show variables for model mas X, describe X.mas",
+"mas model X metadata", "mas model X information", "describe model X" (default to MAS),
+"what inputs does mas X need", "describe mas X"
+
+**Tool**: `sas-score-mas-describe`
+
+**Parameters**:
+```
+
+sas-score-mas-describe({
+  model: "<model name>"
+})
+```
+
+**Returns**:
+- Input variables (name, type, role)
+- Output variables (name, type, possible_values)
+- Model type
+- Description
+
+**Example**:
+```
+User: "What inputs does mas model churnRisk need?"
+
+1. Find: sas-score-find-mas({ name: "churnRisk" })
+2. Get info: sas-score-mas-describe({ model: "churnRisk" })
+3. Return: { inputs: [...], outputs: [...], description: "..." }
+```
+
+---
+
+### Option B: SCR Model Details
+
+**Trigger phrases**: "what does SCR model X need", "describe SCR model X", "scr model X inputs",
+"scr model X schema", "what inputs does scr model X need", "describe scr X"
+
+**Tool**: `sas-score-scr-describe`
+
+**Parameters**:
+```
+sas-score-scr-describe({
+  name: "<scr model name>"
+})
+```
+
+**Returns**:
+- Input schema (variable names, types, required/optional)
+- Output schema (prediction, probabilities, scores)
+- Model metadata
+
+**Example**:
+```
+User: "Show inputs for SCR model loan"
+
+1. Get info: sas-score-scr-describe({ name: "loan" })
+2. Return: { inputs: [...], outputs: [...] }
+```
+
+**Note**: SCR models do not require pre-verification (call scr-describe directly with the model name)
+
+---
+
+### Option C: Table Details
+
+**Trigger phrases**: "what columns in table X", "describe table X", "show schema for table X", "table X structure", "table X metadata"
+
+**Tool**: `sas-score-table-describe`
+
+**Parameters**:
+```
+sas-score-table-describe({
+  lib: "<library>",
+  table: "<table name>",
+  server: "<cas|sas>"
+})
+```
+
+**Returns**:
+- Columns array (name, type, label, format, length)
+- Table info (rowCount, fileSize, created, modified)
+
+**Example**:
+```
+User: "What columns are in the customers table in Public?"
+
+1. Find: sas-score-find-table({ lib: "Public", name: "customers", server: "cas" })
+2. Get info: sas-score-table-describe({ lib: "Public", table: "customers", server: "cas" })
+3. Return: { columns: [...], tableDescribe: {...} }
+```
+
+---
+### Option D: Job Model Details
+
+**Trigger phrases**: "what inputs does job model X need", "describe job model X",
+"show variables for job model X", "job model X metadata", "job model X information",
+"what inputs does job X need", "describe job X"
+
+**Tool**: `sas-score-job-describe`
+
+**Parameters**:
+```
+sas-score-job-describe({
+  name: "<model name>"
+})
+```
+
+**Returns**:
+- Input variables (name, type, role)
+
+**Example**:
+```
+User: "What inputs does job model churnRisk need?"
+
+1. Find: use find-resources skill to job exists
+2. Get Details: sas-score-job-describe({ name: "churnRisk" })
+3. Return: { inputs: [...] }
+```
+
+### Option E: JobDef Model Details
+
+**Trigger phrases**: "what inputs does jobdef model X need", "describe jobdef model X",
+"jobdef model X metadata", "what inputs does jobdef X need", "describe jobdef X"
+
+**Tool**: `sas-score-jobdef-describe` 
+
+**Parameters**:
+```
+sas-score-jobdef-describe({
+  name: "<jobdef name>"
+})
+```
+
+**Example**:
+```
+User: "What inputs does jobdef model myScorer need?"
+
+1. Find: sas-score-find-jobdef({ name: "myScorer" })
+2. Get info: sas-score-jobdef-describe({ name: "myScorer" })
+3. Return: { inputs: [...] }
+```
+
+---
+
+### Option F: SAS Program Model Details
+
+SAS programs are treated as models — they accept parameters via `scenario` and produce scored outputs.
+
+**Trigger phrases**: "describe sas program X", "what parameters does program X take",
+"program model X info", "describe X.sas"
+
+**Note**: SAS programs do not have a dedicated `describe` tool. If the program is wrapped in a Job, use `sas-score-job-describe`. Otherwise ask the user for parameter documentation.
+
+---
+
+
+## Decision Tree
+
+```
+User requests information/details
+  ├─ About a MAS model?
+  │   → Verify: sas-score-find-mas
+  │   → Call: sas-score-mas-describe
+  │
+  ├─ About a SCR model?
+  │   → Call: sas-score-scr-describe (skip verification; use name directly)
+  │
+  ├─ About a Job model?
+  │   → Verify: sas-score-find-job
+  │   → Call: sas-score-job-describe
+  │
+  ├─ About a JobDef model?
+  │   → Verify: sas-score-find-jobdef
+  │   → Call: sas-score-jobdef-describe
+  │
+  └─ About a table?
+      → Verify: sas-score-find-table (determine CAS or SAS server)
+      → Call: sas-score-table-describe
+```
+
+---
+
+## Implementation Checklist
+
+For each detail/information request:
+
+- [ ] **Classify** resource type (MAS / Job / JobDef / SCR / table)
+- [ ] **Verify** resource exists (use find-resources skill, except SCR)
+- [ ] **Determine** server for tables (CAS or SAS)
+- [ ] **Execute** appropriate detail tool
+- [ ] **Format** results (column alignment, readable structure)
+- [ ] **Append** Strategy Summary to response
+
+---
+
+## Response Format
+
+Always append a **Strategy Summary** to responses (canonical template from `request-routing/SKILL.md`):
+
+```
+---
+**Strategy Summary:**
+- **Classification**: [Find / Read / Score / List / Describe]
+- **Verification**: [Resources verified / skipped]
+- **Tool(s)**: [Primary tool(s) invoked]
+- **Decision**: [Server chosen, model type, mapping]
+- **Next steps**: [Follow-ups or clarifications]
+```
+
+---
+
+## Error Recovery
+
+If a request fails:
+
+1. **Resource not found** → Ask user to verify name/spelling
+2. **Server mismatch** → Re-verify server location with find-resources
+3. **Invalid name (SCR)** → Ask for correct SCR model name
+4. **Tool error** → Return error message verbatim and ask for clarification
+
+---
+
+## Examples
+
+### Example 1: Model Information
+
+**User**: "Describe model creditScore"
+
+**Workflow**:
+1. Classify: MAS model detail request
+2. Verify: Find model creditScore → Found ✓
+3. Execute: `sas-score-mas-describe({ model: "creditScore" })`
+4. Return: Model inputs, outputs, and description
+
+### Example 2: SCR Model Schema
+
+**User**: "What inputs does the SCR loan model need?"
+
+**Workflow**:
+1. Classify: SCR model detail request
+2. Execute: `sas-score-scr-describe({ name: "loan" })`
+3. Return: Input schema and output schema
+
+### Example 3: Table Columns
+
+**User**: "Show columns for customers in Public"
+
+**Workflow**:
+1. Classify: Table detail request
+2. Verify:  verify table exists with find-resources skill
+3. Execute: `sas-score-table-describe({ lib: "Public", table: "customers", server: "$server" })` where $server is determined from verification step
+4. Return: Column names, types, and table metadata
+
+