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

package/.skills_claude/instructions.md

@@ -0,0 +1,184 @@
+# .claude Directory — Usage Instructions
+
+This directory contains a complete, unified configuration for the SAS agent across **Claude Desktop**, **GitHub Copilot**, and other Claude clients.
+
+## Directory Structure
+
+```
+.claude/
+├── copilot-instructions.md          # Core SAS agent instructions
+├── claude-desktop-system-prompt.md  # Claude Desktop system prompt
+├── claude-desktop-config.json       # MCP server configuration template
+├── instructions.md                  # This file — usage guide
+├── skills-index.md                  # Quick reference of all skills
+├── README.md                        # Setup & deployment guide
+├── agents/
+│   └── sas-viya-scoring-expert.md   # SAS Viya expert agent definition
+└── skills/
+    ├── sas-request-classifier/SKILL.md       # Classify ambiguous requests
+    ├── sas-find-library-smart/SKILL.md       # Find SAS/CAS libraries
+    ├── sas-list-tables-smart/SKILL.md        # List tables in a library
+    ├── sas-read-and-score/SKILL.md           # Read data + score workflow
+    ├── sas-read-strategy/SKILL.md            # Choose read tool
+    └── sas-score-workflow/SKILL.md           # Route scoring requests
+```
+
+## Getting Started
+
+### For Claude Desktop Users
+
+1. **Copy the MCP configuration:**
+   - Copy `claude-desktop-config.json` to your Claude Desktop config directory:
+     - **macOS/Linux:** `~/.claude/claude_desktop_config.json`
+     - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+2. **Configure your SAS Viya environment:**
+   - Edit the copied config file with your credentials:
+     ```json
+     "VIYA_URL": "https://your-sas-viya.example.com",
+     "VIYA_CLIENT_ID": "your-oauth-client-id",
+     "VIYA_CLIENT_SECRET": "your-oauth-client-secret",//optional
+     "VIYA_TLS_CERT": "/path/to/ca-cert.pem"  // optional
+     ```
+
+3. **Add the system prompt to Claude:**
+   - Open Claude Desktop → **Settings** → **Custom Instructions**
+   - Copy the contents of `claude-desktop-system-prompt.md`
+   - Paste into the custom instructions field
+   - Save
+
+4. **Restart Claude Desktop** to activate the MCP connection
+
+### For GitHub Copilot Users
+
+- The `.github/` folder already contains the equivalent configuration for Copilot
+- For consistency, you can also copy from `.claude/` if updating across platforms
+
+## How the SAS Agent Works
+
+### 1. Skill-First Behavior
+When you make a request, the agent:
+1. **Classifies** your request using **sas-request-classifier** if ambiguous
+2. **Loads the most relevant skill** from `skills/` directory
+3. **Applies domain-specific guidance** before calling MCP tools
+4. **Uses MCP tools** to execute the request safely
+
+### 2. Available Skills
+
+Quick reference — see `skills-index.md` for full details:
+
+| Skill | Purpose | Trigger |
+|-------|---------|---------|
+| **sas-request-classifier** | Disambiguate domain terms | "find my model", "run scoring" |
+| **sas-find-library-smart** | Find CAS or SAS libraries | "find library Public" |
+| **sas-list-tables-smart** | List tables in a library | "list tables in Public" |
+| **sas-read-strategy** | Choose right read tool | "read records from", "aggregate by" |
+| **sas-read-and-score** | Read + score workflow | "score these records" |
+| **sas-score-workflow** | Route scoring by type | "score with model X.job" |
+
+### 3. Example Workflows
+
+**Find a library and browse tables:**
+```
+You: "Find library Public and show me what tables are in it"
+Agent:
+  1. Loads sas-find-library-smart skill
+  2. Checks CAS, then SAS for "Public"
+  3. Finds it in CAS
+  4. Loads sas-list-tables-smart skill
+  5. Returns list of tables
+```
+
+**Read data and score:**
+```
+You: "Score customers from Public.customers with model churn.mas"
+Agent:
+  1. Loads sas-read-and-score skill
+  2. Loads sas-read-strategy to fetch records
+  3. Loads sas-score-workflow to route to correct scorer
+  4. Returns predictions merged with customer data
+```
+
+## Tool Usage Policy
+
+The agent follows this policy to ensure safety and correctness:
+
+- **Read operations first** — Verify libraries, tables, and models exist before executing
+- **Ambiguity resolved** — Classify unclear requests before tool use
+- **No hallucination** — Never invent SAS asset names, job IDs, or model types
+- **Confirmation required** — Ask before running jobs, scoring, deploying, or modifying
+
+## Ambiguous Terms — Always Clarified
+
+The agent automatically disambiguates these overloaded terms:
+
+| Term | Possible Meanings | Clarification |
+|------|------------------|---------------|
+| **model** | MAS model, SAS job, jobdef, SCR, or repository entry | "Find model X" — which type? |
+| **score/scoring** | Model prediction, not test coverage | "Run scoring" → clarify which model |
+| **job** | SAS job/flow, not CI job | "Run this job" → confirm SAS job |
+| **table** | CAS table or SAS dataset | "Open table" → confirm library & server |
+| **code** | SAS/SQL script, not source code repo | "Show code" → clarify context |
+
+## Response Style
+
+The agent responds with:
+- **Precision** — Names the SAS concept being acted on
+- **Clarity** — Explains steps before taking action
+- **Structure** — Short, organized answers with next steps
+- **Honesty** — Never assumes; always verifies
+
+## Configuration Files
+
+### `copilot-instructions.md`
+Core SAS domain guidance shared across all platforms. Contains:
+- Project overview & operating model
+- Request classification targets
+- Skill-first behavior policy
+- Tool usage policy
+- Safety & correctness guidelines
+
+### `claude-desktop-system-prompt.md`
+Claude Desktop-specific system prompt. Includes:
+- MCP tool availability
+- Skill descriptions with file locations
+- Configuration instructions
+- Safety & ambiguity handling
+
+### `claude-desktop-config.json`
+MCP server configuration template. Customize with:
+- Your SAS Viya URL
+- OAuth credentials
+- Path to `cli.js` in this repository
+- TLS certificate path (optional)
+
+## Troubleshooting
+
+### "MCP Server Not Found"
+- Verify the `cli.js` path is absolute and correct
+- Check that Node.js is in your PATH
+- Restart Claude Desktop
+
+### "Authentication Failed"
+- Verify `VIYA_CLIENT_ID` and `VIYA_CLIENT_SECRET`
+- Ensure `VIYA_URL` is accessible
+- Check that credentials are still valid
+
+### "No Tools Available"
+- Restart Claude Desktop after config changes
+- Check MCP server logs for errors
+- Verify SAS Viya connectivity
+
+## Next Steps
+
+1. **Setup Claude Desktop** — Follow README.md
+2. **Review skills** — Open `skills-index.md` for quick reference
+3. **Start using** — Try: "Find library Public and list tables in it"
+4. **Explore agents** — Ask: "/subagent" for available agents
+
+## Support
+
+For issues or questions:
+- Check the README.md for detailed setup
+- Review specific skill files in `skills/` for usage patterns
+- See `copilot-instructions.md` for domain guidance

