@sassoftware/sas-score-mcp-serverjs 0.4.1-20 → 0.4.1-21

package/.claude/sas-score-workflow/SKILL.md

@@ -1,314 +0,0 @@
-gi ---
-name: sas-score-workflow
-description: >
-  Guide the full model scoring workflow: validate model familiarity, route to appropriate scoring tool 
-  based on model type, invoke scoring with scenario data, and present merged results. Use this skill 
-  when the user wants to run predictions on data (already fetched or user-supplied). Supports generic 
-  syntax: "score with model <name>.<type> scenario =<params>" where type is job|jobdef|mas|scr|sas.
-  Trigger phrases: "score these records", "predict using model", "run model on", "score with model X.mas".
----
-
-# SAS Score Workflow
-
-Orchestrates model validation, type-based routing, scoring invocation, and result presentation. 
-Handles both MAS models and alternative scoring engines (jobs, jobdefs, SCR, SAS programs).
-
----
-
-## Generic Scoring Syntax
-
-Users can invoke scoring with a unified syntax that automatically routes to the correct tool:
-
-```
-score with model <name>.<type> [scenario =<key=value pairs>]
-score <name>.<type> [scenario =<key=value pairs>]
-```
-
-**Type determines the routing:**
-- `.job` → route to `sas-score-run-job` with scoring parameters
-- `.jobdef` → route to `sas-score-run-jobdef` with scoring parameters
-- `.mas` → route to `sas-score-model-score` (Model Analytical Service — default)
-- `.scr` → route to `sas-score-scr-score` (SAS Container Runtime)
-- `.sas` → route to `sas-score-run-sas-program` to run sas program in folder
-
-If no type is specified (bare model name), assume `.mas` (MAS model).
-
----
-
-## Type-Based Routing
-
-### Parse and Strip Model Type
-
-When a user provides a model name with a type suffix (e.g., `simplejon.job`, `churn.mas`):
-
-1. **Extract the type:** Split on the last dot to identify the type suffix
-   - `simplejon.job` → type = `job`, base name = `simplejon`
-   - `churn.mas` → type = `mas`, base name = `churn`
-   - `fraud_detector.jobdef` → type = `jobdef`, base name = `fraud_detector`
-
-2. **Validate the type:** Confirm it matches one of the supported types: `job`, `jobdef`, `mas`, `scr`, `sas`
-   - If type is unrecognized, assume `.mas` (default MAS model) and treat the entire input as the model name
-
-3. **Strip the type suffix:** Remove the `.type` from the model name before passing to the routing tool
-   - **Critical:** Always pass the base name (without the dot and type) to the invoked tool
-   - `simplejon.job` → pass `simplejon` to `sas-score-run-job`
-   - `churn.mas` → pass `churn` to `sas-score-model-score`
-   - `fraud_detector.jobdef` → pass `fraud_detector` to `sas-score-run-jobdef`
-
-### Type: `.mas` (Model Aggregation Service)
-- **Tool**: `sas-score-model-score`
-- **Use for**: Standard MAS-deployed predictive models
-- **Example**: `score with model churn.mas scenario =age=45,income=60000`
-- **Invocation**: `sas-score-model-score({ model: "churn", scenario: {...} })`
-
-### Type: `.job` (SAS Viya Job)
-- **Tool**: `sas-score-run-job`
-- **Use for**: Pre-built scoring jobs with parameters
-- **Example**: `score with model monthly_scorer.job scenario =month=10,year=2025`
-- **Invocation**: `sas-score-run-job({ name: "monthly_scorer", scenario: {...} })`
-
-### Type: `.jobdef` (SAS Viya Job Definition)
-- **Tool**: `sas-score-run-jobdef`
-- **Use for**: Job definitions that perform scoring logic
-- **Example**: `score with model fraud_detector.jobdef using amount=500,merchant=online`
-- **Invocation**: `sas-score-run-jobdef({ name: "fraud_detector", scenario: {...} })`
-
-### Type: `.scr` (Score Code Runtime)
-- **Tool**: `sas-score-scr-score`
-- **Use for**: Models deployed in SCR containers (REST endpoints)
-- **Example**: `score https://scr-host/models/loan.scr using age=45,credit=700`
-- **Invocation**: `sas-score-scr-score({ url: "https://scr-host/models/loan", scenario: {...} })`
-
-### Type: `.sas` (SAS Program / SQL)
-- **Tool**: `sas-score-run-sas-program`
-- **Use for**: Custom SAS or SQL scoring code
-- **Example**: `score my_scoring_code.sas using x=1,y=2`
-- **Invocation**: `sas-score-run-sas-program({ folder: "my_scoring_code", scenario: {...} })`
-
-
-
----
-
-## Scenario Parsing
-
-The scenario parameter (comma-separated key=value pairs) is parsed into an object:
-
-```
-scenario =age=45,income=60000,region=South
-  ↓ parsed as:
-{ age: "45", income: "60000", region: "South" }
-```
-
-Accepted formats:
-- **String**: `age=45,income=60000`
-- **Object**: `{ age: 45, income: 60000 }`
-- **Array** (batch): `[ {age:45, income:60000}, {age:50, income:75000} ]`
-
----
-
-## Integration with other skills
-
-- **Before scoring table data**: Use `sas-find-library-smart` to verify the library, then `sas-read-strategy` to fetch records
-- **For read + score workflows**: Use `sas-read-and-score` for the complete end-to-end pattern
-
----
-
-## Step 1 — Check model familiarity before scoring
-
-Score immediately if:
-- The user names a specific model they've used before in this session, OR
-- The model name matches a previously confirmed model in the conversation
-
-Pause and suggest investigation if:
-- The model name is new, vague, or misspelled-looking (e.g. "the churn one", "that cancer model")
-- The user seems unsure of the required input variable names
-
-**Suggested message:**
-> "I don't recognize that model — want me to run `find-model` to confirm it exists,
-> or `model-info` to check its required inputs first?"
-
----
-
-## Step 2 — Prepare the scenario data
-
-**For a single record** (one object):
-```javascript
-scenario = { field1: value1, field2: value2, ... }
-```
-
-**For batch scoring** (multiple records — the typical case):
-```javascript
-scenario = [
-  { field1: val1, field2: val2, ... },
-  { field1: val3, field2: val4, ... },
-  ...
-]
-```
-
-**Critical rules:**
-- Loop or call sas-score-model-score **once per row**.
-- Field names in the scenario must match the model's expected input variable names **exactly**.
-  - If table column names differ from model input names, **flag this to the user** and ask for confirmation before scoring.
-  - Example: Table has `age_years`, but model expects `age` → ask user which column maps to which input.
-- Do not add units, labels, or extra metadata — raw field values only.
-
----
-
-## Step 3 — Invoke the appropriate scoring tool
-
-Based on the type extracted from the model name, invoke the corresponding tool:
-
-**For `.mas` (default):**
-```javascript
-sas-score-model-score({
-  model: "<modelname>",
-  scenario: scenario,  // object or array
-  uflag: false         // set true if you need field names prefixed with _
-})
-```
-
-**For `.job`:**
-```javascript
-sas-score-run-job({
-  name: "<jobname>",
-  scenario: scenario
-})
-```
-
-**For `.jobdef`:**
-```javascript
-sas-score-run-jobdef({
-  name: "<jobdefname>",
-  scenario: scenario
-})
-```
-
-**For `.scr`:**
-```javascript
-sas-score-scr-score({
-  url: "<scr_endpoint_url>",
-  scenario: scenario
-})
-```
-
-**For `.sas`:**
-```javascript
-sas-score-run-sas-program({
-  src: "<sas_or_sql_code>",
-  scenario: scenario
-})
-```
-
-**Rules:**
-- Pass the full batch in one call; do not loop over rows
-- If scoring fails, return the structured error and suggest troubleshooting
-- For MAS models, include uflag parameter if underscore-prefixed output is needed
-- For jobs/jobdefs, scenario becomes parameter arguments
-- For SCR, include full URL endpoint
-
----
-
-## Step 4 — Present the results
-
-Merge the scoring output back with the input records and present as a table where possible.
-
-**Always surface:**
-- The key prediction/score field(s) (e.g. `P_churn`, `score`, `prediction`, `P_risk`)
-- Any probability/confidence fields for classification models (e.g. `P_class0`, `P_class1`)
-- Selected input fields that drove the prediction, so the user can see context
-
-**Formatting:**
-- Present results in a table for clarity
-- If results exceed 10 rows, show the first 10 and ask: *"Want to see more results or export the full set?"*
-- Round numeric predictions to 2–4 decimal places for readability
-
----
-
-## Common flows
-
-**Flow A — Score rows with MAS model**
-> "Score the first 10 customers in Public.customers with the churn model"
-
-1. `sas-score-read-table` → { table: "Public.customers", limit: 10 }
-2. `sas-score-model-score` → { model: "churn", scenario: [ ...10 row objects ] }
-3. Present merged results with prediction + key inputs
-
-**Flow B — Score with a scoring job**
-> "Score December sales with the monthly_scorer job using month=12,year=2025"
-
-1. `sas-score-run-job` → { name: "monthly_scorer", scenario: { month: "12", year: "2025" } }
-2. Capture job output and tables
-3. Present results
-
-**Flow C — Score with a job definition**
-> "Run fraud detection jobdef on transaction amount=500, merchant=online"
-
-1. `sas-score-run-jobdef` → { name: "fraud_detection", scenario: { amount: "500", merchant: "online" } }
-2. Capture log, listings, and tables
-3. Present results
-
-**Flow D — Score with SCR endpoint**
-> "Score with the loan model at https://scr-host/models/loan using age=45, credit_score=700"
-
-1. `sas-score-scr-score` → { url: "https://scr-host/models/loan", scenario: { age: "45", credit_score: "700" } }
-2. Capture prediction response
-3. Present result
-
-**Flow E — Score results of an analytical query with MAS**
-> "Score high-value customers (spend > 5000) in mylib.sales with the fraud model"
-
-1. `sas-score-sas-query` → { table: "mylib.sales", sql: "SELECT * FROM mylib.sales WHERE spend > 5000" }
-2. `sas-score-model-score` → { model: "fraud", scenario: [ ...result rows ] }
-3. Present merged results
-
-**Flow F — User supplies scenario data directly**
-> "Score age=45, income=60000, region=South with the churn model"
-
-1. Skip read step
-2. `sas-score-model-score` → { model: "churn", scenario: { age: "45", income: "60000", region: "South" } }
-3. Present result
-
-**Flow G — Model unfamiliar, need to confirm**
-> "Score Public.applicants with the creditRisk2 model"
-
-1. Pause — "creditRisk2" is new
-2. Suggest: `find-model` to confirm it exists, `model-info` to get input variables
-3. Once confirmed → `sas-score-read-table` + `sas-score-model-score`
-
-**Flow H — Generic score syntax with type routing**
-> "score with model churn.mas scenario =age=45,income=60000"
-> "score fraud_detector.jobdef where scenario =amount=500"
-> "score monthly_report.job using month=10,year=2025"
-
-1. Parse model name to extract type (.mas, .job, .jobdef, .scr, .sas)
-2. Route to appropriate tool based on type
-3. Parse scenario and invoke tool with parameters
-4. Present results from routed tool
-
----
-
-## Error handling
-
-| Problem | Action |
-|---|---|
-| Model not found | Suggest `find-model` to verify the model is deployed |
-| Input field name mismatch | Show the mismatch (table has X, model expects Y), ask user to confirm mapping |
-| Scoring error / invalid inputs | Return structured error, suggest `model-info` to check required inputs and data types |
-| Empty read result | Tell user, ask if they want to adjust the query/filter before scoring |
-| Missing input fields | Ask which table columns map to the required model inputs |
-
----
-
-## Tips
-
-- **Batch is better:** Always pass the full set of records in one `sas-score-model-score` call. Do not loop.
-- **Confirm mappings:** If column names don't match model inputs, ask before scoring.
-- **Show context:** Include key input columns in the result output so predictions make sense.
-- **Limit output:** For large result sets (>10 rows), ask before showing all.
-
----
-
-## Integration with other skills
-
-- **Before scoring table data**: Use `sas-find-library-smart` to verify the library, then `sas-read-strategy` to fetch records
-- **For read + score workflows**: Use `sas-read-and-score` for the complete end-to-end pattern

