@sassoftware/sas-score-mcp-serverjs 1.0.1-7 → 1.0.1-9

package/.skills/sas-list-tables-smart/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: sas-list-tables-smart
+description: >
+  List all tables in a SAS Viya library with intelligent server detection. When the server is not
+  specified, automatically checks CAS first, then SAS if not found. Informs the user if the library
+  does not exist in either server. Use this skill when the user wants to browse or explore available
+  tables. Trigger phrases include: "list tables in", "show tables in", "what tables are in",
+  "browse tables in", "tables in library", "enumerate tables", or any request to explore data sources.
+---
+
+# Smart Data Access in SAS Library (List, Read, Query)
+
+Intelligently enumerates tables in a SAS Viya library, automatically determining the correct server
+when not explicitly specified.
+
+> **Pre-flight check**: Before listing tables, verify the library and table context using the `sas-find-resource-strategy` skill.
+> This ensures consistent server detection across all data operations.
+
+**If the user specifies the server explicitly** (e.g., "list tables in Public in cas"):
+- Use the specified server: `server: "cas"` or `server: "sas"`
+- Proceed directly to listing tables
+
+**If the server is NOT specified:**
+1. **First attempt**: Check CAS (`server: "cas"`)
+2. **If no tables found in CAS**: Check SAS (`server: "sas"`)
+3. **If no tables found in either**:
+   - Inform user: *"The library '<lib>' was not found in CAS or SAS. Please verify the library name is correct."*
+  - Ask for corrected library name or explicit server context
+
+---
+
+## Using sas-score-list-tables
+
+**When:**
+- User wants to browse all tables in a library
+- User wants to see what data is available
+- User wants to explore library contents before querying
+
+**How:**
+```
+sas-score-list-tables({
+  lib: "libraryname",           // required
+  server: "cas" or "sas",       // required; determined by server check
+  limit: 10,                    // optional; default 10, adjust for pagination
+  start: 1                      // optional; default 1, use for pagination
+})
+```
+
+**Rules:**
+- Always determine the correct server first (cas → sas → neither)
+- **For SAS server: always uppercase the library name** (e.g., "maps" → "MAPS")
+- If library name is missing, ask: *"Which library should I list tables from?"*
+- Default page size is 10; adjust based on user request ("show me all", "25 tables", etc.)
+- If returned table count equals the limit, suggest pagination: *"There may be more tables. Use `start: {next_offset}` to see more."*
+- If no tables are found despite library existing, report: *"No tables found in {lib} on {server} server."*
+- Return table names only; do not fetch table metadata unless explicitly requested
+- Do not use list tools to determine whether a specific resource exists
+
+---
+
+## Smart server detection logic
+
+```
+IF server specified by user
+  → IF server is "sas"
+      → uppercase lib
+  → use that server
+ELSE
+  → TRY sas-score-list-tables(lib, server="cas")
+    IF tables found
+      → success, return tables
+    ELSE
+      → uppercase lib
+      → TRY sas-score-list-tables(lib.toUpperCase(), server="sas")
+        IF tables found
+          → success, return tables
+        ELSE
+          → inform user library not found in either server
+```
+
+---
+
+## Common patterns
+
+**Pattern 1 — List tables, server unspecified**
+> "List tables in Public"
+
+1. Try CAS: `sas-score-list-tables({ lib: "Public", server: "cas" })`
+2. If empty, try SAS with uppercase: `sas-score-list-tables({ lib: "PUBLIC", server: "sas" })`
+3. If still empty → inform user
+
+**Pattern 2 — List tables with explicit server (SAS)**
+> "List tables in sashelp in sas"
+
+1. Skip server detection
+2. Call with uppercase lib: `sas-score-list-tables({ lib: "SASHELP", server: "sas" })`
+
+**Pattern 3 — List tables with explicit server (CAS)**
+> "List tables in Public in cas"
+
+1. No uppercase needed for CAS
+2. Call: `sas-score-list-tables({ lib: "Public", server: "cas" })`
+
+**Pattern 4 — Pagination**
+> "Show me 25 tables in Samples, then the next batch"
+
+1. First call: `sas-score-list-tables({ lib: "Samples", limit: 25, start: 1 })`
+2. Next call: `sas-score-list-tables({ lib: "Samples", limit: 25, start: 26 })`
+
+**Pattern 5 — Library not found**
+> "List tables in foo"
+
+1. Try CAS: empty
+2. Try SAS with uppercase: empty
+3. Response: *"The library 'foo' was not found in CAS or SAS. Please verify the library name."*
+
+---
+
+## Error handling
+
+| Scenario | Action |
+|---|---|
+| Library not found in either server | Inform user and ask to verify library name |
+| Empty result on first server | Automatically check second server |
+| User specifies invalid server | Return error; ask user to clarify: `"cas"` or `"sas"` |
+| Missing library name | Ask: *"Which library should I list tables from?"* |
+| Library verification needed | Use `sas-find-resource-strategy` to verify the library exists first |
+

