@sassoftware/sas-score-mcp-serverjs 0.0.2

package/src/toolSet/getEnv.js

@@ -0,0 +1,72 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {z} from 'zod';
+import _getEnv from '../toolHelpers/_getEnv.js';
+function getEnv(_appContext) {
+    let description = `
+## get-env — retrieve a variable value from the runtime environment
+
+LLM Invocation Guidance (When to use)
+Use THIS tool when:
+- The user wants to access a specific environment variable or context value
+- "What is the value of [variable name]?"
+- "Get me the [variable] value"
+- "Show the current [variable]"
+
+Do NOT use this tool for:
+- Retrieving table data (use read-table)
+- Getting model information (use model-info)
+- Looking up job status (use find-job or run-job)
+- Setting environment variables (use set-context to set CAS/SAS contexts)
+
+Purpose
+Retrieve the current value of a named variable from the runtime environment. This is useful for debugging, accessing context information, or verifying current configuration values.
+
+Parameters
+- name (string, required): The name of the variable to retrieve. Variable names are case-sensitive.
+
+Response Contract
+Returns a JSON object containing:
+- The requested variable name as a key
+- The current value of that variable
+- If the variable does not exist, returns null or an error message
+
+Disambiguation & Clarification
+- If variable name is missing: ask "Which variable would you like to retrieve?"
+- If user says "context" without specifying which variable: clarify "Do you mean the CAS context, SAS context, or a specific variable?"
+- Multiple variable request: handle one at a time or ask for clarification
+
+Examples (→ mapped params)
+- "What's the value of myVar" → { name: "myVar" }
+- "Get me the configuration variable" → { name: "configuration" }
+- "Show the current server setting" → { name: "server" }
+
+Negative Examples (should NOT call get-env)
+- "Read all rows from the customers table" (use read-table instead)
+- "Get model details for myModel" (use model-info instead)
+- "Set the CAS server to finance-prod" (use set-context instead)
+
+Related Tools
+- setContext — to set environment context values (CAS and SAS servers)
+- readTable — to retrieve table data
+- modelInfo — to retrieve model metadata
+`;
+  
+    let spec = {
+        name: 'get-env',
+        aliases: ['get-env','get env','get environment'],
+        description: description,
+        schema: {
+            name: z.string()
+        },
+       
+        handler: async (params) => {
+            return await _getEnv(params);
+        }
+    }
+    return spec;
+}
+export default getEnv;

package/src/toolSet/listJobdefs.js

