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

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

@@ -0,0 +1,303 @@
+---
+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;
+  }
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sassoftware/sas-score-mcp-serverjs",
-  "version": "0.4.1-18",
+  "version": "0.4.1-20",
   "description": "A mcp server for SAS Viya",
   "author": "Deva Kumar <deva.kumar@sas.com>",
   "license": "Apache-2.0",
@@ -43,7 +43,8 @@
     "openApi.json",
     "openApi.yaml",
     "skills",
-    "scripts"
+    "scripts",
+    ".claude"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

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

@@ -15,20 +15,24 @@ of the data operation. Determines which server contains the data and which retri
 
 ## Determine the server location
 
-Before retrieving data, verify the library and determine which server(s) contain the table:
+Before retrieving data, locate the table and determine which server contains it:
 
-**Step 1: Verify library existence**
-- Use `sas-find-library-smart` skill to check the library in CAS first, then SAS if needed
-- This establishes the correct server and uppercase convention for SAS libraries
-- Informs the user which server contains the library
+**Smart table lookup with server detection**
 
-**Step 2: Locate the specific table**
-- Use `sas-score-find-table` to check if the table exists in the library
-- Possible outcomes:
-  - If table exists **only in CAS** → set `server: "cas"`
-  - If table exists **only in SAS** → set `server: "sas"`
-  - If table exists **in both** → ask the user: *"The table exists in both CAS and SAS. Which server would you prefer to query from?"*
-  - If table exists **in neither** → inform user and suggest verifying the table name
+Use `sas-score-find-table` with intelligent server detection:
+
+1. **First attempt**: Check CAS server (`server: "cas"`)
+   - If table exists → return table and server to caller
+   - If table not found → proceed to step 2
+
+2. **Second attempt**: Check SAS server (`server: "sas"`)
+   - If table exists → return table and server to caller
+   - If table not found in either server → inform user and suggest verifying the library and table names
+
+**Possible outcomes:**
+- Table found in CAS → use `server: "cas"` for subsequent read operations
+- Table found in SAS → use `server: "sas"` for subsequent read operations
+- Table not found in either server → inform user: *"The table 'lib.table' was not found in CAS or SAS. Please verify the library and table names."*
 
 ---
 
@@ -55,21 +59,31 @@ Ask yourself: does the user already have the data in hand?
 
 **How:**
 ```
+sas-score-find-table({
+  lib: "libraryname",
+  table: "tablename",
+  server: "cas"  // start with CAS
+})
+// if not found, repeat with server: "sas"
+
 sas-score-read-table({
   table: "tablename",
   lib: "libraryname",
-  server: "cas" or "sas",  // determined from sas-score-find-table check
-  limit: N,        // default 10, adjust based on user request
+  server: "cas" or "sas",  // REQUIRED: determined from sas-score-find-table check
+  start: 1,        // REQUIRED: 1-based row offset (default: 1)
+  limit: N,        // REQUIRED: max rows to retrieve (default: 10, max: 1000)
   where: "..."     // optional SQL WHERE clause
 })
 ```
 
 **Rules:**
-- Always determine the server first using `sas-score-find-table`
-- Keep batch size ≤ 50 rows unless the user explicitly requests more
+- Always determine the server first using `sas-score-find-table` with smart detection (CAS → SAS)
+- **ALWAYS set `server` parameter** — never omit it; use the result from `sas-score-find-table` to determine "cas" or "sas"
+- **ALWAYS set `start` parameter** — use 1 for the first call, or the offset for pagination
+- **ALWAYS set `limit` parameter** — keep batch size ≤ 50 rows unless the user explicitly requests more; cap at 1000
 - If table name is missing, ask: *"Which table should I read from? (format: lib.tablename)"*
 - If library is missing, ask: *"Which library contains the table?"*
-- If table exists in both servers, ask user which to use
+- If table exists in both servers, prefer CAS (already determined by smart detection)
 - Return raw column values; do not transform or aggregate
 
 ---