package/.skills/sas-read-and-score-strategy/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: sas-read-and-score-strategy
+description: >
+  Guide the full read → score workflow in SAS Viya: reading records from a table and then scoring
+  them with a MAS model (using sas-score-model-score). Use this skill whenever the user wants to score records
+  from a table, run a model against query results, predict outcomes for a set of rows, or any
+  combination of fetching data and scoring it. Trigger phrases include: "score these records",
+  "score results of my query", "run the model on this table", "predict for these customers",
+  "fetch and score", "read and score", "score rows from", "run model on table data", or any request
+  that combines reading/querying table data with model prediction.
+---
+
+# SAS Read → Score Workflow
+
+Orchestrates the full two-step pattern of reading records from a SAS/CAS table and scoring them
+with a deployed MAS model.
+
+---
+
+## Pre-flight verification
+
+**Before attempting to read or score table data:**
+1. **Verify library exists**: Use `sas-find-resource-strategy` for library lookup (CAS first, then SAS if needed)
+2. **Verify table exists**: Use `sas-find-resource-strategy` for table lookup in the selected library/server
+3. **Verify model exists**: Use `sas-find-resource-strategy` for model lookup before scoring
+4. **Confirm server location**: Ensure you know which server (CAS or SAS) contains the data
+
+This ensures consistent behavior with other data access operations.
+
+---
+
+## Workflow overview
+
+The typical flow involves:
+1. **Fetch data** — Identify which table/query will provide input records
+2. **Validate model** — Confirm the model exists and understand its input schema
+3. **Score** — Invoke the model on the fetched records
+4. **Present results** — Merge predictions with original data and display
+
+---
+
+## Scenario: User already has data
+
+If the user provides scenario data directly (e.g., "Score age=45, income=60000 with model X"):
+- Extract the scenario values
+- Validate against model's input schema
+- Invoke scoring
+- Return prediction
+
+---
+
+## Scenario: User wants to score table rows
+
+If the user specifies a table (e.g., "Score all customers in Public.customers with model X"):
+- Fetch raw rows (possibly filtered: "where status='active'")
+- Validate model compatibility with input columns
+- Invoke scoring on each row
+- Merge results with original data
+- Display combined table
+
+---
+
+## Scenario: User wants to score query results
+
+If the user wants to score aggregated/filtered results (e.g., "Score high-value customers (spend > 5000) with model X"):
+- Determine which records meet criteria (aggregation/filtering)
+- Validate model expects these input columns
+- Invoke scoring
+- Merge predictions with summary data
+- Display results
+
+---
+
+## Scenario: User unfamiliar with model
+
+If the user specifies a model name that's new/unknown:
+- Check if model exists
+- Retrieve model schema (inputs, outputs)
+- Show user what inputs the model expects
+- Confirm before proceeding with scoring
+
+---
+
+## Rules
+
+- Always validate table/library existence before attempting to read
+- Always check model exists before invoking `sas-score-model-score`
+- Match table columns to model input variables; warn on mismatch
+- Use find tools only for resource existence checks; do not use list tools to find resources
+- If multiple records: score batch if possible; fall back to row-by-row
+- Merge predictions with original data using row index or key column
+- Present results as table with original columns + new prediction columns
+
+---
+
+## Error handling
+
+| Problem | Action |
+|---|---|
+| Table not found | Ask for correct lib.tablename |
+| Model not found | Inform user; suggest verifying model name |
+| Field/column mismatch | Show mismatch, ask user to confirm or adjust query |
+| Scoring error | Return structured error, suggest checking model inputs |
+| Empty read result | Inform user, ask if they want to adjust the query/filter |
+| Data type mismatch | Warn user about type conversion, proceed or ask for clarification |
+
+---
+
+## Integration with other skills
+
+- **Before this workflow**: Use `sas-find-resource-strategy` to verify library/table/model resources exist
+- **For data retrieval**: Use `sas-read-strategy` to choose the right read tool (read-table vs sas-query)
+- **For scoring**: Use `sas-score-workflow-strategy` for advanced scoring options beyond MAS models

