@sassoftware/sas-score-mcp-serverjs 1.0.1-3 → 1.0.1-31

package/.skills/skills/read-strategy/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: read-strategy
+description: >
+  Strategy for reading data from CAS or SAS tables. Determines which read tool to use (raw reads vs analytical queries).
+---
+
+# Read Table Strategy
+
+Use this strategy when the user requests to read, fetch, or query data from a table.
+
+## Prerequisites
+
+Before reading:
+1. Verify the table exists using find-resource strategy
+2. Determine the server (CAS or SAS) from the find-resource verification step. If the server cannot be determined, ask the user to specify. Do not proceed with a default server unless explicitly instructed by the user.
+
+---
+
+## Two Types of Read Operations
+
+### Type 1: Raw Row Read
+
+**Trigger phrases**: "read rows from", "show first N records", "fetch records where", "get data from table"
+
+**Tool**: `sas-score-read-table`
+
+**When to use**:
+- User wants raw records, not aggregations
+- User wants to filter by WHERE clause
+- User wants to browse data
+
+**Parameters**:
+```
+lib: "<library>"           # from find-resource verification
+table: "<table>"           # from find-resource verification
+server: "cas" or "sas"     # from find-resource verification
+start: <row number>        # default 1
+limit: <max rows>          # default 10, max 1000
+where: "<SQL WHERE clause>"  # optional filter
+format: true               # default: use formatted values
+```
+
+**Example**:
+```
+sas-score-read-table({
+  lib: "Public",
+  table: "customers",
+  server: "cas",
+  limit: 25,
+  where: "status='active'"
+})
+```
+
+---
+
+### Type 2: Analytical Query
+
+**Trigger phrases**: "how many", "count by", "average", "total", "sum", "group by", "aggregate", "distinct", "join"
+
+**Tool**: `sas-score-sas-query`
+
+**When to use**:
+- User wants aggregations (SUM, AVG, COUNT, etc.)
+- User wants GROUP BY or distinct counts
+- User wants JOIN across tables
+- User wants statistical summaries
+
+**Parameters**:
+```
+table: "lib.table"         # CAS: "Public.customers", SAS: "SASHELP.cars"
+query: "<natural language question>"
+sql: "<SELECT SQL>"        # optional: pre-generated SQL
+```
+
+**Example**:
+```
+sas-score-sas-query({
+  table: "Public.customers",
+  query: "count of customers by region and status",
+  sql: "SELECT region, status, COUNT(*) as count FROM Public.customers GROUP BY region, status"
+})
+```
+
+---
+
+
+## Decision Tree
+
+```
+User requests data from table
+  ↓
+Is it an aggregation? (count, sum, avg, group by, distinct, etc.)
+  ├─ YES → Use sas-score-sas-query
+  └─ NO → Use sas-score-read-table
+
+If the user's intent is ambiguous or mixes aggregation and raw reads, ask the user to clarify whether they want raw records or aggregated results before proceeding.
+```
+
+---
+
+## Table Name Format
+
+- **CAS tables**: `Caslib.table` or `Public.customers` (lowercase caslib, mixed case table)
+- **SAS tables**: `LIBREF.table` or `SASHELP.cars` (uppercase libref, case-insensitive table)
+
+---
+
+## Error Handling
+
+| Error | Action |
+|---|---|
+| Table not found | Verify table exists with find-resource first |
+| Server mismatch | Use server from find-resource verification |
+| Empty result | Ask user to adjust WHERE clause or criteria |
+| Column not found | Ask user to verify column name (case sensitivity) |
+
+---
+
+## Examples
+
+### Example 1: Browse customer records
+**Request**: "read first 20 customers from Public"
+1. Find table customers in Public → CAS
+2. Read: `sas-score-read-table({ lib: "Public", table: "customers", server: "cas", limit: 20 })`
+3. Return 20 rows
+
+### Example 2: Find active customers in a region
+**Request**: "fetch customers from Public where status='active' and region='East'"
+1. Find table customers in Public → CAS
+2. Read: `sas-score-read-table({ lib: "Public", table: "customers", server: "cas", where: "status='active' and region='East'" })`
+3. Return matching rows
+
+### Example 3: Aggregate customers by region
+**Request**: "how many customers by region in Public.customers"
+1. Find table customers in Public → CAS
+2. Query: `sas-score-sas-query({ table: "Public.customers", query: "count of customers by region", sql: "SELECT region, COUNT(*) FROM Public.customers GROUP BY region" })`
+3. Return aggregated result

