@sassoftware/sas-score-mcp-serverjs 1.0.1-9 → 1.1.2

package/src/toolSet/findTable.js

@@ -1,43 +1,48 @@
-/*
- * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+/*
+ * 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';
+import _findTable from '../toolHelpers/_findTable.js';
 
 function findTable(_appContext) {
-  let description = `
-find-table — locate a specific table in a CAS or SAS library.
+  const isAgent = _appContext && _appContext.agent;
+  let description = isAgent ? `
+find-table — verify a table exists in a library.
+PARAMS: lib (string, required), name (string, required), server ('cas'|'sas', required)
+RETURNS: table metadata if found, error if not found
+` : `
+find-table — locate a specific table in a CAS or SAS library.
 
 USE when: find table, does table exist, is table in library, verify table exists, locate table
-DO NOT USE for: list tables (use list-tables), table schema/columns (use table-info), read table data (use read-table), find lib/job/model (use respective tools)
+DO NOT USE for: list tables (use ${_appContext.brand}-list-tables), table schema/columns (use ${_appContext.brand}-table-describe), read table data (use ${_appContext.brand}-read-table), find lib/job/model (use respective tools)
 
 PARAMETERS
-- lib: string (required) — library name (e.g., 'Public', 'sashelp')
-- name: string (required) — table name to locate
-- server: 'cas' | 'sas' . If not specified set it to 'cas' — target environment
+- lib: string (required) — library name (e.g., 'Public', 'sashelp')
+- name: string (required) — table name to locate
+- server: 'cas' | 'sas' (required) — target environment
 
 ROUTING RULES
-- "find table <name> in <lib>" → { lib: "<lib>", name: "<name>", server: "cas" }
-- "find table <name> in <lib> in sas" → { lib: "<lib>", name: "<name>", server: "sas" }
-- "does table <name> exist in <lib>" → { lib: "<lib>", name: "<name>", server: "cas" }
-- "find table" with missing lib → ask "Which library contains the table?"
-- "find table" with missing name → ask "Which table name would you like to find?"
-- "list tables in <lib>" → use list-tables instead
+- "find table <name> in <lib>" → { lib: "<lib>", name: "<name>", server: "cas" }
+- "find table <name> in <lib> in sas" → { lib: "<lib>", name: "<name>", server: "sas" }
+- "does table <name> exist in <lib>" → { lib: "<lib>", name: "<name>", server: "cas" }
+- "find table" with missing lib → ask "Which library contains the table?"
+- "find table" with missing name → ask "Which table name would you like to find?"
+- "list tables in <lib>" → use ${_appContext.brand}-list-tables instead
 
 EXAMPLES
-- "find table iris in Public" → { lib: "Public", name: "iris", server: "cas" }
-- "find table cars in sashelp in sas" → { lib: "sashelp", name: "cars", server: "sas" }
-- "does customers exist in mylib" → { lib: "mylib", name: "customers", server: "cas" }
-- "verify table orders in Samples" → { lib: "Samples", name: "orders", server: "cas" }
+- "find table iris in Public" → { lib: "Public", name: "iris", server: "cas" }
+- "find table cars in sashelp in sas" → { lib: "sashelp", name: "cars", server: "sas" }
+- "does customers exist in mylib" → { lib: "mylib", name: "customers", server: "cas" }
+- "verify table orders in Samples" → { lib: "Samples", name: "orders", server: "cas" }
 
 NEGATIVE EXAMPLES (do not route here)
-- "list tables in Public" (use list-tables)
-- "find library Public" (use find-library)
-- "what columns in cars?" (use table-info)
-- "read data from customers" (use read-table)
+- "list tables in Public" (use ${_appContext.brand}-list-tables)
+- "find library Public" (use ${_appContext.brand}-find-library)
+- "what columns in cars?" (use ${_appContext.brand}-table-describe)
+- "read data from customers" (use ${_appContext.brand}-read-table)
 
 ERRORS
 Returns { tables: [] } if not found; { tables: [name, ...] } if found. Never hallucinate table names.
@@ -47,14 +52,15 @@ Returns { tables: [] } if not found; { tables: [name, ...] } if found. Never hal
     name: 'find-table',
     description: description,
     inputSchema: z.object({
-      lib: z.string(),
-      name: z.string(),
-      server: z.string() 
+      lib: z.string().min(1),
+      name: z.string().min(1),
+      server: z.enum(['cas', 'sas'])
     }),
     
     handler: async (params) => {
       // Check if the params.scenario is a string and parse it
-      let r = await _listTables(params);
+      params.tool = 'find';
+      let r = await _findTable(params);
       return r;
     }
   }
@@ -63,3 +69,4 @@ Returns { tables: [] } if not found; { tables: [name, ...] } if found. Never hal
 
 export default findTable;
 
+

package/src/toolSet/getEnv.js

@@ -10,7 +10,7 @@ function getEnv(_appContext) {
 get-env — retrieve a variable value from the runtime environment.
 
 USE when: what is the value of, get me, show current, what's the, retrieve environment variable
-DO NOT USE for: read table data (use read-table), model info (use model-info), find/run job (use find-job/run-job), set context (use set-context)
+DO NOT USE for: read table data (use ${_appContext.brand}-read-table), model info (use ${_appContext.brand}-model-info), find/score job (use ${_appContext.brand}-find-job/${_appContext.brand}-job-score), set context (use ${_appContext.brand}-set-context)
 
 PARAMETERS
 - name: string (required) — variable name to retrieve (case-sensitive)
@@ -20,8 +20,8 @@ ROUTING RULES
 - "get me <var>" → { name: "<var>" }
 - "show <var>" → { name: "<var>" }
 - "get" with no variable → ask "Which variable would you like to retrieve?"
-- "what context am I using" → use set-context instead (no params)
-- "set <var> to <value>" → use set-context or run-sas-program instead
+    - "what context am I using" → use ${_appContext.brand}-set-context instead (no params)
+    - "set <var> to <value>" → use ${_appContext.brand}-set-context or ${_appContext.brand}-program-score instead
 
 EXAMPLES
 - "What's the value of myVar" → { name: "myVar" }
@@ -29,9 +29,9 @@ EXAMPLES
 - "Show the current server setting" → { name: "server" }
 
 NEGATIVE EXAMPLES (do not route here)
-- "Read rows from customers" (use read-table)
-- "Get model details for myModel" (use model-info)
-- "Set the CAS server to finance-prod" (use set-context)
+-- "Read rows from customers" (use ${_appContext.brand}-read-table)
+-- "Get model details for myModel" (use ${_appContext.brand}-model-info)
+-- "Set the CAS server to finance-prod" (use ${_appContext.brand}-set-context)
 
 ERRORS
 Returns variable name with current value, or null if not found. Return structured error with message field.

package/src/toolSet/jobDescribe.js

@@ -0,0 +1,65 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from 'zod';
+import _findJob from '../toolHelpers/_findJob.js';
+function jobDescribe(_appContext) {
+  const isAgent = _appContext && _appContext.agent;
+  let description = isAgent ? `
+job-describe — return input schema for a Job model.
+PARAMS: intent ('describe', required), name (string, required)
+RETURNS: job input variable definitions
+` : `
+job-describe — return information about a specific SAS Viya job.
+
+USE when: describe job, show job details, what does job X do, job metadata, inputs/outputs for job
+DO NOT USE for: find job or verify it exists (use ${_appContext.brand}-find-job), list jobs (use ${_appContext.brand}-list-jobs), score job (use ${_appContext.brand}-job-score)
+
+PARAMETERS
+- intent: must be 'describe' — only pass if user explicitly asked to describe/inspect a job. Do NOT use for find or verify existence.
+- name: string (required) — name of job whose details are being requested. Should be exact match to job name.
+
+ROUTING RULES
+- "describe job <name>" → { name: "<name>" }
+- "describe model <name.job>"
+- "info for job <name>" → { name: "<name>" }
+
+EXAMPLES
+- "describe job cars_job_v4" → { name: "cars_job_v4" }
+- "describe metricsRefresh.job" → { name: "metricsRefresh" }
+
+NEGATIVE EXAMPLES (do not route here)
+- "list jobs" (use ${_appContext.brand}-list-jobs)
+- "score job cars_job_v4" (use ${_appContext.brand}-job-score)
+- "score jobdef cars_job_v4" (use ${_appContext.brand}-jobdef-score)
+
+ERRORS
+Returns job metadata 
+  `;
+
+  let spec = {
+    name: 'job-describe',
+    description: description,
+    inputSchema: z.object({
+      intent: z.literal('describe'),
+      name: z.string()
+    }),
+    handler: async (params) => {
+      const { intent, ...rest } = params;
+      if (rest.name != null && rest.name.endsWith('.job')) {
+        rest.name = rest.name.slice(0, -4);
+      }
+      rest.tool = 'describe';
+      let r = await _findJob(rest); 
+      return r;
+    }
+  }
+    
+
+  /* correct spec for registerTool with inputSchema */
+  
+  return spec;
+}
+export default jobDescribe;
+

