@sassoftware/sas-score-mcp-serverjs 0.0.2

package/src/createMcpServer.js

@@ -0,0 +1,76 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Creates and configures an MCP server instance.
+ * @param {Object} cache - The session cache to store the MCP server instance.
+ * @returns {Promise<McpServer>} The configured MCP server instance.  
+ * @example
+ * Notes: Handles both http and stdio transports scenarios
+ * 
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import makeTools from "./toolSet/makeTools.js";
+import getLogonPayload from "./toolHelpers/getLogonPayload.js";
+
+async function createMcpServer(cache, _appContext) {
+  
+  let mcpServer = new McpServer(
+    {
+      name: "sasmcp",
+      version: _appContext.version,
+    },
+    {
+      capabilities: {
+        tools: {
+          listChanged: true,
+        },
+      },
+    }
+  );
+  let toolSet = makeTools(_appContext);
+
+  //wrapping tool handler to pass _appContext
+  //can be ignored or used as needed.
+
+  const wrapf = (cache, builtin) => async (args) => {
+    let currentId = cache.get('currentId');
+    let _appContext = cache.get(currentId);
+    let params;
+    // get Viya token 
+    _appContext.contexts.logonPayload = await getLogonPayload(_appContext);
+    if (_appContext.contexts.logonPayload == null) {
+      return { isError: true, content: [{ type: 'text', text: 'Unable to get authentication token for SAS Viya. Please check your configuration.' }] }
+    }
+
+  // create enhanced appContext for tool
+  if (args == null) {
+    params = {_appContext: _appContext.contexts};
+  } else {
+    params = Object.assign({}, args, {_appContext: _appContext.contexts});
+  }
+  
+  // call the actual tool handler
+    let r = await builtin(params); 
+    return r;
+  }
+
+  // Register the tools with brand prefix
+  console.error(`[Note] Brand: ${_appContext.brand}`);
+  let toolNames = [];
+  toolSet.forEach((tool, i) => {
+    let toolName = _appContext.brand + '-' + tool.name;
+   // console.error(`\n[Note] Registering tool ${i + 1} : ${toolName}`);
+    let toolHandler = wrapf(cache, tool.handler);
+   
+    mcpServer.tool(toolName, tool.description, tool.schema, toolHandler);
+    toolNames.push(toolName);
+  });
+  console.error(`[Note] Registered ${toolSet.length} tools: ${toolNames}`);
+  cache.set("mcpServer", mcpServer);
+  return mcpServer;
+}
+
+export default createMcpServer;

package/src/db/scrModels.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+function scrModels(name) {
+
+    // This function returns the URL of the SCR model based on the name.
+    // In a real application the list of scr models would be fetched from a database or configuration file.
+    // For this example, we will use a hardcoded list of models.
+    let scrModels = {
+       "loan": "http://mcphllllll.hggmg3bshufda0et.eastus8080/mcp"
+    };
+
+    if (name.indexOf('http') === 0) {
+        return name;
+    }
+    if (scrModels[name]) {
+        return scrModels[name];
+    }
+    return null;
+}
+
+export default scrModels;

package/src/toolSet/devaScore.js

@@ -0,0 +1,69 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {z} from 'zod';
+
+function devaScore(_appContext) {
+
+    let description = `
+## deva-score — compute a numeric score based on two input values
+
+LLM Invocation Guidance (When to use)
+Use THIS tool when:
+- User wants to calculate the deva score: "Calculate deva score for 5 and 10"
+- User provides two numbers for scoring: "Score these values: 3 and 7"
+- User wants to compute a score in a series: "Calculate scores for [list of numbers]"
+
+Do NOT use this tool for:
+- Scoring models (use model-score)
+- Statistical calculations beyond deva scoring
+- Looking up data or metadata
+
+Purpose
+Compute a numeric deva score by applying the formula (a + b) * 42 to two input numbers. For scoring more than two numbers, call this tool multiple times using the previous result as the first input (left-to-right fold).
+
+Parameters
+- a (number, required): First numeric input value
+- b (number, required): Second numeric input value
+
+Response Contract
+Returns a numeric result: (a + b) * 42
+The result is always a number representing the computed deva score.
+
+Disambiguation & Clarification
+- If user provides more than two numbers without clear instructions: "Do you want to calculate the deva score by combining these numbers left-to-right?"
+- If user provides non-numeric input: "Please provide numeric values"
+
+Examples (→ mapped params)
+- "Calculate deva score for 5 and 10" → { a: 5, b: 10 } returns 630
+- "Score 1 and 2" → { a: 1, b: 2 } returns 126
+- For multiple numbers, chain calls: deva(1,2)→126, then deva(126,3)→5418
+
+Negative Examples (should NOT call deva-score)
+- "Score this customer with the credit model" (use model-score instead)
+- "Calculate the mean of these values" (use run-sas-program or sas-query instead)
+
+Related Tools
+- None directly related (this is a specialized scoring tool)
+
+Notes
+For sequences of numbers, use a left-to-right fold: call devaScore(first, second), then use that result as the first parameter for devaScore(result, third), and so on.
+`;
+    let spec = {
+        name: 'deva-score',
+        aliases: ['devaScore','deva score','deva_score'],
+        description: description,
+        schema: {
+            a: z.number(),
+            b: z.number()
+        },
+        handler: async ({ a, b,_appContext }) => {
+            console.error( a, b);
+            return { content: [{ type: 'text', 
+                text: String((a + b) * 42) }] }
+        }
+    }
+    return spec;
+}
+export default devaScore;