@@ -0,0 +1,96 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from 'zod';
+import _listJobdefs from '../toolHelpers/_listJobdefs.js';
+function listJobdefs(_appContext) {
+
+  let description = `
+  ## list-jobdefs — enumerate SAS Viya job definitions assets(jobdefs)
+
+  LLM Invocation Guidance (When to use)
+  jobdef and jobdefs are used interchangeably here to refer to job definitions.
+  Use THIS tool when the user wants to browse or list many job definitions assets
+  - "list jobdefs"
+  - "show jobdefs"
+  - "list available jobdefs"
+  - "browse jobdefs"
+  - "next jobdefs" (after a previous page)
+  - "list 25 jobdefs" / "list jobdefs limit 25"
+  Do NOT use this tool for:
+  - Checking existence of ONE job (use find-job)
+  - Executing/running a job (use run-job)
+  - Running a job definition (use run-jobdef)
+  - Submitting SAS code (use run-sas-program)
+
+
+  Purpose
+  Page through jobdef assets deployed/registered in SAS Viya.
+
+  Parameters
+  - limit (number, default 10): Number of jobs to return.
+  - start (number, default 1): 1-based offset for paging.
+  - where (string, optional): Filter expression (future use / passthrough; empty string by default). If unsupported, it may be ignored gracefully.
+
+  Response Contract
+  - Returns an array of jobdef names or objects (backend-dependent) inside structuredContent.
+  - If items.length === limit, caller may request next page using start + limit.
+  - Provide optional hint start = start + limit when page might continue.
+
+  Pagination Examples
+  - First page: { start:1, limit:10 }
+  - Next page:  { start:11, limit:10 }
+
+  Disambiguation & Clarification
+  - Input only "list" → ask: "Specify asset to list? (Say 'Please specify what to listlist' to proceed)" unless prior context indicates job definition listing.
+  - Input contains "run"/"execute" plus job name → route to job/jobdef.
+
+  Negative Examples (should NOT call list-jobdefs)
+  - "list libraries" (use list-libraries)
+  - "list tables" (use list-tables)
+  - "list models" (use list-models)
+  - "list jobs" (use list-jobs)
+  - "find job abc" (findJob)
+  - "run job abc" (job)
+  - "job abc" (job)
+  - "find model xyz" (findModel)
+  - "list models" (listModels)
+  - "list tables in lib xyz" (listTables)
+  - "show me libraries" (listLibraries)
+  - "describe job abc" (findJob then possibly job for execution)
+
+  Error Handling
+  - On backend error: surface structured error payload (do not fabricate job names).
+  - Empty page (items.length === 0) with start > 1 may mean caller paged past end.
+
+  Usage Tips
+  - Increase limit for fewer round trips; keep reasonable to avoid large payloads.
+  - Combine with findJobdeffor confirmation before execution.
+
+  Examples (→ mapped params)
+  - "list jobdefs" → { start:1, limit:10 }
+  - "list 25 jobdefs" → { start:1, limit:25 }
+  - "next jobdefs" (after prior {start:1,limit:10}) → { start:11, limit:10 }
+  `;
+
+  let spec = {
+    name: 'list-jobdefs',
+    aliases: ['listJobdefs','list jobdefs','list_jobdefs'],
+    description: description,
+    schema: {
+      limit: z.number().default(10),
+      start: z.number().default(1),
+      where: z.string().default('')
+    },
+  // No 'server' required; backend context is implicit in helper
+  required: [],
+    handler: async (params) => {
+      // _listJobdefs handles all validation and defaults
+      const result = await _listJobdefs(params);
+      return result;
+    }
+  }
+  return spec;
+}
+export default listJobdefs;

package/src/toolSet/listJobs.js