package/.skills/sas-read-strategy/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: sas-read-strategy
+description: >
+  Guide the user in choosing the right data retrieval tool: sas-score-read-table (for raw row access with filters)
+  or sas-score-sas-query (for analytical queries, aggregations, joins). Use this skill when the user wants to
+  fetch records from a SAS/CAS table. Trigger phrases include: "read records from", "get data where",
+  "fetch rows from", "query the table", "give me the first N records", "aggregate by", "join tables",
+  or any request that starts with data retrieval.
+---
+
+# SAS Read Strategy
+
+Guides the decision between `sas-score-read-table` and `sas-score-sas-query` based on the user's intent and the nature
+of the data operation. Determines which server contains the data and which retrieval tool is most appropriate.
+
+## Determine the server location
+
+Before retrieving data, locate the specific table first and determine which server(s) contain it:
+
+**Step 1: Locate the specific table (table-first)**
+- Use `sas-find-resource-strategy` to check if the table exists in CAS first, then SAS if needed
+- Do not perform a separate library-first lookup; table lookup already handles server-aware discovery
+- Possible outcomes:
+  - If table exists **only in CAS** → set `server: "cas"`
+  - If table exists **only in SAS** → set `server: "sas"`
+  - If table exists **in both** → ask the user: *"The table exists in both CAS and SAS. Which server would you prefer to query from?"*
+  - If table exists **in neither** → inform user and suggest verifying the table name
+
+---
+
+## Determine the read strategy
+
+Ask yourself: does the user already have the data in hand?
+
+- **Yes (user pasted values, or data is already in context)** → skip this strategy; data is ready to use.
+- **No** → choose the read tool based on intent:
+
+| User's Intent | Tool | Example |
+|---|---|---|
+| Get specific raw rows, apply simple filter, retrieve first N records | `sas-score-read-table` | "Show me 10 rows from customers where status='active'" |
+| Aggregate/summarize, calculate, join tables, analytical question | `sas-score-sas-query` | "Average salary by department", "Count orders by region" |
+
+---
+
+## Using read-table
+
+**When:**
+- User asks for raw records, row-by-row data
+- Simple WHERE filtering (e.g., "where status = 'active'")
+- Pagination needed ("first 50 rows", "next 10 rows")
+
+**How:**
+```
+sas-score-read-table({
+  table: "tablename",
+  lib: "libraryname",
+  server: "cas" or "sas",  // determined from table-first lookup via sas-find-resource-strategy
+  limit: N,        // default 10, adjust based on user request
+  where: "..."     // optional SQL WHERE clause
+})
+```
+
+**Rules:**
+- Always determine the server first using `sas-find-resource-strategy`
+- Keep batch size ≤ 50 rows unless the user explicitly requests more
+- If table name is missing, ask: *"Which table should I read from? (format: lib.tablename)"*
+- If library is missing, ask: *"Which library contains the table?"*
+- Prefer table-first lookup (CAS first, then SAS) instead of a separate library lookup step
+- If table exists in both servers, ask user which to use
+- Return raw column values; do not transform or aggregate
+- Do not use list tools to determine whether a resource exists
+
+---
+
+## Using sas-query
+
+**When:**
+- User asks for aggregation (SUM, AVG, COUNT, GROUP BY)
+- User asks for joins, calculations, or analytical insights
+- User's question is phrased analytically ("compare", "analyze", "breakdown", "trend")
+
+**How:**
+```
+sas-query({
+  table: "lib.tablename",
+  query: "user's natural language question",
+  sql: "SELECT ... FROM ... WHERE ... GROUP BY ..."  // generated from query
+})
+```
+
+**Rules:**
+- Check which server(s) contain the table using `sas-find-resource-strategy` first
+- If table exists in both CAS and SAS, ask user which to query from
+- Parse the user's natural language question into a PROC SQL SELECT statement
+- Ensure SELECT statement is valid SQL syntax
+- Do not add trailing semicolons to the SQL string
+- If table name is missing, ask: *"Which table should I query? (format: lib.tablename)"*
+- If the intent is unclear, ask for clarification: *"Do you want raw rows, or an aggregated summary?"*
+
+---
+
+## Common patterns
+
+**Pattern A — Raw row retrieval**
+> "Show me the first 5 rows from Public.customers"
+
+→ `sas-score-read-table({ table: "customers", lib: "Public", limit: 5 })`
+
+**Pattern B — Filtered retrieval**
+> "Get all high-value orders (amount > 5000) from mylib.orders"
+
+→ `sas-score-read-table({ table: "orders", lib: "mylib", where: "amount > 5000" })`
+
+**Pattern C — Aggregation**
+> "What is the average price by make in Public.cars?"
+
+→ `sas-score-sas-query({ table: "Public.cars", query: "average price by make", sql: "SELECT make, AVG(msrp) AS avg_price FROM Public.cars GROUP BY make" })`
+
+**Pattern D — Join + analysis**
+> "Show me total sales by customer in the sales and customers tables"
+
+→ `sas-score-sas-query()` with a JOIN in the generated SQL
+
+---
+
+## Error handling
+
+| Problem | Action |
+|---|---|
+| Library missing or unclear | Ask the user which library contains the table |
+| Table not found in either server | Inform user and suggest checking the table name |
+| Table exists in both CAS and SAS | Ask: *"The table exists in both servers. Which would you prefer: CAS or SAS?"* |
+| Table exists only in one server | Use that server automatically in your request |
+| Table name missing entirely | Ask: *"Which table should I read from?"* |
+| Ambiguous intent (raw vs aggregate) | Ask: *"Do you want individual rows or a summary by some field?"* |
+| Empty result | Inform user, ask to adjust filter or query |
+
+---
+
+## Integration with other skills
+
+- **Before this skill**: Use `sas-find-resource-strategy` for table-first resource lookup
+- **After this skill**: Use `sas-read-and-score-strategy` to score the retrieved data
+
+---
+
+## Next steps
+
+Once data is retrieved, typical follow-ups include:
+- **Visualize** — present as table or chart
+- **Export** — format and offer download
+- **Analyze further** — ask clarifying questions
+- **Score** — run predictions on the data
+- **Combine** — join with other datasets

