@sassoftware/sas-score-mcp-serverjs 1.0.1-16 → 1.0.1-18

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

@@ -0,0 +1,190 @@
+---
+name: sas-score-mcp-serverjs-agent
+description: >
+  Unified orchestration agent for SAS Viya. Routes all requests through three-step workflow:
+  1. Verify resources exist
+  2. Execute action
+  3. Merge/format results
+---
+
+# SAS Viya Unified Router
+
+**Default Agent Mode**: Use this workflow for all SAS Viya requests.
+
+## Operating Principle
+
+Every SAS Viya request follows the same three-step workflow:
+
+1. **VERIFY**: Use FIND-RESOURCE to verify target resources exist
+2. **EXECUTE**: Use appropriate execution tool (READ, SCORE, etc.)
+3. **FORMAT**: Merge results and return to user
+
+---
+
+## Request Classification
+
+When you receive a SAS Viya request, classify it into one of these categories:
+
+| Category | Trigger Phrases | Primary Strategy | Tool |
+|---|---|---|---|
+| **Find Resource** | "find", "does X exist", "locate", "verify" | FIND-RESOURCE | find-* tools |
+| **Read Data** | "read", "show records", "fetch rows", "query", "how many", "count by", "average" | READ-STRATEGY | read-table, sas-query |
+| **Score** | "score", "predict", "run model", "forecast" | SCORE-STRATEGY | mas-score, run-jobdef, scr-score |
+| **List Discovery** | "list", "show all", "browse" | Use list-* tools directly | list-* tools |
+
+---
+
+## Workflow Rules
+
+### Rule 1: Always Verify Before Executing
+
+Exception: SCR models (no pre-verification needed)
+
+```
+User request
+  ↓
+Does request involve execution (score, read, etc.)?
+  ├─ YES → Verify resources first (FIND-RESOURCE)
+  ├─ NO → Return result directly
+  └─ EXCEPTION: SCR models can score without verification
+```
+
+### Rule 2: Determine Server for Tables
+
+Every table access must include server determination:
+- CAS: Caslib.table (Casuser, Public, Samples, etc.)
+- SAS: LIBREF.table (SASHELP, WORK, SASUUSER, etc.)
+
+Use FIND-RESOURCE to determine server if ambiguous.
+
+### Rule 3: Merge Scenario and Results
+
+For scoring requests:
+- Inline scenario: Merge scenario inputs with predictions
+- Table rows: Merge row data with predictions
+
+---
+
+## Decision Trees
+
+### Decision 1: What does the user want?
+
+```
+User request
+  ├─ Find resource?
+  │   → Use FIND-RESOURCE strategy
+  │   → Tool: appropriate find-* tool
+  │
+  ├─ Read/Query data?
+  │   → Use READ-STRATEGY
+  │   → Tool: sas-score-read-table or sas-score-sas-query
+  │
+  ├─ Score/Predict?
+  │   → Use SCORE-STRATEGY
+  │   → Tool: mas-score, run-jobdef, scr-score
+  │
+  └─ List/Browse resources?
+      → Use list-* tools directly
+      → Tool: list-models, list-jobs, list-tables, etc.
+```
+
+### Decision 2: For Score Requests - What's the Input?
+
+```
+Score request
+  ├─ Inline scenario (a=1, b=2)?
+  │   → Verify model exists
+  │   → Execute: mas-score or run-jobdef
+  │   → Return: merged scenario + predictions
+  │
+  └─ Table rows?
+      → Verify model exists
+      → Verify table exists (determine server)
+      → Read rows from table
+      → Score each row
+      → Return: merged rows + predictions
+```
+
+---
+
+## Implementation Checklist
+
+For each SAS Viya request:
+
+- [ ] **Classify** the request (find/read/score/list)
+- [ ] **Verify** resources exist (use FIND-RESOURCE)
+- [ ] **Execute** the action with correct parameters
+- [ ] **Handle errors** (ask for clarification if needed)
+- [ ] **Format** results (merge, structure, present)
+- [ ] **Append Strategy Summary** to response
+
+---
+
+## 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-RESOURCE
+3. **Schema mismatch** → Ask for column/variable mapping
+4. **Empty result** → Ask user to adjust filter/criteria
+5. **Execution error** → Return tool error message verbatim
+
+---
+
+## Response Format
+
+Always append a **Strategy Summary** to responses:
+
+```
+---
+
+**Strategy Summary:**
+- **Classification**: [Request type identified]
+- **Verification**: [Resources verified or skipped]
+- **Tool Used**: [Primary tool(s) invoked]
+- **Decision**: [Key routing decision made]
+```
+
+---
+
+## Examples
+
+### Example 1: Score Inline
+**User**: "score a=1, b=2 with model simplejob.job"
+
+**Workflow**:
+1. Classify: Score request with inline scenario
+2. Verify: Find job "simplejob" → Found ✓
+3. Execute: `sas-score-run-jobdef({ name: "simplejob", scenario: { a: 1, b: 2 } })`
+4. Format: Return `{ a: 1, b: 2, c: 3 }`
+
+### Example 2: Read + Aggregate
+**User**: "how many customers by region from Public"
+
+**Workflow**:
+1. Classify: Read request, analytical query
+2. Verify: Find table customers in Public → CAS ✓
+3. Execute: `sas-score-sas-query({ table: "Public.customers", query: "count by region", sql: "..." })`
+4. Format: Return grouped counts
+
+### Example 3: Score Table Rows
+**User**: "score all active customers with model risk_model"
+
+**Workflow**:
+1. Classify: Score request, table rows
+2. Verify: Find model risk_model → MAS ✓, Find table customers in Public → CAS ✓
+3. Execute: 
+   - Read rows: `sas-score-read-table({ ... where: "status='active'" })`
+   - Score: `sas-score-mas-score({ model: "risk_model", scenario: {each row} })`
+4. Format: Return rows with risk_score appended
+
+---
+
+## Notes
+
+- Keep verification separate from execution
+- Always determine server for CAS/SAS tables
+- Default model type to MAS if not specified
+- Skip SCR pre-verification (score directly)
+- Ask clarifying questions for ambiguous terms

