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

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,241 @@
+# 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.
+
+**High-Level Decision Framework:**
+1. Identify the user's intent (Find, Read, Score, List)
+2. Verify resources if required
+3. Select the appropriate tool based on intent and resource type
+4. Execute and format the result
+
+
+---
+
+## 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. |
+| Describe | "describe", "what inputs", "show schema", "metadata", "information" | detail-strategy | sas-score-model-info, sas-score-job-info, sas-score-scr-info, sas-score-table-info |
+
+---
+
+## 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, use MAS as a predefined fallback policy (this is an explicit exception to the 'never invent' rule):
+- `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)
+- **table**: CAS table or SAS dataset? Which library?
+- **resource**: Library, table, model, job,jobdef, scr?
+- **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
+- **list-resource** — How to list resources
+- **detail-strategy** — How to retrieve details about a resource
+- **sas-score-mcp-serverjs-agent** — Main orchestration agent
+
+---
+
+## Response Format
+
+Whenever possible format the response as a markdown table or structured JSON for easy readability.
+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.customers"
+
+**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 in Public.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 |
+| **Detail** | sas-score-model-info | Get MAS model details |
+| | sas-score-job-info | Get Job model details |
+| | sas-score-scr-info | Get SCR model details |
+| | sas-score-table-info | Get table details |
+
+---
+
+## 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.