package/src/toolSet/jobScore.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 _jobSubmit from '../toolHelpers/_jobSubmit.js';
+
+function jobScore(_appContext) {
+  const isAgent = _appContext && _appContext.agent;
+
+  let description = isAgent ? `
+job-score — score by executing a SAS Viya Job model.
+PARAMS: name (string, required), scenario (object, optional)
+RETURNS: job log, ODS output, and any result tables
+` : `
+job-score — score with a deployed SAS Viya job model.
+
+USE when: score with job, run job, execute job model
+DO NOT USE for: arbitrary SAS code (use program-score), macros (use macro-score), list/find jobs
+
+PARAMETERS
+- name: string — job name (required)
+- scenario: object — input parameters as JSON (optional, defaults to {}). Example: {month:10, year:2025}
+
+ROUTING RULES
+- "score with job xyz" → { name: "xyz" }
+- "score with job xyz with param1=10, param2=val2" → { name: "xyz", scenario: {param1:10, param2:"val2"} }
+- "run job xyz" → { name: "xyz" }
+- "run job xyz with param1=10, param2=val2" → { name: "xyz", scenario: {param1:10, param2:"val2"} }
+
+EXAMPLES
+- "score with job xyz" → { name: "xyz" }
+- "score with job monthly_etl with month=10, year=2025" → { name: "monthly_etl", scenario: {month:10, year:2025} }
+- "score with monthly_etl.job with month=10, year=2025" → { name: "monthly_etl", scenario: {month:10, year:2025} }
+- "run job xyz" → { name: "xyz" }
+- "run job monthly_etl with month=10, year=2025" → { name: "monthly_etl", scenario: {month:10, year:2025} }
+
+NEGATIVE EXAMPLES (do not route here)
+- "run SAS code" (use program-score)
+- "score macro X" (use macro-score)
+- "list jobs" (use list-jobs)
+- "find job X" (use find-job)
+
+ERRORS
+Returns log output, listings, tables from job. Error if job not found.
+`;
+
+  let spec = {
+    name: 'job-score',
+    description: description,
+    inputSchema: z.object({
+      name: z.string(),
+      scenario: z.any()
+    }),
+    handler: async (params) => {
+      let {scenario, name} = params;
+
+      if(name.endsWith('.job')) {
+        params.name = name.slice(0, -4);
+      }
+      // Convert the scenario string to an object
+      // Example: "x=1, y=2, z=3" to { x: 1, y: 2, z: 3 }
+      let scenarioObj = {};
+      let count = 0;
+      if (typeof scenario === 'object') {
+        scenarioObj = scenario;
+      } else if (Array.isArray(scenario)) {
+        scenarioObj = scenario[0];
+      } else {
+        //console.error('Incoming scenario', scenario);
+        scenarioObj = scenario.split(',').reduce((acc, pair) => {
+          let [key, value] = pair.split('=');
+          acc[key.trim()] = value;
+          count++;
+          return acc;
+        }, {});
+      }
+      params.scenario = scenarioObj;
+      params.type = 'job';
+      // Provide runtime context for auth and server settings
+      let r = await _jobSubmit(params);
+      return r;
+    }
+  };
+  return spec;
+}
+
+export default jobScore;
+