@@ -0,0 +1,110 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from 'zod';
+import _listJobs from '../toolHelpers/_listJobs.js';
+function listJobs(_appContext) {
+  // LLM guidance object retained for potential future consumption; not exported directly.
+  let llmDescription = {
+    purpose: "Map natural language requests to listJobs parameters and return a machine-readable response.",
+    param_mapping: {
+      limit: "positive integer. if not specified, set limit to 10",
+      start: "1-indexed offset. if not specified, set start to 1",
+      where: "optional filter string, default '' (may be ignored)"
+    },
+    response_schema: "{ jobs: string[] , start?: number }",
+    behavior: "Return only JSON matching response_schema. If ambiguous, ask at most one clarifying question. If no results, return { jobs: [] }. Include start when a full page is returned.",
+    examples: [
+      { input: "list jobs", mapped_params: { start: 1, limit: 10 } },
+      { input: "show me jobs, 20 per page", mapped_params: { start: 1, limit: 20 } },
+      { input: "next jobs", note: "interpret as start = previousStart + previousLimit" }
+    ],
+    safety: "Surface backend errors directly; do not hallucinate job names."
+  };
+
+  let description = `
+  ## list-jobs — enumerate SAS Viya job assets
+
+  LLM Invocation Guidance (When to use)
+  Use THIS tool when the user wants to browse or list many job definitions / job assets:
+  - "list jobs"
+  - "show jobs"
+  - "list available jobs"
+  - "browse jobs"
+  - "next jobs" (after a previous page)
+  - "list 25 jobs" / "list jobs limit 25"
+
+  Do NOT use this tool for:
+  - Checking existence of ONE job (use find-job)
+  - Executing/running a job (use run-job)
+  - Running a job definition (use run-jobdef)
+  - Submitting SAS code (use run-sas-program)
+
+
+  Purpose
+  Page through job assets deployed/registered in SAS Viya Job Execution service.
+
+  Parameters
+  - limit (number, default 10): Number of jobs to return.
+  - start (number, default 1): 1-based offset for paging.
+  - where (string, optional): Filter expression (future use / passthrough; empty string by default). If unsupported, it may be ignored gracefully.
+
+  Response Contract
+  - Returns an array of job names or objects (backend-dependent) inside structuredContent.
+  - If items.length === limit, caller may request next page using start + limit.
+  - Provide optional hint start = start + limit when page might continue.
+
+  Pagination Examples
+  - First page: { start:1, limit:10 }
+  - Next page:  { start:11, limit:10 }
+
+  Disambiguation & Clarification
+  - Input only "list" → ask: "List jobs? (Say 'list jobs' to proceed)" unless prior context indicates jobs listing.
+  - "find job X" → route to findJob instead.
+  - Input contains "run"/"execute" plus job name → route to job/jobdef.
+
+  Negative Examples (should NOT call list-jobs)
+  - "find job abc" (find-job)
+  - "run job abc" (run-job)
+  - "job abc" (run-job)
+  - "find model xyz" (find-model)
+  - "list models" (list-models)
+  - "list tables in lib xyz" (list-tables)
+  - "show me libraries" (list-libraries)
+  - "describe job abc" (find-job then possibly run-job for execution)
+
+  Error Handling
+  - On backend error: surface structured error payload (do not fabricate job names).
+  - Empty page (items.length === 0) with start > 1 may mean caller paged past end.
+
+  Usage Tips
+  - Increase limit for fewer round trips; keep reasonable to avoid large payloads.
+  - Combine with findJob for confirmation before execution.
+
+  Examples (→ mapped params)
+  - "list jobs" → { start:1, limit:10 }
+  - "list 25 jobs" → { start:1, limit:25 }
+  - "next jobs" (after prior {start:1,limit:10}) → { start:11, limit:10 }
+  `;
+
+  let spec = {
+    name: 'list-jobs',
+    aliases: ['listJobs','list jobs','list_jobs'],
+    description: description,
+    schema: {
+      limit: z.number().default(10),
+      start: z.number().default(1),
+      where: z.string().default('')
+    },
+  // No 'server' required; backend context is implicit in helper
+  required: [],
+    handler: async (params) => {
+      // _listJob handles all validation and defaults
+      const result = await _listJobs(params);
+      return result;
+    }
+  }
+  return spec;
+}
+export default listJobs;

package/src/toolSet/listLibraries.js

@@ -0,0 +1,90 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from 'zod';
+import _listLibrary from '../toolHelpers/_listLibrary.js';
+function listLibraries(_appContext) {
+ 
+  let description = `
+  ## 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' }
+  - "next" (after prior call) → { start: previous.start + previous.limit }
+  - "first 20 cas libs" → { server: 'cas', limit: 20 }
+  - If server unspecified: default to CAS.
+
+  Parameters
+  - server (cas|sas, default 'cas')
+  - 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: 'cas', start:1, limit:10 }
+  - "list libs" → { server: 'cas', start:1, limit:10 }
+  - "list sas libs" → { server: 'sas' }
+  - "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.
+  `;
+
+
+  // Canonical kebab-case tool name; legacy aliases preserved for compatibility
+  
+ 
+  let spec = {
+    name: 'list-libraries',
+    aliases: ['listLibraries','list libraries','list_libraries'],
+    description: description,
+    schema: {
+      server: z.string().default('cas'),
+      limit: z.number().default(10),
+      start: z.number().default(1), // added default to match documentation
+      where: z.string().default('')
+    },
+    // 'server' has a default so we don't mark it required
+    required: [],
+    handler: async (params) => {
+      // normalize server just in case caller sends 'CAS'/'SAS'
+      params.server = (params.server || 'cas').toLowerCase();
+      
+      let r = await _listLibrary(params);
+      return r;
+    }
+  };
+  return spec;
+}
+export default listLibraries;
+     

package/src/toolSet/listModels.js

