@sassoftware/sas-score-mcp-serverjs 0.0.2

package/src/toolSet/scrInfo.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 _scrInfo from '../toolHelpers/_scrInfo.js';
+
+function scrInfo(_appContext) {
+
+  let description = `
+## scr-info
+
+Purpose
+Return the input/output schema and metadata for an SCR (Score Code Runtime) model.
+
+Inputs
+- 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
+- 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.
+
+Examples
+- describe scr model "https://scr-host/models/loan"
+- info for scr model "https://scr-host/models/loan"
+`;
+
+  let spec = {
+    name: 'scr-info',
+    aliases: ['scrInfo','scr info','scr_info'],
+    description: description,
+    schema: {
+      name: z.string(),
+    },
+    required: ['name'],
+    handler: async (params) => {
+      let {url, _appContext} = params;
+      if (url === null) {
+        return { status: { statusCode: 2, msg: `SCR model ${url} not found` }, results: {} };
+      }
+      let r = await _scrInfo({url, _appContext});
+      return r;
+    }
+  }
+  return spec;
+}
+
+export default scrInfo;

package/src/toolSet/scrScore.js

@@ -0,0 +1,71 @@
+/*
+ * 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;
+}
+
+export default scrScore;

package/src/toolSet/searchAssets.js

@@ -0,0 +1,52 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from 'zod';
+import _catalogSearch from '../toolHelpers/_catalogSearch.js';
+import debug from 'debug';
+
+
+function searchAssets(_appContext) {
+  const log = debug('tools');
+
+  let description = `
+## searchAssets: 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'.
+- The search string can include keywords, filters, and logical operators.
+- You can specify start and limit to control pagination of results.
+- The searchstring can include:
+  - Simple terms (e.g., customer).
+  - Key-value pairs (e.g., type:dataset or owner:john).
+  - Logical operators AND and OR between terms.
+  - Sets (e.g., status:{active,archived}).
+- The search string is parsed according to these rules:
+  1. Terms without ':' or '=' are treated as search keywords.
+  2. Key-value pairs (with ':') are treated as filters.
+  3. AND/OR are treated as logical operators when between terms.
+  4. Sets in the form key:{value1,value2} are supported as filters.
+`;
+
+  let specs = {
+    name: 'searchAssets',
+    description: description,
+    schema: {
+      searchstring: z.string(),
+      assetType: z.string(),
+      start: z.number().default(0),
+      limit: z.number().default(10),
+
+    },
+    required: ['assetType'],
+    handler: async (params) => {
+      log('searchAssets params', params);
+      return await _catalogSearch(params, 'search');
+    }
+
+  };
+
+  return specs;
+}
+export default searchAssets;

package/src/toolSet/setContext.js

@@ -0,0 +1,98 @@
+/*
+ * 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) => {
+            // Ensure contexts object exists
+            if (_appContext.contexts == null || typeof _appContext.contexts !== 'object') {
+                _appContext.contexts = {
+                    cas: _appContext.DEFAULT_CAS_SERVER || null,
+                    sas: null
+                };
+            }
+            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;

package/src/toolSet/superstat.js

@@ -0,0 +1,60 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import _submitCode from '../toolHelpers/_submitCode.js';
+import { z } from 'zod';
+
+function superstat(_appContext) {
+  let desc = `
+  ## superstat:  compute superstat for two numbers using SAS programming 
+
+  ## Details
+  This is a tool to demonstrate using SAS programming to score. The SAS program for suprestat is
+  below. In a real application this would be a more complex program that is 
+  available to the SAS server.
+
+  
+    ods html style=barrettsblue;  
+    data temp;
+    superstat = (&a + &b) * 42;
+    run;
+    proc print data=temp;
+    run;
+    ods html close; 
+    run;
+  
+  ## Sample Prompt
+
+    - compute superstat for 1 and 2
+    - compute superstat for 3,5
+    
+    `;
+  let spec = {
+    name: 'superstat',
+    description: desc,
+    schema: {
+      a: z.number(),
+      b: z.number()
+    },
+    required: ['a', 'b'],
+    handler: async (params) => {
+      let src = `
+          ods html style=barrettsblue;  
+          data temp;
+          superstat = (&a + &b) * 42;
+          run;
+          proc print data=temp;
+          run;
+          ods html close; 
+          run;
+          `;
+      params.src = src;
+      let r = await _submitCode(params);
+      return r;
+    }
+
+  };
+  return spec;
+}
+export default superstat;

package/src/toolSet/tableInfo.js

@@ -0,0 +1,102 @@
+/*
+ * 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 _tableInfo  from '../toolHelpers/_tableInfo.js';
+function tableInfo(_appContext) {
+
+     let describe = `
+## table-info — retrieve metadata about a table in a CAS or SAS library
+
+LLM Invocation Guidance (When to use)
+Use THIS tool when:
+- User wants table structure/schema: "what columns are in the cars table?"
+- User wants column metadata: "describe the structure of customers table"
+- User wants to see data types: "show me the schema for sales table in Public"
+- User wants table statistics: "how many rows in the orders table?"
+- User wants column information: "what are the columns in the iris table?"
+
+Do NOT use this tool for:
+- Reading actual data rows (use read-table)
+- Listing tables in a library (use list-tables)
+- Checking if a table exists (use find-table)
+- Running queries (use sas-query)
+- Reading sample data (use read-table)
+
+Purpose
+Return metadata about a table in a specified library (caslib or libref). This includes column names, data types, labels, formats, and table-level statistics such as row count, file size, and timestamps.
+
+Parameters
+- table (string, required): The name of the table to inspect.
+- lib (string, required): The caslib or libref containing the table.
+- server (string, default 'cas'): Target server, either 'cas' or 'sas'. Defaults to 'cas' when omitted.
+
+Response Contract
+Returns a JSON object containing:
+- columns: Array of column objects with:
+  - name: Column name (string)
+  - type: Data type (string) - e.g., 'numeric', 'character'
+  - label: Column label if defined (string)
+  - format: Display format if defined (string)
+  - length: Column length for character fields (number)
+- tableInfo: Table-level metadata including:
+  - rowCount: Number of rows (number)
+  - fileSize: File size if available (number)
+  - created: Creation timestamp if available (string)
+  - modified: Last modified timestamp if available (string)
+- Empty object if table not found or accessible
+
+Disambiguation & Clarification
+- Missing library: ask "Which library contains the table you want to inspect?"
+- Missing table: ask "Which table would you like information about?"
+- If user wants data: clarify "Do you want the table structure (use table-info) or actual data rows (use read-table)?"
+- Ambiguous lib.table format: parse and use as separate parameters
+
+Examples (→ mapped params)
+- "describe table cars in sashelp" → { table: "cars", lib: "sashelp", server: "sas" }
+- "what columns are in orders from Public" → { table: "orders", lib: "Public", server: "cas" }
+- "show schema for sales in mylib" → { table: "sales", lib: "mylib", server: "cas" }
+- "table info for iris in Samples" → { table: "iris", lib: "Samples", server: "cas" }
+- "how many rows in customers on cas" → { table: "customers", lib: <lib>, server: "cas" }
+
+Negative Examples (should NOT call table-info)
+- "read 10 rows from cars" (use read-table instead)
+- "list tables in sashelp" (use list-tables instead)
+- "does table cars exist in Public?" (use find-table instead)
+- "run query on customers table" (use sas-query instead)
+- "show me data from the sales table" (use read-table instead)
+
+Usage Tips
+- Use this tool to inspect schema and column types before scoring or reading data.
+- After inspecting structure, use read-table to fetch actual data.
+- Combine with find-table to verify existence before inspection.
+
+Related Tools
+- find-table → table-info → read-table (typical workflow)
+- list-tables — to discover tables before inspecting
+- read-table — to fetch actual data after inspecting structure
+- find-table — to verify a table exists before inspection
+`;
+   
+    let  specs = {
+      name: 'table-info',
+      aliases: ['tableInfo','table info','table_info'],
+      description: describe,
+      schema: {
+        table: z.string(),
+        lib: z.string(),
+        server: z.string()
+      },
+      required: ['table', 'lib'],
+      handler: async (params) => {
+        params.describe = true;
+        let r = await _tableInfo(params);
+        return r;
+      }
+    }
+    return specs;
+}
+export default tableInfo;

package/src/toolhelpers/_catalogSearch.js

@@ -0,0 +1,87 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// An initial pass at using catalog search
+// not sure of its usefulness yet since the search string
+// syntax is designed for nerdy users.
+// Maybe one can instruct LLM to format a user friend search into
+// required syntax
+// But then I am an expert on SAS Catalog
+import restaf from '@sassoftware/restaf';
+
+import _itemsData from '../toolHelpers/_itemsData.js';
+
+async function _catalogSearch(params, rel) {
+  let { searchstring, start, limit , _appContext} = params;
+  let splitsearchstring = searchstring.trimStart().split(' ');
+  let assetType = ' ';
+  if (!splitsearchstring[0].includes(':')) {
+    if (['dataflows',
+      'datasets',
+      'dataplans',
+      'models',
+      'modelprojects',
+      'modelstudioprojects',
+      'report',
+      'rulesets',
+      'referencedatadomains',
+      'codefiles',
+      'decisions',
+      'riskdataprojects',
+      'riskmodels'
+    ].includes(splitsearchstring[0])) {
+      assetType = `${splitsearchstring[0]}`;
+      splitsearchstring[0] = 'AssetType:' + splitsearchstring[0];
+      searchstring = splitsearchstring.join(' ');
+    } else {
+      assetType = `${splitsearchstring[0]}`;
+    }
+  }
+
+  limit = (limit) ? limit : 10;
+  start = (start) ? start : 0;
+
+
+
+  // https://go.documentation.sas.com/doc/en/infocatcdc/v_034/infocatug/n09x2n3z9t2izln1vtx68oho8t8x.htm?requestorId=84052456-0342-4389-a344-5cc71cbec5cc
+
+  try {
+
+     let store = restaf.initStore(_appContext.storeConfig);
+
+    let msg = await store.logon(_appContext.logonPayload);
+
+    if (rel == null) {
+      rel = 'search';
+    }
+   
+    let { catalog } = await store.addServices('catalog');
+    let payload = {
+      qs: { q: searchstring, limit: limit, start: start },
+    };
+  
+
+    let r = await store.apiCall(catalog.links(rel), payload);
+ 
+    let rx = _itemsData(r);
+    return {
+      content: [
+        {
+        type: 'text', text: JSON.stringify(rx)
+        }
+      ],
+      structuredContent: rx,
+    }
+  } catch (err) {
+    console.error('Error in searchAssets:', JSON.stringify(err, null, 4));
+    return {
+      isError: true,
+      content:[{
+        type: 'text', text: JSON.stringify(err)
+      }]
+    }
+  }
+}
+export default _catalogSearch;

package/src/toolhelpers/_getEnv.js

@@ -0,0 +1,10 @@
+
+
+async function _deval(params) {
+  
+
+ const varName = params.name;
+return { content: [{ type: 'text', text: process.env[varName]}]};
+}
+
+export default _deval;

package/src/toolhelpers/_itemsData.js

@@ -0,0 +1,28 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// catalog returns a lot of stuff, so we need to filter it down to just the items
+function _itemsData(r) {
+  let rx = [];
+  let details = {};
+  let text = '';
+  if (r.itemsList().size > 0) {
+    rx = r.itemsList().toJS().map(item => {
+      let rt = r.items(item, 'data').toJS();
+      let row = {name: item, label: rt.label, type: rt.type};
+      if (rt.attributes != null) {
+        row.source = (rt.attributes.sourceSystem) ? rt.attributes.sourceSystem.toLowerCase() : '';
+        row.library = rt.attributes.library;
+      }
+      details[item] = rt;
+      text = text + '\n' + `${item}: ${JSON.stringify(rt)}`;
+      return row;
+    });
+  } else {
+    rx = (r.items('data') != null) ? [r.items('data').toJS()] : {warning: 'No data returned'};
+  }
+  return rx;
+}
+export default _itemsData;

package/src/toolhelpers/_jobSubmit.js

@@ -0,0 +1,78 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import restaf from '@sassoftware/restaf';
+import restaflib from '@sassoftware/restaflib';
+import _submitCode from './_submitCode.js';
+
+async function _jobSubmit(params) {
+  let { name, type, scenario, query, _appContext } = params;
+  console.error(`_jobSubmit called with name: ${name} type: ${type} scenario: ${JSON.stringify(scenario)}`);
+  // setup
+  if (name === 'program') {
+    let src = `
+     proc sql;
+     create table work.query_results as
+     ${scenario.sql};
+    quit; 
+    data work.RESULT;
+    set work.query_results;
+    run;
+    ;
+    `;
+    let iparams = {
+      output: 'RESULT',
+      limit: 100,
+      args: {},
+      src: src,
+      _appContext: _appContext
+    };
+
+    try {
+      let r = await _submitCode(iparams);
+      let response = {tabled: r.structuredContent.tabled};
+      return {
+        content: [{ type: 'text', text: JSON.stringify(response) }],
+        structuredContent: response
+      };
+    } catch (error) {
+      console.error(`Error in _jobSubmit for program: ${JSON.stringify(error)}`);
+      let result = {
+        tables: { Error: [{ Message: "Job failed. Please contact the owner of the job " + name }] }
+      };
+      return { isError: true, content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
+    }
+
+  }
+  else {
+
+    // use a job or job definition
+    try {
+      let store = restaf.initStore(_appContext.storeConfig);
+      let msg = await store.logon(_appContext.logonPayload);
+      type = (type == null) ? 'job' : type.toLowerCase();
+      
+      let r = (type === 'definition' || type === 'def')
+        ? await restaflib.jesRun(store, name, scenario)
+        : await restaflib.jobRun(store, name, scenario);
+
+      let response = (query === true) ? { tabled: r.tables.rows } : { tables: r.tables, listing: r.listing, log: r.log };
+      
+      return {
+        content: [{ type: 'text', text: JSON.stringify(response) }],
+        structuredContent: response
+      };
+    }
+    catch (error) {
+      // Oops! Something went wrong
+      console.error(`Error in _jobSubmit: ${JSON.stringify(error)}`);
+      let result = {
+        tables: { Error: [{ Message: "Job failed. Please contact the owner of the job " + name }] }
+      };
+      return { isError: true, content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
+    }
+  }
+}
+
+export default _jobSubmit;