package/src/toolSet/jobdefDescribe.js

@@ -0,0 +1,67 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from 'zod';
+import _findJobdef from '../toolHelpers/_findJobdef.js';
+function jobdefDescribe(_appContext) {
+  const isAgent = _appContext && _appContext.agent;
+  let description = isAgent ? `
+jobdef-describe — return input schema for a JobDef model.
+PARAMS: intent ('describe', required), name (string, required)
+RETURNS: jobdef input variable definitions
+` : `
+jobdef-describe — return information about a specific SAS Viya jobdef.
+
+USE when: describe jobdef, show jobdef details, what does jobdef X do, jobdef metadata, inputs/outputs for jobdef
+DO NOT USE for: find jobdef or verify it exists (use ${_appContext.brand}-find-jobdef), list jobdefs (use ${_appContext.brand}-list-jobdefs), score jobdef (use ${_appContext.brand}-jobdef-score)
+
+PARAMETERS
+- intent: must be 'describe' — only pass if user explicitly asked to describe/inspect a jobdef. Do NOT use for find or verify existence.
+- name: string (required) — name of jobdef whose details are being requested. Should be exact match to jobdef name.
+
+ROUTING RULES
+- "describe jobdef <name>" → { name: "<name>" }
+- "describe <name.jobdef>"  
+- "describe model <name.jobdef>"
+- "info for jobdef <name>" → { name: "<name>" }
+
+EXAMPLES
+- "describe jobdef cars_job_v4" → { name: "cars_job_v4" }
+- "describe metricsRefresh.jobdef" → { name: "metricsRefresh" }
+- "info for jobdef ETL" → { name: "ETL" }
+
+NEGATIVE EXAMPLES (do not route here)
+- "list jobdefs" (use ${_appContext.brand}-list-jobdefs)
+- "score jobdef cars_job_v4" (use ${_appContext.brand}-jobdef-score)
+- "execute jobdef cars_job_v4" (use ${_appContext.brand}-jobdef-score)
+
+ERRORS
+Returns job metadata 
+  `;
+
+  let spec = {
+    name: 'jobdef-describe',
+    description: description,
+    inputSchema: z.object({
+      intent: z.literal('describe'),
+      name: z.string()
+    }),
+    handler: async (params) => {
+      const { intent, ...rest } = params;
+      if (rest.name != null && rest.name.endsWith('.jobdef')) {
+        rest.name = rest.name.slice(0, -7);
+      }
+      rest.tool = 'describe';
+      let r = await _findJobdef(rest);
+      return r;
+    }
+  }
+    
+
+  /* correct spec for registerTool with inputSchema */
+  
+  return spec;
+}
+export default jobdefDescribe;
+

