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

package/src/toolHelpers/refreshToken.js

@@ -1,49 +1,51 @@
- /*
- * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
- * SPDX-License-Identifier: Apache-2.0
- */
- import { Agent, fetch } from 'undici';
- import getOpts from './getOpts.js';
- async function refreshToken(_appContext,params) {
-  let {host, token} = params;
-    const url = `${host}/SASLogon/oauth/token`;
-    console.error('[Info] Refresh token...', token);
-    let opts = getOpts(_appContext);
-    console.error('opts: ', opts);
-    const agent = new Agent({
-      connect: opts
-    });
-    console.error('[Info] Refreshing token...', token);
-    const body = new URLSearchParams({
-      grant_type: 'refresh_token',
-      refresh_token: token,
-      client_id: 'sas.cli'
+/*
+* Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+* SPDX-License-Identifier: Apache-2.0
+*/
+import { Agent, fetch } from 'undici';
+
+async function refreshToken(_appContext, params) {
+  let { host, token } = params;
+  let url = `${host}/SASLogon/oauth/token`;
+
+  let aconnect = {
+    ca: _appContext.contexts.viyaCert.ca,     // trust this CA
+    rejectUnauthorized: false  // or false, if you really want to bypass checks
+  }
+
+  const agent = new Agent(aconnect);
+
+  console.error('[Info] Refreshing token...', token);
+  const ibody = {
+    grant_type: 'refresh_token',
+    refresh_token: token,
+    client_id: 'sas.cli'
+  };
+
+  let body = new URLSearchParams(ibody);
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Accept': 'application/json',
+        'Content-Type': 'application/x-www-form-urlencoded',
+        dispatcher: agent
+      },
+      body: body.toString()
     });
-    
-    try {
-      const response = await fetch(url, {
-        method: 'POST',
-        headers: {
-          'Accept': 'application/json',
-          'Content-Type': 'application/x-www-form-urlencoded',
-          dispatcher: agent
-        },
-        body: body.toString()
-      });
-
-      if (!response.ok) {
-        const error = await response.text();
-        console.error('[Error] Failed to refresh token: ', error);
-        throw new Error(error);
-      }
-
-      const data = await response.json();
-      console.error('[Info] Token refreshed successfully: ', data.access_token);
-      return data.access_token;
-    } catch (err) {
-      console.error('[Error] Failed to refresh token: ', err);
-      throw err;
+
+    if (!response.ok) {
+      const error = await response.text();
+      console.error('[Error] Failed to refresh token: ', error);
+      throw new Error(error);
     }
+
+    const data = await response.json();
+    return data.access_token;
+  } catch (err) {
+    console.error('[Error] Failed to refresh token: ', err);
+    throw err;
   }
-  
-  export default refreshToken;
+}
+
+export default refreshToken;

package/src/toolHelpers/refreshTokenOauth.js

@@ -3,11 +3,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
  import { Agent, fetch } from 'undici';
