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

package/src/toolSet/listTables.js

@@ -1,95 +1,66 @@
-/*
- * 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;
+/*
+ * 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 library.
+
+USE when: list tables in <lib>, show tables in <lib>, next page
+DO NOT USE for: find table, list libraries, get table structure (use table-info), read data (use read-table)
+
+PARAMETERS
+- lib: string — library to inspect (required)
+- server: string (default: 'cas') — 'cas' or 'sas'
+- limit: number (default: 10) — page size
+- start: number (default: 1) — 1-based offset
+- where: string — optional filter expression
+
+ROUTING RULES
+- "list tables in Samples" → { lib: "Samples", start: 1, limit: 10 }
+- "list 25 tables in sashelp" → { lib: "sashelp", limit: 25, start: 1 }
+- "list cas tables in Public" → { lib: "Public", server: "cas", start: 1, limit: 10 }
+
+EXAMPLES
+- "list tables in Samples" → { lib: "Samples", start: 1, limit: 10 }
+- "show 25 tables in sashelp" → { lib: "sashelp", limit: 25, start: 1 }
+
+NEGATIVE EXAMPLES (do not route here)
+- "list libs" (use list-libraries)
+- "find lib Public" (use find-library)
+- "describe table cars" (use table-info)
+- "read table cars" (use read-table)
+
+ERRORS
+Returns empty array if no tables found.
+  `;
+    
+  let spec = {
+    name: 'list-tables',
+    description: description,
+
+    inputSchema: z.object({
+      lib: z.string(),
+      server: z.string().optional(),
+      limit: z.number().optional(),
+      start: z.number().optional(),
+      where: z.string().optional()
+    }),
+    handler: async (params) => { 
+      let r = await _listTables(params);
+      return r;
+    }
+  }
+  return spec;
+}
+
+export default listTables;
+

package/src/toolSet/makeTools.js

@@ -31,6 +31,7 @@ import findJobdef from './findJobdef.js';
 import sasQuery from './sasQuery.js';
 import setContext from './setContext.js';
 
+
 function makeTools(_appContext) {
   // wrap all tools with 
   let customTools = [];

package/src/toolSet/modelInfo.js

@@ -10,72 +10,39 @@ const log = debug('tools');
 
 function modelInfo(_appContext) {
   let description = `
-## model-info — retrieve detailed metadata for a deployed model
+model-info — retrieve detailed metadata for a deployed model.
 
-LLM Invocation Guidance (When to use)
-Use THIS tool when:
-- User wants input/output variable information: "What inputs does model X need?"
-- User wants to understand model variables: "Describe model myModel"
-- User wants data types and roles: "Show me the variables for myModel"
-- User wants to prepare data for scoring: "What are the required inputs for model sales_forecast?"
+USE when: what inputs does model need, describe model, show variables for model, model inputs/outputs
+DO NOT USE for: find model, list models, score model, table/job operations
 
-Do NOT use this tool for:
-- Checking if a model exists (use find-model)
-- Listing available models (use list-models)
-- Scoring a model (use model-score)
-- Looking up tables or jobs (use respective find/list tools)
+PARAMETERS
+- model: string — model name (required, exact match)
 
-Purpose
-Retrieve detailed metadata for a model deployed to MAS (Model Aggregation Service). This includes input variable names, data types, roles/usage, ranges, and output variable information. Use this before scoring to understand what data the model requires.
+ROUTING RULES
+- "what inputs does model X need?" → { model: "X" }
+- "describe model Y" → { model: "Y" }
+- "show variables for Z" → { model: "Z" }
 
-Parameters
-- model (string, required): The name of the model as published to MAS. Must be exact match.
-
-Response Contract
-Returns a JSON object containing model metadata, typically including:
-- name: The model name
-- inputs: Array of input variable objects with:
-  - name: Variable name
-  - type: Data type (numeric, character, etc.)
-  - role: Role in model (input, key, etc.)
-  - allowed_values or range: Optional constraints
-- outputs: Array of output/prediction objects with:
-  - name: Prediction/output variable name
-  - type: Data type
-  - possible_values: For classification models, the class labels
-- model_type: Type of model (regression, classification, etc.)
-- description: Optional model description
-
-Disambiguation & Clarification
-- If model name is missing: ask "Which model would you like to see information for?"
-- If user says "variables" without specifying model: ask "Which model would you like the variables for?"
-- Multiple model requests: handle one at a time
-
-Examples (→ mapped params)
+EXAMPLES
 - "What inputs does model churnRisk need?" → { model: "churnRisk" }
 - "Describe model creditScore" → { model: "creditScore" }
-- "Show the variables for myModel" → { model: "myModel" }
-- "What are the outputs of model sales_forecast?" → { model: "sales_forecast" }
+- "Show variables for myModel" → { model: "myModel" }
 
-Negative Examples (should NOT call model-info)
-- "List all available models" (use list-models instead)
-- "Find model cancer" (use find-model instead)
-- "Score this customer with model churnRisk" (use model-score instead)
+NEGATIVE EXAMPLES (do not route here)
+- "list models" (use list-models)
+- "find model X" (use find-model)
+- "score with model X" (use model-score)
 
-Related Tools
-- list-models → find-model → model-info → model-score (typical workflow)
-- find-model — to check if a specific model exists
-- model-score — to score data using the model
-`;
+ERRORS
+Returns model metadata: inputs (name, type, role), outputs (name, type, possible_values), model_type, description.
+  `;
 
   let spec = {
     name: 'model-info',
-    aliases: ['modelInfo','model info','model_info'],
     description: description,
-    schema: {
-      'model': z.string()
-    },
-    required: ['model'],
+    inputSchema: z.object({
+      model: z.string()
+    }),
     handler: async (params) => {
       let r = await _masDescribe(params);
       return r;
@@ -85,3 +52,4 @@ Related Tools
 }
 
 export default modelInfo;
+

package/src/toolSet/modelScore.js

@@ -10,93 +10,44 @@ const log = debug('tools');
 
 function modelScore(_appContext) {
   let description = `
-## model-score — score data using a deployed model on MAS
+mas-score — score data using a deployed model on MAS.
 
-LLM Invocation Guidance (When to use)
-Use THIS tool when:
-- User wants to score data with a model: "score this customer with model churnRisk"
-- User provides input values for prediction: "predict using model creditScore with age=45, income=60000"
-- User wants batch scoring: "score these 10 customers with fraud model"
-- User asks for model predictions: "what does the sales forecast model predict for Q4?"
-- User wants to get predictions: "use the risk model to score this applicant"
-- User provides scenario data for a model: "run model cancer1 with age=45, sex=M"
+USE when: score with model, predict using model, batch scoring, model predictions
+DO NOT USE for: find model, model metadata, list models, run programs/jobs, query tables
 
-Do NOT use this tool for:
-- Checking if a model exists (use find-model)
-- Getting model metadata/variables (use model-info)
-- Listing available models (use list-models)
-- Running SAS programs (use run-sas-program)
-- Running jobs (use run-job)
-- Querying tables (use sas-query or read-table)
+PARAMETERS
+- model: string — model name (required, exact match)
+- scenario: string | object | array — input data (required). Accepts: "x=1, y=2", {x:1, y:2}, or array of objects
+- uflag: boolean (default: false) — prefix model fields with underscore when true
 
-Purpose
-Score user-supplied scenario data using a model published to MAS (Model Aggregation Service) on SAS Viya. Returns predictions, probabilities, scores, and other model outputs merged with the input data.
+ROUTING RULES
+- "score with model X using a=1, b=2" → { model: "X", scenario: {a:1, b:2}, uflag: false }
+- "predict using model Y with age=45, income=60000" → { model: "Y", scenario: {age:45, income:60000}, uflag: false }
 
-Parameters
-- model (string, required): The name of the model as published to MAS. Must be exact match.
-- scenario (string | object | array, required): Data to score. Accepts:
-  - A comma-separated key=value string (e.g., "x=1, y=2")
-  - A plain object with field names and values (e.g., {x: 1, y: 2})
-  - An array of objects for batch scoring
-- uflag (boolean, default false): When true, returned model field names will be prefixed with an underscore.
+EXAMPLES
+- "score with model churn using age=45, income=60000" → { model: "churn", scenario: {age:45, income:60000}, uflag: false }
+- "predict creditScore for credit=700, debt=20000" → { model: "creditScore", scenario: {credit:700, debt:20000}, uflag: false }
 
-Parsing & Behavior
-- If scenario is a string, the tool parses comma-separated key=value pairs into an object
-- If scenario is an array, supports batch scoring (processes multiple records)
-- Numeric values in strings remain as strings; validate and cast as needed before scoring
+NEGATIVE EXAMPLES (do not route here)
+- "find model X" (use find-model)
+- "what inputs does model need" (use model-info)
+- "list models" (use list-models)
+- "run job X" (use run-job)
 
-Response Contract
-Returns a JSON object containing:
-- Input fields merged with scoring results
-- Prediction/score field(s) from the model (field names depend on model)
-- Probability fields for classification models (e.g., P_class1, P_class2)
-- Model metadata: model name, version if available
-- _variables_: Variable metadata if uflag=true
-- Error object if scoring fails with error message
-
-Disambiguation & Clarification
-- Missing model name: ask "Which model would you like to use for scoring?"
-- Missing scenario data: ask "What input values should I use for scoring?"
-- If model unknown: suggest "Use find-model to verify the model exists or list-models to see available models"
-- If unsure of inputs: suggest "Use model-info to see the required input variables first"
-
-Examples (→ mapped params)
-- "score with model churn using age=45, income=60000" → { model: "churn", scenario: { age: "45", income: "60000" }, uflag: false }
-- "predict creditScore for applicant: credit=700, debt=20000" → { model: "creditScore", scenario: { credit: "700", debt: "20000" }, uflag: false }
-- "use fraud model to score transaction amount=500, merchant=online" → { model: "fraud", scenario: { amount: "500", merchant: "online" }, uflag: false }
-- "run model cancer1 with age=45, sex=M, tumor=stage2" → { model: "cancer1", scenario: { age: "45", sex: "M", tumor: "stage2" }, uflag: false }
-
-Negative Examples (should NOT call model-score)
-- "find model churnRisk" (use find-model instead)
-- "what inputs does model need?" (use model-info instead)
-- "list all models" (use list-models instead)
-- "run job scoring_job" (use run-job instead)
-- "read table scores from Public" (use read-table instead)
-
-Usage Tips
-- Use model-info first to understand required input variables and data types
-- Verify model exists with find-model before attempting to score
-- For batch scoring, provide an array of objects as the scenario parameter
-- Ensure MAS connectivity and credentials are available
-
-Related Tools
-- list-models → find-model → model-info → model-score (typical workflow)
-- find-model — to verify model exists before scoring
-- model-info — to understand required inputs and expected outputs
-- list-models — to discover available models
-`;
+ERRORS
+Returns predictions, probabilities, scores merged with input data. Returns error if model not found or scoring fails.
+  `;
 
  
   let spec = {
-    name: 'model-score',
-    aliases: ['modelScore','model score','model_score'],
+    name: 'mas-score',
     description: description,
-    schema: {
-      'model': z.string(),
-      'scenario': z.any(),
-      'uflag': z.boolean()
-    },
-    required: ['model', 'scenario'],
+    inputSchema:z.object({
+      model: z.string(),
+      scenario: z.string(),
+      uflag: z.boolean().optional()
+    }),
+      
     handler: async (iparams) => {
       let params = {...iparams}; 
       let scenario = params.scenario;
@@ -119,6 +70,12 @@ Related Tools
           }, {});
         }
       params.scenario= scenarioObj;
+      
+      // Drop model extension (e.g., .job, .model)
+      if (params.model && params.model.includes('.')) {
+        params.model = params.model.substring(0, params.model.lastIndexOf('.'));
+      }
+      
       log('modelScore params', params);
       // Check if the params.scenario is a string and parse it
       let r = await _masScoring(params)
@@ -129,3 +86,4 @@ Related Tools
 }
 
 export default modelScore;
+

package/src/toolSet/readTable.js

@@ -1,104 +1,63 @@
-/*
- * 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 _readTable from  '../toolHelpers/_readTable.js';
-function readTable(_appContext) {
-   
-     let describe = `
-## read-table — retrieve rows from a table in a CAS or SAS library
-
-LLM Invocation Guidance (When to use)
-Use THIS tool when:
-- User wants to read data from a table: "read table xyz.customers"
-- User wants sample rows: "show me 10 rows from lib.sales"
-- User wants filtered data: "read from mylib.orders where status = 'shipped'"
-- User wants from specific library: "read table cars in sashelp"
-- User wants from specific server: "read table from mylib.employees on sas"
-
-Do NOT use this tool for:
-- Listing tables in a library (use list-tables)
-- Getting table structure/metadata (use table-info)
-- Running SQL queries (use sas-query)
-- Executing SAS programs (use run-sas-program)
-- Running statistical analysis (use appropriate analytics tools)
-
-Purpose
-Read one or more rows from a specified table in a CAS caslib or SAS libref. Supports pagination, filtering with WHERE clauses, and formatted/raw value display. Use this to inspect table data, sample rows, or retrieve filtered subsets.
-
-Parameters
-- table (string, required): Table name to read.
-- lib (string, required): The caslib or libref containing the table.
-- server (string, default 'cas'): Target server: 'cas' or 'sas'.
-- start (number, default 1): 1-based row index to start reading from.
-- limit (number, default 10): Maximum number of rows to return (1-1000 recommended).
-- where (string, optional): SQL-style WHERE clause to filter rows (e.g., "age > 30 AND status = 'active'").
-- format (boolean, default true): When true, return formatted/labeled values; when false return raw values.
-- row (number, optional): Read a single specific row (sets start to this value and limit to 1).
-
-Response Contract
-Returns a JSON object containing:
-- rows: Array of row objects with column names as keys
-- total (optional): Total count of rows in table (if available)
-- filtered_count (optional): Count of rows matching WHERE clause (if WHERE used)
-- columns (optional): Column metadata including names and types
-- Empty array if no rows match the criteria
-
-Pagination & Filtering
-- First page default: { start: 1, limit: 10 }
-- To get next page: increment start by limit (e.g., { start: 11, limit: 10 })
-- Use WHERE clause for server-side filtering: { where: "age > 30" }
-
-Disambiguation & Clarification
-- Missing library: ask "Which library contains the table you want to read?"
-- Missing table: ask "Which table would you like to read?"
-- Ambiguous lib.table format: parse and use as separate parameters
-- Multiple tables: clarify which one (readTable handles one table at a time)
-
-Examples (→ mapped params)
-- "read table cars in Samples" → { table: "cars", lib: "Samples", start: 1, limit: 10 }
-- "show 25 rows from customers" → { table: "customers", lib: <current_lib>, limit: 25, start: 1 }
-- "read orders where status = 'shipped' limit 50" → { table: "orders", lib: <lib>, where: "status = 'shipped'", limit: 50, start: 1 }
-- "read row 15 from employees in mylib on sas" → { table: "employees", lib: "mylib", server: "sas", row: 15 }
-- "get next 10 rows" (after previous {start:1,limit:10}) → { table: <same>, lib: <same>, start: 11, limit: 10 }
-
-Negative Examples (should NOT call read-table)
-- "list tables in Samples" (use list-tables instead)
-- "what columns are in the cars table?" (use table-info instead)
-- "execute this SQL query" (use sas-query instead)
-- "run this SAS code" (use run-sas-program instead)
-
-Related Tools
-- list-tables — to browse available tables in a library
-- table-info — to inspect table structure, columns, and metadata
-- find-table — to check if a table exists in a library
-- list-libraries — to browse available libraries
-- sas-query — to run complex SQL queries across tables
-`;
-  
-    let  specs = {
-      name: 'read-table',
-      aliases: ['readTable','read table','read_table'],
-      description: describe,
-      schema: {
-        table: z.string(),
-        lib: z.string(),
-        start: z.number(),
-        limit: z.number().default(10),
-        server: z.string().default('cas'),
-        where: z.string().default(''),
-        format: z.boolean().default(true)
-
-      },
-      required: ['table', 'lib'],
-      handler: async (params) => {
-        let r = await _readTable(params,'query');
-        return r;
-      }
-    }
-    return specs;
-}
-export default readTable;
+/*
+ * 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 _readTable from  '../toolHelpers/_readTable.js';
+function readTable(_appContext) {
+   
+     let describe = `
+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
+
+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
+
+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 }
+
+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 }
+
+NEGATIVE EXAMPLES (do not route here)
+- "list tables in Samples" (use list-tables)
+- "what columns are in cars" (use table-info)
+- "execute SQL query" (use sas-query)
+- "run SAS code" (use run-sas-program)
+
+ERRORS
+Returns rows array, total count, filtered_count, columns metadata. Empty array if no matches.
+  `;
+  
+    let  specs = {
+      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()
+      }),
+    handler: async (params) => {
+        let r = await _readTable(params,'query');
+        return r;
+      }
+    }
+    return specs;
+}
+export default readTable;