package/.skills/skills/request-routing/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: request-routing
+description: >
+  Universal routing strategy for all SAS Viya requests. Every request follows the same three-step workflow.
+---
+
+# Universal Request Routing Strategy
+
+All SAS Viya requests follow this three-step workflow:
+
+## Step 1: Verify Resources Exist
+
+Before executing any action, verify that the target resources exist.
+
+| Resource Type | Find Tool | Notes |
+|---|---|---|
+| Library | `sas-score-find-library` | For tables, if server is not specified (cas or sas), determine server here. Other resource types do not require server specification. |
+| Table | `sas-score-find-table` | Requires library name and server. |
+| MAS Model | `sas-score-find-model` | No server selection. |
+| Job | `sas-score-find-job` | No server selection. |
+| JobDef | `sas-score-find-jobdef` | No server selection. |
+| SCR Model | Skip verification | SCR models do not require pre-verification. |
+
+**Rule**: Always verify before executing. Exception: SCR models can be scored directly.
+
+---
+
+## Step 2: Execute the Request
+
+Once resources are verified to exist, select the appropriate execution tool:
+
+| Request Type | Tool | Input |
+|---|---|---|
+| Read table rows | `sas-score-read-table` | lib, table, server (from Step 1) |
+| Query table (aggregation) | `sas-score-sas-query` | lib.table, SQL query |
+| Score with MAS model | `sas-score-mas-score` | model name, scenario data |
+| Run Job | `sas-score-run-jobdef` | job name, scenario parameters |
+| Run JobDef | `sas-score-run-jobdef` | jobdef name, scenario parameters |
+| Score with SCR model | `sas-score-scr-score` | SCR URL, scenario data |
+| Describe MAS model | `sas-score-model-info` | model name |
+| Describe Job/JobDef | `sas-score-job-info` | job or jobdef name |
+| Describe SCR model | `sas-score-scr-info` | SCR URL |
+| Describe table | `sas-score-table-info` | lib, table, server |
+
+---
+
+## Step 3: Merge Results
+
+Combine verification and execution results:
+
+- For **read/query**: Return rows as-is.
+- For **scoring**: Merge predictions with input scenario data.
+- For **jobs/jobdefs**: Return execution results (tables, logs).
+
+---
+
+
+## Special Case: Read + Score (Combined Workflow)
+
+When the user requests scoring records from a table, follow these sub-workflows in order:
+
+1. **Verify**
+  - Find the table (determine server as described above)
+  - Find the model
+2. **Read**
+  - Fetch rows from the table using `sas-score-read-table` or `sas-score-sas-query`
+3. **Map**
+  - Check if table columns match model input variables
+  - If not, ask user for mapping
+4. **Score**
+  - Score each row using `sas-score-mas-score` (for MAS) or `sas-score-scr-score` (for SCR)
+5. **Merge**
+  - Combine predictions with original rows
+
+---
+
+## Error Handling
+
+| Error | Action |
+|---|---|
+| Resource not found | Ask user to verify name and server (for tables). |
+| Column/input mismatch | Ask user to map table columns to model inputs. |
+| Empty result | Ask whether to adjust filter/criteria. |
+
+---
+
+## Examples
+
+### Example 1: Read a table
+**Request**: "read customers in Public"
+1. Find library Public → Verified (CAS)
+2. Read table customers in Public (CAS)
+3. Return rows
+
+### Example 2: Score with inline scenario
+**Request**: "score a=1, b=2 with model simplejob.job"
+1. Find job simplejob → Verified
+2. Run simplejob with scenario {a: 1, b: 2}
+3. Return result
+
+### Example 3: Score records from table
+**Request**: "score records from Public.customers with model risk_model.mas"
+1. Find table customers in Public → Verified (CAS)
+2. Find model risk_model → Verified (MAS)
+3. Read rows from Public.customers
+4. Score each row with risk_model
+5. Return merged predictions + original data

