@sassoftware/sas-score-mcp-serverjs 0.3.18 → 0.4.0

package/cli.js

@@ -16,29 +16,112 @@ import createMcpServer from './src/createMcpServer.js';
 import fs from 'fs';
 import { randomUUID } from 'node:crypto';
 
-import refreshToken from './src/toolHelpers/refreshToken.js';
-import getOptsViya from './src/toolHelpers/getOptsViya.js';
+//import refreshToken from './src/toolHelpers/refreshToken.js';
+//import getOptsViya from './src/toolHelpers/getOptsViya.js';
+import readCerts from './src/toolHelpers/readCerts.js';
 
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
+import { parseArgs } from "node:util";
 
 import NodeCache from 'node-cache';
-import getOpts from './src/toolHelpers/getOpts.js';
+//import getOpts from './src/toolHelpers/getOpts.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 let pkg = fs.readFileSync(__dirname + '/package.json', 'utf8');
 
+// Parse command line arguments
+const args = parseArgs({
+  options: {
+    port: {
+      type: 'string',
+      short: 'p',
+      description: 'Port to run the server on'
+    },
+    mcptype: {
+      type: 'string',
+      short: 'm',
+      description: 'MCP server type (http or stdio)'
+    },
+    viya: {
+      type: 'string',
+      short: 'v',
+      description: 'Viya server URL'
+    },
+    authflow: {
+      type: 'string',
+      short: 'a',
+      description: 'Authentication flow (sascli, code, token)'
+    },
+    profile: {
+      type: 'string',
+      description: 'SAS CLI profile name'
+    },
+    config: {
+      type: 'string',
+      description: 'SAS CLI config directory'
+    },
+    envfile: {
+      type: 'string',
+      short: 'e',
+      description: 'Environment file path'
+    },
+    help: {
+      type: 'boolean',
+      short: 'h',
+      description: 'Show help message'
+    },
+    version: {
+      type: 'boolean',
+      short: 'v',
+      description: 'Show version'
+    }
+  },
+  strict: false,
+  allowPositionals: false
+});
+
+// Handle help flag
+if (args.values.help) {
+  console.log(`
+Usage: sas-score-mcp-serverjs [options]
+
+Options:
+  -p, --port <port>           Port to run the server on (default: 8080)
+  -m, --mcptype <type>        MCP server type: http or stdio (default: http)
+  -v, --viya <url>            Viya server URL
+  -a, --authflow <flow>       Authentication flow: sascli, code, or token
+  --profile <name>            SAS CLI profile name
+  --config <path>             SAS CLI config directory
+  -e, --envfile <path>        Environment file path
+  -h, --help                  Show this help message
+  --version                   Show version
+
+Environment Variables:
+  Use .env file or set environment variables for configuration.
+  See README.md for more information.
+  `);
+  process.exit(0);
+}
+
+// Handle version flag
+if (args.values.version) {
+  let pkgJson = JSON.parse(pkg);
+  console.log(pkgJson.version);
+  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...');
 } else {
   console.error('Working Directory', process.cwd());
-  let envf = process.cwd() + '\\.env'; 
+  let envf = process.env.ENVFILE || (process.cwd() + '\\.env');
   //__dirname + '\\.env';
   console.error('Env file:', envf); 
   if (fs.existsSync(envf)) {
-    console.error(`Loading environment variables rom ${envf}...`);
+    console.error(`Loading environment variables from ${envf}...`);
     let e = iconfig(envf); // avoid dotenv since it writes to console.log
     console.error('[Note]: Environment variables loaded from .env file...');
     console.error('Loaded env variables:', e);
@@ -50,6 +133,37 @@ if (process.env.ENVFILE === 'FALSE') {
   }
 }
 
+// Apply command line arguments to override environment variables
+if (args.values.port) {
+  process.env.PORT = args.values.port;
+  console.error(`[Note] PORT set from command line: ${args.values.port}`);
+}
+
+if (args.values.mcptype) {
+  process.env.MCPTYPE = args.values.mcptype;
+  console.error(`[Note] MCPTYPE set from command line: ${args.values.mcptype}`);
+}
+
+if (args.values.viya) {
+  process.env.VIYA_SERVER = args.values.viya;
+  console.error(`[Note] VIYA_SERVER set from command line: ${args.values.viya}`);
+}
+
+if (args.values.authflow) {
+  process.env.AUTHFLOW = args.values.authflow;
+  console.error(`[Note] AUTHFLOW set from command line: ${args.values.authflow}`);
+}
+
+if (args.values.profile) {
+  process.env.SAS_CLI_PROFILE = args.values.profile;
+  console.error(`[Note] SAS_CLI_PROFILE set from command line: ${args.values.profile}`);
+}
+
+if (args.values.config) {
+  process.env.SAS_CLI_CONFIG = args.values.config;
+  console.error(`[Note] SAS_CLI_CONFIG set from command line: ${args.values.config}`);
+}
+
 if (process.env.APPHOST == null) {
   process.env.APPHOST = 'localhost';
 } 
@@ -70,7 +184,7 @@ console.error(
 // and storage provided by cloud providers
 console.error(process.env.COMPUTECONTEXT);
 debugger;
-let sessionCache = new NodeCache({ stdTTL: 0, checkperiod: 2 * 60, useClones: false });
+let sessionCache = new NodeCache({ stdTTL: 24 *60*60, checkperiod: 2 * 60, useClones: false });
 
 //
 // Load environment variables from .env file if present
@@ -135,6 +249,8 @@ const appEnvBase = {
     process.env.TOOLSETS != null
       ? process.env.TOOLSETS.split(',')
       : ['default'],
+  // command line arguments
+  cliArgs: args.values,
   // user defined tools
   //runtime variables
   tokenRefresh: process.env.TOKENREFRESH === 'FALSE' ? false : true,
@@ -167,6 +283,7 @@ const appEnvBase = {
     casSession: null, /* restaf cas session object */
     computeSession: null, /* restaf compute session object */
     viyaCert: null, /* ssl/tsl certificates to connect to viya */
+    appCert: null,
     logonPayload: null, /* viya logon payload  to connect to viya */
     casServerId: null,
     computeSessonId: null,
@@ -179,10 +296,15 @@ const appEnvBase = {
 process.env.APPPORT=appEnvBase.PORT;
 
 // setup TLS options for viya calls
-
 console.error('[Note]Viya SSL dir set to: ' + appEnvBase.VIYACERT);
-await getOptsViya(appEnvBase); /* appEnvBase.contexts.viyaCert is set here */
-appEnvBase.tlsOpts = getOpts(appEnvBase);
+appEnvBase.contexts.viyaCert = readCerts(appEnvBase.VIYACERT); /* appEnvBase.contexts.viyaCert is set here */
+
+// setup TLS options for app server (expressMcpServer or hapiMcpServer)
+
+console.error('[Note]App SSL dir set to: ' + appEnvBase.SSLCERT);
+appEnvBase.tlsOpts = readCerts(appEnvBase.SSLCERT);
+appEnvBase.contexts.appCert = appEnvBase.tlsOpts; /* just for completeness */
+
 appEnvBase.contexts.storeConfig = {
   casProxy: true,
   options: { ns: null, proxyServer: null, httpOptions: appEnvBase.contexts.viyaCert }
@@ -205,19 +327,7 @@ if (appEnvBase.TOKENFILE != null) {
   }
 }
 
-// handle refresh token flow 
-// use this for testing only. 
-if (appEnvBase.REFRESH_TOKEN != null) {
-  appEnvBase.refreshToken = appEnvBase.REFRESH_TOKEN;
-  appEnvBase.AUTHFLOW = 'refresh';
-  let t = await refreshToken(appEnvBase, { token: appEnvBase.REFRESH_TOKEN, host: appEnvBase.VIYA_SERVER });
-  appEnvBase.contexts.logonPayload = {
-    host: appEnvBase.VIYA_SERVER,
-    authType: 'server',
-    token: t,
-    tokenType: 'Bearer'
-  }
-}
+
 
 // if authflow is cli or code, postpone getting logonPayload until needed
 
@@ -232,16 +342,20 @@ let appEnvTemplate = Object.assign({}, appEnvBase);
 
 sessionCache.set('appEnvTemplate', appEnvTemplate);
 
-let transports = {};
+let transports = {
+  "dummy": null
+};
 sessionCache.set('transports', transports);
 
 // set this for stdio transport use
 // dummy sessionId for use in the tools  
 let useHapi = process.env.AUTHFLOW === 'code' ? true : false;
+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);
+useHapi = false; // for now disable hapi for authflow code since it is not working well, and code flow is not commonly used in server side applications, and http transport works better for code flow since it requires multiple back and forth calls to complete the auth process which is not ideal for stdio transport, this will be revisited in the future to either fix the issues with hapi or implement the code flow in a way that works better with stdio transport
 if (mcpType === 'stdio') {
-  let sessionId = randomUUID();
-  sessionCache.set('currentId', sessionId);
-  sessionCache.set(sessionId, appEnvBase);
   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);
@@ -249,6 +363,7 @@ if (mcpType === 'stdio') {
 } else {
   console.error('[Note] Starting HTTP MCP server...');
   if (useHapi === true) {
+    process.env.AUTHTYPE = null;
     await hapiMcpServer(mcpServer, sessionCache, appEnvBase);
     console.error('[Note] Using HAPI HTTP server...')
   } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sassoftware/sas-score-mcp-serverjs",
-  "version": "0.3.18",
+  "version": "0.4.0",
   "description": "A mcp server for SAS Viya",
   "author": "Deva Kumar <deva.kumar@sas.com>",
   "license": "Apache-2.0",
@@ -10,7 +10,7 @@
   },
   "type": "module",
   "scripts": {
-    "start": "node  cli.js",
+    "start": "cross-env NODE_TLS_REJECT_UNAUTHORIZED=0 node  cli.js",
     "testi": "cross-env NODE_TLS_REJECT_UNAUTHORIZED=0 npx @modelcontextprotocol/inspector",
     "test": "cd test && node",
     "debug": "cross-env NODE_TLS_REJECT_UNAUTHORIZED=0  node --inspect-brk cli.js",
@@ -39,7 +39,8 @@
     "src",
     "cli.js",
     "openApi.json",
-    "openApi.yaml"
+    "openApi.yaml",
+    "skills"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",

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 |