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

package/skills/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;
-  }
-}
-```