package/.skills/skills/score-strategy/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: score-strategy
+description: >
+  Unified scoring workflow. Handles MAS, Job, JobDef, SCR, and combined read+score scenarios.
+  Always verify resources before scoring.
+
+  To reduce cognitive load, follow the stepwise flowchart below for scoring requests.
+---
+
+# Score Strategy
+
+Use this strategy when the user requests model scoring, predictions, or running jobs/jobdefs.
+
+## Prerequisites
+
+1. Verify the model/job exists using find-resources skill
+2. If scoring table rows: Verify the table exists and determine server using find-resources skill
+3. If scoring with inline scenario: Parse the scenario data
+
+---
+
+
+## Step 1: Parse the Score Request
+
+Identify the scoring target (model type) and input source:
+
+### Identify Model Type
+
+```
+score with model X.mas       → MAS model
+score with model X.job       → Job
+score with model X.jobdef    → JobDef
+score with model X.scr       → SCR model
+score with model X (default to MAS if type is not specified) → MAS model
+```
+
+### Visual Flowchart
+
+```mermaid
+flowchart TD
+  A[User score request] --> B{Model type specified?}
+  B -- .mas --> C[MAS model]
+  B -- .job --> D[Job]
+  B -- .jobdef --> E[JobDef]
+  B -- .scr --> F[SCR model]
+  B -- none --> C
+  C --> G[Verify MAS model]
+  D --> H[Verify Job]
+  E --> I[Verify JobDef]
+  F --> J[Skip verification]
+```
+
+### Identify Input Source
+
+```
+score a=1, b=2               → Inline scenario
+score with scenario {...}    → Inline scenario
+score records from table X   → Table rows
+score results of query...    → Query results
+```
+
+---
+
+## Step 2: Execute Scoring
+
+### Option A: Score with Inline Scenario
+
+**Trigger phrases**: "score a=1, b=2", "predict with values", "score scenario"
+
+**Tools**:
+- MAS: `sas-score-mas-score`
+- Job: `sas-score-run-job`
+- JobDef: `sas-score-run-jobdef`
+- SCR: `sas-score-scr-score`
+
+**Flow**:
+1. Find model (find-resources)
+2. Score with inline data
+3. Return prediction + input data merged
+
+**Parameters** (MAS):
+
+```
+sas-score-mas-score({
+  model: "<model name>",
+  scenario: { a: 1, b: 2 }
+})
+```
+
+**Parameters** (job):
+```
+sas-score-run-job({
+  name: "<job name>",
+  scenario: { a: 1, b: 2 }
+})
+```
+
+**Parameters** (jobdef):
+```
+sas-score-run-jobdef({
+  name: "<jobdef name>",
+  scenario: { a: 1, b: 2 }
+})
+```
+
+**Parameters** (SCR):
+```
+sas-score-scr-score({
+  url: "<scr endpoint>",
+  scenario: { a: 1, b: 2 }
+})
+```
+
+---
+
+### Option B: Score Table Rows (Read + Score)
+
+**Trigger phrases**: "score records from", "run model on table", "predict for customers in", "score rows from"
+
+**Flow**:
+1. Find model (find-resources)
+2. Find table (find-resources) → get server
+3. Read rows from table (read-strategy)
+4. Score each row (or batch score)
+5. Merge predictions with original rows
+
+**Decision**: Read strategy first
+- If user requests aggregation: Use `sas-score-sas-query`
+- If user requests raw rows: Use `sas-score-read-table`
+
+**Example workflow**:
+```
+Request: "score records from Public.customers with model risk_model"
+
+1. Find table customers in Public → CAS
+2. Find model risk_model → MAS
+3. Read rows: sas-score-read-table({ lib: "Public", table: "customers", server: "cas", limit: 1000 })
+4. Score each row: for each row, sas-score-mas-score({ model: "risk_model", scenario: {row} })
+5. Merge: combine risk score with customer data
+```
+
+---
+
+## Step 3: Result Formatting
+
+### MAS Scoring Result
+
+Return merged object:
+```
+Input data + Prediction fields
+Example: { a: 1, b: 2, prediction: 0.85, probability_0: 0.15, probability_1: 0.85 }
+```
+
+### Job/JobDef Result
+
+Return execution output:
+```
+Tables, logs, listings as returned by job
+```
+
+### SCR Result
+
+Return merged object:
+```
+Input data + Prediction fields from SCR response
+```
+
+### Batch Scoring (Table Rows)
+
+Return rows with predictions appended:
+```
+[
+  { customer_id: 1, name: "Alice", ..., risk_score: 0.32 },
+  { customer_id: 2, name: "Bob", ..., risk_score: 0.78 },
+  ...
+]
+```
+
+---
+
+## Column/Variable Mapping
+
+If table columns don't match model input variable names:
+
+1. Ask user: "Which table column maps to model input X?"
+2. Wait for mapping: e.g., { customer_age: age, customer_income: income }
+3. Transform row data using mapping
+4. Score transformed data
+5. Return with original column names
+
+---
+
+## Error Handling
+
+| Error | Action |
+|---|---|
+| Model not found | Verify model name with user |
+| Table not found | Verify table name and library |
+| Scenario mismatch | Ask user to verify input variable names |
+| Empty table | Ask whether to adjust filter or continue |
+| Scoring failure | Return error message from scoring tool |
+
+---
+
+## Examples
+
+### Example 1: Score with inline scenario
+**Request**: "score a=1, b=2 with model simplejob.job"
+1. Find job simplejob using find-resources strategy
+2. Run: `sas-score-run-jobdef({ name: "simplejob", scenario: { a: 1, b: 2 } })`
+3. Return: `{ c: 3 }`
+
+### Example 2: Score with MAS model
+**Request**: "predict churn for age=45, income=60000 with model churn_predictor"
+1. Find model churn_predictor.mas using find-resources strategy
+2. Score: `sas-score-mas-score({ model: "churn_predictor", scenario: { age: 45, income: 60000 } })`
+3. Return: `{ age: 45, income: 60000, churn_probability: 0.23, prediction: "no_churn" }`
+
+### Example 3: Score table rows
+**Request**: "score all active customers with model risk_model and table Public.customers"
+1. Find model risk_model.mad using find-resources strategy
+2. Find table Public.customers using find-resources strategy
+3. Read: `sas-score-read-table({ lib: "Public", table: "customers", server: "cas", where: "status='active'" })`
+4. Score each row with risk_model
+5. Return: customers with risk_score appended
+
+### Example 4: Score with SCR model
+**Request**: "score age=50, income=75000 with model loan.scr"
+1. Prepare: SCR URL for "loan"
+2. Score: `sas-score-scr-score({ url: "loan", scenario: { age: 50, income: 75000 } })`
+3. Return predictions from SCR endpoint