package/.skills/sas-request-classifier/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: sas-request-classifier
+description: Classify ambiguous SAS or Viya requests before using MCP tools. Use when prompts mention jobs, code, models, scoring, CAS tables, content, or resources and the correct SAS domain is not yet clear.
+---
+
+# SAS Request Classifier
+
+Use this skill to determine what kind of SAS object, workflow, or environment the user is referring to before selecting tools.
+
+## When to use
+Use this skill when the request contains ambiguous domain terms such as:
+- model
+- score
+- scoring
+- read
+- query
+- job
+- jobdef
+- code
+- table
+- content
+- asset
+- resource
+
+Use this skill before any execution-oriented tool call if there is a chance the request is referring to the wrong SAS domain.
+
+## Goal
+Map the user request to the most likely SAS domain and hand off to the correct downstream skill or tool path.
+
+## Classification targets
+Classify the request into one or more of these categories:
+- Resource existence lookup (library/table/model/job/jobdef) -> Route to **sas-find-resource-strategy**
+- Resource listing (library/table/model/job/jobdef) -> Route to **sas-list-resource-strategy**
+- Reading or querying tables → Route to **sas-read-strategy**
+- CAS resource, SAS resource, caslib, or table discovery → Route to **sas-find-library-smart** 
+- SAS data, libref, or table discovery → Route to **sas-find-library-smart** 
+- Score model or scoring artifact → Route to **sas-score-workflow-strategy**
+- Read data and score together → Route to **sas-read-and-score-strategy**
+- SAS job or flow execution
+- SAS code or program analysis
+- General content or metadata lookup
+- Environment, auth, or connectivity issue
+
+## Procedure
+1. Read the request and identify ambiguous nouns and verbs.
+2. Infer whether the request is asking to discover, inspect, execute, deploy, score, compare, or troubleshoot.
+3. Decide the most likely SAS domain and matching skill.
+4. If confidence is low, ask one focused clarifying question.
+5. If confidence is high, load and use the relevant skill:
+   - **sas-find-resource-strategy** — Unified find-only strategy for library/table/model/job/jobdef
+   - **sas-list-resource-strategy** — Unified list strategy for library/table/model/job/jobdef with non-null pagination defaults
+   - **sas-find-library-smart** — Find CAS or SAS libraries
+   - **sas-list-tables-smart** — Browse tables in a library
+   - **sas-read-strategy** — Choose read-table vs. sas-query for data retrieval
+   - **sas-read-and-score-strategy** — Combine data reading with model scoring
+   - **sas-score-workflow-strategy** — Route scoring requests to correct execution engine
+6. Only after classification and skill guidance, use MCP tools.
+
+## Disambiguation hints
+- "Run" often implies job execution, but may also mean scoring or model invocation. Check for "score" or "model" context.
+- "Model" may refer to MAS models, SAS jobs, jobdefs, or SCR models. Look for context or type suffix (e.g., `.job`, `.mas`, `.scr`).
+- "Score" may refer to model scoring or job execution. Look for model name or context.
+- "Table" usually suggests CAS or SAS but confirm library name and server context.
+- "Find" — resource lookup. Route to sas-find-resource-strategy.
+- "List" or "browse" — resource exploration. Route to sas-list-resource-strategy.
+- "Read", "query", "fetch" — data retrieval. Route to sas-read-strategy.
+- "Predict", "score records", "run model on data" — combined workflow. Route to sas-read-and-score-strategy  or sas-score-workflow-strategy.
+
+## Output
+When you finish classification, state:
+- the inferred SAS domain
+- the confidence level
+- the relevant skill(s) to load
+- any remaining ambiguity or clarifying questions needed