package/src/toolSet/jobdefScore.js

@@ -0,0 +1,85 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { z } from 'zod';
+import _jobSubmit from '../toolHelpers/_jobSubmit.js';
+
+function jobdefScore(_appContext) {
+  // JSON object for LLM/tooling
+  const isAgent = _appContext && _appContext.agent;
+  let description = isAgent ? `
+jobdef-score — score by executing a SAS Viya JobDef model.
+PARAMS: name (string, required), scenario (object, optional)
+RETURNS: jobdef log, ODS output, and any result tables
+` : `
+jobdef-score — score with a deployed SAS Viya job definition model.
+
+USE when: score with jobdef, run jobdef, execute jobdef model
+DO NOT USE for: arbitrary SAS code (use program-score), macros (use macro-score), list/find jobdefs
+
+PARAMETERS
+- name: string — jobdef name (required)
+- scenario: object — input parameters as JSON (optional, defaults to {}). Example: {month:10, year:2025}
+
+ROUTING RULES
+- "score jobdef xyz" → { name: "xyz" }
+- "score jobdef xyz with param1=10, param2=val2" → { name: "xyz", scenario: {param1:10, param2:"val2"} }
+
+EXAMPLES
+- "score jobdef xyz" → { name: "xyz" }
+- "score jobdef monthly_report with month=10, year=2025" → { name: "monthly_report", scenario: {month:10, year:2025} }
+
+NEGATIVE EXAMPLES (do not route here)
+- "run SAS code" (use program-score)
+- "score macro X" (use macro-score)
+- "list jobdefs" (use list-jobdefs)
+- "find jobdef X" (use find-jobdef)
+
+ERRORS
+Returns log output, listings, tables from jobdef. Error if jobdef not found.
+  `;
+ 
+  let spec = {
+    name: 'jobdef-score',
+    description: description,
+    inputSchema: z.object({
+      name: z.string(),
+      scenario: z.any()
+    }),
+    handler: async (params) => {
+      let {scenario, name} = params;
+
+      if (name.endsWith('.job')) {
+        params.name = name.slice(0, -4);
+      }
+      // Convert the scenario string to an object
+      // Example: "x=1, y=2, z=3" to { x: 1, y: 2, z: 3 }
+      let scenarioObj = {};
+      let count = 0;
+      if (typeof scenario === 'object') {
+        scenarioObj = scenario;
+      } else if (Array.isArray(scenario)) {
+        scenarioObj = scenario[0];
+      } else {
+        //console.error('Incoming scenario', scenario);
+        scenarioObj = scenario.split(',').reduce((acc, pair) => {
+          let [key, value] = pair.split('=');
+          acc[key.trim()] = value;
+          count++;
+          return acc;
+        }, {});
+      }
+      params.scenario = scenarioObj;      
+      params.type = 'def';
+      // Provide runtime context for auth and server settings
+      let r = await _jobSubmit(params);
+      return r;
+    }
+  };
+  return spec;
+}
+
+export default jobdefScore;
+

package/src/toolSet/listJobdefs.js

