@sassoftware/sas-score-mcp-serverjs 0.4.1 → 1.0.1-0

package/src/toolSet/runCasProgram.js

@@ -8,74 +8,53 @@ import _submitCode from '../toolHelpers/_submitCode.js';
 
 function runCasProgram(_appContext) {
   let description = `
-## run-cas-program
+run-cas-program — execute a CAS program on SAS Viya server.
 
-Execute a cas program on a SAS Viya server
+USE when: run cas program, execute cas, submit cas, cas action
+DO NOT USE for: macros (use run-macro), sas code (use run-sas-program), jobs (use run-job), jobdefs (use run-jobdef)
 
-Required Parameters
-- src(string, required): The cas program to execute. 
+PARAMETERS
+- src: string (required) — CAS program to execute verbatim
+- scenario: string or object (optional) — input parameters
+- folder: string — server folder path for .sas files
+- output: string — table name to return in response
+- limit: number (default: 100) — max rows to return
 
-Optional Parameters:
+ROUTING RULES
+- run cas program action echo → { src: action echo }
+- execute cas action simple.summary → { src: action simple.summary }
 
-- scenario (string | object ,optional): Input values to program/ Accepts:
-  - a comma-separated key=value string (e.g. "x=1, y=2"),
-  - a JSON object with field names and values (recommended for typed inputs),
+EXAMPLES
+- run cas program action echo → { src: action echo }
+- cas program sample folder=/Public/models → { src: sample, folder: /Public/models }
 
-LLM Invocation Guidance
-Use THIS tool when the user wants to run a Cas program on the server:
-- "run cas program 'action echo / code='aaaa'"
-- "cas program 'action echo / code='aaaa'"
-- 'submit cas "action echo / code='aaaa'"'
+NEGATIVE EXAMPLES (do not route here)
+- run sas macro (use run-macro)
+- submit sas code (use run-sas-program)
+- run job X (use run-job)
 
+NOTES
+Sends src verbatim without validation. For SAS macros use run-macro. For arbitrary SAS code use run-sas-program.
 
-Do NOT use this tool when the user wants:
-- run macro -> use run-macro
-- submit sas -> use run-sas-program
-- run job -> use run-job
-- run sas  -> use run-sas-program
-- run jobdef -> use run-jobdef
-- run job -> use run-job
-- list jobs -> use list-jobs
-- list jobdefs -> use list-jobdefs
-- find job -> use find-job
-- find jobdef -> use find-jobdef
-- find model -> use find-model
-
-
-Behavior & usage notes
-- This tool sends the supplied \`src\` verbatim to the SAS execution helper. It does not modify or validate the SAS code.
-- For invoking pre-defined SAS macros, prefer the \`runMacro\` helper which converts simple parameter formats into \`%let\` statements and invokes the macro cleanly.
-- Be cautious when executing arbitrary code — validate or sanitize inputs in untrusted environments.
-
-Response
-- If output is specified and the specified table exists in the response, display the data as a markdown table. 
-Examples
-- run program "data a; x=1; run;"  - this is the simplest usage  -- {src= "data a; x=1; run;", folder=" ", output=" ", limit=100}
-- program "data work.a; x=1; run;" output=a limit=50  -- {src= "data work.a; x=1; run;", folder=" ", output="a", limit=50}
-
-- run program sample folder=/Public/models output=A limit=50 -- {src= "sample", folder="/Public/models", output="A", limit=50}
-- run program sample folder=/Public/models scenario="name='John', age=45" output=a limit=50 -- {src= "sample", folder="/Public/models", scenario: {name: "John", age: 45}, output="a", limit=50}
-- run program sample folder=/Public/models with scenario name=John,age=45 output=a limit=50  -- {src= "sample.sas", folder="/Public/models", scenario: {name: "John", age: 45}, output="a", limit=50}
-  - this should be the same as the previous example and is just a different syntax. The result should be
-    {program: "sample", folder: "/Public/models", scenario: {name: "John", age: 45}, output: "a", limit: 50}
+RESPONSE
+Log output and CAS results. If output table specified, returned as markdown table.
 `;
 
   let spec = {
-    name: 'run-sas-program',
-    aliases: ['Program','run program'],
+    name: 'run-cas-program',
     description: description,
-    schema: {
+    inputSchema:z.object({
       src: z.string(),
-      scenario: z.any().default(''),
-      output: z.string().default(''),
-      folder: z.string().default(''),
-      limit: z.number().default(100)
-    },
+      scenario: z.string(),
+      output: z.string().optional,
+      folder: z.string().optional,
+      limit: z.number().optional
+    }),
+    
   // NOTE: Previously 'required' incorrectly listed 'program' which does not
   // exist in the schema. This prevented execution in some orchestrators that
   // enforce required parameter presence, causing only descriptions to appear.
   // Corrected to 'src'.
-  required: ['src'],
     handler: async (params) => {
       let {src, folder, scenario, _appContext} = params;
       // figure out src
@@ -116,3 +95,4 @@ Examples
 }
 
 export default runCasProgram;
+

package/src/toolSet/runJob.js

@@ -9,41 +9,40 @@ import _jobSubmit from '../toolHelpers/_jobSubmit.js';
 function runJob(_appContext) {
  
   let description = `
-## run-job — execute a deployed SAS Viya job
+run-job — score with a deployed SAS Viya job.
 
-LLM Invocation Guidance (When to use)
-Use THIS tool when:
-- You want to run a registered Job Execution asset by name
-- You have simple parameter inputs to pass to the job
+USE when: score with job, run job, execute job
+DO NOT USE for: arbitrary SAS code (use run-sas-program), macros (use run-macro), list/find jobs
 
-Do NOT use this tool for:
-- Running arbitrary SAS code (use run-sas-program)
-- Invoking pre-defined SAS macros (use run-macro)
-- Listing or finding jobs (use list-jobs / find-job)
+PARAMETERS
+- name: string — job name (required)
+- scenario: string | object — input parameters. Accepts: "x=1, y=2" or {x:1, y:2}
 
-Parameters
-- name (string, required): The job name to execute
-- scenario (string | object, optional): Input values to the job. Accepts:
-  - a comma-separated key=value string (e.g. "x=1, y=2")
-  - a JSON object with field names and values (recommended)
+ROUTING RULES
+- "run job xyz" → { name: "xyz" }
+- "run job xyz with param1=10, param2=val2" → { name: "xyz", scenario: {param1:10, param2:"val2"} }
 
-Response
-- Log output, listings, and tables depending on the job’s design. Table outputs will be displayed when present.
+EXAMPLES
+- "run job xyz" → { name: "xyz" }
+- "run job monthly_etl with month=10, year=2025" → { name: "monthly_etl", scenario: {month:10, year:2025} }
 
-Examples (→ mapped params)
-- "run job xyz param1=10,param2=val2" → { name: "xyz", scenario: { param1: 10, param2: "val2" } }
-- "run-job name=monthly_etl, scenario=month=10,year=2025" → { name: "monthly_etl", scenario: { month: 10, year: 2025 } }
+NEGATIVE EXAMPLES (do not route here)
+- "run SAS code" (use run-sas-program)
+- "run macro X" (use run-macro)
+- "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 = {
-    aliases: ['run job', 'run-job', 'runjob'],
     name: 'run-job',
     description: description,
-    schema: {
+    inputSchema: z.object({
       name: z.string(),
-      scenario: z.any().default(''),
-    },
-    required: ['name'],
+      scenario: z.string().optional()
+    }),
     handler: async (params) => {
       let scenario = params.scenario;
       let scenarioObj = {};
@@ -79,3 +78,4 @@ Examples (→ mapped params)
 }
 
 export default runJob;
+

package/src/toolSet/runJobdef.js

@@ -6,48 +6,44 @@
 import { z } from 'zod';
 import _jobSubmit from '../toolHelpers/_jobSubmit.js';
 
-
 function runJobdef(_appContext) {
   // JSON object for LLM/tooling
  
   let description = `
-## run-jobdef — execute a SAS Viya job definition
+run-jobdef — score with a deployed SAS Viya job definition.
+
+USE when: score with jobdef, run jobdef, execute jobdef
+DO NOT USE for: arbitrary SAS code (use run-sas-program), macros (use run-macro), list/find jobdefs
 
-LLM Invocation Guidance (When to use)
-Use THIS tool when:
-- You want to run a registered Job Definition by name
-- You can pass parameters to the job definition
+PARAMETERS
+- name: string — jobdef name (required)
+- scenario: string | object — input parameters. Accepts: "x=1, y=2" or {x:1, y:2}
 
-Do NOT use this tool for:
-- Running arbitrary SAS code (use run-program tool)
-- Invoking SAS macros (use run-macro tool)
-- Listing or finding jobdefs (use list-jobdefs tool / find-jobdef tool)
+ROUTING RULES
+- "run jobdef xyz" → { name: "xyz" }
+- "run jobdef xyz with param1=10, param2=val2" → { name: "xyz", scenario: {param1:10, param2:"val2"} }
 
-Parameters
-- name (string, required): The job definition name to execute
-- scenario (string | object, optional): Input values. Accepts:
-  - a comma-separated key=value string (e.g. "x=1, y=2")
-  - a JSON object with field names and values (recommended)
+EXAMPLES
+- "run jobdef xyz" → { name: "xyz" }
+- "run jobdef monthly_report with month=10, year=2025" → { name: "monthly_report", scenario: {month:10, year:2025} }
 
-Response
-- Log output, listings, and tables depending on the job definition's design. Table outputs will be displayed when present.
+NEGATIVE EXAMPLES (do not route here)
+- "run SAS code" (use run-sas-program)
+- "run macro X" (use run-macro)
+- "list jobdefs" (use list-jobdefs)
+- "find jobdef X" (use find-jobdef)
 
-Examples (→ mapped params)
-- "jobdef xyz param1=10,param2=val2" → { name: "xyz", scenario: { param1: 10, param2: "val2" } }
-- "run jobdef name=monthly_report, scenario=month=10,year=2025" → { name: "monthly_report", scenario: { month: 10, year: 2025 } }
-- "run-jobdef xyz param1=10,param2=val2" → { name: "xyz", scenario: { param1: 10, param2: "val2" } }
-- "jobdef name=monthly_report, scenario=month=10,year=2025" → { name: "monthly_report", scenario: { month: 10, year: 2025 } 
-`;
+ERRORS
+Returns log output, listings, tables from jobdef. Error if jobdef not found.
+  `;
  
   let spec = {
-      name: 'run-jobdef',
-      aliases: ['jobDef','jobdef','jobdef'],
+    name: 'run-jobdef',
     description: description,
-    schema: {
+    inputSchema: z.object({
       name: z.string(),
-      scenario: z.any().default(''),
-    },
-    required: ['name'],
+      scenario: z.string().optional()
+    }),
     handler: async (params) => {
       let scenario = params.scenario;
       let scenarioObj = {};
@@ -83,3 +79,4 @@ Examples (→ mapped params)
 }
 
 export default runJobdef;
+

package/src/toolSet/runMacro.js

@@ -1,82 +1,82 @@
-/*
- * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { z } from 'zod';
-import _submitCode from '../toolHelpers/_submitCode.js';
-
-
-function runMacro(_appContext) {
-  let description = `
-## run-macro
-
-Submit and execute a SAS macro on a SAS Viya server by generating and sending SAS code.
-
-Inputs
-- macro (string, required): The name of the macro to execute (provide the macro identifier without the leading "%").
-- scenario (string, optional): Parameters or SAS setup code to send before invoking the macro. Accepted formats:
-  - Comma-separated key=value pairs (e.g. "x=1, y=abc") — converted to SAS %let statements.
-  - Raw SAS macro code (e.g. "%let x=1; %let y=abc;") — passed through unchanged when it already contains SAS macro syntax.
-
-Behavior
-- If \`scenario\` contains SAS macro syntax (contains \`%let\` or other macro markers), it is sent unchanged.
-- Otherwise the tool converts comma-separated parameters into \`%let\` statements (e.g. "x=1,y=abc" → "%let x=1; %let y=abc;") and appends a macro invocation \`%<macro>;\`.
-- The resulting SAS code is submitted via the internal \`_submitCode\` helper and the submission result is returned.
-
-Output
-- Returns the response produced by \`_submitCode\`, typically including ods, log, list of tables created by the macro
-
-Usage notes
-- Ensure the target SAS environment has the macro defined
-- This helper does not perform advanced input validation or type coercion — validate parameters before calling when needed.
-
-Examples
-- run macro \`abc\` with scenario \`x=1, y=2\`
-- run macro \`summarize\` with raw SAS code \`%let x=1; %let y=2;\` (the helper will pass it through unchanged)
-`;
-
-  let spec = {
-    name: 'run-macro',
-    aliases: ['runMacro','run macro','run_macro'],
-    description: description,
-    
-     schema: {
-      macro: z.string(),
-      scenario: z.string()
-    },
-    required: ['macro'],
-    handler: async (params) => {
-      const scenarioRaw = (params.scenario || '').trim();
-      let setup = '';
-      if (scenarioRaw) {
-        // If the scenario already contains macro syntax, send it through unchanged
-        const hasMacroSyntax = /%let\b|%[a-zA-Z_]\w*\s*\(|%[a-zA-Z_]\w*\s*;/.test(scenarioRaw) || scenarioRaw.includes('%');
-        if (hasMacroSyntax) {
-          setup = scenarioRaw;
-        } else {
-          // Convert "x=1,y=abc" -> "%let x=1; %let y=abc;"
-          setup = scenarioRaw.split(',')
-            .map(p => p.trim())
-            .filter(Boolean)
-            .map(p => {
-              const [k, ...rest] = p.split('=');
-              if (!k) return '';
-              const key = k.trim();
-              const val = rest.join('=').trim();
-              return `%let ${key}=${val};`;
-            })
-            .filter(Boolean)
-            .join(' ');
-        }
-      }
-      const src = `${setup} %${params.macro};`;
-      params.src = src;
-      let r = await _submitCode(params);
-      return r;
-    }
-  }
-  return spec;
-}
-
-export default runMacro;
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { z } from 'zod';
+import _submitCode from '../toolHelpers/_submitCode.js';
+
+
+function runMacro(_appContext) {
+  let description = `
+run-macro — submit and execute a SAS macro on SAS Viya server.
+
+USE when: run macro, execute macro with parameters
+DO NOT USE for: arbitrary SAS code (use run-sas-program), jobs, jobdefs
+
+PARAMETERS
+- macro: string — macro name without "%" (required)
+- scenario: string — parameters or setup code (optional). Accepts: "x=1, y=abc" or "%let x=1; %let y=abc;"
+
+ROUTING RULES
+- "run macro abc" → { macro: "abc", scenario: "" }
+- "run macro abc with x=1, y=2" → { macro: "abc", scenario: "x=1, y=2" }
+- "run macro xyz with %let a=1; %let b=2;" → { macro: "xyz", scenario: "%let a=1; %let b=2;" }
+
+EXAMPLES
+- "run macro abc" → { macro: "abc", scenario: "" }
+- "run macro summarize with x=1, y=2" → { macro: "summarize", scenario: "x=1, y=2" }
+
+NEGATIVE EXAMPLES (do not route here)
+- "run SAS code" (use run-sas-program)
+- "run job X" (use run-job)
+- "run jobdef X" (use run-jobdef)
+
+ERRORS
+Returns log, ods, tables created by macro. Auto-converts "x=1, y=2" to "%let x=1; %let y=2;" format.
+  `;
+
+  let spec = {
+    name: 'run-macro',
+    description: description,
+    
+    inputSchema: z.object({
+      macro: z.string(),
+      scenario: z.string().optional()
+    }),
+     
+    handler: async (params) => {
+      const scenarioRaw = (params.scenario || '').trim();
+      let setup = '';
+      if (scenarioRaw) {
+        // If the scenario already contains macro syntax, send it through unchanged
+        const hasMacroSyntax = /%let\b|%[a-zA-Z_]\w*\s*\(|%[a-zA-Z_]\w*\s*;/.test(scenarioRaw) || scenarioRaw.includes('%');
+        if (hasMacroSyntax) {
+          setup = scenarioRaw;
+        } else {
+          // Convert "x=1,y=abc" -> "%let x=1; %let y=abc;"
+          setup = scenarioRaw.split(',')
+            .map(p => p.trim())
+            .filter(Boolean)
+            .map(p => {
+              const [k, ...rest] = p.split('=');
+              if (!k) return '';
+              const key = k.trim();
+              const val = rest.join('=').trim();
+              return `%let ${key}=${val};`;
+            })
+            .filter(Boolean)
+            .join(' ');
+        }
+      }
+      const src = `${setup} %${params.macro};`;
+      params.src = src;
+      let r = await _submitCode(params);
+      return r;
+    }
+  }
+  return spec;
+}
+
+export default runMacro;
+

package/src/toolSet/runProgram.js

@@ -8,101 +8,48 @@ import _submitCode from '../toolHelpers/_submitCode.js';
 
 function runProgram(_appContext) {
   let description = `
-## run-sas-program — execute SAS code or programs on SAS Viya server
+run-sas-program — execute SAS code or programs on SAS Viya server.
 
-LLM Invocation Guidance (When to use)
-Use THIS tool when the user wants to run a SAS program on the server:
-- "run program 'data a; x=1; run;'"
-- "execute this SAS code: proc print data=sashelp.cars; run;"
-- "program 'data work.a; x=1; run;' output=a limit=50"
-- "run sas program sample folder=/Public/models output=A limit=50"
-- "run sas program with parameters name=John, age=45"
-- "execute SAS file myprogram.sas from /Public folder"
+USE when: run program, execute SAS code, run .sas file
+DO NOT USE for: macros (use run-macro), jobs (use run-job), jobdefs (use run-jobdef), SQL queries (use sas-query), read data (use read-table)
 
-Do NOT use this tool when the user wants:
-- run macro -> use run-macro
-- run job -> use run-job
-- run jobdef -> use run-jobdef
-- list jobs -> use list-jobs
-- list jobdefs -> use list-jobdefs
-- find job -> use find-job
-- find jobdef -> use find-jobdef
-- find model -> use find-model
-- Query tables with SQL -> use sas-query
-- Read table data -> use read-table
+PARAMETERS
+- src: string — SAS code or .sas filename (required)
+- folder: string (default: '') — server folder path for .sas files
+- scenario: string | object — parameter values. Accepts: "x=1, y=2" or {x:1, y:2}
+- output: string (default: '') — table name to return (case-sensitive)
+- limit: number (default: 100) — max rows from output
 
-Purpose
-Execute SAS code or programs on a SAS Viya server. Can run inline SAS code or execute .sas files stored on the server. Supports parameter passing via scenario values and can return output tables.
-
-Parameters
-- src (string, required): The SAS program to execute. Can be either:
-  - Inline SAS code as a string (e.g., "data a; x=1; run;")
-  - Name of a .sas file stored on the server (used with folder parameter)
-- folder (string, default ''): Server folder path where the .sas file is located (e.g., "/Public/models")
-- scenario (string | object, optional): Input parameter values. Accepts:
-  - Comma-separated key=value string (e.g., "x=1, y=2")
-  - JSON object with field names and values (recommended)
-- output (string, default ''): Table name to return in response (case-sensitive)
-- limit (number, default 100): Maximum number of rows to return from output table
-
-Response Contract
-Returns a JSON object containing:
-- log: Execution log from SAS
-- ods: ODS output if generated
-- tables: Array of table names created during execution
-- data: If output parameter specified, returns the table data (up to limit rows)
-- error: Error message if execution fails
-- Empty content if no results produced
-
-Disambiguation & Clarification
-- Missing SAS code: ask "What SAS program or code would you like to execute?"
-- Inline code vs file unclear: ask "Do you want to run inline SAS code or execute a .sas file from the server?"
-- If output table not returned: clarify "The output table name is case-sensitive. Did you specify the exact name?"
-- If unclear about parameters: ask "What parameter values should I pass to the program?"
-
-Examples (→ mapped params)
+ROUTING RULES
 - "run program 'data a; x=1; run;'" → { src: "data a; x=1; run;", folder: "", output: "", limit: 100 }
-- "program 'data work.a; x=1; run;' output=a limit=50" → { src: "data work.a; x=1; run;", folder: "", output: "a", limit: 50 }
-- "run sas program sample folder=/Public/models output=A limit=50" → { src: "sample", folder: "/Public/models", output: "A", limit: 50 }
-- "run program mycode.sas in /Public with name=John, age=45" → { src: "mycode", folder: "/Public", scenario: { name: "John", age: 45 }, output: "", limit: 100 }
+- "run sas program sample folder=/Public/models" → { src: "sample", folder: "/Public/models", output: "", limit: 100 }
+- "run program with name=John, age=45" → { src: "<code>", scenario: {name:"John", age:45}, output: "", limit: 100 }
 
-Negative Examples (should NOT call run-sas-program)
-- "run macro summarize" (use run-macro instead)
-- "run job monthly_report" (use run-job instead)
-- "run jobdef etl_process" (use run-jobdef instead)
-- "how many customers by region in Public.customers" (use sas-query instead)
-- "read 10 rows from cars" (use read-table instead)
+EXAMPLES
+- "run program 'data a; x=1; run;'" → { src: "data a; x=1; run;", folder: "", output: "", limit: 100 }
+- "run sas file sample in /Public" → { src: "sample", folder: "/Public", output: "", limit: 100 }
 
-Behavior & Usage Notes
-- Sends the supplied src verbatim to the SAS execution helper
-- For .sas files, specify the file name (with or without .sas extension) and the folder path
-- For invoking pre-defined SAS macros, prefer run-macro which handles %let statements automatically
-- Scenario values are converted to macro variables when provided
-- Be cautious when executing arbitrary code in production environments
+NEGATIVE EXAMPLES (do not route here)
+- "run macro X" (use run-macro)
+- "run job X" (use run-job)
+- "run jobdef X" (use run-jobdef)
+- "SQL query" (use sas-query)
+- "read table" (use read-table)
 
-Related Tools
-- run-macro — for executing predefined SAS macros with parameters
-- run-job — for executing registered Job Execution assets
-- sas-query — for natural language SQL queries
-- read-table — for simple data retrieval
-`;
+ERRORS
+Returns log, ods, tables array, data (if output specified). Error if execution fails.
+  `;
 
   let spec = {
-    name: 'run-sas-program',
-    aliases: ['Program','run program'],
+    name: 'run-program',
     description: description,
-    schema: {
+    inputSchema: z.object({
       src: z.string(),
-      scenario: z.any().default(''),
-      output: z.string().default(''),
-      folder: z.string().default(''),
-      limit: z.number().default(100)
-    },
-  // NOTE: Previously 'required' incorrectly listed 'program' which does not
-  // exist in the schema. This prevented execution in some orchestrators that
-  // enforce required parameter presence, causing only descriptions to appear.
-  // Corrected to 'src'.
-  required: ['src'],
+      scenario: z.string().optional(),
+      output: z.string().optional(),
+      folder: z.string().optional(),
+      limit: z.number().optional()
+    }),
     handler: async (params) => {
       let {src, folder, scenario, _appContext} = params;
       // figure out src
@@ -143,3 +90,4 @@ Related Tools
 }
 
 export default runProgram;
+