@sassoftware/sas-score-mcp-serverjs 0.3.29-0 → 0.4.1-1

package/cli.js

@@ -22,6 +22,7 @@ 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';
@@ -30,16 +31,97 @@ 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);
@@ -51,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';
 } 
@@ -136,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,
@@ -252,7 +367,7 @@ if (mcpType === 'stdio') {
     console.error('[Note] Using HAPI HTTP server...')
   } else {
     await expressMcpServer(mcpServer, sessionCache, appEnvBase);
-    console.error('[Note] MCP HTTP server started on port ' + appEnvBase.PORT);
+    console.error('[Note] MCP HTTP express server started on port ' + appEnvBase.PORT);
   }
 }
 

package/openApi.yaml

@@ -1,121 +1,121 @@
-swagger: "2.0"
-info:
-  title: SAS Viya Sample MCP Server API
-  version: "1.0.0"
-  description: API for interacting with the SAS Viya Sample MCP Server.
-host: localhost:8080
-basePath: /
-schemes:
-  - http
-  - https
-consumes:
-  - application/json
-produces:
-  - application/json
-paths:
-  /health:
-    get:
-      summary: Health check
-      description: Returns health and version information.
-      responses:
-        200:
-          description: Health information
-          schema:
-            type: object
-            properties:
-              name:
-                type: string
-              version:
-                type: string
-              description:
-                type: string
-              endpoints:
-                type: object
-              usage:
-                type: string
-  /apiMeta:
-    get:
-      summary: API metadata
-      description: Returns the OpenAPI specification for this server.
-      responses:
-        200:
-          description: OpenAPI document
-          schema:
-            type: object
-  /mcp:
-    options:
-      summary: CORS preflight
-      description: CORS preflight endpoint.
-      responses:
-        204:
-          description: No Content
-    post:
-      summary: MCP request
-      description: Handles MCP JSON-RPC requests.
-      parameters:
-        - name: body
-          in: body
-          required: true
-          schema:
-            type: object
-        - name: Authorization
-          in: header
-          required: false
-          type: string
-          description: Bearer token for authentication
-        - name: X-VIYA-SERVER
-          in: header
-          required: false
-          type: string
-          description: Override VIYA server
-        - name: X-REFRESH-TOKEN
-          in: header
-          required: false
-          type: string
-          description: Refresh token for authentication
-        - name: mcp-session-id
-          in: header
-          required: false
-          type: string
-          description: Session ID
-      responses:
-        200:
-          description: MCP response
-          schema:
-            type: object
-        500:
-          description: Server error
-          schema:
-            type: object
-    get:
-      summary: Get MCP session
-      description: Retrieves information for an MCP session.
-      parameters:
-        - name: mcp-session-id
-          in: header
-          required: true
-          type: string
-          description: Session ID
-      responses:
-        200:
-          description: Session information
-          schema:
-            type: object
-        400:
-          description: Invalid or missing session ID
-    delete:
-      summary: Delete MCP session
-      description: Deletes an MCP session.
-      parameters:
-        - name: mcp-session-id
-          in: header
-          required: true
-          type: string
-          description: Session ID
-      responses:
-        200:
-          description: Session deleted
-          schema:
-            type: object
-        400:
-          description: Invalid or missing session ID
+swagger: "2.0"
+info:
+  title: SAS Viya Sample MCP Server API
+  version: "1.0.0"
+  description: API for interacting with the SAS Viya Sample MCP Server.
+host: localhost:8080
+basePath: /
+schemes:
+  - http
+  - https
+consumes:
+  - application/json
+produces:
+  - application/json
+paths:
+  /health:
+    get:
+      summary: Health check
+      description: Returns health and version information.
+      responses:
+        200:
+          description: Health information
+          schema:
+            type: object
+            properties:
+              name:
+                type: string
+              version:
+                type: string
+              description:
+                type: string
+              endpoints:
+                type: object
+              usage:
+                type: string
+  /apiMeta:
+    get:
+      summary: API metadata
+      description: Returns the OpenAPI specification for this server.
+      responses:
+        200:
+          description: OpenAPI document
+          schema:
+            type: object
+  /mcp:
+    options:
+      summary: CORS preflight
+      description: CORS preflight endpoint.
+      responses:
+        204:
+          description: No Content
+    post:
+      summary: MCP request
+      description: Handles MCP JSON-RPC requests.
+      parameters:
+        - name: body
+          in: body
+          required: true
+          schema:
+            type: object
+        - name: Authorization
+          in: header
+          required: false
+          type: string
+          description: Bearer token for authentication
+        - name: X-VIYA-SERVER
+          in: header
+          required: false
+          type: string
+          description: Override VIYA server
+        - name: X-REFRESH-TOKEN
+          in: header
+          required: false
+          type: string
+          description: Refresh token for authentication
+        - name: mcp-session-id
+          in: header
+          required: false
+          type: string
+          description: Session ID
+      responses:
+        200:
+          description: MCP response
+          schema:
+            type: object
+        500:
+          description: Server error
+          schema:
+            type: object
+    get:
+      summary: Get MCP session
+      description: Retrieves information for an MCP session.
+      parameters:
+        - name: mcp-session-id
+          in: header
+          required: true
+          type: string
+          description: Session ID
+      responses:
+        200:
+          description: Session information
+          schema:
+            type: object
+        400:
+          description: Invalid or missing session ID
+    delete:
+      summary: Delete MCP session
+      description: Deletes an MCP session.
+      parameters:
+        - name: mcp-session-id
+          in: header
+          required: true
+          type: string
+          description: Session ID
+      responses:
+        200:
+          description: Session deleted
+          schema:
+            type: object
+        400:
+          description: Invalid or missing session ID

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sassoftware/sas-score-mcp-serverjs",
-  "version": "0.3.29-0",
+  "version": "0.4.1-1",
   "description": "A mcp server for SAS Viya",
   "author": "Deva Kumar <deva.kumar@sas.com>",
   "license": "Apache-2.0",
@@ -39,10 +39,11 @@
     "src",
     "cli.js",
     "openApi.json",
-    "openApi.yaml"
+    "openApi.yaml",
+    "skills"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@sassoftware/restaf": "^5.6.0",
     "@sassoftware/restafedit": "^3.11.1-10",
     "@sassoftware/restaflib": "^5.6.0",
@@ -56,10 +57,8 @@
     "express-list-endpoints": "^7.1.1",
     "express-rate-limit": "^8.2.1",
     "helmet": "^8.1.0",
-    "mcp-framework": "^0.2.16",
     "node-cache": "^5.1.2",
     "open": "^11.0.0",
-    "puppeteer": "^24.34.0",
     "selfsigned": "^5.2.0",
     "undici": "^7.16.0",
     "uuid": "^13.0.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