@sassoftware/sas-score-mcp-serverjs 0.0.2

package/TOOL_DESCRIPTION_TEMPLATE.md

@@ -0,0 +1,157 @@
+# Tool Description Template
+
+This template standardizes how all tool descriptions should be written in the MCP Server project. Every tool should follow this structure.
+
+## Template Format
+
+```javascript
+function toolName(_appContext) {
+  let description = `
+## toolName — brief one-line description
+
+LLM Invocation Guidance (When to use)
+Use THIS tool when:
+- User request example 1
+- User request example 2
+- User request example 3
+
+Do NOT use this tool for:
+- When to use tool X instead
+- When to use tool Y instead
+- Common misconceptions
+
+Purpose
+Clear explanation of what this tool does and why someone would use it. Can be 1-3 sentences.
+
+Parameters
+[If tool has no required parameters, state "This tool requires no parameters."]
+- paramName (type, default value): Description of what this parameter does and any constraints.
+- anotherParam (type): Required parameter. Description of what it does.
+
+Response Contract
+Describe the format and structure of the response. Include:
+- The top-level structure (object, array, etc.)
+- Key fields in the response
+- Possible error conditions
+- Example response structure
+
+Disambiguation & Clarification
+- If user says "X" but might mean "Y" → clarify with: "Did you mean...?"
+- If parameter is ambiguous → explain how to handle missing/unclear values
+- List common confusion points with other similar tools
+
+Examples (→ mapped params)
+Real-world examples showing user input and how parameters map:
+- "user request example 1" → { param1: "value", param2: 10 }
+- "user request example 2" → { param1: "value" }
+
+Negative Examples (should NOT call toolName)
+- "user request that should use tool X" (use toolX instead)
+- "another incorrect usage" (use toolY instead)
+
+Related Tools
+Link to other tools in the workflow:
+- First step: listSomething or findSomething
+- Get details: infoTool or detailTool
+- Take action: actionTool or executeTool
+`;
+
+  let spec = {
+    name: 'toolName',
+    description: description,
+    schema: {
+      'paramName': z.string(),
+      'anotherParam': z.number().default(10)
+    },
+    required: ['paramName'],
+    handler: async (params) => {
+      let r = await _helperFunction(params);
+      return r;
+    }
+  }
+
+  return spec;
+}
+
+export default toolName;
+```
+
+## Section Guidelines
+
+### LLM Invocation Guidance
+- List 3-5 specific user request patterns that would trigger this tool
+- Use quotes for actual user phrases: `"find model X"`, `"list models"`
+- List 2-4 common misconceptions or tools to use instead
+- Be explicit: "Use THIS tool when..." and "Do NOT use this tool for..."
+
+### Purpose
+- 1-3 sentences maximum
+- Explain the business value, not just the mechanics
+- Can reference other tools if relevant
+
+### Parameters
+- **Format**: `paramName (type, default): description`
+- Include all parameters (required and optional)
+- Specify defaults clearly
+- Add constraints if applicable: `(1-100)`, `(required)`, `(optional)`, `(read-only)`
+- Be specific about what values are valid
+
+### Response Contract
+- Describe JSON structure the LLM will receive
+- Include key field names and their types
+- Mention empty/null cases
+- If applicable, show example response
+
+### Disambiguation & Clarification
+- Format as bullet points with possible user input and clarification
+- Include exact clarification question to ask (in quotes)
+- Mention edge cases
+
+### Examples
+- Format as: `"user phrase" → { param: "value" }`
+- Show 3-5 real-world examples
+- Include examples with different parameter combinations
+- Must demonstrate parameter mapping clearly
+
+### Negative Examples
+- Format as: `"incorrect user request" (use toolX instead)`
+- Show 2-3 common mistakes
+- Always specify which tool to use instead
+
+### Related Tools
+- Show workflow chains: listThing → findThing → infoThing → actionThing
+- Mention which tools come before/after in typical usage
+
+## Tone & Style Guidelines
+
+1. **Be specific**: Use actual examples and parameter values, not abstractions
+2. **Be explicit**: Say "Use THIS tool when" not "Can be used when"
+3. **Be practical**: Focus on when/how LLMs should invoke the tool
+4. **Be complete**: Include all parameters and all guidance sections
+5. **Be concise**: Keep descriptions focused and avoid redundancy
+
+## Validation Checklist
+
+Before marking a tool as conforming to the template:
+
+- [ ] Has "LLM Invocation Guidance" section with "Use THIS" and "Do NOT"
+- [ ] Has "Purpose" section explaining what the tool does
+- [ ] Has "Parameters" section documenting all params with types and defaults
+- [ ] Has "Response Contract" describing the response format
+- [ ] Has "Disambiguation & Clarification" section
+- [ ] Has "Examples" section with 3+ real-world examples showing param mapping
+- [ ] Has "Negative Examples" section with 2+ examples of what NOT to do
+- [ ] Has "Related Tools" section showing workflow context (if applicable)
+- [ ] Uses markdown formatting properly (## headers, - bullets, `code`)
+- [ ] Consistent formatting across all sections
+
+## Tools Updated to Template
+
+- [x] listModels.js - ✅ Already conforms
+- [x] findModel.js - 🔧 Needs cleanup (remove redundancy)
+- [ ] deval.js - 🔧 Needs major expansion
+- [ ] devaScore.js - 🔧 Needs expansion
+- [ ] setContext.js - 🔧 Needs expansion
+- [ ] modelInfo.js - 🔧 Needs expansion
+- [ ] readTable.js - ✅ Mostly conforms (minor tweaks)
+- [ ] ... (other tools)

package/TOOL_UPDATES_SUMMARY.md

@@ -0,0 +1,208 @@
+# Tool Description Standardization - Update Summary
+
+## Overview
+All tool descriptions have been standardized to follow a consistent template format. This ensures:
+- Clear, explicit "when to use" guidance for LLMs
+- Consistent structure across all tools
+- Comprehensive parameter and response documentation
+- Real-world examples with parameter mappings
+- Negative examples showing what NOT to do
+- Related tools showing workflow context
+
+## Template Reference
+See `TOOL_DESCRIPTION_TEMPLATE.md` for the complete template specification and validation checklist.
+
+## Tools Updated
+
+### ✅ Tools Fully Conforming to Template
+
+#### Major Updates (5 tools)
+
+1. **findModel.js** - Cleaned up and standardized
+   - ✂️ Removed redundant JSON metadata object
+   - ✂️ Removed confusing/error lines (41-47) that listed find lib/table/job incorrectly
+   - ✅ Now has all required template sections
+   - ✅ Clear LLM invocation guidance
+
+2. **deval.js** - Expanded from 2 lines to comprehensive format
+   - ➕ Added "LLM Invocation Guidance" section with 4 use cases
+   - ➕ Added "Do NOT use this tool for" section (4 items)
+   - ➕ Added clear "Purpose" statement
+   - ➕ Added "Parameters" documentation
+   - ➕ Added "Response Contract" describing return format
+   - ➕ Added "Disambiguation & Clarification" section
+   - ➕ Added 3 real-world "Examples" with parameter mappings
+   - ➕ Added "Negative Examples" section
+   - ➕ Added "Related Tools" section
+
+3. **setContext.js** - Expanded with comprehensive guidance
+   - ➕ Added "LLM Invocation Guidance" section with 4 use cases
+   - ➕ Added "Do NOT use" section
+   - ➕ Added detailed "Purpose" explaining session context switching
+   - ➕ Enhanced "Parameters" with real server examples
+   - ➕ Added "Response Contract" with detailed structure
+   - ➕ Added "Disambiguation & Clarification" for edge cases
+   - ➕ Added 4 real-world "Examples" with parameter mappings
+   - ➕ Added "Negative Examples" section
+   - ➕ Added "Related Tools" section
+
+4. **devaScore.js** - Reformatted with template structure
+   - 🔄 Restructured from instruction-heavy to template format
+   - ➕ Added "LLM Invocation Guidance" section
+   - ➕ Added "Do NOT use" section
+   - ➕ Added clear parameter documentation
+   - ➕ Added "Response Contract" section
+   - ➕ Added "Examples" and "Negative Examples" sections
+   - ➕ Added "Notes" section explaining left-to-right fold
+
+5. **modelInfo.js** - Expanded with comprehensive structure
+   - ➕ Added "LLM Invocation Guidance" with 4 use cases
+   - ➕ Added "Do NOT use" section
+   - ➕ Enhanced "Purpose" statement
+   - ➕ Added detailed "Response Contract" describing metadata fields
+   - ➕ Added "Disambiguation & Clarification" section
+   - ➕ Added 4 real-world "Examples" with parameter mappings
+   - ➕ Added "Negative Examples" section
+   - ➕ Added "Related Tools" showing workflow chain
+
+#### Moderate Updates (1 tool)
+
+6. **readTable.js** - Enhanced to fully conform to template
+   - 🔄 Restructured sections for template consistency
+   - ➕ Enhanced "LLM Invocation Guidance" with 5 specific use cases
+   - ➕ Improved "Do NOT use" section with explanation
+   - ➕ Clarified "Parameters" format and added constraints
+   - 🔄 Renamed "Output" to "Response Contract" per template
+   - ➕ Added "Pagination & Filtering" section with examples
+   - ➕ Enhanced "Examples" with 5 detailed parameter mappings
+   - ➕ Added comprehensive "Related Tools" section
+
+#### Already Conforming (1 tool)
+
+7. **listModels.js** - ✅ Already fully compliant
+   - Already had comprehensive template format
+   - No changes needed
+
+## Template Sections Included in All Updated Tools
+
+### 1. LLM Invocation Guidance (When to use)
+Explicit "Use THIS tool when" bullet points with real user phrases. Typically 3-5 examples.
+
+### 2. Do NOT use this tool for
+Clear list of what NOT to do and which tools to use instead. Prevents misuse.
+
+### 3. Purpose
+1-3 sentence explanation of what the tool does and why.
+
+### 4. Parameters
+- Name, type, default value, and description for each parameter
+- Constraints and valid value ranges where applicable
+- Required vs optional clearly indicated
+
+### 5. Response Contract
+- JSON structure of the response
+- Key fields and their types
+- Edge cases (empty, null, errors)
+- Example response format
+
+### 6. Disambiguation & Clarification
+- How to handle missing parameters
+- How to clarify ambiguous requests
+- Exact clarification questions to ask
+
+### 7. Examples (→ mapped params)
+- Real-world user phrases
+- Parameter mappings shown
+- Includes various parameter combinations
+- Format: `"user input" → { param: value }`
+
+### 8. Negative Examples (should NOT call toolName)
+- Common mistakes showing what NOT to do
+- Specifies which tool to use instead
+- Format: `"bad request" (use toolX instead)`
+
+### 9. Related Tools
+- Workflow chains showing which tools work together
+- Dependencies and typical call sequences
+- Links to prerequisite/follow-up tools
+
+## Statistics
+
+| Metric | Count |
+|--------|-------|
+| Tools with major updates | 5 |
+| Tools with moderate updates | 1 |
+| Tools already conforming | 1 |
+| Total tools standardized | 7 |
+| Template file created | 1 |
+
+## Key Improvements
+
+### Consistency
+- All tools now follow the same structure
+- Uniform formatting and section ordering
+- Consistent tone and style
+
+### Clarity
+- Explicit "when to use" guidance for LLMs
+- Clear parameter documentation with types and defaults
+- Real-world examples instead of abstractions
+
+### Completeness
+- All tools include negative examples
+- All tools explain related tools/workflows
+- All tools have response contracts
+
+### Usability
+- LLMs can understand tool purpose immediately
+- Clear disambiguation guidance for edge cases
+- Parameter mappings prevent incorrect invocations
+
+## Files Modified
+
+1. `src/toolSet/findModel.js` - Cleaned up redundancy
+2. `src/toolSet/deval.js` - Expanded description (2 → 47 lines)
+3. `src/toolSet/setContext.js` - Expanded description (9 → 60 lines)
+4. `src/toolSet/devaScore.js` - Reformatted (12 → 54 lines)
+5. `src/toolSet/modelInfo.js` - Expanded description (12 → 69 lines)
+6. `src/toolSet/readTable.js` - Enhanced description (56 → 80 lines)
+
+## Files Created
+
+1. `TOOL_DESCRIPTION_TEMPLATE.md` - Master template specification
+2. `TOOL_UPDATES_SUMMARY.md` - This file
+
+## Next Steps (Optional)
+
+Consider updating remaining tools in the toolSet directory to match this template:
+- `listTables.js` - Already fairly complete, minor tweaks possible
+- `listLibraries.js`
+- `listJobs.js`
+- `findJob.js`
+- `findLibrary.js`
+- `findTable.js`
+- `job.js`
+- `jobdef.js`
+- `tableInfo.js`
+- `program.js`
+- `sasQuery.js`
+- `modelScore.js`
+- `scrInfo.js`
+- `scrScore.js`
+- And any others...
+
+## Validation Checklist
+
+To verify a tool conforms to the template, check:
+
+- [ ] Has "LLM Invocation Guidance" section with "Use THIS tool when" list
+- [ ] Has "Do NOT use this tool for" section with specific alternatives
+- [ ] Has "Purpose" section explaining what the tool does
+- [ ] Has "Parameters" section with type, default, and description for each param
+- [ ] Has "Response Contract" describing the return format
+- [ ] Has "Disambiguation & Clarification" section for edge cases
+- [ ] Has "Examples (→ mapped params)" section with 3+ real-world examples
+- [ ] Has "Negative Examples (should NOT call...)" section with what NOT to do
+- [ ] Has "Related Tools" section showing workflow context
+- [ ] Uses proper markdown formatting (## headers, - bullets, `code`)
+- [ ] Consistent formatting and tone throughout

package/cli.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Main entry point for MCP server
+
+
+import coreSSE from './src/coreSSE.js';
+import corehttp from './src/corehttp.js';
+import createMcpServer from './src/createMcpServer.js';
+import { config } from 'dotenv';
+// import dotenvExpand from 'dotenv-expand';
+import fs from 'fs';
+import { randomUUID } from 'node:crypto';
+
+import refreshToken from './src/toolHelpers/refreshToken.js';
+import getOptsViya from './src/toolHelpers/getOptsViya.js';
+
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+import NodeCache from 'node-cache';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+let pkg = fs.readFileSync(__dirname + '/package.json', 'utf8');
+
+/********************************* */
+const BRAND = 'sas-score'
+/********************************* */
+let pkgJson = JSON.parse(pkg);
+let version = pkgJson.version;
+let mcpType = process.env.MCPTYPE || 'http';
+console.error(
+  `\nStarting MCP ServerJS - Version: ${pkgJson.version} - ${new Date().toISOString()}\n
+     brand: ${process.env.BRAND || BRAND}\n
+     mcpType: ${mcpType}\n
+     viyaServer: ${process.env.VIYA_SERVER}\n`
+);
+// session sessionCache
+// For more robust caching consider products like Redis
+// and storage provided by cloud providers
+
+debugger;
+let sessionCache = new NodeCache({ stdTTL: 0, checkperiod: 2 * 60, useClones: false });
+
+//
+// Load environment variables from .env file if present
+// swithching to:
+// stdio: set the env in the mcp config
+// http: use dotenv-cli to load env before starting the mcp server
+
+
+// need to tell core what transport to use(http or stdio)
+
+//  subclasses for sasQuery tool (special use case)
+// to be replaced by the planned adding external tool definition capability
+
+let subclassJson = [];
+if (process.env.SUBCLASS != null) {
+  console.error(`Using subclass: ${process.env.SUBCLASS}`);
+  let subclass = process.env.SUBCLASS;
+  if (fs.existsSync(subclass)) {
+    console.error(`Loading subclass information from ${subclass}...`);
+    let s = fs.readFileSync(subclass, 'utf8');
+    subclassJson = JSON.parse(s);
+    console.error(`Loaded subclass: ${JSON.stringify(subclassJson, null, 2)}`);
+  }
+}
+// setup base appEnv 
+// for stdio this is the _appContext
+// for http each session a copy of this as appEnvTemplate is created in corehttp
+const appEnvBase = {
+  version: version,
+  mcpType: mcpType,
+  brand: (process.env.BRAND == null) ? BRAND : process.env.BRAND,
+  HTTPS:
+    process.env.HTTPS != null && process.env.HTTPS.toUpperCase() === 'TRUE'
+      ? true
+      : false,
+  SAS_CLI_PROFILE: process.env.SAS_CLI_PROFILE || 'Default',
+  SAS_CLI_CONFIG: process.env.SAS_CLI_CONFIG || process.env.HOME, // default to user home directory
+  SSLCERT: process.env.SSLCERT || null,
+  VIYACERT: process.env.VIYACERT || null,
+
+  AUTHFLOW: process.env.AUTHFLOW || 'sascli',
+  VIYA_SERVER: process.env.VIYA_SERVER,
+  PORT: process.env.PORT || 8080,
+  USERNAME: process.env.USERNAME || null,
+  PASSWORD: process.env.PASSWORD || null,
+  CLIENTIDPW: process.env.CLIENTIDPW || null,
+  CLIENTSECRET: process.env.CLIENTSECRETPW || null,
+  TOKEN: process.env.TOKEN || null,
+  REFRESH_TOKEN: process.env.REFRESH_TOKEN || null,
+  TOKENFILE: process.env.TOKENFILE || null,
+  TLS_CREATE: process.env.TLS_CREATE || null,
+  SUBCLASS: process.env.SUBCLASS || null,
+  subclassJson: subclassJson,
+  // future use for controlling tool list using env variable
+  toolsets:
+    process.env.TOOLSETS != null
+      ? process.env.TOOLSETS.split(',')
+      : ['default'],
+  // user defined tools
+  //runtime variables
+  tokenRefresh: process.env.TOKENREFRESH === 'FALSE' ? false : true,
+  tls: null,
+  refreshToken: null,
+  transports: {},
+  mcpServer: null,
+  viyaSessions: {},
+  store: null,
+  casServer: null,
+  casSessionId: null,
+  computeSessionId: null,
+  logonPayload: null,
+  bearerToken: null,
+  tlsOpts: null,
+  contexts: {
+    store: null, /* for restaf users */
+    storeConfig: {},
+    casSession: null, /* restaf cas session object */
+    computeSession: null, /* restaf compute session object */
+    viyaCert: null, /* ssl/tsl certificates to connect to viya */
+    logonPayload: null, /* viya logon payload  to connect to viya */
+    casServerId: null,
+    computeSessonId: null,
+    sas: (process.env.COMPUTECONTEXT == null) ? 'SAS Job Execution compute context' : process.env.COMPUTECONTEXT,
+    cas: (process.env.CASSERVER == null) ? 'cas-shared-default' : process.env.CASSERVER,
+    ext: {} /* for additional extensions that a developer may want to add */
+  }
+};
+
+// 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.contexts.storeConfig = {
+  casProxy: true,
+  options: { ns: null, proxyServer: null, httpOptions: appEnvBase.contexts.viyaCert }
+};
+
+if (appEnvBase.TOKENFILE != null) {
+  try {
+    console.error(`[Note]Loading token from file: ${appEnvBase.TOKENFILE}...`);
+    appEnvBase.TOKEN = fs.readFileSync(appEnvBase.TOKENFILE, { encoding: 'utf8' });
+    appEnvBase.AUTHFLOW = 'token';
+    appEnvBase.appContexts.logonPayload = {
+      host: appEnvBase.VIYA_SERVER,
+      authType: 'server',
+      token: appEnvBase.TOKEN,
+      tokenType: 'Bearer'
+
+    }
+  } catch (err) {
+    console.error(`[Error] Failed to read token file: ${err}`);
+  }
+}
+
+// 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, postpone getting logonPayload until needed
+
+/*
+if(appEnvBase.AUTHFLOW ==='sascli') {
+  let logonPayload = await getLogonPayload(appEnvBase);
+  appEnvBase.logonPayload = logonPayload;
+}
+  */
+
+// setup mcpServer (both http and stdio use this)
+// this is singleton - best practices recommend this
+
+let mcpServer = await createMcpServer(sessionCache, appEnvBase);
+
+sessionCache.set('appEnvBase', appEnvBase);
+let appEnvTemplate = Object.assign({}, appEnvBase);
+
+sessionCache.set('appEnvTemplate', appEnvTemplate);
+
+let transports = {};
+sessionCache.set('transports', transports);
+
+// set this for stdio transport use
+// dummy sessionId for use in the tools  
+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);
+
+} else {
+  console.error('[Note] Starting HTTP MCP server...');
+  await corehttp(mcpServer, sessionCache, appEnvBase);
+  console.error('[Note] MCP HTTP server started on port ' + appEnvBase.PORT);
+}
+
+