@@ -0,0 +1,83 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { z } from 'zod';
+import _listModels from '../toolHelpers/_listModels.js';
+
+function listModels(_appContext) {
+  let description = `
+  ## list-models — enumerate models published to MAS (Model Publish / Scoring service)
+
+  LLM Invocation Guidance (When to use)
+  Use THIS tool when the user wants a collection of models, e.g.:
+  - "list models"
+  - "show models"
+  - "list available models"
+  - "browse models"
+  - "list 25 models" / "list models limit 25"
+  - "next models" (after a previous page)
+
+  Do NOT use this tool for:
+  - Checking a single model's existence (use find-model)
+  - Getting model metadata / variables (use model-info)
+  - Scoring a model (use model-score)
+  - list libraries, tables, jobs, or jobdefs (use respective list/find tools)
+  - Looking up jobs, libraries, tables, or SCR endpoints (route to respective tools)
+
+  Purpose
+  Provide a paginated view of MAS-registered models so the caller can then drill into one via modelInfo or score it.
+
+  Parameters
+  - limit (number, default 10): Number of models to return for this page.
+  - start (number, default 1): 1-based offset. For paging: start = start + limit.
+
+  Response Contract
+  - Returns an array of model entries (names or metadata objects). Empty array if no models.
+  - If returned length === limit, caller may request the next page.
+
+  Pagination Examples
+  - First page: { start:1, limit:10 }
+  - Next page: { start:11, limit:10 }
+
+  Disambiguation & Clarification
+  - Input only "list" → ask: "List models? (Say 'list models' to proceed)" unless prior context strongly indicates models.
+  - "find model X" → use find-model instead.
+  - "score model X" → use model-score.
+  - "describe model X" → use model-info.
+
+  Negative Examples (should NOT call list-models)
+  - "find model churn" (find-model)
+  - "model info customerRisk" (model-info)
+  - "score model sales_pred" (model-score)
+  - "list jobs" (list-jobs)
+
+  Usage Tips
+  - Combine with findModel for narrowing down after a broad list.
+  - Increase limit judiciously; very large pages can impact latency.
+
+  Examples (→ mapped params)
+  - "list models" → { start:1, limit:10 }
+  - "list 25 models" → { start:1, limit:25 }
+  - "next models" (after prior {start:1,limit:10}) → { start:11, limit:10 }
+  `;
+
+  let spec = {
+    name: 'list-models',
+    aliases: ['listModels','list models','list_models'],
+    description: description,
+    schema: {
+      'limit': z.number().default(10),
+      'start': z.number().default(1) 
+        },
+    handler: async (params) => { 
+      let r  = await _listModels(params);
+      return r;
+    }
+  }
+  
+  return spec;
+}
+
+export default listModels;

package/src/toolSet/listTables.js