@@ -1,61 +1,70 @@
-/*
- * 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 (jobdefs) assets.
-
-USE when: list jobdefs, show jobdefs, browse jobdefs, list available jobdefs, next page
-DO NOT USE for: find single jobdef (use find-jobdef), execute jobdef (use run-jobdef), find job (use find-job), sas code (use run-sas-program)
-
-PARAMETERS
-- limit: number (default: 10) — number of jobdefs per page
-- start: number (default: 1) — 1-based page offset
-- where: string (default: '') — optional filter expression
-
-ROUTING RULES
-- list jobdefs → { start: 1, limit: 10 }
-- show me 25 jobdefs → { start: 1, limit: 25 }
-- next jobdefs → { start: previousStart + previousLimit, limit: previousLimit }
-
-EXAMPLES
-- list jobdefs → { start: 1, limit: 10 }
-- list 25 jobdefs → { start: 1, limit: 25 }
-- next jobdefs → { start: 11, limit: 10 }
-
-NEGATIVE EXAMPLES (do not route here)
-- find jobdef abc (use find-jobdef)
-- list jobs (use list-jobs)
-- run jobdef abc (use run-jobdef)
-- list models (use list-models)
-
-PAGINATION
-If returned length === limit, hint: next start = start + limit. Empty result with start > 1 means paged past end.
-
-ERRORS
-Surface backend error directly; never fabricate jobdef names.
-  `;
-
-  let spec = {
-    name: 'list-jobdefs',
-    description: description,
-    inputSchema: z.object({
-      limit: z.number().optional(),
-      start: z.number().optional(),
-      where: z.string().optional()
-    }),
-  // No 'server' required; backend context is implicit in helper
-    handler: async (params) => {
-      // _listJobdefs handles all validation and defaults
-      const result = await _listJobdefs(params);
-      return result;
-    }
-  }
-  return spec;
-}
-export default listJobdefs;
-
+/*
+ * 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) {
+  const isAgent = _appContext && _appContext.agent;
+  let description = isAgent ? `
+list-jobdefs — list available JobDef models.
+PARAMS: intent ('list', required), start (number, default 1), limit (number, default 10)
+RETURNS: array of jobdef names and metadata
+` : `
+list-jobdefs — enumerate SAS Viya job definitions (jobdefs) assets.
+
+USE when: list jobdefs, show jobdefs, browse jobdefs, list available jobdefs, next page
+DO NOT USE for: find single jobdef (use ${_appContext.brand}-find-jobdef), score jobdef (use ${_appContext.brand}-jobdef-score), find job (use ${_appContext.brand}-find-job), sas code (use ${_appContext.brand}-program-score)
+
+PARAMETERS
+- intent: must be 'list' — only pass if user explicitly asked to list/enumerate jobdefs. Do NOT use for find, verify, or execute.
+- limit: number (default: 10) — number of jobdefs per page
+- start: number (default: 1) — 1-based page offset
+- where: string (default: '') — optional filter expression
+
+ROUTING RULES
+- list jobdefs → { start: 1, limit: 10 }
+- show me 25 jobdefs → { start: 1, limit: 25 }
+- next jobdefs → { start: previousStart + previousLimit, limit: previousLimit }
+
+EXAMPLES
+- list jobdefs → { start: 1, limit: 10 }
+- list 25 jobdefs → { start: 1, limit: 25 }
+- next jobdefs → { start: 11, limit: 10 }
+
+NEGATIVE EXAMPLES (do not route here)
+- find jobdef abc (use ${_appContext.brand}-find-jobdef)
+- does jobdef X exist (use ${_appContext.brand}-find-jobdef)
+- is jobdef X available (use ${_appContext.brand}-find-jobdef)
+- list jobs (use ${_appContext.brand}-list-jobs)
+- score jobdef abc (use ${_appContext.brand}-jobdef-score)
+- list models (use ${_appContext.brand}-list-models)
+
+PAGINATION
+If returned length === limit, hint: next start = start + limit. Empty result with start > 1 means paged past end.
+
+ERRORS
+Surface backend error directly; never fabricate jobdef names.
+  `;
+
+  let spec = {
+    name: 'list-jobdefs',
+    description: description,
+    inputSchema: z.object({
+      intent: z.literal('list'),
+      limit: z.number().optional(),
+      start: z.number().optional(),
+      where: z.string().optional()
+    }),
+  // No 'server' required; backend context is implicit in helper
+    handler: async (params) => {
+      // _listJobdefs handles all validation and defaults
+      const { intent, ...rest } = params;
+      const result = await _listJobdefs(rest);
+      return result;
+    }
+  }
+  return spec;
+}
+export default listJobdefs;
+