@sassoftware/sas-score-mcp-serverjs 0.4.1 → 1.0.0

package/src/toolSet/sasQuery.js

@@ -1,126 +1,77 @@
-/*
- * 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
-
-LLM Invocation Guidance (When to use)
-Use THIS tool when:
-- User asks a natural language question about table data: "how many customers by region?"
-- User wants aggregated analytics: "show total sales by year"
-- User needs complex filtering: "find all orders over $1000 from last month"
-- User requests joined data: "show products with their category names"
-- User wants statistical summaries: "average, min, max salary by department"
-- User asks for specific calculations: "percentage of customers by state"
-
-Do NOT use this tool for:
-- Reading raw table data without filtering (use read-table)
-- Getting table structure or column info (use table-info)
-- Running pre-written SAS programs (use run-sas-program)
-- Running jobs or job definitions (use run-job or run-jobdef)
-- Executing macros (use run-macro)
-- Simple table reads with no aggregation (use read-table)
-
-Purpose
-Convert natural language queries into SAS PROC SQL SELECT statements and execute them to retrieve analyzed data. The LLM generates the SQL from the natural language query, and this tool executes it against the specified table.
-
-Parameters
-- table (string, required): Table name in lib.table format (e.g., "Public.cars", "sashelp.class")
-- query (string, required): Natural language description of what data you want
-- sql (string, optional): Pre-generated SQL SELECT statement (LLM should generate this from the query)
-- job (string, default 'program'): Job name to execute the query (default is 'program')
-
-Behavior & Processing
-- LLM converts the natural language query into a valid SAS PROC SQL SELECT statement
-- Do not add semicolons to the end of SQL statements
-- SQL reference: https://go.documentation.sas.com/doc/en/pgmsascdc/v_067/sqlproc/n0w2pkrm208upln11i9r4ogwyvow.htm
-- Tool executes the generated SQL against the specified table
-- Returns data in JSON format
-
-Response Contract
-Returns a JSON object containing:
-- rows: Array of row objects with query results
-- columns: Column metadata from the query result
-- log: Execution log if available
-- If error: structured error message
-- If more than 10 rows: only first 10 displayed (ask user if they want more)
-
-Disambiguation & Clarification
-- If table missing: ask "Which table should I query (format: lib.tablename)?"
-- If query too vague: ask "Can you be more specific about what data or calculation you want?"
-- If table format unclear: ask "Please specify table as library.tablename (e.g., Public.cars)"
-- If ambiguous calculation: ask for clarification on what to aggregate or filter
-
-Examples (→ mapped params)
-- "how many cars by make in sashelp.cars" → { table: "sashelp.cars", query: "how many cars by make", sql: "SELECT make, COUNT(*) AS count FROM sashelp.cars GROUP BY make" }
-- "average horsepower by origin" → { table: "sashelp.cars", query: "average horsepower by origin", sql: "SELECT origin, AVG(horsepower) AS avg_hp FROM sashelp.cars GROUP BY origin" }
-- "total sales over $1000 by region" → { table: "mylib.sales", query: "total sales over $1000 by region", sql: "SELECT region, SUM(amount) AS total FROM mylib.sales WHERE amount > 1000 GROUP BY region" }
-- "percentage of students by year in Public.students" → { table: "Public.students", query: "percentage by year", sql: "SELECT year, COUNT(*) * 100.0 / (SELECT COUNT(*) FROM Public.students) AS pct FROM Public.students GROUP BY year" }
-
-Negative Examples (should NOT call sas-query)
-- "read table cars from sashelp" (use read-table instead)
-- "show me 10 rows from customers" (use read-table instead)
-- "what columns are in the sales table?" (use table-info instead)
-- "run this SAS code: proc sql; select * from..." (use run-sas-program instead)
-- "execute job monthly_report" (use run-job instead)
-- "run macro summarize_data" (use run-macro instead)
-
-Usage Tips
-- Ensure table is specified in lib.tablename format
-- Be specific in natural language queries for better SQL generation
-- Use table-info first to understand column names and types
-- For simple reads without filtering/aggregation, prefer read-table
-
-Related Tools
-- read-table — for simple data reading without SQL queries
-- table-info — to inspect table schema before querying
-- run-sas-program — for executing pre-written SAS/SQL code
-- find-table — to verify table exists before querying
-`;
-
-
-    let spec = {
-        name: 'sas-query',
-        aliases: ['sasQuery','sas query','sas_query'],
-        description: description,
-        schema: {
-            query: z.string(),
-            table: z.string(),
-            sql: z.string().optional(),
-            job: z.string().default('program')
-        },
-        required: ['query', 'table'],
-        handler: async (params) => {
-            let {table,query, sql, job, _appContext} = params;
-            let sqlinput = (sql == null) ? ' ' : sql.replaceAll(';', ' ').replaceAll('\n', ' ').replaceAll('\r', ' ');
-            
-            let iparams = {
-                scenario: {
-                    table: table,
-                    prompt: query,
-                    sql: sqlinput
-                },
-                name: (job == null) ? 'program' : job,
-                type: 'job',
-                query: true,
-                _appContext: _appContext
-            };
-            if (sql == null || sql.trim().length === 0) {
-                return { content: [{ type: 'text', text: 'Error: The SQL statement generated is blank. Please provide a valid natural language query that can be converted to SQL.' }] };
-            }
-         
-            let r = await _jobSubmit(iparams);
-            return r;
-            
-           }
-        }
-    return spec;
-}
-export default sasQuery;
+/*
+ * 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.
+
+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
+
+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
+
+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" }
+
+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" }
+
+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)
+
+ERRORS
+Returns rows array, columns metadata, log. Returns error if SQL invalid or table not found.
+  `;
+
+
+    let spec = {
+    name: 'sas-query',
+    description: description,
+        inputSchema: z.object({
+      query: z.string(),
+      table: z.string(),
+      sql: z.string().optional()
+    }),
+    handler: async (params) => {
+            let {table,query, sql, job, _appContext} = params;
+            let sqlinput = (sql == null) ? ' ' : sql.replaceAll(';', ' ').replaceAll('\n', ' ').replaceAll('\r', ' ');
+            
+            let iparams = {
+                scenario: {
+                    table: table,
+                    prompt: query,
+                    sql: sqlinput
+                },
+                name: (job == null) ? 'program' : job,
+                type: 'job',
+                query: true,
+                _appContext: _appContext
+            };
+            if (sql == null || sql.trim().length === 0) {
+                return { content: [{ type: 'text', text: 'Error: The SQL statement generated is blank. Please provide a valid natural language query that can be converted to SQL.' }] };
+            }
+         
+            let r = await _jobSubmit(iparams);
+            return r;
+            
+           }
+        }
+    return spec;
+}
+export default sasQuery;
+

package/src/toolSet/sasQueryTemplate.js

@@ -108,13 +108,12 @@ async function sasQueryTemplate(uparams) {
         name: toolname,
         description: description,
        
-        schema: {
+        inputSchema: z.object({
             query: z.string(),
             table: z.string().default(uTable),
-            sql: z.string().optional()
-        },
-        required: ['query', 'table'],
-        handler: async (params) => {
+            sql: z.string()
+        }),
+    handler: async (params) => {
             
           
             let { table, query, sql, _appContext} = params;

package/src/toolSet/sasQueryTemplate2.js

@@ -102,14 +102,13 @@ async function sasQueryTemplate2(uparams) {
         name: toolname,
         description: description,
        
-        schema: {
+        inputSchema: z.object({
             query: z.string(),
             table: z.string().default(uTable),
-            sql: z.string().optional(),
+            sql: z.string(),
           
-        },
-        required: ['query', 'table'],
-        handler: async (params) => {
+        }),
+    handler: async (params) => {
             
             let { table, query, sql } = params;
             let sqlinput = (sql == null) ? ' ' : sql.replaceAll(';', ' ').replaceAll('\n', ' ').replaceAll('\r', ' ');

package/src/toolSet/scrInfo.js

@@ -15,7 +15,7 @@ Purpose
 Return the input/output schema and metadata for an SCR (Score Code Runtime) model.
 
 Inputs
-- name (string): The SCR model identifier. 
+- url (string): The SCR model identifier. 
 What it returns
 - A JSON object describing the model's interface, typically including:
   - Input variables (names, types, required/optional)
@@ -23,7 +23,6 @@ What it returns
   
 
 Usage notes
-- If no local mapping exists and \`name\` looks like a URL, the tool will attempt to fetch the schema from that URL.
 - Ensure network connectivity and credentials for the remote SCR service when needed.
 - Use scr-score to score data after inspecting the schema.
 
@@ -34,12 +33,10 @@ Examples
 
   let spec = {
     name: 'scr-info',
-    aliases: ['scrInfo','scr info','scr_info'],
     description: description,
-    schema: {
-      name: z.string(),
-    },
-    required: ['name'],
+    inputSchema: z.object({
+      url: z.string()
+    }),
     handler: async (params) => {
       let {url, _appContext} = params;
       if (url === null) {

package/src/toolSet/scrScore.js

@@ -1,71 +1,70 @@
-/*
- * 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',
-    aliases: ['scrScore','scr score','scr_score'],
-    description: description,
-    schema: {
-      url: z.string(),
-      scenario: z.any()
-    },
-    required: ['url'],
-    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;
-}
-
+/*
+ * 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;

package/src/toolSet/searchAssets.js

@@ -30,16 +30,15 @@ function searchAssets(_appContext) {
 `;
 
   let specs = {
-    name: 'searchAssets',
+    name: 'search-assets',
     description: description,
-    schema: {
+    inputSchema: z.object({
       searchstring: z.string(),
       assetType: z.string(),
-      start: z.number().default(0),
-      limit: z.number().default(10),
+      start: z.number(),
+      limit: z.number()
 
-    },
-    required: ['assetType'],
+    }),
     handler: async (params) => {
       log('searchAssets params', params);
       return await _catalogSearch(params, 'search');

package/src/toolSet/setContext.js

@@ -1,92 +1,65 @@
-/*
- * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import {z} from 'zod';
-
-function setContext(_appContext) {
-    let description = `
-## set-context — set the CAS and SAS server contexts for subsequent tool calls
-
-LLM Invocation Guidance (When to use)
-Use THIS tool when:
-- User wants to switch to a different CAS server: "Use the finance-cas-server"
-- User wants to change the compute context: "Switch to 'SAS Studio Compute Context'"
-- User wants to check current context: "What context am I using?"
-- User wants to set both: "Use finance-cas-server for CAS and my-compute for SAS"
-
-Do NOT use this tool for:
-- Retrieving variable values (use get-env)
-- Reading table data (use read-table)
-- Running programs or queries (use run-sas-program or sas-query)
-- Listing available servers or contexts (no tool for this; would require backend support)
-
-Purpose
-Set the active CAS server and/or SAS compute context for all subsequent tool calls in this session. This allows switching between different server environments. If neither parameter is provided, the tool returns the current context values.
-
-Parameters
-- cas (string, optional): The name of the CAS server to use for subsequent CAS operations. Examples: 'cas-shared-default', 'finance-cas-server', 'analytics-cas'
-- sas (string, optional): The name of the SAS compute context to use for subsequent SAS operations. Examples: 'SAS Studio Compute Context', 'my-compute', 'batch-compute'
-
-Response Contract
-Returns a JSON object containing:
-- cas: The current/new CAS server name (string or null)
-- sas: The current/new SAS compute context name (string or null)
-- If no parameters provided, returns the current context values
-- If parameters provided, updates and returns the new context values
-- On error: error message if context cannot be set (e.g., invalid server name)
-
-Disambiguation & Clarification
-- If user says "switch servers" without specifying which: ask "Which server would you like to use: CAS, SAS, or both?"
-- If user provides a server name that may not exist: proceed with setting it (the backend will validate)
-- If user says "reset context": ask "Should I reset the CAS context, SAS context, or both?"
-- If user only says "context": ask "Would you like to check the current context or set a new one?"
-
-Examples (→ mapped params)
-- "Use the finance-cas-server" → { cas: "finance-cas-server" }
-- "Switch to SAS Studio Compute Context" → { sas: "SAS Studio Compute Context" }
-- "Set CAS to prod-cas and SAS to batch-compute" → { cas: "prod-cas", sas: "batch-compute" }
-- "What's my current context?" → { } (no parameters returns current context)
-- "Show me the active CAS server" → { } (no parameters returns current context)
-
-Negative Examples (should NOT call set-context)
-- "Read 10 rows from the customers table" (use read-table instead)
-- "What's the value of myVariable?" (use get-env instead)
-- "Run this SAS program" (use run-sas-program instead)
-
-Related Tools
-- get-env — to retrieve individual environment variable values
-- read-table — to read data using the current context
-- run-sas-program — to execute SAS programs in the current context
-- sas-query — to execute SQL queries in the current context
-`;
-  
-    let spec = {
-        name: 'set-context',
-        aliases: ['setContext','set context','set_context'],
-        description: description,
-        schema: {
-            cas: z.string().optional(),
-            sas: z.string().optional()
-        },
-       
-        handler: async (params) => {
-            
-            let {cas, sas} = params;
-            if (typeof cas === 'string' && cas.trim().length > 0) {
-                _appContext.contexts.cas = cas.trim();
-            }
-            if (typeof sas === 'string' && sas.trim().length > 0) {
-                _appContext.contexts.sas = sas.trim();
-            }
-            // Return a structured response without extraneous keys
-            return {
-                content: [{ type: 'text', text: JSON.stringify(_appContext.contexts) }],
-                structuredContent: _appContext.contexts
-            };
-        }
-    }
-    return spec;
-}
-export default setContext;
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {z} from 'zod';
+
+function setContext(_appContext) {
+    let description = `
+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)
+
+PARAMETERS
+- cas: string — CAS server name (optional), e.g. 'cas-shared-default', 'finance-cas-server'
+- sas: string — SAS compute context (optional), e.g. 'SAS Studio Compute Context', 'batch-compute'
+
+ROUTING RULES
+- "use finance-cas-server" → { cas: "finance-cas-server" }
+- "switch to SAS Studio Compute Context" → { sas: "SAS Studio Compute Context" }
+- "use finance-cas for CAS and batch-compute for SAS" → { cas: "finance-cas", sas: "batch-compute" }
+- "what context am I using" → { } (no params, returns current)
+
+EXAMPLES
+- "use finance-cas-server" → { cas: "finance-cas-server" }
+- "switch to batch-compute" → { sas: "batch-compute" }
+- "what's my current context" → { }
+
+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)
+
+ERRORS
+Returns current or updated context values {cas, sas}. Error if server not found or invalid name.
+  `;
+  
+    let spec = {
+    name: 'set-context',
+    description: description,
+        inputSchema: z.object({
+      cas: z.string().optional(),
+      sas: z.string().optional()
+    }),
+    handler: async (params) => {
+            
+            let {cas, sas} = params;
+            if (typeof cas === 'string' && cas.trim().length > 0) {
+                _appContext.contexts.cas = cas.trim();
+            }
+            if (typeof sas === 'string' && sas.trim().length > 0) {
+                _appContext.contexts.sas = sas.trim();
+            }
+            // Return a structured response without extraneous keys
+            return {
+                content: [{ type: 'text', text: JSON.stringify(_appContext.contexts) }],
+                structuredContent: _appContext.contexts
+            };
+        }
+    }
+    return spec;
+}
+export default setContext;
+