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

package/src/toolSet/findModel.js

@@ -9,69 +9,45 @@ import _listModels from '../toolHelpers/_listModels.js';
 
 function findModel(_appContext) {
   let description = `
-  ## find-model — locate a specific model deployed to MAS (Model Publish / Scoring service)
-
-  LLM Invocation Guidance (When to use)
-  Use THIS tool when the user wants to know whether ONE model exists or is deployed:
-  - "find model cancerRisk"
-  - "does model churn_tree exist"
-  - "is model sales_forecast deployed"
-  - "lookup model claimFraud"
-  - "verify model credit_score_v2 exists"
-
-  Do NOT use this tool for:
-  - Listing many / browsing models (use list-models)
-  - Retrieving detailed input/output variable metadata (use model-info)
-  - Scoring or running a model (use model-score)
-  - Searching model execution containers or SCR endpoints (use scr-info / scr-score if appropriate)
-  - Finding a table (use find-table)
-  - Finding a library (use find-library)
-  - Finding a job or jobdef (use find-job / find-jobdef)
-
-  Purpose
-  Quick existence / lookup check for a MAS‑published model. Returns a list with zero or more matches (typically 0 or 1 for an exact name).
-
-  Parameters
-  - name (string, required): Exact model name. If user supplies phrases like "model named X" extract X. If multiple names are given (comma or space separated), prefer the first and (optionally) ask for a single name.
-
-  Matching Rules
-  - Attempt exact match first. If backend supports partial search, a substring match MAY return multiple models; preserve order.
-  - Do not fabricate models. Empty array means not found.
-
-  Response Contract
-  - Always: { models: Array<object|string> }
-  - Never return prose when invoked programmatically; only the JSON structure.
-  - On error: surface backend error object directly (no rewriting) so the caller can display/log it.
-
-  Disambiguation & Clarification
-  - Missing name (e.g., "find model") → ask: "Which model name would you like to find?"
-  - Plural intent (e.g., "find models" / "list models") → use list-models instead.
-  - If user requests scoring ("score model X") → route to model-score not find-model.
-
-  Examples (→ mapped params)
-  - "find model myModel" → { name: "myModel" }
-  - "does model churn_score exist" → { name: "churn_score" }
-  - "is model riskModel deployed" → { name: "riskModel" }
-  - "lookup model claims_fraud_v1" → { name: "claims_fraud_v1" }
-
-  Negative Examples (should NOT call find-model)
-  - "list models" (list-models)
-  - "score model myModel" (model-score)
-  - "describe model myModel" (model-info)
-
-  Notes
-  - Chain usage: find-model → model-info → model-score.
-  - For batch existence checks iterate over a list and call find-model per entry.
+find-model — locate a specific MAS model deployed to MAS server 
+
+USE when: find model, does model exist, is model deployed, lookup model, verify model exists
+DO NOT USE for: list models (use list-models), model info/variables (use model-info), score model (use model-score), find table/job/lib (use respective tools), scr models (use scr-info/scr-score)
+
+PARAMETERS
+- name: string (required) — model name to locate; if multiple supplied, use first
+
+ROUTING RULES
+- "find model <name>" → { name: "<name>" }
+- "does model <name> exist" → { name: "<name>" }
+- "is model <name> deployed" → { name: "<name>" }
+- "lookup/verify model <name>" → { name: "<name>" }
+- "find model" with no name → ask "Which model name would you like to find?"
+- "find all models / list models" → use list-models instead
+- "score model <name>" → use model-score instead
+- "describe model / model info" → use model-info instead
+
+EXAMPLES
+- "find model myModel" → { name: "myModel" }
+- "does model churn_score exist" → { name: "churn_score" }
+- "is model riskModel deployed" → { name: "riskModel" }
+- "lookup model claims_fraud_v1" → { name: "claims_fraud_v1" }
+
+NEGATIVE EXAMPLES (do not route here)
+- "list models" (use list-models)
+- "score model myModel" (use model-score)
+- "model info for churnRisk" (use model-info)
+
+ERRORS
+Returns { models: [] } if not found; { models: [name, ...] } if found. Never hallucinate model names.
   `;
 
   let spec = {
     name: 'find-model',
-    aliases: ['findModel','find model','find_model'],
     description: description,
-    schema: {
-      'name': z.string()
-    },
-    required: ['name'],
+    inputSchema: z.object({
+      name: z.string()
+    }),
     handler: async (params) => { 
       let r = await _listModels(params);
       return r;
@@ -81,3 +57,4 @@ function findModel(_appContext) {
 }
 
 export default findModel;
+

package/src/toolSet/findTable.js

@@ -9,79 +9,49 @@ import _listTables from '../toolHelpers/_listTables.js';
 
 function findTable(_appContext) {
   let description = `
-## find-table — locate a specific table in a CAS or SAS library
+find-table — locate a specific table in a CAS or SAS library.
 
-LLM Invocation Guidance (When to use)
-Use THIS tool when the user wants to find or verify a table in a specific library:
-- "find table iris in Public library in cas"
-- "find table cars in sashelp in sas server"
-- "does table customers exist in mylib?"
-- "is there a table named sales in the Samples library?"
-- "verify table orders exists in Public"
+USE when: find table, does table exist, is table in library, verify table exists, locate table
+DO NOT USE for: list tables (use list-tables), table schema/columns (use table-info), read table data (use read-table), find lib/job/model (use respective tools)
 
-Do NOT use this tool when the user wants:
-- find lib -> use find-library
-- find model -> use find-model
-- find job -> use find-job
-- find jobdef -> use find-jobdef
-- Columns or schema of a table (use table-info)
-- Reading data from a table (use read-table)
-- Listing all tables in a library (use list-tables)
+PARAMETERS
+- lib: string (required) — library name (e.g., 'Public', 'sashelp')
+- name: string (required) — table name to locate
+- server: 'cas' | 'sas' . If not specified set it to 'cas' — target environment
 
-Purpose
-Locate a table contained in a specified library (caslib or libref) on a CAS or SAS server. Returns matching table names or empty array if not found.
+ROUTING RULES
+- "find table <name> in <lib>" → { lib: "<lib>", name: "<name>", server: "cas" }
+- "find table <name> in <lib> in sas" → { lib: "<lib>", name: "<name>", server: "sas" }
+- "does table <name> exist in <lib>" → { lib: "<lib>", name: "<name>", server: "cas" }
+- "find table" with missing lib → ask "Which library contains the table?"
+- "find table" with missing name → ask "Which table name would you like to find?"
+- "list tables in <lib>" → use list-tables instead
 
-Parameters
-- lib (string, required): The library to search in (e.g., 'Public', 'sashelp', or a caslib name)
-- name (string, required): Table name or substring to search for. Matching is case-insensitive.
-- server (string, default 'cas'): Either 'cas' or 'sas'. Defaults to 'cas' when omitted.
-
-Response Contract
-Returns a JSON object with:
-- tables: Array of matching table names (strings)
-- Empty array { tables: [] } when no matches found
-- Do not fabricate table names; only return actual matches
-
-Disambiguation & Clarification
-- Missing library: ask "Which library do you want to search in?"
-- Missing table name: ask "Which table name would you like to find?"
-- Server ambiguous: ask "Do you mean CAS or SAS?"
-- If user wants multiple tables: suggest "Use list-tables to see all tables in a library"
-
-Examples (→ mapped params)
-- "find table iris in Public library in cas" → { lib: "Public", name: "iris", server: "cas" }
-- "find table cars in sashelp in sas server" → { lib: "sashelp", name: "cars", server: "sas" }
+EXAMPLES
+- "find table iris in Public" → { lib: "Public", name: "iris", server: "cas" }
+- "find table cars in sashelp in sas" → { lib: "sashelp", name: "cars", server: "sas" }
 - "does customers exist in mylib" → { lib: "mylib", name: "customers", server: "cas" }
 - "verify table orders in Samples" → { lib: "Samples", name: "orders", server: "cas" }
 
-Negative Examples (should NOT call find-table)
-- "list tables in Public" (use list-tables instead)
-- "find library Public" (use find-library instead)
-- "what columns in cars table?" (use table-info instead)
-- "read data from customers" (use read-table instead)
+NEGATIVE EXAMPLES (do not route here)
+- "list tables in Public" (use list-tables)
+- "find library Public" (use find-library)
+- "what columns in cars?" (use table-info)
+- "read data from customers" (use read-table)
 
-Usage Tips
-- Use this tool to verify table existence before reading or querying
-- For discovery of multiple tables, use list-tables instead
-- After finding a table, use table-info for schema or read-table for data
-
-Related Tools
-- find-table → table-info → read-table (typical workflow)
-- list-tables — to discover all tables in a library
-- find-library — to verify library exists
-- table-info — to inspect table structure after finding it
-`;
+ERRORS
+Returns { tables: [] } if not found; { tables: [name, ...] } if found. Never hallucinate table names.
+  `;
   
   let spec = {
     name: 'find-table',
-    aliases: ['findTable','find table','find_table'],
     description: description,
-    schema: {
-      server: z.string().default('cas'), // default server is 'cas',
+    inputSchema: z.object({
+      lib: z.string(),
       name: z.string(),
-      lib: z.string()
-    },
-    required: ['name', 'lib'],
+      server: z.string() 
+    }),
+    
     handler: async (params) => {
       // Check if the params.scenario is a string and parse it
       let r = await _listTables(params);
@@ -92,3 +62,4 @@ Related Tools
 }
 
 export default findTable;
+

package/src/toolSet/getEnv.js

@@ -7,66 +7,51 @@ import {z} from 'zod';
 import _getEnv from '../toolHelpers/_getEnv.js';
 function getEnv(_appContext) {
     let description = `
-## get-env — retrieve a variable value from the runtime environment
+get-env — retrieve a variable value from the runtime environment.
 
-LLM Invocation Guidance (When to use)
-Use THIS tool when:
-- The user wants to access a specific environment variable or context value
-- "What is the value of [variable name]?"
-- "Get me the [variable] value"
-- "Show the current [variable]"
+USE when: what is the value of, get me, show current, what's the, retrieve environment variable
+DO NOT USE for: read table data (use read-table), model info (use model-info), find/run job (use find-job/run-job), set context (use set-context)
 
-Do NOT use this tool for:
-- Retrieving table data (use read-table)
-- Getting model information (use model-info)
-- Looking up job status (use find-job or run-job)
-- Setting environment variables (use set-context to set CAS/SAS contexts)
+PARAMETERS
+- name: string (required) — variable name to retrieve (case-sensitive)
 
-Purpose
-Retrieve the current value of a named variable from the runtime environment. This is useful for debugging, accessing context information, or verifying current configuration values.
+ROUTING RULES
+- "what is the value of <var>" → { name: "<var>" }
+- "get me <var>" → { name: "<var>" }
+- "show <var>" → { name: "<var>" }
+- "get" with no variable → ask "Which variable would you like to retrieve?"
+- "what context am I using" → use set-context instead (no params)
+- "set <var> to <value>" → use set-context or run-sas-program instead
 
-Parameters
-- name (string, required): The name of the variable to retrieve. Variable names are case-sensitive.
-
-Response Contract
-Returns a JSON object containing:
-- The requested variable name as a key
-- The current value of that variable
-- If the variable does not exist, returns null or an error message
-
-Disambiguation & Clarification
-- If variable name is missing: ask "Which variable would you like to retrieve?"
-- If user says "context" without specifying which variable: clarify "Do you mean the CAS context, SAS context, or a specific variable?"
-- Multiple variable request: handle one at a time or ask for clarification
-
-Examples (→ mapped params)
+EXAMPLES
 - "What's the value of myVar" → { name: "myVar" }
 - "Get me the configuration variable" → { name: "configuration" }
 - "Show the current server setting" → { name: "server" }
 
-Negative Examples (should NOT call get-env)
-- "Read all rows from the customers table" (use read-table instead)
-- "Get model details for myModel" (use model-info instead)
-- "Set the CAS server to finance-prod" (use set-context instead)
+NEGATIVE EXAMPLES (do not route here)
+- "Read rows from customers" (use read-table)
+- "Get model details for myModel" (use model-info)
+- "Set the CAS server to finance-prod" (use set-context)
 
-Related Tools
-- setContext — to set environment context values (CAS and SAS servers)
-- readTable — to retrieve table data
-- modelInfo — to retrieve model metadata
-`;
+ERRORS
+Returns variable name with current value, or null if not found. Return structured error with message field.
+    `;
   
     let spec = {
-        name: 'get-env',
-        aliases: ['get-env','get env','get environment'],
-        description: description,
-        schema: {
-            name: z.string()
+    name: 'get-env',
+    description: description,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' }
+            },
+            required: ['name']
         },
-       
-        handler: async (params) => {
+    handler: async (params) => {
             return await _getEnv(params);
         }
     }
     return spec;
 }
 export default getEnv;
+

package/src/toolSet/listJobdefs.js

@@ -1,96 +1,61 @@
-/*
- * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
- * SPDX-License-Identifier: Apache-2.0
- */
-import { z } from 'zod';
-import _listJobdefs from '../toolHelpers/_listJobdefs.js';
-function listJobdefs(_appContext) {
-
-  let description = `
-  ## list-jobdefs — enumerate SAS Viya job definitions assets(jobdefs)
-
-  LLM Invocation Guidance (When to use)
-  jobdef and jobdefs are used interchangeably here to refer to job definitions.
-  Use THIS tool when the user wants to browse or list many job definitions assets
-  - "list jobdefs"
-  - "show jobdefs"
-  - "list available jobdefs"
-  - "browse jobdefs"
-  - "next jobdefs" (after a previous page)
-  - "list 25 jobdefs" / "list jobdefs limit 25"
-  Do NOT use this tool for:
-  - Checking existence of ONE job (use find-job)
-  - Executing/running a job (use run-job)
-  - Running a job definition (use run-jobdef)
-  - Submitting SAS code (use run-sas-program)
-
-
-  Purpose
-  Page through jobdef assets deployed/registered in SAS Viya.
-
-  Parameters
-  - limit (number, default 10): Number of jobs to return.
-  - start (number, default 1): 1-based offset for paging.
-  - where (string, optional): Filter expression (future use / passthrough; empty string by default). If unsupported, it may be ignored gracefully.
-
-  Response Contract
-  - Returns an array of jobdef names or objects (backend-dependent) inside structuredContent.
-  - If items.length === limit, caller may request next page using start + limit.
-  - Provide optional hint start = start + limit when page might continue.
-
-  Pagination Examples
-  - First page: { start:1, limit:10 }
-  - Next page:  { start:11, limit:10 }
-
-  Disambiguation & Clarification
-  - Input only "list" → ask: "Specify asset to list? (Say 'Please specify what to listlist' to proceed)" unless prior context indicates job definition listing.
-  - Input contains "run"/"execute" plus job name → route to job/jobdef.
-
-  Negative Examples (should NOT call list-jobdefs)
-  - "list libraries" (use list-libraries)
-  - "list tables" (use list-tables)
-  - "list models" (use list-models)
-  - "list jobs" (use list-jobs)
-  - "find job abc" (findJob)
-  - "run job abc" (job)
-  - "job abc" (job)
-  - "find model xyz" (findModel)
-  - "list models" (listModels)
-  - "list tables in lib xyz" (listTables)
-  - "show me libraries" (listLibraries)
-  - "describe job abc" (findJob then possibly job for execution)
-
-  Error Handling
-  - On backend error: surface structured error payload (do not fabricate job names).
-  - Empty page (items.length === 0) with start > 1 may mean caller paged past end.
-
-  Usage Tips
-  - Increase limit for fewer round trips; keep reasonable to avoid large payloads.
-  - Combine with findJobdeffor confirmation before execution.
-
-  Examples (→ mapped params)
-  - "list jobdefs" → { start:1, limit:10 }
-  - "list 25 jobdefs" → { start:1, limit:25 }
-  - "next jobdefs" (after prior {start:1,limit:10}) → { start:11, limit:10 }
-  `;
-
-  let spec = {
-    name: 'list-jobdefs',
-    aliases: ['listJobdefs','list jobdefs','list_jobdefs'],
-    description: description,
-    schema: {
-      limit: z.number().default(10),
-      start: z.number().default(1),
-      where: z.string().default('')
-    },
-  // No 'server' required; backend context is implicit in helper
-  required: [],
-    handler: async (params) => {
-      // _listJobdefs handles all validation and defaults
-      const result = await _listJobdefs(params);
-      return result;
-    }
-  }
-  return spec;
-}
-export default listJobdefs;
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from 'zod';
+import _listJobdefs from '../toolHelpers/_listJobdefs.js';
+function listJobdefs(_appContext) {
+
+  let description = `
+list-jobdefs — enumerate SAS Viya job definitions (jobdefs) assets.
+
+USE when: list jobdefs, show jobdefs, browse jobdefs, list available jobdefs, next page
+DO NOT USE for: find single jobdef (use find-jobdef), execute jobdef (use run-jobdef), find job (use find-job), sas code (use run-sas-program)
+
+PARAMETERS
+- limit: number (default: 10) — number of jobdefs per page
+- start: number (default: 1) — 1-based page offset
+- where: string (default: '') — optional filter expression
+
+ROUTING RULES
+- list jobdefs → { start: 1, limit: 10 }
+- show me 25 jobdefs → { start: 1, limit: 25 }
+- next jobdefs → { start: previousStart + previousLimit, limit: previousLimit }
+
+EXAMPLES
+- list jobdefs → { start: 1, limit: 10 }
+- list 25 jobdefs → { start: 1, limit: 25 }
+- next jobdefs → { start: 11, limit: 10 }
+
+NEGATIVE EXAMPLES (do not route here)
+- find jobdef abc (use find-jobdef)
+- list jobs (use list-jobs)
+- run jobdef abc (use run-jobdef)
+- list models (use list-models)
+
+PAGINATION
+If returned length === limit, hint: next start = start + limit. Empty result with start > 1 means paged past end.
+
+ERRORS
+Surface backend error directly; never fabricate jobdef names.
+  `;
+
+  let spec = {
+    name: 'list-jobdefs',
+    description: description,
+    inputSchema: z.object({
+      limit: z.number().optional(),
+      start: z.number().optional(),
+      where: z.string().optional()
+    }),
+  // No 'server' required; backend context is implicit in helper
+    handler: async (params) => {
+      // _listJobdefs handles all validation and defaults
+      const result = await _listJobdefs(params);
+      return result;
+    }
+  }
+  return spec;
+}
+export default listJobdefs;
+