package/.claude/sas-spec-migration/SKILL.md

@@ -1,303 +0,0 @@
----
-name: sas-spec-migration
-description: >
-  Migrate or clean up SAS MCP tool spec objects. Use this skill whenever the user asks
-  to migrate, convert, update, or clean up tool specs. Covers two patterns:
-  (1) Old Zod-based format (z.string(), z.number(), top-level schema/required) → new
-  JSON Schema inputSchema format.
-  (2) Existing JSON Schema specs that need cleanup: removing $schema, fixing required
-  arrays (optional fields like "where" should not be in required), typing untyped fields
-  like scenario. Also trigger on: "migrate my tools", "update my specs", "clean up my
-  specs", "remove $schema", "fix required", or any request to standardize tool specs.
----
-
-# SAS Tool Spec Migration
-
-Covers two migration scenarios:
-
-- **Zod → JSON Schema**: Old format using `z.string()`, `z.number()` etc. with top-level `schema` and `required`
-- **JSON Schema cleanup**: Existing `inputSchema` specs that need `$schema` removed, `required` fixed, or untyped fields corrected
-
-Identify which pattern applies before proceeding.
-
----
-
-## Pattern 1 — JSON Schema cleanup
-
-Use when the tool already has `inputSchema` but needs tidying. Apply all of these fixes:
-
-### Remove `$schema`
-
-Drop the `$schema` declaration entirely — the MCP SDK and LLMs ignore it at runtime and
-it wastes tokens.
-
-```js
-// Before
-inputSchema: {
-  $schema: "http://json-schema.org/draft-07/schema#",
-  type: "object",
-  ...
-}
-
-// After
-inputSchema: {
-  type: "object",
-  ...
-}
-```
-
-### Fix `required` arrays
-
-Only include a field in `required` if it is truly mandatory. Common mistakes:
-
-| Field | Rule |
-|---|---|
-| `where` (filter expression) | Optional — remove from `required`, default to `""` in handler |
-| `scenario` (job params) | Optional — not all jobs need parameters; remove from `required` |
-| `name` | Required — always include |
-| `limit`, `start` | Required for list tools — include |
-
-### Type untyped fields
-
-If a field has `{}` or no type, infer the correct type:
-
-| Field | Type |
-|---|---|
-| `scenario` | `{ type: "string" }` — handler already parses it as JSON |
-| `where` | `{ type: "string" }` |
-| Any flexible input | `{ type: "string" }` with note to parse in handler |
-
-### Full cleanup example
-
-**Before:**
-```js
-inputSchema: {
-  $schema: "http://json-schema.org/draft-07/schema#",
-  type: "object",
-  properties: {
-    name: { type: "string" },
-    scenario: {}
-  },
-  required: ["name", "scenario"]
-}
-```
-
-**After:**
-```js
-inputSchema: {
-  type: "object",
-  properties: {
-    name: { type: "string" },
-    scenario: { type: "string" }
-  },
-  required: ["name"]
-}
-```
-
----
-
-## Pattern 2 — Zod → JSON Schema
-
-## What changes
-
-**Old format:**
-```js
-let spec = {
-  name: 'find-job',
-  aliases: [...],
-  description: description,
-  schema: {
-    name: z.string(),
-    limit: z.number().optional(),
-  },
-  required: ['name'],
-  handler: async (params) => { ... }
-}
-```
-
-**New format:**
-```js
-let spec = {
-  name: 'find-job',
-  aliases: [...],
-  description: description,
-  inputSchema: {
-    type: "object",
-    properties: {
-      name: { type: "string", description: "Job name to locate" },
-      limit: { type: "number", description: "Max results to return" }
-    },
-    required: ['name']
-  },
-  handler: async (params) => { ... }
-}
-```
-
-**Summary of changes:**
-- `schema` → `inputSchema`
-- `inputSchema` gains `type: "object"` and `properties: {}`
-- Each Zod field moves inside `properties` as a JSON Schema object
-- Top-level `required` array moves inside `inputSchema`
-- Fields with `.optional()` are NOT included in `required`
-- Fields without `.optional()` ARE included in `required` (unless already excluded)
-
----
-
-## Zod → JSON Schema type mapping
-
-| Zod | JSON Schema |
-|---|---|
-| `z.string()` | `{ type: "string" }` |
-| `z.number()` | `{ type: "number" }` |
-| `z.boolean()` | `{ type: "boolean" }` |
-| `z.array(z.string())` | `{ type: "array", items: { type: "string" } }` |
-| `z.array(z.number())` | `{ type: "array", items: { type: "number" } }` |
-| `z.object({...})` | `{ type: "object", properties: {...} }` |
-| `z.enum(['a','b'])` | `{ type: "string", enum: ["a", "b"] }` |
-| `.describe("text")` | Add `description: "text"` to the property |
-| `.optional()` | Omit field from `required` array |
-| `.optional().describe("text")` | Omit from `required`, add `description` |
-
----
-
-## Step-by-step migration
-
-### Step 1 — Identify the fields
-
-Read the existing `schema` object. For each key, note:
-- Its Zod type (string, number, boolean, array, enum, object)
-- Whether it has `.optional()`
-- Whether it has `.describe("...")` — extract the description text
-- Whether it appears in the top-level `required` array
-
-### Step 2 — Build `properties`
-
-For each field in `schema`, create a JSON Schema property object:
-
-```js
-// Old
-fieldName: z.string().describe("The name of the thing")
-
-// New
-fieldName: { type: "string", description: "The name of the thing" }
-```
-
-If no `.describe()` is present, infer a short description from the field name and tool context.
-Keep descriptions concise — one sentence, imperative style ("Job name to locate", not "This is the name of the job").
-
-### Step 3 — Build `required`
-
-Include a field in `required` if:
-- It appeared in the old top-level `required` array, OR
-- It has no `.optional()` in its Zod definition
-
-Exclude a field from `required` if:
-- It has `.optional()` in its Zod definition
-
-### Step 4 — Assemble `inputSchema`
-
-```js
-inputSchema: {
-  type: "object",
-  properties: {
-    // one entry per field from Step 2
-  },
-  required: [/* field names from Step 3 */]
-}
-```
-
-If `required` would be empty, omit it entirely rather than including `required: []`.
-
-### Step 5 — Remove old fields
-
-Remove `schema` and the top-level `required` from the spec object.
-Leave everything else unchanged: `name`, `aliases`, `description`, `handler`.
-
----
-
-## Edge cases
-
-**Field in `required` but also `.optional()` in Zod:**
-Trust `.optional()` — exclude from `required`. The old `required` array may be stale.
-
-**Nested `z.object()`:**
-```js
-// Old
-config: z.object({ host: z.string(), port: z.number() })
-
-// New
-config: {
-  type: "object",
-  properties: {
-    host: { type: "string", description: "Host address" },
-    port: { type: "number", description: "Port number" }
-  }
-}
-```
-
-**`z.union()` / `z.any()` / `z.unknown()`:**
-Use `{}` (empty schema, accepts anything) or `{ type: "string" }` with a note that the
-field accepts flexible input. Flag this to the user for review.
-
-**No `schema` field at all:**
-The tool takes no inputs. Set `inputSchema: { type: "object", properties: {} }` or omit
-`inputSchema` entirely — both are valid. Omitting is cleaner for zero-input tools.
-
-**`schema` is already a plain JSON object (not Zod):**
-Check if values use `z.` prefix. If not, the schema may already be partially migrated —
-wrap it in `{ type: "object", properties: { ... } }` and move `required` inside.
-
----
-
-## Output format
-
-- Preserve the existing code style (quote style, indentation, trailing commas)
-- Output the full updated spec object, not just the diff
-- If migrating multiple specs at once, process them all and output each in full
-- After outputting, note any fields that used `z.union()`, `z.any()`, or other ambiguous
-  types that the user should review manually
-
----
-
-## Example — full migration
-
-**Input:**
-```js
-let spec = {
-  name: 'find-job',
-  aliases: ['findJob', 'find job'],
-  description: description,
-  schema: {
-    name: z.string(),
-    caslib: z.string().optional().describe("CAS library name"),
-    limit: z.number().optional(),
-  },
-  required: ['name'],
-  handler: async (params) => {
-    let r = await _listJobs(params);
-    return r;
-  }
-}
-```
-
-**Output:**
-```js
-let spec = {
-  name: 'find-job',
-  aliases: ['findJob', 'find job'],
-  description: description,
-  inputSchema: {
-    type: "object",
-    properties: {
-      name: { type: "string", description: "Job name to locate" },
-      caslib: { type: "string", description: "CAS library name" },
-      limit: { type: "number", description: "Max results to return" }
-    },
-    required: ['name']
-  },
-  handler: async (params) => {
-    let r = await _listJobs(params);
-    return r;
-  }
-}
-```