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

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

@@ -0,0 +1,272 @@
+---
+name: detail-strategy
+description: >
+  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 (except SCR models, which can be queried directly).
+---
+
+# 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?").
+
+Verification vs Retrieval (simplified)
+
+- We separate the workflow into two clear, sequential phases to reduce branching and cognitive load:
+  1. Verification phase — confirm the resource exists and determine its exact type and server. Use the appropriate "find" tool for all resource types except SCR models.
+  2. Retrieval phase — after successful verification, call the detail/read tool appropriate for the identified resource type to fetch metadata or content.
+
+- Exception for SCR models: document the exception inline — SCR models may be queried directly with `sas-score-scr-info` when the user provides a specific SCR endpoint. Even when skipping verification, still validate the endpoint/URL format before calling the tool.
+
+Apply this separation consistently across MAS models, Job models, JobDef models, SCR models, and tables.
+
+---
+
+## Classification & Verification Process
+
+### Phase 1: Classify the Resource Type
+
+Determine resource type from context/naming conventions:
+
+| Pattern                  | Resource Type |
+|--------------------------|---------------|
+| model X (or X.mas)       | MAS model     |
+| model X.scr              | SCR model     |
+| model X.job              | Job model     |
+| model X.jobdef           | JobDef model  |
+| table X in library Y     | Table         |
+
+If resource is ambiguous, ask user for clarification.
+
+### Phase 2: Verify Resource Exists (Skip for SCR Models)
+
+For each resource type, use the appropriate verification tool:
+
+| Resource Type | Tool              |
+|---------------|-------------------|
+| MAS model     | sas-score-find-model |
+| Job model     | sas-score-find-job   |
+| JobDef model  | sas-score-find-jobdef |
+| Table         | sas-score-find-table  |
+| SCR model     | *(no verification needed)* |
+
+If verification fails, inform the user and ask for additional details or corrections.
+
+---
+
+## Detail Retrieval Process
+
+### Phase 3: Get Details
+
+### Option A: MAS Model Details
+
+**Trigger phrases**: "what inputs does model X need", "describe model X", "show variables for model X", "model X metadata", "model X information"
+
+**Tool**: `sas-score-model-info`
+
+**Parameters**:
+```
+sas-score-model-info({
+  model: "<model name>"
+})
+```
+
+**Returns**:
+- Input variables (name, type, role)
+- Output variables (name, type, possible_values)
+- Model type
+- Description
+
+**Example**:
+```
+User: "What inputs does model churnRisk need?"
+
+1. Find: sas-score-find-model({ name: "churnRisk" })
+2. Get info: sas-score-model-info({ 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"
+
+**Tool**: `sas-score-scr-info`
+
+**Parameters**:
+```
+sas-score-scr-info({
+  url: "<scr endpoint>"
+})
+```
+
+**Returns**:
+- Input schema (variable names, types, required/optional)
+- Output schema (prediction, probabilities, scores)
+- Model metadata
+
+**Example**:
+```
+User: "Show inputs for SCR model at https://scr-host/models/loan"
+
+1. Get info: sas-score-scr-info({ url: "https://scr-host/models/loan" })
+2. Return: { inputs: [...], outputs: [...] }
+```
+
+**Note**: SCR models typically do not require pre-verification (can call scr-info directly)
+
+---
+
+### 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-info`
+
+**Parameters**:
+```
+sas-score-table-info({
+  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-info({ lib: "Public", table: "customers", server: "cas" })
+3. Return: { columns: [...], tableInfo: {...} }
+```
+
+---
+### 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"
+
+**Tool**: `sas-score-job-info`
+
+**Parameters**:
+```
+sas-score-job-info({
+  model: "<model name>"
+})
+```
+
+**Returns**:
+- Input variables (name, type, role)
+
+**Example**:
+```
+User: "What inputs does job model churnRisk need?"
+
+1. Find: sas-score-find-job({ name: "churnRisk" })
+2. Get info: sas-score-job-info({ model: "churnRisk" })
+3. Return: { inputs: [...] }
+```
+
+## Decision Tree
+
+```
+User requests information/details
+  ├─ About a MAS model?
+  │   → Verify: sas-score-find-model
+  │   → Call: sas-score-model-info
+  │
+  ├─ About a SCR model?
+  │   → Call: sas-score-scr-info (skip verification; validate URL first)
+  │
+  ├─ About a Job model?
+  │   → Verify: sas-score-find-job
+  │   → Call: sas-score-job-info
+  │
+  ├─ About a JobDef model?
+  │   → Verify: sas-score-find-jobdef
+  │   → Call: sas-score-job-info
+  │
+  └─ About a table?
+      → Verify: sas-score-find-table (determine CAS or SAS server)
+      → Call: sas-score-table-info
+```
+
+---
+
+## 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:
+
+```
+---
+
+**Strategy Summary:**
+- **Classification**: [Resource type identified]
+- **Verification**: [Resource found or skipped (SCR)]
+- **Tool Used**: [Detail tool invoked]
+- **Server**: [CAS/SAS for tables, N/A for models]
+```
+
+---
+
+## 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 URL (SCR)** → Ask for correct SCR endpoint URL
+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-model-info({ 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-info({ url: "https://scr-host/models/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: Find table customers in Public → CAS ✓
+3. Execute: `sas-score-table-info({ lib: "Public", table: "customers", server: "cas" })`
+4. Return: Column names, types, and table metadata

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

@@ -0,0 +1,155 @@
+---
+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 verifying or finding specific resources; list tools are for discovery and exploration only.
+---
+
+# Unified Resource Finding Strategy
+
+Use this strategy to verify that a resource exists before executing any action.
+
+Do **not** use list tools for verifying or finding specific resources. List tools are for discovery and exploration only, not for confirming the existence of a specific resource.
+
+## 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**:
+1. If server is specified: Use that server directly.
+2. If server is not specified:
+  - Step 1: Try CAS first: `sas-score-find-library({ name: "<lib>", server: "cas" })`
+  - Step 2: If not found in CAS, try SAS with the library name uppercased: `sas-score-find-library({ name: "<LIB>", server: "sas" })`
+  - Step 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**:
+1. If you already know that the table exists in a specific server, return that result directly.
+2. Otherwise, follow these steps:
+  - Step 1: If library is a known CAS library (Casuser, Public, Samples, etc.), use CAS as server.
+  - Step 2: If library is a known SAS library (SASHELP, WORK, SASUSER, etc.), use SAS as server.
+  - Step 3: If the server has been identified in an earlier step for this library, use that as the server.
+3. If server is known at this point:
+  - If server is SAS, uppercase the library name and try: `sas-score-find-table({ lib: "<LIB>", name: "<table>", server: "sas" })`
+  - Otherwise, use the provided server: `sas-score-find-table({ lib: "<library>", name: "<table>", server: "<server>" })`
+4. If server is not known:
+  - Step 1: Try CAS first: `sas-score-find-table({ lib: "<library>", name: "<table>", server: "cas" })`
+  - Step 2: If not found in CAS, try SAS with the library name uppercased: `sas-score-find-table({ lib: "<LIBRARY>", name: "<table>", server: "sas" })`
+5. If the table was found, report success and server.
+6. 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.
+If the SCR URL/endpoint is invalid or missing, prompt the user to provide a valid URL.
+
+
+---
+
+
+
+## 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

package/.skills/skills/list-resource/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: list-resource
+description: >
+  Unified resource listing strategy. Use appropriate list tools for listing and browsing.
+  Determines pagination parameters. Use list tools for listing only; use find tools for verification of existence or discovery.
+---
+
+# Unified Resource Listing Strategy
+
+
+Use this strategy to list available resources (libraries, tables, models, jobs, jobdefs).
+
+## Resource Type to Tool Mapping
+
+| Resource Type | List Tool |
+|--------------|-----------|
+| Libraries    | sas-score-list-libraries |
+| Tables       | sas-score-list-tables    |
+| Models       | sas-score-list-models    |
+| Jobs         | sas-score-list-jobs      |
+| JobDefs      | sas-score-list-jobdefs   |
+
+Use this table to select the correct tool for each resource type. Then follow the logic for parameters and pagination below.
+
+## Resource Types and List Tools
+
+### 1. List Libraries
+
+**Trigger**: "list libraries", "show all libs", "list available libraries", "browse libraries"
+
+**Tool**: `sas-score-list-libraries`
+
+**Logic**:
+- If server is specified: List from that server only
+- If server is not specified: List from all servers (default)
+
+**Parameters**:
+```
+server: "cas" | "sas" | "all"  # "cas" = CAS only, "sas" = SAS only, "all" = both
+start: <offset>                 # 1-based page number (default 1)
+limit: <page size>              # items per page (default 10, max varies)
+where: "<filter expression>"    # optional filter
+```
+
+**Examples**:
+```
+# List all CAS libraries
+sas-score-list-libraries({ server: "cas", start: 1, limit: 10 })
+
+# List SAS libraries
+sas-score-list-libraries({ server: "sas", start: 1, limit: 10 })
+
+# List all libraries
+sas-score-list-libraries({ server: "all", start: 1, limit: 10 })
+
+# Pagination: show next page
+sas-score-list-libraries({ server: "all", start: 11, limit: 10 })
+```
+
+---
+
+### 2. List Tables in Library
+
+**Trigger**: "list tables in X", "show tables in library X", "browse tables in X", "what tables are in X"
+
+**Tool**: `sas-score-list-tables`
+
+**Required inputs**:
+- Library name
+- Server (determined from library context or user specification)
+
+**Logic**:
+- If library is a known CAS library (Casuser, Public, Samples, etc.), use CAS
+- If library is a known SAS library (SASHELP, WORK, SASUSER, etc.), use SAS
+- If ambiguous: Ask the user to clarify. If no clarification is provided, attempt both options (CAS and SAS) and return results for each, clearly labeled by server.
+
+**Parameters**:
+```
+lib: "<library>"               # Required: library name
+server: "cas" or "sas"         # Determined from library
+start: <offset>                # 1-based page number (default 1)
+limit: <page size>             # items per page (default 10)
+where: "<filter expression>"   # optional filter
+```
+
+**Examples**:
+```
+# List tables in Public (CAS)
+sas-score-list-tables({ lib: "Public", server: "cas", start: 1, limit: 10 })
+
+# List tables in SASHELP (SAS)
+sas-score-list-tables({ lib: "SASHELP", server: "sas", start: 1, limit: 10 })
+
+# Pagination: show next page
+sas-score-list-tables({ lib: "Public", server: "cas", start: 11, limit: 10 })
+```
+
+---
+
+### 3. List Models
+
+**Trigger**: "list models", "show all models", "browse models", "what models are available"
+
+**Tool**: `sas-score-list-models`
+
+**Logic**: Lists all models published to the Model Administration Service (MAS).
+- No server selection required (MAS is centralized)
+
+**Parameters**:
+```
+start: <offset>  # 1-based page number (default 1)
+limit: <size>    # items per page (default 10)
+```
+
+**Examples**:
+```
+# List first 10 models
+sas-score-list-models({ start: 1, limit: 10 })
+
+# List 25 models
+sas-score-list-models({ start: 1, limit: 25 })
+
+# Pagination: show next page
+sas-score-list-models({ start: 11, limit: 10 })
+```
+
+---
+
+### 4. List Jobs
+
+**Trigger**: "list jobs", "show all jobs", "browse jobs", "what jobs are available"
+
+**Tool**: `sas-score-list-jobs`
+
+**Logic**: Lists all SAS Viya job assets.
+
+**Parameters**:
+```
+start: <offset>                # 1-based page number (default 1)
+limit: <page size>             # items per page (default 10)
+where: "<filter expression>"   # optional filter
+```
+
+**Examples**:
+```
+# List first 10 jobs
+sas-score-list-jobs({ start: 1, limit: 10 })
+
+# List 25 jobs
+sas-score-list-jobs({ start: 1, limit: 25 })
+
+# Pagination: show next page
+sas-score-list-jobs({ start: 11, limit: 10 })
+```
+
+---
+
+### 5. List JobDefs
+
+**Trigger**: "list jobdefs", "show all jobdefs", "browse jobdefs", "what jobdefs are available"
+
+**Tool**: `sas-score-list-jobdefs`
+
+**Logic**: Lists all SAS Viya job definition assets.
+
+**Parameters**:
+```
+start: <offset>                # 1-based page number (default 1)
+limit: <page size>             # items per page (default 10)
+where: "<filter expression>"   # optional filter
+```
+
+**Examples**:
+```
+# List first 10 jobdefs
+sas-score-list-jobdefs({ start: 1, limit: 10 })
+
+# List 25 jobdefs
+sas-score-list-jobdefs({ start: 1, limit: 25 })
+
+# Pagination: show next page
+sas-score-list-jobdefs({ start: 11, limit: 10 })
+```
+
+---
+
+## Pagination Strategy
+
+All list operations support pagination via `start` and `limit` parameters:
+
+| Parameter | Type | Default | Notes |
+|---|---|---|---|
+| `start` | number | 1 | 1-based page offset |
+| `limit` | number | 10 | items per page |
+
+**Pagination Detection**:
+```
+If returned items < limit
+  → End of list reached
+Else if returned items === limit
+  → Hint: More items available. Next start = start + limit
+```
+
+**Example**:
+```
+List 1: start=1, limit=10 → returns 10 items
+List 2: start=11, limit=10 → returns 10 items
+List 3: start=21, limit=10 → returns 5 items (< limit)
+        → End of list (total: 25 items)
+```
+
+---
+
+## Decision Tree
+
+```
+User requests to list/browse resources
+  ↓
+What resource type?
+  ├─ Libraries? → Use sas-score-list-libraries
+  ├─ Tables in library X? → Use sas-score-list-tables
+  ├─ Models? → Use sas-score-list-models
+  ├─ Jobs? → Use sas-score-list-jobs
+  └─ JobDefs? → Use sas-score-list-jobdefs
+```
+
+---
+
+## Known Default Libraries
+
+### CAS Libraries (server: "cas")
+- Casuser
+- Formats
+- ModelPerformanceData
+- Models
+- Public
+- Samples
+- SystemData
+
+### SAS Libraries (server: "sas")
+- MAPS
+- MAPSGFK
+- MAPSSAS
+- SASDQREF
+- SASHELP
+- SASUSER
+- WORK
+
+---
+
+## Differences: Find vs List
+
+| Aspect | Find | List |
+|---|---|---|
+| Purpose | Verify/discover existence | List available resources |
+| Returns | Single resource or not found | Multiple resources with pagination |
+| Use case | Before execution | Listing of resources |
+| Tool suffix | `find-*` | `list-*` |