@sassoftware/sas-score-mcp-serverjs 0.4.1-19 → 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-19",
+  "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

@@ -69,15 +69,18 @@ sas-score-find-table({
 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` with smart detection (CAS → SAS)
-- Keep batch size ≤ 50 rows unless the user explicitly requests more
+- **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, prefer CAS (already determined by smart detection)
@@ -124,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?"