@@ -0,0 +1,95 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { z } from 'zod';
+import debug from 'debug';
+import _listTables from '../toolHelpers/_listTables.js';
+
+
+function listTables(_appContext) {
+  const log = debug('tools');
+
+    let description = `
+    ## list-tables — enumerate tables within a specific CAS or SAS library
+
+  LLM Invocation Guidance (When to use)
+  Use THIS tool when the user explicitly wants the tables inside ONE library:
+  - "list tables in Samples"
+  - "show tables in sashelp"
+  - "list cas tables in Public"
+  - "list 25 tables in Samples"
+  - "next tables" (after a prior listTables call)
+
+  Do NOT use this tool to list the following
+  - lib -> use list-libraries
+  - list models -> use list-models
+  - list jobs -> use list-jobs
+  - list jobdefs -> use list-jobdefs
+  - Finding whether a library exists (use find-library)
+  - Describing a single table's columns or metadata (use table-info)
+  - Reading table data rows (use read-table)
+  - Listing jobs/models (other specialized tools)
+
+  Purpose
+  Return the names (and possibly lightweight metadata) of tables contained in a specified library (CAS caslib or SAS libref).
+
+  Parameters
+  - lib (string, required): Library to inspect (e.g. "Samples", "sashelp").
+  - server (cas|sas, default 'cas'): Target environment; default when unspecified is CAS.
+  - limit (number, default 10): Page size.
+  - start (number, default 1): 1-based offset for pagination.
+  - where (string, optional): Filter expression (if supported by backend) or ignored safely.
+
+  Response Contract
+  - JSON: { tables: string[] [, start:number]? }
+  - tables array is empty when no matches.
+  - Include start = start + limit when length === limit (possible more pages).
+
+  Pagination Examples
+  - First page: { lib:'Samples', start:1, limit:10 }
+  - Next page:  { lib:'Samples', start:11, limit:10 }
+
+  Disambiguation & Clarification
+  - Missing library name → ask: "Which library do you want to list tables from?"
+  - Input only "list tables" → ask for the library unless prior context supplies one.
+  - If user mentions multiple libs ("tables in Public and Samples") → request a single library.
+
+  Negative Examples (should NOT call list-tables)
+  - "list libs" (list-libraries)
+  - "find lib Public" (find-library)
+  - "describe table cars" (table-info)
+  - "read table cars from sashelp" (read-table)
+
+  Usage Tips
+  - After listing, call table-info to inspect structure or read-table for sample data.
+  - Keep limit moderate; page for very large libraries.
+
+  Examples (→ mapped params)
+  - "list tables in samples" → { lib:"samples", start:1, limit:10 }
+  - "show 25 tables in sashelp" → { lib:"sashelp", limit:25, start:1 }
+  - "next tables" (after previous {start:1,limit:10}) → { start:11, limit:10, lib:<previousLib> }
+  `;
+    
+  let spec = {
+      name: 'list-tables',
+      aliases: ['listTables','list tables','list_tables'],
+    description: description,
+
+    schema: {
+      'lib': z.string(),
+      'server': z.string().default('cas'),
+      'limit': z.number().default(10),
+      'start': z.number().default(1)
+    },
+    required: ['lib'],
+    handler: async (params) => { 
+      let r = await _listTables(params);
+      return r;
+    }
+  }
+  return spec;
+}
+
+export default listTables;

package/src/toolSet/makeTools.js

@@ -0,0 +1,75 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import listModels from './listModels.js';
+import listTables from './listTables.js';
+import modelScore from './modelScore.js';
+import modelInfo from './modelInfo.js';
+import findLibrary from './findLibrary.js';
+import readTable from './readTable.js';
+import tableInfo from './tableInfo.js';
+import listLibraries from './listLibraries.js';
+
+import scrInfo from './scrInfo.js';
+import scrScore from './scrScore.js';
+
+import devaScore from './devaScore.js';
+
+import findTable from './findTable.js';
+import findModel from './findModel.js';
+import runProgram from './runProgram.js';
+import runMacro from './runMacro.js';
+import runJob from './runJob.js';
+import listJobs from './listJobs.js';
+import runJobdef from './runJobdef.js';
+import findJob from './findJob.js';
+import listJobdefs from './listJobdefs.js';
+import findJobdef from './findJobdef.js';
+
+import sasQuery from './sasQuery.js';
+import setContext from './setContext.js';
+
+function makeTools(_appContext) {
+  // wrap all tools with 
+  let customTools = [];
+
+  // get the tool definitions and handler 
+  let list = [
+    listModels(_appContext),
+    
+    findModel(_appContext),
+    modelInfo(_appContext),
+    modelScore(_appContext),
+
+    scrInfo(_appContext),
+    scrScore(_appContext),
+
+    findLibrary(_appContext),
+    listLibraries(_appContext),
+    findTable(_appContext),
+    tableInfo(_appContext),
+    listTables(_appContext),
+    readTable(_appContext),
+    sasQuery(_appContext),
+
+    runProgram(_appContext),
+    runMacro(_appContext),
+
+    findJob(_appContext),
+    listJobs(_appContext),
+    runJob(_appContext),
+    listJobdefs(_appContext),
+    findJobdef(_appContext),
+    runJobdef(_appContext),
+
+    devaScore(_appContext),
+    setContext(_appContext)
+    
+  ];
+  let listWithCustom = list.concat(customTools);
+  console.error(`\n[Note] Loaded a total of ${listWithCustom.length} tools.`);
+  return listWithCustom;
+}
+export default makeTools;