package/src/toolSet/findJob.js

@@ -0,0 +1,90 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from 'zod';
+import _listJobs from '../toolHelpers/_listJobs.js';
+function findJob(_appContext) {
+  let llmDescription= {
+  "purpose": "Map natural language requests to find a job in SAS Viya and return structured results.",
+  "param_mapping": {
+    "name": "required - single name. If missing, ask 'Which job name would you like to find?'.",
+
+  },
+  "response_schema": "{ jobs: Array<string|object> }",
+  "behavior": "Return only JSON matching response_schema when invoked by an LLM. If no matches, return { jobs: [] }"
+};
+  let description = `
+  ## find-job — locate a specific SAS Viya job
+
+  LLM Invocation Guidance
+  Use THIS tool when the user intent is to check if ONE job exists or retrieve its metadata:
+  - "find job cars_job_v4"
+  - "does job sales_summary exist"
+  - "is there a job named churnScorer"
+  - "lookup job forecast_monthly"
+  - "verify job ETL_Daily" 
+
+  Do NOT use this tool when the user asks for:
+  - A list or browse of many jobs (use listJobs)
+  - Do not use this tool if the user want to find lib, find table, find model and similar requests
+  - Executing a job (use job)
+  - Running a job definition (use jobdef)
+  - Submitting arbitrary code (use program)
+
+  Purpose
+  Quickly determine whether a named job asset is present in the Viya environment and return its entry (or an empty result if not found).
+
+  Parameters
+  - name (string, required): Exact job name (case preserved). If multiple tokens/names supplied, take the first and ignore the rest; optionally ask for a single name.
+
+  Behavior & Matching
+  - Attempt exact match first (backend determines sensitivity).
+  - Returns { jobs: [...] } where array length is 0 (not found) or 1+ (if backend returns multiple with the same display name).
+  - No fuzzy guesses—never fabricate a job.
+  - If no name provided: ask "Which job name would you like to find?".
+
+  Response Contract
+  - Always: { jobs: Array<string|object> }
+  - On error: propagate structured server error (do not wrap in prose when invoked programmatically).
+
+  Disambiguation Rules
+  - Input only "find job" → ask for missing name.
+  - Input contains verbs like "run" or "execute" → use run-job or run-jobdef instead.
+  - Input requesting many (e.g., "find all jobs") → use list-jobs.
+
+  Examples (→ mapped params)
+  - "find job cars_job_v4" → { name: "cars_job_v4" }
+  - "does job ETL exist" → { name: "ETL" }
+  - "is there a job named metricsRefresh" → { name: "metricsRefresh" }
+
+  Negative Examples (should NOT call find-job)
+  - "list jobs" (list-jobs)
+  - "run job cars_job_v4" (run-job)
+  - "execute jobdef cars_job_v4" (run-jobdef)
+
+  Clarifying Question Template
+  - Missing name: "Which job name would you like to find?"
+  - Multiple names: "Please provide just one job name (e.g. 'cars_job_v4')."
+
+  Notes
+  - For bulk existence checks loop over names and call find-job per name.
+  - Combine with run-job tool if user wants to execute after confirming existence.
+  `;
+
+  let spec = {
+    name: 'find-job',
+    aliases: ['findJob','find job','find_job'],
+    description: description,
+    schema: {
+      name: z.string()
+    },
+    required: ['name'],
+    handler: async (params) => {
+      let r = await _listJobs(params);
+      return r;
+    }
+  }
+  return spec;
+}
+export default findJob;

