@sassoftware/sas-score-mcp-serverjs 0.4.1-5 → 0.4.1-7

package/cli.js

@@ -21,7 +21,8 @@ import { randomUUID } from 'node:crypto';
 import readCerts from './src/toolHelpers/readCerts.js';
 
 import { fileURLToPath } from 'url';
-import { dirname } from 'path';
+import { dirname, join } from 'path';
+import os from 'os';
 import { parseArgs } from "node:util";
 
 import NodeCache from 'node-cache';
@@ -76,6 +77,10 @@ const args = parseArgs({
       type: 'boolean',
       short: 'v',
       description: 'Show version'
+    },
+    'install-skills': {
+      type: 'boolean',
+      description: 'Install bundled skills to ~/.claude/skills/'
     }
   },
   strict: false,
@@ -97,6 +102,7 @@ Options:
   -e, --envfile <path>        Environment file path
   -h, --help                  Show this help message
   --version                   Show version
+  --install-skills            Install bundled skills to ~/.claude/skills/
 
 Environment Variables:
   Use .env file or set environment variables for configuration.
@@ -112,6 +118,39 @@ if (args.values.version) {
   process.exit(0);
 }
 
+// Handle install-skills flag
+if (args.values['install-skills']) {
+  const skillsSrc = join(__dirname, 'skills');
+  const skillsDest = join(os.homedir(), '.claude', 'skills');
+
+  if (!fs.existsSync(skillsSrc)) {
+    console.error('No skills directory found in this package.');
+    process.exit(1);
+  }
+
+  fs.mkdirSync(skillsDest, { recursive: true });
+
+  const skills = fs.readdirSync(skillsSrc, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => d.name);
+
+  if (skills.length === 0) {
+    console.error('No skills found to install.');
+    process.exit(1);
+  }
+
+  for (const skill of skills) {
+    const src = join(skillsSrc, skill);
+    const dest = join(skillsDest, skill);
+    fs.cpSync(src, dest, { recursive: true });
+    console.error(`  installed: ${skill}`);
+  }
+
+  console.error(`\n${skills.length} skill(s) installed to ${skillsDest}`);
+  console.error('Restart Claude Code to activate the new skills.');
+  process.exit(0);
+}
+
 if (process.env.ENVFILE === 'FALSE') {
   //use this when using remote mcp server and no .env file is desired
   console.error('[Note]: Skipping .env file as ENVFILE is set to FALSE...');
@@ -354,7 +393,10 @@ console.error('[Note] appEnvBase is', JSON.stringify(appEnvBase, null,2));
 // creat a dummy sessionId for stdio since there is only one session and transport in that case, and tools need a sessionId to access the appEnvBase and contexts
 let sessionId = randomUUID();
 sessionCache.set(sessionId, appEnvBase);
+sessionCache.set('currentId', sessionId);
+useHapi = false;
 if (mcpType === 'stdio') {
+
   console.error('[Note] Setting up stdio transport with sessionId:', sessionId);
   console.error('[Note] Used in setting up tools and some persistence(not all).');
   await coreSSE(mcpServer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sassoftware/sas-score-mcp-serverjs",
-  "version": "0.4.1-5",
+  "version": "0.4.1-7",
   "description": "A mcp server for SAS Viya",
   "author": "Deva Kumar <deva.kumar@sas.com>",
   "license": "Apache-2.0",

package/skills/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/skills/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/skills/sas-read-and-score/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: sas-read-and-score
+description: >
+  Guide the full read → score workflow in SAS Viya: reading records from a table (using read-table
+  or sas-query) and then scoring them with a MAS model (using 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 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.
+
+This skill chains two sub-skills:
+1. **sas-read-strategy** — Choose between `read-table` and `sas-query`
+2. **sas-score-workflow** — Validate model, invoke scoring, present results
+
+---
+
+## Quick reference
+
+1. **Does the user already have data in hand?**
+   - Yes → skip to Step 2 (scoring)
+   - No → use `sas-read-strategy` to fetch data
+
+2. **Is the model name familiar?**
+   - Yes → proceed to score
+   - No → pause and use `find-model` / `model-info`
+
+3. **Invoke model-score** with the fetched data
+
+4. **Merge results** and present as a table
+
+---
+
+## Common flows
+
+**Flow A — Score rows from a table directly**
+> "Score the first 10 customers in Public.customers with the churn model"
+
+1. Apply `sas-read-strategy` → use `read-table` to fetch 10 rows
+2. Apply `sas-score-workflow` → invoke `model-score` and present results
+
+**Flow B — Score results of an analytical query**
+> "Score high-value customers (spend > 5000) in mylib.sales with the fraud model"
+
+1. Apply `sas-read-strategy` → use `sas-query` for aggregation
+2. Apply `sas-score-workflow` → invoke `model-score` and present results
+
+**Flow C — User supplies scenario data directly**
+> "Score age=45, income=60000, region=South with the churn model"
+
+1. Skip read strategy
+2. Apply `sas-score-workflow` → invoke `model-score` and present result
+
+**Flow D — Model unfamiliar**
+> "Score Public.applicants with the creditRisk2 model"
+
+1. Model unfamiliar → use `find-model` to verify existence
+2. Apply `sas-read-strategy` to fetch data
+3. Apply `sas-score-workflow` to score
+
+---
+
+## For detailed guidance
+
+- **Read strategy decisions?** See `sas-read-strategy` skill
+- **Scoring validation and presentation?** See `sas-score-workflow` skill
+
+**Flow D — Model unfamiliar**
+> "Score Public.applicants with the creditRisk2 model"
+
+1. Pause — "creditRisk2" is new
+2. Suggest: `find-model` to confirm it exists, `model-info` to get input variables
+3. Once confirmed → `read-table` + `model-score`
+
+---
+
+## Error handling
+
+| Problem | Action |
+|---|---|
+| Table not found | Ask for correct lib.tablename |
+| Model not found | Suggest find-model |
+| Field name mismatch | Show mismatch, ask user to confirm mapping |
+| Scoring error | Return structured error, suggest model-info |
+| Empty read result | Tell user, ask if they want to adjust the query/filter |

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

@@ -0,0 +1,143 @@
+---
+name: sas-read-strategy
+description: >
+  Guide the user in choosing the right data retrieval tool: read-table (for raw row access with filters)
+  or 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 `read-table` and `sas-query` based on the user's intent and the nature
+of the data operation.
+
+---
+
+## Determine the server location
+
+Before retrieving data, check which server(s) contain the table:
+
+1. **Check both servers**: Use `find-table` to check if the table exists in CAS and/or SAS
+2. **Decide server placement**:
+   - 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 ask which library to search in
+
+---
+
+## 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 | `read-table` | "Show me 10 rows from customers where status='active'" |
+| Aggregate/summarize, calculate, join tables, analytical question | `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:**
+```
+read-table({
+  table: "tablename",
+  lib: "libraryname",
+  server: "cas" or "sas",  // determined from find-table check
+  limit: N,        // default 10, adjust based on user request
+  where: "..."     // optional SQL WHERE clause
+})
+```
+
+**Rules:**
+- Always determine the server first using `find-table`
+- 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?"*
+- If table exists in both servers, ask user which to use
+- Return raw column values; do not transform or aggregate
+
+---
+
+## 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 `find-table` 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"
+
+→ `read-table({ table: "customers", lib: "Public", limit: 5 })`
+
+**Pattern B — Filtered retrieval**
+> "Get all high-value orders (amount > 5000) from mylib.orders"
+
+→ `read-table({ table: "orders", lib: "mylib", where: "amount > 5000" })`
+
+**Pattern C — Aggregation**
+> "What is the average price by make in Public.cars?"
+
+→ `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-query()` with a JOIN in the generated SQL
+
+---
+
+## Error handling
+
+| Problem | Action |
+|---|---|
+| Table not found in either server | Ask: *"Which library contains the table? (e.g., Public, Samples, mylib)"* |
+| 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 |
+| Library not found | Ask: *"Which library contains the table? (e.g., Public, Samples, mylib)"* |
+| 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 |
+
+---
+
+## Next steps
+
+Once data is retrieved, decide the next action based on context:
+- If user wants to **score** the data → move to `sas-score-workflow`
+- If user wants to **visualize** → present as table or chart
+- If user wants to **export** → format and offer download
+- If user wants to **analyze further** → ask clarifying questions