@@ -83,6 +97,13 @@ sas-score-read-table({
 
 **How:**
 ```
+sas-score-find-table({
+  lib: "libraryname",
+  table: "tablename",
+  server: "cas"  // start with CAS
+})
+// if not found, repeat with server: "sas"
+
 sas-query({
   table: "lib.tablename",
   query: "user's natural language question",
@@ -91,8 +112,8 @@ sas-query({
 ```
 
 **Rules:**
-- Check which server(s) contain the table using `sas-score-find-table` first
-- If table exists in both CAS and SAS, ask user which to query from
+- Check which server contains the table using `sas-score-find-table` with smart detection (CAS → SAS) first
+- If table exists in CAS, query from CAS; if only in SAS, query from SAS
 - Parse the user's natural language question into a PROC SQL SELECT statement
 - Ensure SELECT statement is valid SQL syntax
 - Do not add trailing semicolons to the SQL string
@@ -106,12 +127,12 @@ sas-query({
 **Pattern A — Raw row retrieval**
 > "Show me the first 5 rows from Public.customers"
 
-→ `sas-score-read-table({ table: "customers", lib: "Public", limit: 5 })`
+→ `sas-score-read-table({ table: "customers", lib: "Public", server: "cas", start: 1, limit: 5 })`
 
 **Pattern B — Filtered retrieval**
 > "Get all high-value orders (amount > 5000) from mylib.orders"
 
-→ `sas-score-read-table({ table: "orders", lib: "mylib", where: "amount > 5000" })`
+→ `sas-score-read-table({ table: "orders", lib: "mylib", server: "sas", start: 1, limit: 50, where: "amount > 5000" })`
 
 **Pattern C — Aggregation**
 > "What is the average price by make in Public.cars?"
@@ -129,11 +150,12 @@ sas-query({
 
 | Problem | Action |
 |---|---|
-| Library not found | Use `sas-find-library-smart` skill to verify the library exists |
-| Table not found in either server | Inform user and suggest checking the table name |
-| Table exists in both CAS and SAS | Ask: *"The table exists in both servers. Which would you prefer: CAS or SAS?"* |
-| Table exists only in one server | Use that server automatically in your request |
-| Table name missing entirely | Ask: *"Which table should I read from?"* |
+| Table not found in CAS | Try SAS server using `sas-score-find-table` with `server: "sas"` |
+| Table not found in either server | Inform user: *"The table 'lib.table' was not found in CAS or SAS. Please verify the library and table names."* |
+| Table exists only in CAS | Use `server: "cas"` automatically for read operations |
+| Table exists only in SAS | Use `server: "sas"` automatically for read operations |
+| Table name missing entirely | Ask: *"Which table should I read from? (format: lib.tablename)"* |
+| Library name missing | Ask: *"Which library contains the table?"* |
 | Ambiguous intent (raw vs aggregate) | Ask: *"Do you want individual rows or a summary by some field?"* |
 | Empty result | Inform user, ask to adjust filter or query |
 
@@ -141,7 +163,7 @@ sas-query({
 
 ## Integration with other skills
 
-- **Before this skill**: Use `sas-find-library-smart` to verify and locate the library
+- **Before this skill**: Use `sas-score-find-table` to verify the table exists and determine the server location
 - **After this skill**: Use `sas-read-and-score` to score the retrieved data
 
 ---

package/src/toolSet/findTable.js

@@ -17,7 +17,7 @@ DO NOT USE for: list tables (use list-tables), table schema/columns (use table-i
 PARAMETERS
 - lib: string (required) — library name (e.g., 'Public', 'sashelp')
 - name: string (required) — table name to locate
-- server: 'cas' | 'sas' (default: 'cas') — target environment
+- server: 'cas' | 'sas' . If not specified set it to 'cas' — target environment
 
 ROUTING RULES
 - "find table <name> in <lib>" → { lib: "<lib>", name: "<name>", server: "cas" }
@@ -49,7 +49,7 @@ Returns { tables: [] } if not found; { tables: [name, ...] } if found. Never hal
     inputSchema: z.object({
       name: z.string(),
       lib: z.string(),
-      server: z.string().optional() // default server is 'cas'
+      server: z.string() 
     }),
     
     handler: async (params) => {