package/src/toolSet/findJobdef.js

@@ -0,0 +1,95 @@
+/*
+ * 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 findJobdef(_appContext) {
+  let llmDescription= {
+  "purpose": "Map natural language requests to find a jobdef (job definition) in SAS Viya and return structured results.",
+  "param_mapping": {
+    "name": "required - single name. If missing, ask 'Which jobdef name would you like to find?'.",
+
+  },
+  "response_schema": "{ jobs: Array<string|object> }",
+  "behavior": "Return only JSON matching response_schema when invoked by an LLM. If no matches, return { jobs: [] }"
+};
+  let description = `
+  ## find-jobdef — locate a specific SAS Viya job
+
+  LLM Invocation Guidance
+  Use THIS tool when the user intent is to check if ONE job exists or retrieve its metadata:
+  - "find jobdef cars_job_v4"
+  - "does jobdef sales_summary exist"
+  - "is there a jobdef named churnScorer"
+  - "lookup jobdef forecast_monthly"
+  - "verify jobdef ETL_Daily" 
+
+  Do NOT use this tool when the user asks for:
+  - find job  (use find-job)
+  - find table (use find-table
+  - find model (use find-model)
+  - find lib (use find-library)
+  - Executing a job (use job)
+  - Running a job definition (use jobdef)
+  - Submitting arbitrary code (use program)
+
+  Purpose
+  Quickly determine whether a named jobdef asset is present in the Viya environment and return its entry (or an empty result if not found).
+
+  Parameters
+  - name (string, required): Exact jobdef name (case preserved). If multiple tokens/names supplied, take the first and ignore the rest; optionally ask for a single name.
+
+  Behavior & Matching
+  - Attempt exact match first (backend determines sensitivity).
+  - Returns { jobdefs: [...] } where array length is 0 (not found) or 1+ (if backend returns multiple with the same display name).
+  - No fuzzy guesses—never fabricate a job.
+  - If no name provided: ask "Which jobdef name would you like to find?".
+
+  Response Contract
+  - Always: { jobdefs: Array<string|object> }
+  - On error: propagate structured server error (do not wrap in prose when invoked programmatically).
+
+  Disambiguation Rules
+  - Input only "find job" → ask for missing name.
+  - Input contains verbs like "run" or "execute" → use run-job or run-jobdef instead.
+  - Input requesting many (e.g., "find all jobs") → use list-jobs.
+
+  Examples (→ mapped params)
+  - "find jobdef cars_job_v4" → { name: "cars_job_v4" }
+  - "does jobdef ETL exist" → { name: "ETL" }
+  - "is there a jobdef named metricsRefresh" → { name: "metricsRefresh" }
+
+  Negative Examples (should NOT call find-jobdef)
+  - find lib (use find-library)
+  - find table (use find-table)
+  - find model (use find-model)
+  - "list job" (list-jobdefs)
+  - "run job cars_job_v4" (run-job)
+  - "execute jobdef cars_job_v4" (run-jobdef)
+
+  Clarifying Question Template
+  - Missing name: "Which jobdef name would you like to find?"
+  - Multiple names: "Please provide just one jobdef name (e.g. 'cars_job_v4')."
+
+  Notes
+  - For bulk existence checks loop over names and call find-jobdef per name.
+  - Combine with run-jobdef tool if user wants to execute after confirming existence.
+  `;
+
+  let spec = {
+    name: 'find-jobdef',
+    aliases: ['findJobdef','find jobdef','find_jobdef'],
+    description: description,
+    schema: {
+      name: z.string()
+    },
+    required: ['name'],
+    handler: async (params) => {
+      let r = await _listJobdefs(params);
+      return r;
+    }
+  }
+  return spec;
+}
+export default findJobdef;

package/src/toolSet/findLibrary.js

@@ -0,0 +1,100 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from 'zod';
+import _listLibrary from '../toolHelpers/_listLibrary.js';
+function findLibrary(_appContext) {
+  
+  let description = `
+  ## find-library — locate a specific CAS or SAS library
+
+  LLM Invocation Guidance
+  Use THIS tool when the user asks any of the following (intent = existence / lookup of ONE library):
+  - "find library Public"
+  - "find lib Public"
+  - "does library SASHELP exist"
+  - "is PUBLIC library available in cas"
+  - "lookup library sasuser in sas"
+  - "show me library metadata for Models"
+
+  Aliases for lib are: library, caslib, libref
+  
+  Do NOT use this tool when the user wants:
+  - find model -> use find-model
+  - find table -> use find-table
+  - find job -> use find-job
+  - find jobdef -> use find-jobdef
+  - Columns or schema of a table (use table-info)
+  - Creating/assigning libraries (use run-sas-program or another admin tool)
+
+  Purpose
+  Quickly verify whether a single named library exists on CAS or SAS and return its entry (or empty if not found).
+
+  Parameters
+  - name (string, required) : Exact library (caslib) name to locate. If multiple names provided (comma/space separated), use the first and ignore the rest; optionally ask for one name.
+  - server (cas|sas, default 'cas') : Target environment. If omitted or ambiguous default to 'cas'.
+
+  Behavior & Matching
+  - Performs an exact name match (case-insensitive where backend supports it).
+  - Returns an object: { libraries: [...] } where the array contains zero or one items (backend may still return richer metadata).
+  - If no match: { libraries: [] } (do NOT fabricate suggestions).
+  - If user supplies no name: ask a clarifying question: "Which library name would you like to find?".
+  - If user clearly wants a list ("list", "show all", "enumerate") route to listLibrary instead.
+
+  Response Contract
+  - Always: { libraries: Array<string|object> }
+  - Never include prose when invoked programmatically; only the JSON structure.
+
+  Disambiguation Rules
+  - Input only "find library" → ask for the missing name.
+  - Input with both library name and words like "tables" → prefer listTables.
+  - Input like "find libraries" (plural) → prefer listLibrary unless user clarifies to a single name.
+
+  Examples (→ mapped params)
+  - "find lib Public" → { name: "Public", server: "cas" }
+  - "find library sasuser in sas" → { name: "sasuser", server: "sas" }
+  - "does library Formats exist" → { name: "Formats", server: "cas" }
+  - "is SystemData library in cas" → { name: "SystemData", server: "cas" }
+
+  Negative Examples (should NOT call find-library)
+  - "list libs" (list-libraries)
+  -  Do not use this tool if the user want to find table, find job, find model, find job, find jobdef  and similar requests
+  - "show tables in Public" (list-tables)
+  - "describe table cars in sashelp" (table-info)
+
+  Clarifying Question Template
+  - Missing name: "Which library name would you like to find?"
+  - Multiple names: "Please provide just one library name to look up (e.g. 'Public')."
+
+  Notes
+  - For bulk validation of many names, call this tool repeatedly per name.
+  - For pagination or discovery, switch to list-libraries.
+  `;
+
+  let spec = {
+    name: 'find-library',
+    aliases: ['findLibrary','find library','find_library'],
+    description: description,
+    schema: {
+      name: z.string(),
+      server: z.string().default('cas')
+    },
+    required: ['name'],
+    handler: async (params) => {
+      // normalize server to lowercase & default
+      if (!params.server) params.server = 'cas';
+      params.server = params.server.toLowerCase();
+
+      // If multiple names passed (comma or space separated), take the first token (defensive)
+      if (params.name && /[,\s]+/.test(params.name.trim())) {
+        params.name = params.name.split(/[,\s]+/).filter(Boolean)[0];
+      }
+
+      let r = await _listLibrary(params);
+      return r;
+    }
+  }
+  return spec;
+}
+export default findLibrary;

package/src/toolSet/findModel.js

@@ -0,0 +1,83 @@
+/*
+ * Copyright © 2025, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { z } from 'zod';
+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.
+  `;
+
+  let spec = {
+    name: 'find-model',
+    aliases: ['findModel','find model','find_model'],
+    description: description,
+    schema: {
+      'name': z.string()
+    },
+    required: ['name'],
+    handler: async (params) => { 
+      let r = await _listModels(params);
+      return r;
+    }
+  }
+  return spec;
+}
+
+export default findModel;

package/src/toolSet/findTable.js

@@ -0,0 +1,94 @@
+/*
+ * 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 findTable(_appContext) {
+  let description = `
+## 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"
+
+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)
+
+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.
+
+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" }
+- "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)
+
+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
+`;
+  
+  let spec = {
+    name: 'find-table',
+    aliases: ['findTable','find table','find_table'],
+    description: description,
+    schema: {
+      server: z.string().default('cas'), // default server is 'cas',
+      name: z.string(),
+      lib: z.string()
+    },
+    required: ['name', 'lib'],
+    handler: async (params) => {
+      // Check if the params.scenario is a string and parse it
+      let r = await _listTables(params);
+      return r;
+    }
+  }
+  return spec;
+}
+
+export default findTable;