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

package/src/toolSet/{runProgram.js → programScore.js}

@@ -1,93 +1,96 @@
-/*
- * 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 runProgram(_appContext) {
-  let description = `
-run-sas-program — execute SAS code or programs on SAS Viya server.
-
-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)
-
-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
-
-ROUTING RULES
-- "run program 'data a; x=1; run;'" → { src: "data a; x=1; run;", folder: "", 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 }
-
-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 }
-
-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)
-
-ERRORS
-Returns log, ods, tables array, data (if output specified). Error if execution fails.
-  `;
-
-  let spec = {
-    name: 'run-program',
-    description: description,
-    inputSchema: z.object({
-      src: z.string(),
-      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
-      let isrc = src;
-      if (folder != null && folder.trim().length > 0) {
-        if (isrc.indexOf('.sas') < 0) {
-          isrc = isrc + '.sas';
-        }
-        isrc = `
-          filename mcptemp filesrvc folderpath="${folder}";
-          %include mcptemp("${isrc}");
-          filename mcptemp clear;
-        `;
-      }
-      // figure out macros
-  
-      if (typeof scenario === 'string' && scenario.includes('=')) {
-        scenario = scenario.split(',').reduce((acc, pair) => {
-          const [k, ...rest] = pair.split('=');
-          if (!k) return acc;
-          acc[k.trim()] = rest.join('=').trim();
-          return acc;
-        }, {});
-      }
-      let iparms = {
-        args: scenario,
-        output: params.output,
-        limit: params.limit,
-        src: isrc,
-        _appContext: _appContext
-      }
-     // console.error('iparms', iparms);
-      let r = await _submitCode(iparms);
-      return r;
-    }
-  }
-  return spec;
-}
-
-export default runProgram;
-
+/*
+ * 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 programScore(_appContext) {
+  const isAgent = _appContext && _appContext.agent;
+  let description = isAgent ? `
+program-score — execute a SAS program model.
+PARAMS: src (string, required), folder (string, optional), scenario (string|object, optional), output (string, optional), limit (number, optional)
+RETURNS: log, ODS output, optional output table rows
+` : `
+program-score — execute a SAS program model on SAS Viya server.
+
+USE when: score program, execute SAS code, run .sas file
+DO NOT USE for: macros (use macro-score), jobs (use job-score), jobdefs (use jobdef-score), SQL queries (use sas-query), read 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
+
+ROUTING RULES
+- "score program 'data a; x=1; run;'" → { src: "data a; x=1; run;", folder: "", output: "", limit: 100 }
+- "score sas program sample folder=/Public/models" → { src: "sample", folder: "/Public/models", output: "", limit: 100 }
+- "score program with name=John, age=45" → { src: "<code>", scenario: {name:"John", age:45}, output: "", limit: 100 }
+
+EXAMPLES
+- "score program 'data a; x=1; run;'" → { src: "data a; x=1; run;", folder: "", output: "", limit: 100 }
+- "score sas file sample in /Public" → { src: "sample", folder: "/Public", output: "", limit: 100 }
+
+NEGATIVE EXAMPLES (do not route here)
+- "score macro X" (use macro-score)
+- "score job X" (use job-score)
+- "score jobdef X" (use jobdef-score)
+- "SQL query" (use sas-query)
+- "read table" (use read-table)
+
+ERRORS
+Returns log, ods, tables array, data (if output specified). Error if execution fails.
+  `;
+
+  let spec = {
+    name: 'program-score',
+    description: description,
+    inputSchema: z.object({
+      src: z.string(),
+      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
+      let isrc = src;
+      if (folder != null && folder.trim().length > 0) {
+        if (isrc.indexOf('.sas') < 0) {
+          isrc = isrc + '.sas';
+        }
+        isrc = `
+          filename mcptemp filesrvc folderpath="${folder}";
+          %include mcptemp("${isrc}");
+          filename mcptemp clear;
+        `;
+      }
+      // figure out macros
+
+      if (typeof scenario === 'string' && scenario.includes('=')) {
+        scenario = scenario.split(',').reduce((acc, pair) => {
+          const [k, ...rest] = pair.split('=');
+          if (!k) return acc;
+          acc[k.trim()] = rest.join('=').trim();
+          return acc;
+        }, {});
+      }
+      let iparms = {
+        args: scenario,
+        output: params.output,
+        limit: params.limit,
+        src: isrc,
+        _appContext: _appContext
+      }
+      let r = await _submitCode(iparms);
+      return r;
+    }
+  }
+  return spec;
+}
+
+export default programScore;

package/src/toolSet/readTable.js

@@ -1,5 +1,5 @@
-/*
- * 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';
@@ -7,36 +7,52 @@ import debug from 'debug';
 
 import _readTable from  '../toolHelpers/_readTable.js';
 function readTable(_appContext) {
-   
-     let describe = `
-read-table — retrieve rows from a table in a CAS or SAS library.
+  const isAgent = _appContext && _appContext.agent;
+
+     let describe = isAgent ? `
+read-table — read rows from a CAS or SAS table.
+PARAMS: lib (string, required), table (string, required), server ('cas'|'sas', required), where (string, optional filter), start (number, default 1), limit (number, default 10)
+RETURNS: array of row objects
+` : `
+read-table -  retrieve rows from a table in a CAS or SAS library.
 
 USE when: read table, show rows, read from library, filtered data with WHERE
-DO NOT USE for: list tables, table structure (use table-info), SQL queries (use sas-query), SAS programs
+DO NOT USE for: list tables, table structure (use table-describe), SQL queries (use sas-query), SAS programs
 
 PARAMETERS
-- table: string — table name (required)
-- lib: string — caslib or libref (required)
-- server: string (default: 'cas') — 'cas' or 'sas'
-- start: number (default: 1) — 1-based row index
-- limit: number (default: 10) — max rows (1-1000)
-- where: string — SQL WHERE clause filter
-- format: boolean (default: true) — formatted or raw values
+- table: string — table name (required)
+- lib: string — caslib or libref (required)
+- server: string (default: 'cas') — 'cas' or 'sas'
+- start: number (default: 1) — 1-based row index
+- limit: number (default: 10) — max rows (1-1000)
+- where: string — SQL WHERE clause filter
+- format: boolean (default: true) — formatted or raw values
+
+PARSING ROWS FROM USER INPUT
+"first N rows/records"        → start: 1, limit: N   ("first" = count from beginning, never an offset)
+"top N rows"                  → start: 1, limit: N
+"N rows" / "N records"        → start: 1, limit: N
+"read N rows from lib.table"  → lib: "lib", table: "table", start: 1, limit: N
+"rows N to M"                 → start: N, limit: M-N+1
+"starting from row N"         → start: N, limit: 10 (default)
+(no count specified)          → start: 1, limit: 10 (default)
+
+DOTTED FORMAT: "lib.table" → lib: "lib", table: "table" (split on first dot)
 
 ROUTING RULES
-- "read table cars in Samples" → { table: "cars", lib: "Samples", start: 1, limit: 10 }
-- "show 25 rows from customers" → { table: "customers", lib: "<lib>", limit: 25, start: 1 }
-- "read from mylib.orders where status='shipped'" → { table: "orders", lib: "mylib", where: "status='shipped'", start: 1, limit: 10 }
+- "read table cars in Samples" → { table: "cars", lib: "Samples", start: 1, limit: 10 }
+- "show 25 rows from customers" → { table: "customers", lib: "<lib>", limit: 25, start: 1 }
+- "read from mylib.orders where status='shipped'" → { table: "orders", lib: "mylib", where: "status='shipped'", start: 1, limit: 10 }
 
 EXAMPLES
-- "read table cars in Samples" → { table: "cars", lib: "Samples", start: 1, limit: 10 }
-- "show 25 rows from customers" → { table: "customers", lib: "mylib", limit: 25, start: 1 }
+- "read table cars in Samples" → { table: "cars", lib: "Samples", start: 1, limit: 10 }
+- "show 25 rows from customers" → { table: "customers", lib: "mylib", limit: 25, start: 1 }
 
 NEGATIVE EXAMPLES (do not route here)
 - "list tables in Samples" (use list-tables)
-- "what columns are in cars" (use table-info)
+- "what columns are in cars" (use table-describe)
 - "execute SQL query" (use sas-query)
-- "run SAS code" (use run-sas-program)
+- "run SAS code" (use program-score)
 
 ERRORS
 Returns rows array, total count, filtered_count, columns metadata. Empty array if no matches.
@@ -46,12 +62,12 @@ Returns rows array, total count, filtered_count, columns metadata. Empty array i
       name: 'read-table',
       description: describe,
       inputSchema: z.object({
-        table: z.string(),
-        lib: z.string().optional(),
-        start: z.number().optional(),
-        limit: z.number().optional(),
-        server: z.string().optional(),
-        where: z.string().optional()
+        table: z.string().min(1),
+        lib: z.string().min(1).optional(),
+        start: z.number().int().min(1).optional(),
+        limit: z.number().int().min(1).max(1000).optional(),
+        server: z.enum(['cas', 'sas']).optional(),
+        where: z.string().min(1).optional()
       }),
     handler: async (params) => {
         let r = await _readTable(params,'query');
@@ -61,3 +77,4 @@ Returns rows array, total count, filtered_count, columns metadata. Empty array i
     return specs;
 }
 export default readTable;
+

package/src/toolSet/sasQuery.js

@@ -1,38 +1,43 @@
-/*
- * 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 _jobSubmit from '../toolHelpers/_jobSubmit.js';
 
-function sasQuery() {
- 
-    let description = `
-sas-query — convert natural language questions into SQL queries and execute them.
+function sasQuery(_appContext) {
+  const isAgent = _appContext && _appContext.agent;
+
+    let description = isAgent ? `
+sas-query — run a SQL aggregation query against a table.
+PARAMS: table (string as lib.table, required), query (string, SQL WHERE/aggregation clause, required)
+RETURNS: aggregated query result rows
+` : `
+sas-query -  convert natural language questions into SQL queries and execute them.
 
 USE when: how many/count/total/average by, aggregated analytics, complex filtering, statistical summaries
-DO NOT USE for: raw reads without filtering (use read-table), table structure (use table-info), SAS programs (use run-sas-program), jobs/jobdefs
+DO NOT USE for: raw reads without filtering (use read-table), table structure (use table-describe), SAS programs (use program-score), jobs/jobdefs
 
 PARAMETERS
-- table: string — table in lib.table format (required), e.g. "Public.cars" or "sashelp.class"
-- query: string — natural language question (required)
-- sql: string — pre-generated SQL SELECT (optional, LLM generates)
-- job: string (default: 'program') — job name to execute
+- table: string — table in lib.table format (required), e.g. "Public.cars" or "sashelp.class"
+- query: string — natural language question (required)
+- sql: string — pre-generated SQL SELECT (optional, LLM generates)
+- job: string (default: 'program') — job name to execute
 
 ROUTING RULES
-- "how many cars by make in sashelp.cars" → { table: "sashelp.cars", query: "how many cars by make", sql: "SELECT make, COUNT(*) FROM sashelp.cars GROUP BY make" }
-- "average salary by department in Public.employees" → { table: "Public.employees", query: "average salary by department", sql: "SELECT department, AVG(salary) FROM Public.employees GROUP BY department" }
+- "how many cars by make in sashelp.cars" → { table: "sashelp.cars", query: "how many cars by make", sql: "SELECT make, COUNT(*) FROM sashelp.cars GROUP BY make" }
+- "average salary by department in Public.employees" → { table: "Public.employees", query: "average salary by department", sql: "SELECT department, AVG(salary) FROM Public.employees GROUP BY department" }
 
 EXAMPLES
-- "how many cars by make in sashelp.cars" → { table: "sashelp.cars", query: "how many cars by make", sql: "SELECT make, COUNT(*) FROM sashelp.cars GROUP BY make" }
-- "total sales by region from mylib.sales" → { table: "mylib.sales", query: "total sales by region", sql: "SELECT region, SUM(amount) FROM mylib.sales GROUP BY region" }
+- "how many cars by make in sashelp.cars" → { table: "sashelp.cars", query: "how many cars by make", sql: "SELECT make, COUNT(*) FROM sashelp.cars GROUP BY make" }
+- "total sales by region from mylib.sales" → { table: "mylib.sales", query: "total sales by region", sql: "SELECT region, SUM(amount) FROM mylib.sales GROUP BY region" }
 
 NEGATIVE EXAMPLES (do not route here)
 - "read table cars" (use read-table)
 - "show 10 rows" (use read-table)
-- "table structure" (use table-info)
-- "run SAS code" (use run-sas-program)
-- "run job/macro" (use run-job/run-macro)
+- "table structure" (use table-describe)
+- "run SAS code" (use program-score)
+- "score job/macro" (use job-score/macro-score)
 
 ERRORS
 Returns rows array, columns metadata, log. Returns error if SQL invalid or table not found.
@@ -75,3 +80,4 @@ Returns rows array, columns metadata, log. Returns error if SQL invalid or table
 }
 export default sasQuery;
 
+

package/src/toolSet/scrDescribe.js

@@ -0,0 +1,55 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { z } from 'zod';
+import _scrDescribe from '../toolHelpers/_scrDescribe.js';
+
+function scrDescribe(_appContext) {
+  const isAgent = _appContext && _appContext.agent;
+  let description = isAgent ? `
+scr-describe — return input/output schema for a SCR model.
+PARAMS: intent ('describe', required), name (string, required)
+RETURNS: input/output schema and model metadata
+` : `
+scr-describe -  return the input/output schema and metadata for an SCR (Score Code Runtime) model.
+
+Inputs
+- intent: must be 'describe' — only pass if user explicitly asked to describe/inspect an SCR model. Do NOT use for find or verify existence.
+- name (string): The SCR model identifier.
+What it returns
+- A JSON object describing the model's interface, typically including:
+  - Input variables (names, types, required/optional)
+  - Output variables (predictions, probabilities, scores)
+
+
+Usage notes
+- Ensure network connectivity and credentials for the remote SCR service when needed.
+- Use scr-score to score data after inspecting the schema.
+
+Examples
+- describe scr model "loan"
+- info for scr model "loan"
+`;
+
+  let spec = {
+    name: 'scr-describe',
+    description: description,
+    inputSchema: z.object({
+      intent: z.literal('describe'),
+      name: z.string()
+    }),
+    handler: async (params) => {
+      const { intent, name, _appContext } = params;
+      if (name === null) {
+        return { status: { statusCode: 2, msg: `SCR model ${name} not found` }, results: {} };
+      }
+      let r = await _scrDescribe({name, _appContext});
+      return r;
+    }
+  }
+  return spec;
+}
+
+export default scrDescribe;

package/src/toolSet/scrScore.js

@@ -1,70 +1,63 @@
-/*
- * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { z } from 'zod';
-import _scrScore from '../toolHelpers/_scrScore.js';
-
-function scrScore(_appContext) {
-  let description = `
-## scr-score
-
-Purpose
-Score a scenario using a model deployed as a SCR container  in Azure or another host).
-
-Inputs
-- url (string, required): SCR model identifier (URL)
-- scenario (string | object | array, optional): Input values to score. 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),
-  - an array of objects for batch scoring. If omitted, the tool will return the model's input variable definitions.
-
-What it returns
-- When scoring: the SCR endpoint response (predictions, probabilities, scores) merged with or alongside the supplied inputs.
-- When \`scenario\` is omitted: metadata describing the model's input variables (names, types, required/optional).
-
-Usage notes
-- Run \`scr-info\` first to inspect the expected input variables and types.
-- Prefer structured objects for numeric/date values to avoid type ambiguity; the simple string parser keeps values as strings.
-- Ensure network connectivity and any required credentials for the target SCR service.
-
-Examples
-- scrScore with url="loan" and scenario="age=45, income=60000"
-- scrScore with url="https://scr-host/models/loan" and scenario={age:45, income:60000}
-`;
-
-  let spec = {
-    name: 'scr-score',
-    description: description,
-    inputSchema: z.object({
-      url: z.string(),
-      scenario: z.string().optional()
-    }),
-    
-    handler: async (params) => {
-      let {url, scenario,_appContext} = params;
-  
-      if (url === null) {
-        return { status: { statusCode: 2, msg: `SCR model ${url} was not specified` }, results: {} };
-      }
-
-      // Normalize simple string scenarios like "x=1, y=2" into an object
-      if (typeof scenario === 'string' && scenario.includes('=')) {
-        scenario = scenario.split(',').reduce((acc, pair) => {
-          const [k, ...rest] = pair.split('=');
-          if (!k) return acc;
-          acc[k.trim()] = rest.join('=').trim();
-          return acc;
-        }, {});
-      }
-
-      let r = await _scrScore({ url: url, scenario: scenario , _appContext: _appContext});
-      return r;
-    }
-  }
-
-  return spec;
-}
-
-export default scrScore;
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { z } from 'zod';
+import _scrScore from '../toolHelpers/_scrScore.js';
+
+function scrScore(_appContext) {
+  const isAgent = _appContext && _appContext.agent;
+  let description = isAgent ? `
+scr-score — score a scenario using a SCR model endpoint.
+PARAMS: name (string, required), scenario (object, optional)
+RETURNS: SCR endpoint response with predictions merged with inputs
+` : `
+scr-score -  score a scenario using a model deployed as a SCR container in Azure or another host.
+
+Inputs
+- name (string, required): SCR model identifier (URL)
+- scenario (object, optional): Input values to score as a JSON object (e.g. {age:45, income:60000}). If omitted, defaults to {} and the tool will return the model's input variable definitions.
+
+What it returns
+- When scoring: the SCR endpoint response (predictions, probabilities, scores) merged with or alongside the supplied inputs.
+- When \`scenario\` is omitted: metadata describing the model's input variables (names, types, required/optional).
+
+Usage notes
+- Run \`scr-describe\` first to inspect the expected input variables and types.
+- Prefer structured objects for numeric/date values to avoid type ambiguity; the simple string parser keeps values as strings.
+- Ensure network connectivity and any required credentials for the target SCR service.
+
+Examples
+- scrScore with name="loan" and scenario={age:45, income:60000}
+`;
+
+  let spec = {
+    name: 'scr-score',
+    description: description,
+    inputSchema: z.object({
+      name: z.string(),
+      scenario: z.union([z.record(z.any()), z.string()]).optional()
+    }),
+    
+    handler: async (params) => {
+      let {name, _appContext} = params;
+      let scenario = params.scenario;
+      if (typeof scenario === 'string') {
+        try { scenario = JSON.parse(scenario); } catch { scenario = {}; }
+      }
+      if (name === null) {
+        return { status: { statusCode: 2, msg: `SCR model ${name} was not specified` }, results: {} };
+      }
+
+      const scenarioObj = (scenario != null && typeof scenario === 'object') ? scenario : {};
+
+      let r = await _scrScore({ name: name, scenario: scenarioObj, _appContext: _appContext});
+      return r;
+    }
+  }
+
+  return spec;
+}
+
+export default scrScore;

package/src/toolSet/searchAssets.js

@@ -11,7 +11,7 @@ function searchAssets(_appContext) {
   const log = debug('tools');
 
   let description = `
-## searchAssets: Search the SAS Catalog for assets using a flexible search string.
+search-assets -  Search the SAS Catalog for assets using a flexible search string.
 
 - Supports searching for various asset types (e.g., datasets, dataflows, models).
  - the default asset type is 'datasets'.

package/src/toolSet/setContext.js

@@ -6,11 +6,16 @@
 import {z} from 'zod';
 
 function setContext(_appContext) {
-    let description = `
+  const isAgent = _appContext && _appContext.agent;
+    let description = isAgent ? `
+set-context — set runtime context variables (CAS server, SAS server, etc.).
+PARAMS: cas (string, optional), sas (string, optional), other key=value context fields
+RETURNS: updated context confirmation
+` : `
 set-context — set the CAS and SAS server contexts for subsequent tool calls.
 
 USE when: switch to CAS server, change compute context, check current context, set both
-DO NOT USE for: get variables (use get-env), read data (use read-table), run programs (use run-sas-program)
+DO NOT USE for: get variables (use get-env), read data (use read-table), score programs (use program-score)
 
 PARAMETERS
 - cas: string — CAS server name (optional), e.g. 'cas-shared-default', 'finance-cas-server'
@@ -30,7 +35,7 @@ EXAMPLES
 NEGATIVE EXAMPLES (do not route here)
 - "read table cars" (use read-table)
 - "what's the value of X" (use get-env)
-- "run program" (use run-sas-program)
+- "score program" (use program-score)
 
 ERRORS
 Returns current or updated context values {cas, sas}. Error if server not found or invalid name.