- import getOpts from './getOpts.js';
+ //import getOpts from './getOpts.js';
  async function refreshTokenOauth(_appContext, oauthInfo ){
  
     const url = `${process.env.VIYA_SERVER}/SASLogon/oauth/token`;
-    let opts = getOpts(_appContext);
+    let opts = _appContext.contexts.appCert;
 
     const agent = new Agent({
       connect: opts

package/src/toolHelpers/tlogon.js

@@ -0,0 +1,9 @@
+import getLogonPayload from "./getLogonPayload.js";
+
+async function tlogon(_appContext) {
+    console.error('[Info] Starting tlogon...');
+    let r = await getLogonPayload(_appContext);
+    console.error('[Info] tlogon completed');
+    return r;
+}
+export default tlogon;

package/src/toolSet/devaScore.js

@@ -7,49 +7,36 @@ import {z} from 'zod';
 function devaScore(_appContext) {
 
     let description = `
-## deva-score — compute a numeric score based on two input values
+deva-score — compute a numeric score based on two input values.
 
-LLM Invocation Guidance (When to use)
-Use THIS tool when:
-- User wants to calculate the deva score: "Calculate deva score for 5 and 10"
-- User provides two numbers for scoring: "Score these values: 3 and 7"
-- User wants to compute a score in a series: "Calculate scores for [list of numbers]"
+USE when: calculate deva score, score these values, compute score for numbers
+DO NOT USE for: model scoring (use model-score), statistical calculations, data lookup
 
-Do NOT use this tool for:
-- Scoring models (use model-score)
-- Statistical calculations beyond deva scoring
-- Looking up data or metadata
+PARAMETERS
+- a: number (required) — first input value
+- b: number (required) — second input value
 
-Purpose
-Compute a numeric deva score by applying the formula (a + b) * 42 to two input numbers. For scoring more than two numbers, call this tool multiple times using the previous result as the first input (left-to-right fold).
+FORMULA: (a + b) * 42
 
-Parameters
-- a (number, required): First numeric input value
-- b (number, required): Second numeric input value
+ROUTING RULES
+- "calculate deva score for 5 and 10" → { a: 5, b: 10 }
+- "score 1 and 2" → { a: 1, b: 2 }
+- "deva score a=3, b=7" → { a: 3, b: 7 }
+- Multiple numbers → chain calls left-to-right: call(first, second), then call(result, third)
 
-Response Contract
-Returns a numeric result: (a + b) * 42
-The result is always a number representing the computed deva score.
-
-Disambiguation & Clarification
-- If user provides more than two numbers without clear instructions: "Do you want to calculate the deva score by combining these numbers left-to-right?"
-- If user provides non-numeric input: "Please provide numeric values"
-
-Examples (→ mapped params)
+EXAMPLES
 - "Calculate deva score for 5 and 10" → { a: 5, b: 10 } returns 630
 - "Score 1 and 2" → { a: 1, b: 2 } returns 126
-- For multiple numbers, chain calls: deva(1,2)→126, then deva(126,3)→5418
-
-Negative Examples (should NOT call deva-score)
-- "Score this customer with the credit model" (use model-score instead)
-- "Calculate the mean of these values" (use run-sas-program or sas-query instead)
+- "Deva score 20 and 30" → { a: 20, b: 30 } returns 2100
 
-Related Tools
-- None directly related (this is a specialized scoring tool)
+NEGATIVE EXAMPLES (do not route here)
+- "Score this customer with credit model" (use model-score)
+- "Calculate the mean of these values" (use run-sas-program or sas-query)
+- "Statistical analysis of numbers" (use sas-query)
 
-Notes
-For sequences of numbers, use a left-to-right fold: call devaScore(first, second), then use that result as the first parameter for devaScore(result, third), and so on.
-`;
+RESPONSE
+Returns { score: (a + b) * 42 }
+    `;
     let spec = {
         name: 'deva-score',
         aliases: ['devaScore','deva score','deva_score'],
@@ -58,12 +45,17 @@ For sequences of numbers, use a left-to-right fold: call devaScore(first, second
             a: z.number(),
             b: z.number()
         },
-        handler: async ({ a, b,_appContext }) => {
+        handler: async ({ a, b }) => {
             console.error( a, b);
-            return { content: [{ type: 'text', 
-                text: String((a + b) * 42) }] }
+            let r = {score: (a + b) * 42};
+            console.error('deva score result', r);
+            return {
+                content: [{type: 'text', text: 'deva score result: ' + JSON.stringify(r)}],
+                structuredContent: r
+             };
+            }
         }
-    }
+        
     return spec;
 }
 export default devaScore;

package/src/toolSet/findJob.js

@@ -16,61 +16,35 @@ function findJob(_appContext) {
   "behavior": "Return only JSON matching response_schema when invoked by an LLM. If no matches, return { jobs: [] }"
 };
   let description = `
-  ## find-job — locate a specific SAS Viya job
+find-job — locate a specific SAS Viya job.
 
-  LLM Invocation Guidance
-  Use THIS tool when the user intent is to check if ONE job exists or retrieve its metadata:
-  - "find job cars_job_v4"
-  - "does job sales_summary exist"
-  - "is there a job named churnScorer"
-  - "lookup job forecast_monthly"
-  - "verify job ETL_Daily" 
+USE when: find job, does job exist, is there a job named, lookup job, verify job exists
+DO NOT USE for: list jobs (use list-jobs), run job (use run-job), execute jobdef (use run-jobdef), find lib/table/model (use respective tools)
 
-  Do NOT use this tool when the user asks for:
-  - A list or browse of many jobs (use listJobs)
-  - Do not use this tool if the user want to find lib, find table, find model and similar requests
-  - Executing a job (use job)
-  - Running a job definition (use jobdef)
-  - Submitting arbitrary code (use program)
+PARAMETERS
+- name: string (required) — job name to locate; if multiple supplied, use first
 
-  Purpose
-  Quickly determine whether a named job asset is present in the Viya environment and return its entry (or an empty result if not found).
+ROUTING RULES
+- "find job <name>" → { name: "<name>" }
+- "does job <name> exist" → { name: "<name>" }
+- "is there a job named <name>" → { name: "<name>" }
+- "lookup/verify job <name>" → { name: "<name>" }
+- "find job" with no name → ask "Which job name would you like to find?"
+- "find all jobs / list jobs" → use list-jobs instead
+- "run job <name>" → use run-job instead
 
-  Parameters
-  - name (string, required): Exact job name (case preserved). If multiple tokens/names supplied, take the first and ignore the rest; optionally ask for a single name.
+EXAMPLES
+- "find job cars_job_v4" → { name: "cars_job_v4" }
+- "does job ETL exist" → { name: "ETL" }
+- "is there a job named metricsRefresh" → { name: "metricsRefresh" }
 
-  Behavior & Matching
-  - Attempt exact match first (backend determines sensitivity).
-  - Returns { jobs: [...] } where array length is 0 (not found) or 1+ (if backend returns multiple with the same display name).
-  - No fuzzy guesses—never fabricate a job.
-  - If no name provided: ask "Which job name would you like to find?".
+NEGATIVE EXAMPLES (do not route here)
+- "list jobs" (use list-jobs)
+- "run job cars_job_v4" (use run-job)
+- "execute jobdef cars_job_v4" (use run-jobdef)
 
-  Response Contract
-  - Always: { jobs: Array<string|object> }
-  - On error: propagate structured server error (do not wrap in prose when invoked programmatically).
-
-  Disambiguation Rules
-  - Input only "find job" → ask for missing name.
-  - Input contains verbs like "run" or "execute" → use run-job or run-jobdef instead.
-  - Input requesting many (e.g., "find all jobs") → use list-jobs.
-
-  Examples (→ mapped params)
-  - "find job cars_job_v4" → { name: "cars_job_v4" }
-  - "does job ETL exist" → { name: "ETL" }
-  - "is there a job named metricsRefresh" → { name: "metricsRefresh" }
-
-  Negative Examples (should NOT call find-job)
-  - "list jobs" (list-jobs)
-  - "run job cars_job_v4" (run-job)
-  - "execute jobdef cars_job_v4" (run-jobdef)
-
-  Clarifying Question Template
-  - Missing name: "Which job name would you like to find?"
-  - Multiple names: "Please provide just one job name (e.g. 'cars_job_v4')."
-
-  Notes
-  - For bulk existence checks loop over names and call find-job per name.
-  - Combine with run-job tool if user wants to execute after confirming existence.
+ERRORS
+Returns { jobs: [] } if not found; { jobs: [name, ...] } if found. Never hallucinate job names.
   `;
 
   let spec = {

package/src/toolSet/findJobdef.js

@@ -15,66 +15,36 @@ function findJobdef(_appContext) {
   "behavior": "Return only JSON matching response_schema when invoked by an LLM. If no matches, return { jobs: [] }"
 };
   let description = `
-  ## find-jobdef — locate a specific SAS Viya job
+find-jobdef — locate a specific SAS Viya job definition.
 
-  LLM Invocation Guidance
-  Use THIS tool when the user intent is to check if ONE job exists or retrieve its metadata:
-  - "find jobdef cars_job_v4"
-  - "does jobdef sales_summary exist"
-  - "is there a jobdef named churnScorer"
-  - "lookup jobdef forecast_monthly"
-  - "verify jobdef ETL_Daily" 
+USE when: find jobdef, does jobdef exist, is there a jobdef named, lookup jobdef, verify jobdef exists
+DO NOT USE for: list jobdefs (use list-jobdefs), run jobdef (use run-jobdef), find job/lib/table/model (use respective tools)
 
-  Do NOT use this tool when the user asks for:
-  - find job  (use find-job)
-  - find table (use find-table
-  - find model (use find-model)
-  - find lib (use find-library)
-  - Executing a job (use job)
-  - Running a job definition (use jobdef)
-  - Submitting arbitrary code (use program)
+PARAMETERS
+- name: string (required) — jobdef name to locate; if multiple supplied, use first
 
-  Purpose
-  Quickly determine whether a named jobdef asset is present in the Viya environment and return its entry (or an empty result if not found).
+ROUTING RULES
+- "find jobdef <name>" → { name: "<name>" }
+- "does jobdef <name> exist" → { name: "<name>" }
+- "is there a jobdef named <name>" → { name: "<name>" }
+- "lookup/verify jobdef <name>" → { name: "<name>" }
+- "find jobdef" with no name → ask "Which jobdef name would you like to find?"
+- "find all jobdefs / list jobdefs" → use list-jobdefs instead
+- "run jobdef <name>" → use run-jobdef instead
 
-  Parameters
-  - name (string, required): Exact jobdef name (case preserved). If multiple tokens/names supplied, take the first and ignore the rest; optionally ask for a single name.
+EXAMPLES
+- "find jobdef cars_job_v4" → { name: "cars_job_v4" }
+- "does jobdef ETL exist" → { name: "ETL" }
+- "is there a jobdef named metricsRefresh" → { name: "metricsRefresh" }
 
-  Behavior & Matching
-  - Attempt exact match first (backend determines sensitivity).
-  - Returns { jobdefs: [...] } where array length is 0 (not found) or 1+ (if backend returns multiple with the same display name).
-  - No fuzzy guesses—never fabricate a job.
-  - If no name provided: ask "Which jobdef name would you like to find?".
+NEGATIVE EXAMPLES (do not route here)
+- "list jobdefs" (use list-jobdefs)
+- "run jobdef cars_job_v4" (use run-jobdef)
+- "find job ETL" (use find-job)
+- "find table cars" (use find-table)
 
-  Response Contract
-  - Always: { jobdefs: Array<string|object> }
-  - On error: propagate structured server error (do not wrap in prose when invoked programmatically).
-
-  Disambiguation Rules
-  - Input only "find job" → ask for missing name.
-  - Input contains verbs like "run" or "execute" → use run-job or run-jobdef instead.
-  - Input requesting many (e.g., "find all jobs") → use list-jobs.
-
-  Examples (→ mapped params)
-  - "find jobdef cars_job_v4" → { name: "cars_job_v4" }
-  - "does jobdef ETL exist" → { name: "ETL" }
-  - "is there a jobdef named metricsRefresh" → { name: "metricsRefresh" }
-
-  Negative Examples (should NOT call find-jobdef)
-  - find lib (use find-library)
-  - find table (use find-table)
-  - find model (use find-model)
-  - "list job" (list-jobdefs)
-  - "run job cars_job_v4" (run-job)
-  - "execute jobdef cars_job_v4" (run-jobdef)
-
-  Clarifying Question Template
-  - Missing name: "Which jobdef name would you like to find?"
-  - Multiple names: "Please provide just one jobdef name (e.g. 'cars_job_v4')."
-
-  Notes
-  - For bulk existence checks loop over names and call find-jobdef per name.
-  - Combine with run-jobdef tool if user wants to execute after confirming existence.
+ERRORS
+Returns { jobdefs: [] } if not found; { jobdefs: [name, ...] } if found. Never hallucinate jobdef names.
   `;
 
   let spec = {

package/src/toolSet/findLibrary.js

@@ -7,69 +7,37 @@ import _listLibrary from '../toolHelpers/_listLibrary.js';
 function findLibrary(_appContext) {
   
   let description = `
-  ## find-library — locate a specific CAS or SAS library
+find-library — locate a specific CAS or SAS library.
 
-  LLM Invocation Guidance
-  Use THIS tool when the user asks any of the following (intent = existence / lookup of ONE library):
-  - "find library Public"
-  - "find lib Public"
-  - "does library SASHELP exist"
-  - "is PUBLIC library available in cas"
-  - "lookup library sasuser in sas"
-  - "show me library metadata for Models"
+USE when: find library, find lib, does library exist, is library available, lookup library
+DO NOT USE for: list libraries (use list-libraries), find table/job/jobdef/model (use respective tools), table structure (use table-info), create library (use run-sas-program)
 
-  Aliases for lib are: library, caslib, libref
-  
-  Do NOT use this tool when the user wants:
-  - find model -> use find-model
-  - find table -> use find-table
-  - find job -> use find-job
-  - find jobdef -> use find-jobdef
-  - Columns or schema of a table (use table-info)
-  - Creating/assigning libraries (use run-sas-program or another admin tool)
-
-  Purpose
-  Quickly verify whether a single named library exists on CAS or SAS and return its entry (or empty if not found).
-
-  Parameters
-  - name (string, required) : Exact library (caslib) name to locate. If multiple names provided (comma/space separated), use the first and ignore the rest; optionally ask for one name.
-  - server (cas|sas, default 'cas') : Target environment. If omitted or ambiguous default to 'cas'.
-
-  Behavior & Matching
-  - Performs an exact name match (case-insensitive where backend supports it).
-  - Returns an object: { libraries: [...] } where the array contains zero or one items (backend may still return richer metadata).
-  - If no match: { libraries: [] } (do NOT fabricate suggestions).
-  - If user supplies no name: ask a clarifying question: "Which library name would you like to find?".
-  - If user clearly wants a list ("list", "show all", "enumerate") route to listLibrary instead.
-
-  Response Contract
-  - Always: { libraries: Array<string|object> }
-  - Never include prose when invoked programmatically; only the JSON structure.
-
-  Disambiguation Rules
-  - Input only "find library" → ask for the missing name.
-  - Input with both library name and words like "tables" → prefer listTables.
-  - Input like "find libraries" (plural) → prefer listLibrary unless user clarifies to a single name.
+PARAMETERS
+- name: string (required) — library/caslib name; if multiple supplied, use first
+- server: 'cas' | 'sas' (default: 'cas') — target environment
 
-  Examples (→ mapped params)
-  - "find lib Public" → { name: "Public", server: "cas" }
-  - "find library sasuser in sas" → { name: "sasuser", server: "sas" }
-  - "does library Formats exist" → { name: "Formats", server: "cas" }
-  - "is SystemData library in cas" → { name: "SystemData", server: "cas" }
+ROUTING RULES
+- "find lib <name>" → { name: "<name>", server: "cas" }
+- "find lib <name> in cas" → { name: "<name>", server: "cas" }
+- "find library <name> in sas" → { name: "<name>", server: "sas" }
+- "does library <name> exist" → { name: "<name>", server: "cas" }
+- "find lib" with no name → ask "Which library name would you like to find?"
+- "list libraries / list libs" → use list-libraries instead
+- "tables in <lib>" → use list-tables instead
 
-  Negative Examples (should NOT call find-library)
-  - "list libs" (list-libraries)
-  -  Do not use this tool if the user want to find table, find job, find model, find job, find jobdef  and similar requests
-  - "show tables in Public" (list-tables)
-  - "describe table cars in sashelp" (table-info)
+EXAMPLES
+- "find lib Public" → { name: "Public", server: "cas" }
+- "find library sasuser in sas" → { name: "sasuser", server: "sas" }
+- "does library Formats exist" → { name: "Formats", server: "cas" }
 
-  Clarifying Question Template
-  - Missing name: "Which library name would you like to find?"
-  - Multiple names: "Please provide just one library name to look up (e.g. 'Public')."
+NEGATIVE EXAMPLES (do not route here)
+- "list libs" (use list-libraries)
+- "show tables in Public" (use list-tables)
+- "find table cars in sashelp" (use find-table)
+- "find job cars_job" (use find-job)
 
-  Notes
-  - For bulk validation of many names, call this tool repeatedly per name.
-  - For pagination or discovery, switch to list-libraries.
+ERRORS
+Returns { libraries: [] } if not found; { libraries: [name, ...] } if found. Never hallucinate library names.
   `;
 
   let spec = {

package/src/toolSet/findModel.js

@@ -9,59 +9,37 @@ import _listModels from '../toolHelpers/_listModels.js';
 
 function findModel(_appContext) {
   let description = `
-  ## find-model — locate a specific model deployed to MAS (Model Publish / Scoring service)
-
-  LLM Invocation Guidance (When to use)
-  Use THIS tool when the user wants to know whether ONE model exists or is deployed:
-  - "find model cancerRisk"
-  - "does model churn_tree exist"
-  - "is model sales_forecast deployed"
-  - "lookup model claimFraud"
-  - "verify model credit_score_v2 exists"
-
-  Do NOT use this tool for:
-  - Listing many / browsing models (use list-models)
-  - Retrieving detailed input/output variable metadata (use model-info)
-  - Scoring or running a model (use model-score)
-  - Searching model execution containers or SCR endpoints (use scr-info / scr-score if appropriate)
-  - Finding a table (use find-table)
-  - Finding a library (use find-library)
-  - Finding a job or jobdef (use find-job / find-jobdef)
-
-  Purpose
-  Quick existence / lookup check for a MAS‑published model. Returns a list with zero or more matches (typically 0 or 1 for an exact name).
-
-  Parameters
-  - name (string, required): Exact model name. If user supplies phrases like "model named X" extract X. If multiple names are given (comma or space separated), prefer the first and (optionally) ask for a single name.
-
-  Matching Rules
-  - Attempt exact match first. If backend supports partial search, a substring match MAY return multiple models; preserve order.
-  - Do not fabricate models. Empty array means not found.
-
-  Response Contract
-  - Always: { models: Array<object|string> }
-  - Never return prose when invoked programmatically; only the JSON structure.
-  - On error: surface backend error object directly (no rewriting) so the caller can display/log it.
-
-  Disambiguation & Clarification
-  - Missing name (e.g., "find model") → ask: "Which model name would you like to find?"
-  - Plural intent (e.g., "find models" / "list models") → use list-models instead.
-  - If user requests scoring ("score model X") → route to model-score not find-model.
-
-  Examples (→ mapped params)
-  - "find model myModel" → { name: "myModel" }
-  - "does model churn_score exist" → { name: "churn_score" }
-  - "is model riskModel deployed" → { name: "riskModel" }
-  - "lookup model claims_fraud_v1" → { name: "claims_fraud_v1" }
-
-  Negative Examples (should NOT call find-model)
-  - "list models" (list-models)
-  - "score model myModel" (model-score)
-  - "describe model myModel" (model-info)
-
-  Notes
-  - Chain usage: find-model → model-info → model-score.
-  - For batch existence checks iterate over a list and call find-model per entry.
+find-model — locate a specific model deployed to MAS (Model Aggregation Service).
+
+USE when: find model, does model exist, is model deployed, lookup model, verify model exists
+DO NOT USE for: list models (use list-models), model info/variables (use model-info), score model (use model-score), find table/job/lib (use respective tools), scr models (use scr-info/scr-score)
+
+PARAMETERS
+- name: string (required) — model name to locate; if multiple supplied, use first
+
+ROUTING RULES
+- "find model <name>" → { name: "<name>" }
+- "does model <name> exist" → { name: "<name>" }
+- "is model <name> deployed" → { name: "<name>" }
+- "lookup/verify model <name>" → { name: "<name>" }
+- "find model" with no name → ask "Which model name would you like to find?"
+- "find all models / list models" → use list-models instead
+- "score model <name>" → use model-score instead
+- "describe model / model info" → use model-info instead
+
+EXAMPLES
+- "find model myModel" → { name: "myModel" }
+- "does model churn_score exist" → { name: "churn_score" }
+- "is model riskModel deployed" → { name: "riskModel" }
+- "lookup model claims_fraud_v1" → { name: "claims_fraud_v1" }
+
+NEGATIVE EXAMPLES (do not route here)
+- "list models" (use list-models)
+- "score model myModel" (use model-score)
+- "model info for churnRisk" (use model-info)
+
+ERRORS
+Returns { models: [] } if not found; { models: [name, ...] } if found. Never hallucinate model names.
   `;
 
   let spec = {