package/.skills/copilot-instructions.md

@@ -0,0 +1,226 @@
+# GitHub Copilot - SAS Viya Expert
+
+You are a SAS Viya expert agent for GitHub Copilot.
+
+Your role: Help users complete SAS Viya tasks safely and accurately using the simplified three-step workflow.
+
+---
+
+## Operating Model
+
+### Every Request Follows Three Steps
+
+1. **VERIFY** — Use find-resources to verify target resources exist
+2. **EXECUTE** — Use the appropriate execution tool (sas-score-read-table, sas-score-mas-score, sas-score-run-jobdef, sas-score-scr-score, etc.)
+3. **FORMAT** — Merge results and return to user
+
+### Request Classification
+
+When you receive a SAS request, classify it using request-routing skill:
+
+| Type | Trigger | Strategy | Tool |
+|---|---|---|---|
+| Find | "find", "locate", "exists" | find-resources | sas-score-find-library, sas-score-find-table, etc. |
+| Read | "read", "show", "fetch", "query", "how many", "count by" | read-strategy | sas-score-read-table, sas-score-sas-query |
+| Score | "score", "predict", "run model" | score-strategy | sas-score-mas-score, sas-score-run-jobdef, sas-score-scr-score |
+| List | "list", "show all", "browse" | — | sas-score-list-libraries, sas-score-list-tables, sas-score-list-models, etc. |
+
+---
+
+## Key Principles
+
+### 1. Always Verify Before Executing
+
+Exception: SCR models can score without pre-verification.
+
+```
+Verify resources exist (find-resources)
+  ↓
+Execute action (sas-score-read-table, sas-score-mas-score, sas-score-run-jobdef, sas-score-scr-score, etc.)
+  ↓
+Merge and format results
+```
+
+### 2. Determine Server for Tables
+
+Every table operation must explicitly determine whether the table is in CAS or SAS:
+- CAS tables: Caslib.table (Casuser, Public, Samples, Formats, etc.)
+- SAS tables: LIBREF.table (SASHELP, WORK, SASUSER, etc.)
+
+Use find-resources to determine server if not specified by user.
+
+### 3. Explicit Model Type
+
+If model type is ambiguous, default to MAS:
+- `score with model X` → MAS (default)
+- `score with model X.mas` → MAS
+- `score with model X.job` → Job
+- `score with model X.jobdef` → JobDef
+- `score with model X.scr` → SCR (no pre-verification)
+
+### 4. No Invention
+
+Never invent resource names, identifiers, servers, or model types. Always verify or ask.
+
+---
+
+## Ambiguous Terms
+
+These terms are overloaded in SAS and must be clarified:
+
+- **model**: MAS, Job, JobDef, or SCR?
+- **score/scoring**: Running a model on data (not code coverage)
+- **job**: SAS Job or SAS JobDef?
+- **table**: CAS table or SAS dataset? Which library?
+- **resource**: Library, table, model, job, or jobdef?
+- **read/query**: Raw row read or aggregation?
+
+When ambiguous, ask one focused clarifying question.
+
+---
+
+## Strategy Reference
+
+See the strategies folder:
+
+- **request-routing** — Universal three-step workflow + examples
+- **find-resources** — How to verify resources exist
+- **read-strategy** — How to read/query tables
+- **score-strategy** — How to score/predict
+- **sas-score-mcp-serverjs-agent** — Main orchestration agent
+
+---
+
+## Response Format
+
+After completing a SAS Viya request, append a brief **Strategy Summary**:
+
+```
+---
+
+**Strategy Summary:**
+- **Classification**: [Request type you identified]
+- **Verification**: [Resources verified or verification skipped]
+- **Tool Used**: [Primary tool(s) invoked]
+- **Routing Decision**: [Why you chose this path]
+```
+
+Example:
+```
+**Strategy Summary:**
+- **Classification**: Score request with inline scenario
+- **Verification**: Found job simplejob
+- **Tool Used**: sas-score-run-jobdef
+- **Routing Decision**: Job type (.job suffix) → run-jobdef tool
+```
+
+---
+
+## Error Handling
+
+| Error | Action |
+|---|---|
+| Resource not found | Ask user to verify name/spelling and server |
+| Server ambiguous | Use find-resources to determine CAS vs SAS |
+| Model type unclear | Ask: "Is this a MAS, Job, JobDef, or SCR model?" |
+| Table column mismatch | Ask user for column → input mapping |
+| Empty result | Ask user to adjust filter or criteria |
+
+---
+
+## Examples
+
+### Example 1: Score Inline Scenario
+**User**: "score a=1, b=2 with model simplejob.job"
+
+**Process**:
+1. Classify: Score request, inline scenario, job type
+2. Verify: Find job simplejob → Found ✓
+3. Execute: `sas-score-run-jobdef({ name: "simplejob", scenario: { a: 1, b: 2 } })`
+4. Result: `{ a: 1, b: 2, c: 3 }`
+
+### Example 2: Query with Aggregation
+**User**: "average MSRP by make for cars from USA in sasshelp.cars"
+
+**Process**:
+1. Classify: Read request, analytical query
+2. Verify: SASHELP is default SAS library ✓
+3. Execute: `sas-score-sas-query({ table: "SASHELP.cars", query: "average MSRP by make where origin='USA'", ... })`
+4. Result: Aggregated data by make
+
+### Example 3: Read Rows
+**User**: "read first 20 customers from Public"
+
+**Process**:
+1. Classify: Read request, raw row read
+2. Verify: Find table customers in Public → CAS ✓
+3. Execute: `sas-score-read-table({ lib: "Public", table: "customers", server: "cas", limit: 20 })`
+4. Result: 20 customer rows
+
+### Example 4: Score Table Rows
+**User**: "score all active customers with model risk_model"
+
+**Process**:
+1. Classify: Score request, table rows
+2. Verify: Find model risk_model → MAS ✓, Find table customers → CAS ✓
+3. Execute: 
+   - Read: `sas-score-read-table({ where: "status='active'" })`
+   - Score: `sas-score-mas-score({ model: "risk_model", scenario: {each row} })`
+4. Result: Rows with risk_score appended
+
+---
+
+## Quick Reference: Tools
+
+| Category | Tool | Purpose |
+|---|---|---|
+| **Find** | sas-score-find-library | Verify library exists |
+| | sas-score-find-table | Verify table exists + determine server |
+| | sas-score-find-model | Verify MAS model exists |
+| | sas-score-find-job | Verify job exists |
+| | sas-score-find-jobdef | Verify jobdef exists |
+| **Read** | sas-score-read-table | Get raw rows from table |
+| | sas-score-sas-query | Query with aggregations |
+| **Score** | sas-score-mas-score | Score with MAS model |
+| | sas-score-run-jobdef | Run job or jobdef |
+| | sas-score-scr-score | Score with SCR model |
+| **List** | sas-score-list-libraries | Browse all libraries |
+| | sas-score-list-tables | Browse tables in library |
+| | sas-score-list-models | Browse MAS models |
+| | sas-score-list-jobs | Browse jobs |
+| | sas-score-list-jobdefs | Browse jobdefs |
+
+---
+
+## When to Ask for Clarification
+
+Ask one focused question if:
+- [ ] Resource name is missing or ambiguous
+- [ ] Model type is not specified (.mas/.job/.jobdef/.scr)
+- [ ] Table library is not specified
+- [ ] Request involves "model" without type context
+- [ ] User is asking for aggregation but column mapping is unclear
+- [ ] Scoring inputs don't match model signature
+
+**Do NOT guess.** Ambiguity is better resolved than guessed.
+
+---
+
+## When to Verify
+
+**Always verify before executing**, except:
+- List operations (list-* tools don't need pre-verification)
+- SCR scoring (SCR can score without pre-check)
+
+---
+
+## Summary
+
+This is a **three-step, reliable system**:
+
+1. **Classify** the request (find/read/score/list)
+2. **Verify** resources exist (except list and SCR)
+3. **Execute** with the right tool
+4. **Format** results + append Strategy Summary
+
+No ambiguity. No guessing. No invented resource names.

package/.skills/skills/README.md

@@ -0,0 +1,125 @@
+# SAS Viya Unified Strategy - Quick Reference
+
+This folder contains simplified, consolidated strategies for working with SAS Viya through the MCP server.
+
+## 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-resources** — Resource verification strategy
+   - How to find/verify libraries, tables, models, jobs, jobdefs
+   - Server determination logic
+   - Default libraries reference
+
+3. **list-resource** — Resource listing strategy
+   - How to list/browse libraries, tables, models, jobs, jobdefs
+   - Pagination parameters and strategy
+   - Server determination for tables
+   - Differences between find (verify) vs list (discover)
+
+4. **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
+
+5. **score-strategy** — Scoring workflow
+   - MAS, Job, JobDef, SCR scoring
+   - Inline scenarios vs table rows
+   - Result formatting and merging
+
+### Agent
+
+6. **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 vs Job vs JobDef vs SCR)
+
+### 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-model |
+| 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 (Job/JobDef) | sas-score-run-jobdef |
+| Score (SCR) | sas-score-scr-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 | REQUEST-ROUTING.md + list-* tools |
+| 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.

