@sassoftware/sas-score-mcp-serverjs 0.0.2

package/src/toolSet/modelInfo.js

@@ -0,0 +1,87 @@
+/*
+ * 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 _masDescribe from '../toolHelpers/_masDescribe.js';
+const log = debug('tools');
+
+function modelInfo(_appContext) {
+  let description = `
+## 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?"
+
+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)
+
+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.
+
+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)
+- "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" }
+
+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)
+
+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
+`;
+
+  let spec = {
+    name: 'model-info',
+    aliases: ['modelInfo','model info','model_info'],
+    description: description,
+    schema: {
+      'model': z.string()
+    },
+    required: ['model'],
+    handler: async (params) => {
+      let r = await _masDescribe(params);
+      return r;
+    }
+  }
+  return spec;
+}
+
+export default modelInfo;

package/src/toolSet/modelScore.js

@@ -0,0 +1,131 @@
+/*
+ * 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 _masScoring from '../toolHelpers/_masScoring.js';
+const log = debug('tools');
+
+function modelScore(_appContext) {
+  let description = `
+## model-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"
+
+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)
+
+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.
+
+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.
+
+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
+
+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
+`;
+
+ 
+  let spec = {
+    name: 'model-score',
+    aliases: ['modelScore','model score','model_score'],
+    description: description,
+    schema: {
+      'model': z.string(),
+      'scenario': z.any(),
+      'uflag': z.boolean()
+    },
+    required: ['model', 'scenario'],
+    handler: async (iparams) => {
+      let params = {...iparams}; 
+      let scenario = params.scenario;
+   
+        // 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;
+      log('modelScore params', params);
+      // Check if the params.scenario is a string and parse it
+      let r = await _masScoring(params)
+      return r;
+    }
+  }
+  return spec;
+}
+
+export default modelScore;

package/src/toolSet/readTable.js

@@ -0,0 +1,104 @@
+/*
+ * 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;

package/src/toolSet/runCasProgram.js

@@ -0,0 +1,118 @@
+/*
+ * 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 runCasProgram(_appContext) {
+  let description = `
+## run-cas-program
+
+Execute a cas program on a SAS Viya server
+
+Required Parameters
+- src(string, required): The cas program to execute. 
+
+Optional Parameters:
+
+- 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),
+
+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'"'
+
+
+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}
+`;
+
+  let spec = {
+    name: 'run-sas-program',
+    aliases: ['Program','run program'],
+    description: description,
+    schema: {
+      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'],
+    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 runCasProgram;

package/src/toolSet/runJob.js

@@ -0,0 +1,81 @@
+/*
+ * 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 runJob(_appContext) {
+ 
+  let description = `
+## run-job — execute 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
+
+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, 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)
+
+Response
+- Log output, listings, and tables depending on the job’s design. Table outputs will be displayed when present.
+
+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 } }
+`;
+
+  let spec = {
+    aliases: ['run job', 'run-job', 'runjob'],
+    name: 'run-job',
+    description: description,
+    schema: {
+      name: z.string(),
+      scenario: z.any().default(''),
+    },
+    required: ['name'],
+    handler: async (params) => {
+      let scenario = params.scenario;
+      let scenarioObj = {};
+      let count = 0;
+      // 
+      if (scenario == null) {
+        scenarioObj = {};
+      } else if (typeof scenario === 'object') {
+        scenarioObj = scenario;
+      } else if (Array.isArray(scenario)) {
+        scenarioObj = scenario[0];
+      } else if (typeof scenario === 'string') {
+        if (scenario.trim() === '') {
+          scenarioObj = {};
+        } 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.type = 'job';
+      params.scenario = scenarioObj;
+      // Provide runtime context for auth and server settings
+      let r = await _jobSubmit(params);
+      return r;
+    }
+  };
+  return spec;
+}
+
+export default runJob;

package/src/toolSet/runJobdef.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 runJobdef(_appContext) {
+  // JSON object for LLM/tooling
+ 
+  let description = `
+## run-jobdef — execute a SAS Viya job definition
+
+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
+
+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)
+
+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)
+
+Response
+- Log output, listings, and tables depending on the job definition's design. Table outputs will be displayed when present.
+
+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 } 
+`;
+ 
+  let spec = {
+      name: 'run-jobdef',
+      aliases: ['jobDef','jobdef','jobdef'],
+    description: description,
+    schema: {
+      name: z.string(),
+      scenario: z.any().default(''),
+    },
+    required: ['name'],
+    handler: async (params) => {
+      let scenario = params.scenario;
+      let scenarioObj = {};
+      let count = 0;
+      // 
+      if (scenario == null) {
+        scenarioObj = {};
+      } else if (typeof scenario === 'object') {
+        scenarioObj = scenario;
+      } else if (Array.isArray(scenario)) {
+        scenarioObj = scenario[0];
+      } else if (typeof scenario === 'string') {
+        if (scenario.trim() === '') {
+          scenarioObj = {};
+        } 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.type = 'def';
+      params.scenario = scenarioObj;
+      // Provide runtime context for auth and server settings
+      let r = await _jobSubmit(params);
+      return r;
+    }
+  };
+  return spec;
+}
+
+export default runJobdef;