package/{.skills → .skills_claude}/skills/sas-find-library-smart/SKILL.md

@@ -13,6 +13,8 @@ description: >
 Intelligently locates a SAS Viya library by checking CAS first, then SAS if the library is not found 
 in CAS. Provides the user with clear information about library availability and location.
 
+> Primary strategy: use `sas-find-resource-strategy` for all resource existence checks.
+
 **If the user specifies the server explicitly** (e.g., "find library Public in cas"):
 - Use the specified server: `server: "cas"` or `server: "sas"`
 - Proceed directly to finding the library
@@ -22,7 +24,7 @@ in CAS. Provides the user with clear information about library availability and
 2. **If not found in CAS**: Check SAS with uppercase library name (`server: "sas"`)
 3. **If not found in either**:
    - Inform user: *"The library '<lib>' was not found in CAS or SAS servers. Please verify the library name."*
-   - Suggest: *"Would you like to list available libraries?"* (suggest `sas-score-list-libraries`)
+   - Ask for corrected library name or explicit server context
 4. **If found**:
    - Inform user which server contains the library: *"Found library '<lib>' in CAS"* or *"Found library '<lib>' in SAS"*
    - Offer next steps: *"Would you like to list tables in this library?"* (suggest `sas-score-list-tables`)
@@ -50,8 +52,9 @@ sas-score-find-library({
 - **For SAS server: always uppercase the library name** (e.g., "public" → "PUBLIC")
 - If library name is missing, ask: *"Which library name would you like to find?"*
 - Return the server where the library was found
-- If not found in either server, clearly inform the user and offer to list available libraries
+- If not found in either server, clearly inform the user and request corrected name or server context
 - Do not proceed with table access until library existence is confirmed
+- Do not use list tools to find whether a library exists
 
 ---
 
@@ -86,7 +89,7 @@ ELSE
 1. Try CAS: `sas-score-find-library({ name: "Public", server: "cas" })`
 2. If not found, try SAS with uppercase: `sas-score-find-library({ name: "PUBLIC", server: "sas" })`
 3. If found in CAS → *"Found library 'Public' in CAS. Would you like to list tables in it?"*
-4. If found in SAS → *"Found library 'PUBLIC' in SAS. Would you like to list tables in it?"*
+4. If found in SAS → *"Found library 'PUBLIC' in SAS. Would you like tPlease confirm the name or specify a server.
 5. If not found → *"The library 'Public' was not found in CAS or SAS. Would you like to list available libraries?"*
 
 **Pattern 2 — Find library with explicit server (CAS)**
@@ -110,9 +113,7 @@ ELSE
 2. Try SAS: `sas-score-find-library({ name: "STAGING", server: "sas" })` → not found
 3. Respond:
    - *"The library 'staging' was not found in CAS or SAS."*
-   - *"Would you like to:"*
-     - *"List all available libraries? (use `sas-score-list-libraries`))"*
-     - *"Check a different library name?"*
+  - *"Please confirm the library name or specify the server (CAS or SAS)."*
 
 **Pattern 5 — Library found, follow-up action**
 > "Verify library samples exists"
@@ -143,12 +144,14 @@ Suggestions:
 • Check the spelling of the library name
 • List available libraries (use list-libraries tool)
 • Try a different library name
+``Specify the intended server (CAS or SAS)
+• Try a different library name
 ```
 
 ---
 
 ## Integration with other skills
 
+- **Primary find strategy**: Use `sas-find-resource-strategy` for existence checks
 - **After finding library → List tables**: Use `sas-list-tables-smart` skill to browse available tables
-- **After finding library → Read data**: Use `sas-read-strategy` skill to retrieve data from tables
-- **Library not found → Explore**: Use `sas-score-list-libraries` tool to see all available libraries
+- **After finding library → Read data**: Use `sas-read-strategy` skill to retrieve data from tabl

package/.skills_claude/skills/sas-find-resource-strategy/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: sas-find-resource-strategy
+description: >
+  Unified strategy for finding SAS Viya resources using find tools only. Supports library, table,
+  model, job, and jobdef lookup with server-aware behavior for CAS/SAS resources. Use this skill
+  whenever the task is to verify whether a resource exists.
+---
+
+# SAS Find Resource Strategy
+
+Use this skill to verify resource existence without using list tools.
+
+## Scope
+
+Supported resource types:
+- library
+- table
+- model
+- job
+- jobdef
+
+## Mandatory rule
+
+- Use only find tools to verify existence.
+- Do not use list tools to find a resource.
+
+## Tool mapping
+
+- Library -> `sas-score-find-library`
+- Table -> `sas-score-find-table`
+- Model -> `sas-score-find-model`
+- Job -> `sas-score-find-job`
+- Jobdef -> `sas-score-find-jobdef`
+
+## Strategy by resource type
+
+### Find library
+
+If server is provided:
+- CAS: `sas-score-find-library({ name: "<lib>", server: "cas" })`
+- SAS: uppercase first, then `sas-score-find-library({ name: "<LIB>", server: "sas" })`
+
+If server is not provided:
+1. Check CAS first.
+2. If not found, check SAS with uppercase library name.
+3. Report where found, or report not found in either.
+
+### Find table
+
+Required inputs:
+- library name
+- table name
+
+If server is provided:
+- CAS: `sas-score-find-table({ lib: "<lib>", name: "<table>", server: "cas" })`
+- SAS: uppercase library first, then `sas-score-find-table({ lib: "<LIB>", name: "<table>", server: "sas" })`
+
+If server is not provided:
+1. Check CAS first.
+2. If not found, check SAS (uppercase library).
+3. If found in both, report both and ask user which server to use for follow-up reads.
+
+### Find model
+
+Use:
+- `sas-score-find-model({ name: "<model>" })`
+
+If a model type suffix is provided (for example `.mas`, `.job`, `.jobdef`, `.scr`):
+- For MAS model discovery, strip suffix and look up base name with `sas-score-find-model`.
+- For `.job` and `.jobdef`, use job and jobdef find tools instead of model find.
+
+### Find job
+
+Use:
+- `sas-score-find-job({ name: "<job>" })`
+
+### Find jobdef
+
+Use:
+- `sas-score-find-jobdef({ name: "<jobdef>" })`
+
+## Clarifying prompts
+
+Ask one focused question if required fields are missing:
+- Library missing for table lookup: "Which library contains the table?"
+- Table name missing: "Which table name should I check?"
+- Resource type ambiguous: "Do you want me to find a library, table, model, job, or jobdef?"
+
+## Output format
+
+For found resources:
+- Confirm exact resource name returned by the tool.
+- Confirm server when applicable (CAS/SAS).
+
+For not found resources:
+- State that the resource was not found.
+- Ask for corrected name or server context.
+
+## Examples
+
+- "find library Samples" -> CAS first, then SAS fallback using uppercase.
+- "find table costchange in Samples" -> CAS first, then SAS fallback using uppercase library.
+- "find model breastcancer" -> `sas-score-find-model`.
+- "find job simplejob" -> `sas-score-find-job`.
+- "find jobdef daily_run" -> `sas-score-find-jobdef`.

package/.skills_claude/skills/sas-list-resource-strategy/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: sas-list-resource-strategy
+description: >
+  Unified strategy for listing SAS Viya resources using list tools. Supports libraries,
+  tables, models, jobs, and jobdefs. Always normalize pagination so start and limit are
+  never null: default start=1 and limit=10 when not provided.
+---
+
+# SAS List Resource Strategy
+
+Use this skill to list resources with consistent pagination defaults.
+
+## Scope
+
+Supported resource types:
+- library
+- table
+- model
+- job
+- jobdef
+
+## Mandatory pagination rule
+
+For every list operation:
+- `start` must never be null
+- `limit` must never be null
+- If `start` is missing or null, set `start: 1`
+- If `limit` is missing or null, set `limit: 10`
+
+Normalization pattern:
+```
+start = (start == null) ? 1 : start
+limit = (limit == null) ? 10 : limit
+```
+
+## Tool mapping
+
+- Library -> `sas-score-list-libraries`
+- Table -> `sas-score-list-tables`
+- Model -> `sas-score-list-models`
+- Job -> `sas-score-list-jobs`
+- Jobdef -> `sas-score-list-jobdefs`
+
+## Strategy by resource type
+
+### List libraries
+
+Use:
+```
+sas-score-list-libraries({
+  server: "all" | "cas" | "sas",  // optional based on user intent
+  start: 1,
+  limit: 10
+})
+```
+
+If user provides server, honor it. If not, use default server behavior.
+
+### List tables
+
+Required input:
+- library name (`lib`)
+
+Use:
+```
+sas-score-list-tables({
+  lib: "libraryname",
+  server: "cas" | "sas",  // optional if strategy/tool supports detection
+  start: 1,
+  limit: 10
+})
+```
+
+If `lib` is missing, ask: "Which library should I list tables from?"
+
+### List models
+
+Use:
+```
+sas-score-list-models({
+  start: 1,
+  limit: 10
+})
+```
+
+### List jobs
+
+Use:
+```
+sas-score-list-jobs({
+  start: 1,
+  limit: 10
+})
+```
+
+### List jobdefs
+
+Use:
+```
+sas-score-list-jobdefs({
+  start: 1,
+  limit: 10
+})
+```
+
+## Clarifying prompts
+
+Ask one focused question if required context is missing:
+- Resource type unclear: "Do you want libraries, tables, models, jobs, or jobdefs?"
+- Listing tables without library: "Which library should I list tables from?"
+
+## Output and paging
+
+- Return the listed resources from the selected tool.
+- If result count equals `limit`, suggest next page with `start + limit`.
+- Keep using normalized pagination defaults unless user overrides.
+
+## Examples
+
+- "list jobs" -> `sas-score-list-jobs({ start: 1, limit: 10 })`
+- "list models" -> `sas-score-list-models({ start: 1, limit: 10 })`
+- "list jobdefs" -> `sas-score-list-jobdefs({ start: 1, limit: 10 })`
+- "list tables in Public" -> `sas-score-list-tables({ lib: "Public", start: 1, limit: 10 })`
+- "next jobs" after `{ start: 1, limit: 10 }` -> `sas-score-list-jobs({ start: 11, limit: 10 })`

package/{.skills → .skills_claude}/skills/sas-list-tables-smart/SKILL.md

@@ -13,7 +13,7 @@ description: >
 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 exists using the `sas-find-library-smart` skill.
+> **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"):
@@ -25,7 +25,7 @@ when not explicitly specified.
 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: *"Would you like to list available libraries?"* (suggest `sas-score-list-libraries`)
+  - Ask for corrected library name or explicit server context
 
 ---
 
@@ -124,4 +124,3 @@ ELSE
 | 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-library-smart` skill to verify library exists first |
-

package/{.skills → .skills_claude}/skills/sas-read-and-score/SKILL.md

@@ -20,9 +20,10 @@ with a deployed MAS model.
 ## Pre-flight verification
 
 **Before attempting to read or score table data:**
-1. **Verify library exists**: Use `sas-find-library-smart` to check the library in CAS first, then SAS if needed
-2. **Verify table exists**: Use `sas-score-find-table` to confirm the table is in the library
-3. **Confirm server location**: Ensure you know which server (CAS or SAS) contains the 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.
 

package/{.skills → .skills_claude}/skills/sas-read-strategy/SKILL.md

@@ -15,15 +15,11 @@ of the data operation. Determines which server contains the data and which retri
 
 ## Determine the server location
 
-Before retrieving data, verify the library and determine which server(s) contain the table:
+Before retrieving data, locate the specific table first and determine which server(s) contain it:
 
-**Step 1: Verify library existence**
-- Use `sas-find-library-smart` skill to check the library in CAS first, then SAS if needed
-- This establishes the correct server and uppercase convention for SAS libraries
-- Informs the user which server contains the library
-
-**Step 2: Locate the specific table**
-- Use `sas-score-find-table` to check if the table exists in the library
+**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"`
@@ -58,19 +54,21 @@ Ask yourself: does the user already have the data in hand?
 sas-score-read-table({
   table: "tablename",
   lib: "libraryname",
-  server: "cas" or "sas",  // determined from sas-score-find-table check
+  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-score-find-table`
+- 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
 
 ---
 
@@ -91,7 +89,7 @@ sas-query({
 ```
 
 **Rules:**
-- Check which server(s) contain the table using `sas-score-find-table` first
+- 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
@@ -129,7 +127,7 @@ sas-query({
 
 | Problem | Action |
 |---|---|
-| Library not found | Use `sas-find-library-smart` skill to verify the library exists |
+| 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 |
@@ -141,7 +139,7 @@ sas-query({
 
 ## Integration with other skills
 
-- **Before this skill**: Use `sas-find-library-smart` to verify and locate the library
+- **Before this skill**: Use `sas-find-resource-strategy` for table-first resource lookup
 - **After this skill**: Use `sas-read-and-score` to score the retrieved data
 
 ---

package/{.skills → .skills_claude}/skills/sas-request-classifier/SKILL.md

@@ -66,4 +66,4 @@ 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
+- any remaining ambiguity or clarifying questions needed