package/labs/.subclass.json

@@ -0,0 +1,13 @@
+[
+
+   {
+      "name": "query-customer-usage",
+      "template": "sasQueryTemplate",
+      "table": "Public.gidb_current",
+      "selectColumns": "opsys, offering, product,  rate, quantity, quantype, currency",
+      "columns": null,
+      "job": "run_sql_query",
+      "server": "cas"
+   }
+
+]

package/labs/README.md

@@ -0,0 +1,4 @@
+# Lab
+
+This folder has files that are for some future work.
+Not used by the current mcp server

package/mcpConfigurations/README.md

@@ -0,0 +1,3 @@
+# Configurations
+
+Typical mvp configuration files

package/mcpConfigurations/http.json

@@ -0,0 +1,8 @@
+{
+	"servers": {
+		"sasmcp": {
+			"type": "http",
+			"url": "http://localhost:8080/mcp"
+		}
+	}
+}

package/mcpConfigurations/stdio.json

@@ -0,0 +1,20 @@
+{
+	"servers": {
+		"sasmcp": {
+			"type": "stdio",
+			"command": "npx",
+			"args": [
+				"@sassoftware/sas-score-mcp-serverjs"
+			],
+			"env": {
+				"MCPTYPE": "stdio",
+				"AUTHFLOW": "sascli", 
+				"SAS_CLI_PROFILE": "cis",
+				"SAS_CLI_CONFIG": "c:\\Users\\kumar",
+				"SSLCERT": "c:\\Users\\kumar\\.tls",
+				"COMPUTECONTEXT": "SAS Job Execution compute context",
+				"CAS_SERVER": "cas-shared-default"
+			}
+		}
+	}
+}

package/mcpConfigurations/stdiodev.json

@@ -0,0 +1,20 @@
+{
+	"servers": {
+		"sasmcp": {
+			"type": "stdio",
+			"command": "node",
+			"args": [
+				"c:\\dev\\gitlab\\mcp-serverjs\\cli.js"
+			],
+			"env": {
+				"MCPTYPE": "stdio",
+				"AUTHFLOW": "sascli", 
+				"SAS_CLI_PROFILE": "cis",
+				"SAS_CLI_CONFIG": "c:\\Users\\kumar",
+				"SSLCERT": "c:\\Users\\kumar\\.tls",
+				"COMPUTECONTEXT": "SAS Job Execution compute context",
+				"CAS_SERVER": "cas-shared-default"
+			}
+		}
+	}
+}