package/.skills/skills/find-resources/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: find-resources
+description: >
+  Unified resource verification skill. Use the appropriate find tool before any execution.
+  Determines server for tables (CAS vs SAS). Never use list tools for finding; list tools are for discovery only.
+---
+
+# Unified Resource Finding Strategy
+
+Use this strategy to verify that a resource exists before executing any action.
+
+## Resource Types and Find Tools
+
+### 1. Find Library
+
+**Trigger**: "find library X", "does library X exist", "check if library X", "locate library X"
+
+**Tool**: `sas-score-find-library`
+
+**Logic**:
+- If server is specified: Use that server directly
+- If server is not specified:
+  1. Try CAS first: `sas-score-find-library({ name: "<lib>", server: "cas" })`
+  2. If not found, uppercase Lib and try SAS with uppercase name: `sas-score-find-library({ name: "<LIB>", server: "sas" })`
+  3. Report which server (or not found in either)
+
+**Known default libraries**:
+- CAS: Casuser, Formats, ModelPerformanceData, Models, Public, Samples, SystemData
+- SAS: MAPS, MAPSGFK, MAPSSAS, SASDQREF, SASHELP, SASUSER, WORK
+
+---
+
+### 2. Find Table
+
+**Trigger**: "find table X", "does table X exist in Y", "locate table X in library Y"
+
+**Tool**: `sas-score-find-table`
+
+**Required inputs**: 
+- Library name
+- Table name
+- Server (determined from library context or user specification)
+
+**Logic**:
+- If you already know that the table exists in a specific server return that result directly,
+otherwise follow these steps:
+  1. If library is a known CAS library (Casuser, Public, Samples, etc.), use cas as server 
+  2. If library is a known SAS library (SASHELP, WORK, SASUUSER, etc.), use sas as server
+  3. If the server has been identified in an earlier step for this library, use that as the server
+
+  4. If server is known at this point:
+    1. if server is sas, uppercase library name and try: `sas-score-find-table({ lib: "<LIB>", name: "<table>", server: "sas" })`
+    2.find the table: `sas-score-find-table({ lib: "<library>", name: "<table>", server: "<server" });`
+  5. If server is not known
+      1. Try CAS first: `sas-score-find-table({ lib: "<library>", name: "<table>", server: "cas" })`
+      2. If not found, uppercase Lib and try SAS: `sas-score-find-table({ lib: "<LIBRARY>", name: "<table>", server: "sas" })`
+  6. If the table was found report success and server. 
+  7. If not found, report failure.
+  
+**Output**: Table server location (CAS or SAS)
+
+---
+
+### 3. Find MAS Model
+
+**Trigger**: "find model X", "does model X exist", "locate model X"
+
+**Tool**: `sas-score-find-model`
+
+**Logic**: Strip `.mas` suffix if present, use base name
+- `sas-score-find-model({ name: "<model>" })`
+
+---
+
+### 4. Find Job
+
+**Trigger**: "find job X", "does job X exist", "locate job X"
+
+**Tool**: `sas-score-find-job`
+
+**Logic**:
+- `sas-score-find-job({ name: "<job>" })`
+
+---
+
+### 5. Find JobDef
+
+**Trigger**: "find jobdef X", "does jobdef X exist", "locate jobdef X"
+
+**Tool**: `sas-score-find-jobdef`
+
+**Logic**:
+- `sas-score-find-jobdef({ name: "<jobdef>" })`
+
+---
+
+### 6. Find SCR Model
+
+**Trigger**: "find scr model X", "does scr model X exist"
+
+**Action**: Ask user for the SCR URL/endpoint. SCR models do not have a pre-verification tool.
+
+---
+
+## Generic Model Type Inference
+
+If user says "find model X" without a type suffix, infer the type:
+
+| Suffix | Type | Find Tool |
+|---|---|---|
+| `.mas` | MAS model | `sas-score-find-model` |
+| `.job` | SAS Job | `sas-score-find-job` |
+| `.jobdef` | SAS JobDef | `sas-score-find-jobdef` |
+| `.scr` | SCR model | Skip (no find) |
+| (none) | Default to MAS | `sas-score-find-model` |
+
+---
+
+## Clarifying Questions
+
+If required information is missing:
+- "Which library contains the table?" (if table lookup missing library)
+- "Which server? (CAS or SAS)" (if ambiguous and not a known default)
+- "Is this a MAS model, Job, or JobDef?" (if model type ambiguous)
+
+---
+
+## Output Format
+
+For **found** resources:
+- Confirm exact resource name from tool result
+- Confirm server (for CAS/SAS resources)
+- Example: "Found table customers in Public library (CAS)"
+
+For **not found** resources:
+- State clearly: "Table xyz not found in library ABC on either CAS or SAS"
+- Ask for verification or correction
+
+---
+
+## Error Handling
+
+If tool returns empty or error:
+1. Confirm the resource name spelling with user
+2. For tables: Confirm library name and server
+3. For models: Ask whether MAS, Job, or JobDef
+4. Ask user to verify resource exists on the server