@sassoftware/sas-score-mcp-serverjs 0.4.1-18 → 0.4.1-20

package/.claude/mcp-tool-description-optimizer/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: mcp-tool-description-optimizer
+description: >
+  Optimize MCP (Model Context Protocol) tool descriptions for token efficiency and LLM routing accuracy.
+  Use this skill whenever a user shares a raw, verbose, or poorly structured MCP tool description and wants
+  it improved, rewritten, or reviewed. Trigger on phrases like: "optimize this tool description",
+  "rewrite my MCP tool description", "make this tool description more efficient", "clean up my tool spec",
+  "improve how Claude picks my tool", or when a user pastes a JavaScript/TypeScript tool description string
+  and asks for help with it. Also trigger when the user mentions token efficiency, tool routing,
+  or LLM disambiguation in the context of MCP servers.
+---
+
+# MCP Tool Description Optimizer
+
+Rewrites verbose or poorly structured MCP tool descriptions into compact, signal-rich versions that
+improve LLM tool selection accuracy while reducing token usage.
+
+## Why this matters
+
+Claude and other LLMs select MCP tools based entirely on the `description` field. Descriptions that are
+too long, redundant, or badly structured waste context tokens and reduce routing precision.
+A well-optimized description:
+- States what the tool does and when to use it upfront
+- Eliminates redundancy (same info repeated across sections)
+- Uses a compact, scannable format (labeled blocks, not nested markdown)
+- Includes clear negative examples to prevent mis-routing
+- Keeps parameters terse — name, type, default, one-line purpose
+
+---
+
+## Optimization Process
+
+### Step 1 — Analyze the input description
+
+Before rewriting, identify these problems in the original:
+
+| Problem | Example |
+|---|---|
+| **Redundancy** | Trigger phrases listed in 3+ places |
+| **Filler sections** | "Rationale", "Behavior Summary", "Response Contract" with no routing signal |
+| **Orphaned syntax** | Arrows (`→`) or bullets with no target |
+| **Overlong examples** | Long prose examples when one-liners suffice |
+| **Heavy markdown** | `##` headers for every minor point |
+| **Duplicated parameter docs** | Same param described in both a table and prose |
+
+Call out 2–4 of the most impactful issues before writing the new version.
+
+### Step 2 — Rewrite using the standard template
+
+Use this exact block structure for the output. Omit blocks that don't apply.
+
+```
+<tool-name> — <one-line purpose>.
+
+USE when: <comma-separated user intents or trigger phrases>
+DO NOT USE for: <comma-separated anti-patterns with → redirect where applicable>
+
+PARAMETERS
+- <name>: <type> (default: <val>) — <one-line purpose>
+...
+
+ROUTING RULES
+- "<trigger phrase>" → { param: value }
+- "<trigger phrase>" → { param: value }
+- <ambiguous case> → <ask for clarification | default behavior>
+
+EXAMPLES
+- "<user utterance>" → { param: value, ... }
+- "<user utterance>" → { param: value, ... }
+
+NEGATIVE EXAMPLES (do not route here)
+- "<user utterance>" → <correct tool>
+
+PAGINATION (include only if tool is paginated)
+If returned count === limit → hint: next start = start + limit.
+If start > 1 and result empty → note paging may exceed available items.
+
+ERRORS
+<One or two lines: return structure, hallucination policy>
+```
+
+### Step 3 — Apply these rules consistently
+
+**USE/DO NOT USE block**
+- Write as comma-separated inline list, not a bullet list
+- DO NOT USE entries should name the redirect tool in parentheses where known
+
+**ROUTING RULES block**
+- One rule per line; quote the trigger phrase; use `→ { }` for param mapping
+- Consolidate synonyms on one line: `"cas libs / cas libraries / in cas" → { server: 'cas' }`
+- List the default/fallback rule last
+
+**PARAMETERS block**
+- One line per param: `- name: type (default: val) — purpose`
+- Skip obvious params (e.g. don't explain what `limit` means if it's standard pagination)
+
+**EXAMPLES block**
+- Each example fits on one line
+- For "next page" examples, include the prior call's state inline: `"next" (prev: start:1, limit:10) → { start: 11, limit: 10 }`
+
+**NEGATIVE EXAMPLES block**
+- Only include when mis-routing is a real risk
+- Format: `"<utterance>" → <correct-tool-name>`
+
+**Tone**
+- Imperative, terse. No filler words ("Please note that...", "It is important to...")
+- Never include a "Rationale" or "Behavior Summary" section — if behavior matters, encode it as a rule
+
+### Step 4 — Validate before returning
+
+Check the rewritten description against this list:
+
+- [ ] No trigger phrase appears in more than one block
+- [ ] No orphaned `→` arrows or dangling bullets
+- [ ] Parameter defaults are stated explicitly
+- [ ] Negative examples cover the tool's most common mis-routing risks
+- [ ] Total length is ≤ 50% of the original (target: 30–40% reduction)
+
+---
+
+## Output format
+
+Always return:
+
+1. **Analysis** — 2–4 bullet points naming the key issues found in the original
+2. **Rewritten description** — inside a JavaScript code block (matching the user's original code style)
+3. **Change summary** — a short table or bullet list of what changed and why
+
+See `references/examples.md` for before/after examples of real tool descriptions.

package/.claude/mcp-tool-description-optimizer/references/examples.md

@@ -0,0 +1,123 @@
+# Before / After Examples
+
+## Example 1 — list-libraries (SAS Viya MCP)
+
+### BEFORE (~620 tokens)
+
+```
+## list-libraries — enumerate CAS or SAS libraries
+
+LLM Invocation Guidance (critical)
+Use THIS tool when the user asks for: "list libs", "list libraries", "show cas libs", "show sas libs",
+"what libraries are available", "list caslib(s)", "enumerate libraries", "libraries in cas", "libraries in sas".
+DO NOT use this tool when the user asks for: tables inside a specific library (choose listTables),
+columns/metadata of a table, job/program execution, models, or scoring.
+
+Trigger Phrase → Parameter Mapping
+- "cas libs" / "in cas" / "cas libraries" → { server: 'cas' }
+- "sas libs" / "in sas" / "base sas libraries" → { server: 'sas' }
+- "all libs" / "all libs" -> {server: 'all'}
+→ { server: 'all' }
+- "next" (after prior call) → { start: previous.start + previous.limit }
+- "first 20 cas libs" → { server: 'cas', limit: 20 }
+- If server unspecified: default to all.
+
+Parameters
+- server (cas|sas|all, default 'all')
+- limit (integer > 0, default 10)
+- start (1-based offset, default 1)
+- where (optional filter expression, default '')
+
+Response Contract
+Return JSON-like structure from helper; consumers may extract an array of library objects/names.
+If number of returned items === limit supply a pagination hint: start = start + limit.
+
+Behavior Summary
+- Pure listing; no side effects.
+- If ambiguous short request like "list" or "libs" and no prior context: assume { server: 'cas' }.
+- If user explicitly asks for ALL (e.g. "all cas libs") and count likely large, honor limit=50 unless
+  user supplies a value; include note about paging.
+
+Disambiguation Rules
+- If user mentions a singular library name plus desire for tables ("list tables in SASHELP") choose
+  listTables (not this tool).
+- If user mixes "tables" and "libraries" ask for clarification unless clearly about libraries.
+
+Examples
+- "list libraries" → { server: 'all', start:1, limit:10 }
+- "list libs" → { server: 'all', start:1, limit:10 }
+- "list sas libs" → { server: 'sas' }
+- "list cas libraries" → { server: 'cas' }
+- "show me 25 cas libraries" → { server:'cas', limit:25 }
+- "next" (after prior call {start:1,limit:10}) → { start:11, limit:10 }
+- "filter cas libs" (no criterion) → ask: "Provide a filter or continue without one?"
+
+Negative Examples (do not route here)
+- "list tables in public" (route to list-tables)
+- "list models, list tables, list jobs, list jobdef and similar request"
+- "describe library" (likely list-tables or table-info depending on follow-up)
+- "run program to make a lib" (run-sas-program tool)
+
+Error Handling
+- On backend error: return structured error with message field; do not hallucinate libraries.
+- Empty result set → return empty list plus (if start>1) a hint that paging may have exceeded available items.
+
+Rationale
+Concise, signal-rich description increases probability this spec is selected for generic library
+enumeration intents.
+```
+
+### AFTER (~210 tokens)
+
+```
+list-libraries — enumerate CAS or SAS libraries.
+
+USE when: list/show/enumerate libraries, caslibs, sas libs, available libraries
+DO NOT USE for: listing tables in a library (→ list-tables), column/table metadata, job execution, models, scoring
+
+PARAMETERS
+- server: 'cas' | 'sas' | 'all' (default: 'all')
+- limit: integer > 0 (default: 10)
+- start: 1-based offset (default: 1)
+- where: optional filter expression (default: '')
+
+ROUTING RULES
+- "cas libs / cas libraries / in cas"          → { server: 'cas' }
+- "sas libs / sas libraries / in sas"          → { server: 'sas' }
+- "all libs / all libraries"                   → { server: 'all' }
+- "all cas libs" with no limit given           → { server: 'cas', limit: 50 } + paging note
+- "next" after prior call (start:S, limit:L)   → { start: S + L, limit: L }
+- "filter cas libs" with no filter given       → ask: "What filter expression should I apply?"
+- server unspecified / ambiguous "list"/"libs" → { server: 'cas' }
+
+EXAMPLES
+- "list libraries"                → { server: 'all', start: 1, limit: 10 }
+- "list cas libraries"            → { server: 'cas', start: 1, limit: 10 }
+- "show me 25 sas libs"           → { server: 'sas', limit: 25, start: 1 }
+- "next" (prev: start:1,limit:10) → { server: <same>, start: 11, limit: 10 }
+
+NEGATIVE EXAMPLES (do not route here)
+- "list tables in SASHELP"        → list-tables
+- "list models / jobs / jobdefs"  → respective tools
+- "run a program to create a lib" → run-sas-program
+
+PAGINATION
+If returned count === limit → hint: next start = start + limit.
+If start > 1 and result empty → note paging may exceed available items.
+
+ERRORS
+Return structured error with message field. Never hallucinate library names.
+```
+
+**Token reduction: ~66%**
+
+---
+
+## Key patterns illustrated
+
+- Trigger phrases consolidated from 3 blocks → 1 ROUTING RULES block
+- "Rationale", "Behavior Summary", "Response Contract" sections eliminated
+- Orphaned `→ { server: 'all' }` arrow removed
+- Parameter defaults made explicit inline
+- Examples trimmed to one line each
+- Negative examples now name the redirect tool explicitly

package/.claude/sas-find-library-smart/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: sas-find-library-smart
+description: >
+  Find a SAS Viya library (libref or caslib) with intelligent server detection. Automatically checks 
+  CAS first, then SAS if not found. Use this skill when the user needs to verify a library exists,
+  before accessing tables within it. Trigger phrases include: "find library", "does library exist",
+  "check if library", "locate library", "is there a library named", "verify library", or any request 
+  to confirm a library's availability across servers.
+---
+
+# Smart Library Lookup (Find Library)
+
+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.
+
+**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
+
+**If the server is NOT specified:**
+1. **First attempt**: Check CAS (`server: "cas"`)
+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`)
+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`)
+
+---
+
+## Using sas-score-find-library
+
+**When:**
+- User wants to verify a library exists
+- User needs to determine which server contains a library
+- User wants to check library availability before accessing it
+- User wants to explore available libraries (before querying)
+
+**How:**
+```
+sas-score-find-library({
+  name: "libraryname",          // required
+  server: "cas" or "sas"        // optional; determined by server check if not specified
+})
+```
+
+**Rules:**
+- Always determine the correct server first (cas → sas → neither)
+- **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
+- Do not proceed with table access until library existence is confirmed
+
+---
+
+## Smart server detection logic
+
+```
+IF server specified by user
+  → IF server is "sas"
+      → uppercase lib
+  → use that server, call sas-score-find-library
+ELSE
+  → TRY sas-score-find-library(lib, server="cas")
+    IF library found
+      → success, inform user: library found in CAS
+    ELSE
+      → uppercase lib
+      → TRY sas-score-find-library(lib.toUpperCase(), server="sas")
+        IF library found
+          → success, inform user: library found in SAS
+        ELSE
+          → inform user library not found in either server
+          → offer to list available libraries
+```
+
+---
+
+## Common patterns
+
+**Pattern 1 — Find library, server unspecified**
+> "Find library Public"
+
+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?"*
+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)**
+> "Find library MyData in cas"
+
+1. Skip server detection
+2. Call: `sas-score-find-library({ name: "MyData", server: "cas" })`
+3. Result → *"Found library 'MyData' in CAS"* or *"Library 'MyData' not found in CAS"*
+
+**Pattern 3 — Find library with explicit server (SAS)**
+> "Does library SASHELP exist in sas"
+
+1. Skip server detection
+2. Uppercase lib: `sas-score-find-library({ name: "SASHELP", server: "sas" })`
+3. Result → *"Found library 'SASHELP' in SAS"* or *"Library 'SASHELP' not found in SAS"*
+
+**Pattern 4 — Library not found, offer next steps**
+> "Check if library staging exists"
+
+1. Try CAS: `sas-score-find-library({ name: "staging", server: "cas" })` → not found
+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?"*
+
+**Pattern 5 — Library found, follow-up action**
+> "Verify library samples exists"
+
+1. Try CAS: `sas-score-find-library({ name: "samples", server: "cas" })` → found
+2. Respond:
+   - *"Found library 'samples' in CAS."*
+   - *"Would you like to list tables in this library? (use `sas-score-list-tables`))"*
+
+---
+
+## Output presentation
+
+**When library is found:**
+```
+✓ Found library '<lib>' in <SERVER>
+
+Would you like to:
+• List tables in this library (use sas-list-tables-smart skill)
+• Read data from a specific table (use sas-read-strategy skill)
+```
+
+**When library is not found:**
+```
+✗ Library '<lib>' not found in either CAS or SAS
+
+Suggestions:
+• Check the spelling of the library name
+• List available libraries (use list-libraries tool)
+• Try a different library name
+```
+
+---
+
+## Integration with other skills
+
+- **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

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

@@ -0,0 +1,127 @@
+---
+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 exists using the `sas-find-library-smart` 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: *"Would you like to list available libraries?"* (suggest `sas-score-list-libraries`)
+
+---
+
+## 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
+
+---
+
+## 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-library-smart` skill to verify library exists first |
+

package/.claude/sas-read-and-score/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: sas-read-and-score
+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-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
+
+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
+- 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-library-smart` to verify the library exists
+- **For data retrieval**: Use `sas-read-strategy` to choose the right read tool (read-table vs sas-query)
+- **For scoring**: Use `sas-score-workflow` for advanced scoring options beyond MAS models