package/README.md

@@ -1,5 +1,6 @@
 # sas-score-mcp-serverjs
-A Model Context Protocol (MCP) Server for Scoring with SAS Viya
+A Model Context Protocol (MCP) Server for Scoring with SAS Viya. 
+See [wiki](https://github.com/sassoftware/sas-score-mcp-serverjs/wiki) for the capabilities of the server.
 
 ## Major changes in release 1.0.0
 
@@ -8,6 +9,8 @@ A Model Context Protocol (MCP) Server for Scoring with SAS Viya
 
 - Agent - can be deployed as an agent
 
+- Docker image:  ghcr.io/sassoftware/sas-score-mcp-serverjs
+
 
 ## Overview
 This MCP server is designed for scoring with SAS Viya.
@@ -22,6 +25,33 @@ Some examples are:
   - job Definitions
   - jobs using SAS Studio or other interfaces
 
+## Start the mcp server
+
+If using stdio transport, most of the mcp clients will start the server automatically.
+But for http transport, the mcp server must be started. 
+
+If running locally
+```sh
+npx @sassoftware/sas-score-mcp-serverjs@latest
+```
+
+The mcp is also available as a docker image. Add or remove the env variables as needed.
+
+```sh
+docker run -p 8080:8080 --name sasscore -e VIYA_SERVER=<yourviyaserver> -e AUTHFLOW=oauth ghcr.io/sassoftware/sas-score-mcp-serverjs:latest
+```
+
+## Capabilities
+
+The tools can be grouped into these categories
+
+- Scoring with MAS models, job, jobdef and scr
+- Viewing and querying tables
+
+Supporting tools can be grouped into these categories
+- Listing of  MAS models, job, jobdef , tables
+- Describing MAS models, job, jobdef, scr and tables
+
 ## Target Audience
 This MCP server was developed for two types of SAS users.
 
@@ -44,88 +74,102 @@ Typically these are set either in the .env file or as environment variables or a
 
 ### Required Options
 
-VIYA_SERVER=<url for Viya server>
-MCPTYPE=http|stdio
-MCPHOST=<url for the mcp server = http://localhost:8080 or some remote mcp server>
+1. VIYA_SERVER=
+   <url for Viya server>. 
 
->Recommended authflow is oauth - the most secure of all the options since all oauth flow occurs in the server and the actual token is never sent to the client. Bearer authflow is useful when the mcp server is remote with its own authentication process
+### Options with defaults
 
-AUTHFLOW=oauth|oauthclient|bearer|sascli|token|password
+These can be customized
 
-> Options for oauth. The clientid must have a redirect of http://localhost:8080/callback,https://localhost:8080/callback
+1. AUTHFLOW=**oauth**|oauthclient|bearer|sascli|token|password 
+    - Authentication method. Default is oauth
 
-CLIENTID=<pkce clientid>
+2. CLIENTID=**vscodemcp** 
+     - Clientid for oauth and oauthclient AUTHFlOW. Must be PKCE clientid. 
+     
 
+3. MCPTYPE=**http**|stdio  
+    - The transport protocol for the mcp server. 
 
-> OauthClient Flow. Clientid with redirect appropriate for the client. Some examples are shown below. Note that the explicit port used by github copilot is not guaranteed. 
+4. MCPHOST=**http://localhost:8080**
+   - URL of the mcp server. If using remote mcp server, set this to remote MCP server
 
-- github copilot: http://127.0.0.1:33418/
-- claude: https://claude.ai/api/mcp/auth_callback,https://claude.ai/api/auth/callback
+5. PROFILE=**~/.sas**
+    - profile name used by sas-cli to store the tokens 
 
-> bearer - Use this when the remote mcp server sends the token in the header.
+6. PORT=**8080**
+    - set it to what fits your environment. 
 
+7. CASSERVER=**cas-shared-default** 
+    - Set to a valid cas server
 
-> sascli - Use sas-viya cli to create the token information. It is stored in ~/.sas folder by default
+8. COMPUTECONTEXT=**"SAS Job Execution compute context"**
+    - Use one that is appropriate
 
-```env
-PROFILE=<profile name used by sas-cli to store the tokens in ~/.sas> 
-```
+### Clientid specifications
 
-### Other options
+If using remote mcp server, change the url in redirect to the remote url
 
-```env
-PORT=<default is 8080>
-HTTPS=FALSE
-CASSERVER=CAS server name (default: cas-shared-default)
-COMPUTECONTEXT=Compute session name or context (default: SAS Job Execution compute context) 
+```js
+{
+  client_id: 'vscodemcp',
+  scope: [ 'openid' ],
+  resource_ids: [ 'none' ],
+  autoapprove: true,
+  authorized_grant_types: [ 'authorization_code' ],
+  access_token_validity: 86400,
+  allowpublic: true,
+  redirect_uri: [ 'http://localhost:8080/callback' ]
+}
 ```
 
-## Agent
+> OauthClient Flow. Clientid with redirect appropriate for the client. Some examples are shown below. Note that the explicit port used by github copilot is not guaranteed. 
+
+- github copilot: http://127.0.0.1:33418/
+- claude: https://claude.ai/api/mcp/auth_callback,https://claude.ai/api/auth/callback
 
-> The mcp server can be deployed as an agent in github copilot
-> The configuration files for claude can be installed locally. You have to move the files to the appriopiate place.
 
-Specify the following configuration values to enable agent mode
+## Agent and skills
 
-```env
-AGENT=TRUE
-MCPCLIENT=github|claude
-```
+> The mcp server can be deployed as an agent in github copilot
+> The configuration files for claude can be installed locally. You have to move the files to the appriopiate place.
 
-By default the agent information is installed in the user's home directory as .github or .claude} To install it where the mcp server is running do the following:
+To download the skills to your environment issue this command:
 
-```env
-MCPCLIENT=.github|.claude
+```sh
+npx @sassoftware/sas-score-mcp-serverjs --skills github|claude
 ```
+The skills and related files will be written to .github or .claude 
 
 
 ## Configure the mcp client for localhost
 
-The mcp configuration is show below
+The mcp configuration for oauth flow. For remote mcp, change the url to the
+remote url
 
 ```json
  "sasmcp": {
     "type": "http",
-    "url": "http://localhost:8080/mcp"``
+    "url": "http://localhost:8080/mcp"
     "oauth: {
-      "type": "oauth2"
+      "type": "oauth2",
+      "clientId: "vscodemcp"
     }
  }
 ```
 
-For remote mcp servers:
+For bearer authflow. 
 ```json
  "sasmcp": {
     "type": "http",
-    "url": "your remote mcp server`,
-    "oauth": {
-      "type": 'oauth2
-    }
+    "url": "http://localhost:8080/mcp`,
+    "headers" {
+      "Authorization": "bearer <tokenstring>"
+      }
  }
 ```
 
-For transport protocol stdio. For claude drop the type
-
+For stdio scenario
 ```json
 "sas-mcp-server": {
       "type: "stdio"
@@ -141,17 +185,7 @@ For transport protocol stdio. For claude drop the type
     }
 ```
 
-#### Step 2: Start the mcp server
 
-If using stdio transport, most of the mcp clients will start the server automatically.
-But this step is necessary of using http transport.
-
-
-```sh
-npx @sassoftware/sas-score-mcp-serverjs@latest
-```
-
-Make sure that the .env file is in the current working directory or specify the options in the command line
 
 
 ## Notes
@@ -196,7 +230,15 @@ NODE_EXTRA_CA_CERTS=c:\Users\<your_username>\AppData\Local\mkcert\rootCA.pem
 ```
 
 ## License
-This project is licensed under the [Apache 2.0 license](LICENSE).
+This project is licensed under the Apache License 2.0. See [LICENSE](LICENSE).
+
+The container image published from this repository also includes third-party software, each component under its own license:
+
+- The npm dependencies that ship with this project, along with their respective licenses, are listed in [LICENSES.json](LICENSES.json).
+- The container is built from the 25-alpine base image; license texts for its included software ship inside the image itself. License information for each Alpine package is available at [pkgs.alpinelinux.org](https://pkgs.alpinelinux.org/packages).
+
+As with any container image, direct and indirect dependencies are governed by their own licenses.
+Users of the published container image are responsible for ensuring that their use complies with all applicable licenses.
 
 ## Additional Resources