@sassoftware/sas-score-mcp-serverjs 0.4.1-1 → 0.4.1-15

package/skills/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/src/authpkce.js

@@ -0,0 +1,219 @@
+/**
+ * SAS Viya PKCE Authorization Flow
+ *
+ * Uses the Authorization Code flow with PKCE (RFC 7636).
+ * Starts a local HTTP server to capture the redirect callback.
+ *
+ * Usage:
+ *   node sas-viya-pkce-auth.js
+ *
+ * Prerequisites:
+ *   - A SAS Viya client registered with:
+ *       grant_types: authorization_code
+ *       redirect_uri: http://localhost:3000/callback
+ *       PKCE enabled (no client_secret required)
+ */
+
+import http from "http";
+import https from "https";
+import crypto from "crypto";
+import url from "url";
+
+    let VIYA_SERVER=process.env.VIYA_SERVER;
+    let PORT=8080;
+    let CLIENTID='pkcemcp';
+    // ── Configuration ────────────────────────────────────────────────────────────
+  
+    const CONFIG = {
+        authBaseUrl: `${VIYA_SERVER}/oauth/SASLogon`,
+        clientId: CLIENTID,       // <-- replace with your client ID
+        redirectUri: `http://localhost:${PORT}/callback`,
+        scopes: "openid profile",
+        localPort: PORT,
+    };
+
+    main().catch((err) => {
+      console.error("Unexpected error:", err);
+      process.exit(1);
+    });
+
+    // ─────────────────────────────────────────────────────────────────────────────
+
+    // Generate a cryptographically random code verifier (43–128 chars, base64url)
+    function generateCodeVerifier() {
+        return crypto.randomBytes(64).toString("base64url");
+    }
+
+    // Derive the code challenge: BASE64URL(SHA-256(verifier))
+    function generateCodeChallenge(verifier) {
+        return crypto.createHash("sha256").update(verifier).digest("base64url");
+    }
+
+    // Build the SASLogon authorization URL
+    function buildAuthUrl(codeChallenge, state) {
+        const params = new URLSearchParams({
+            response_type: "code",
+            client_id: CONFIG.clientId,
+            redirect_uri: CONFIG.redirectUri,
+            scope: CONFIG.scopes,
+            state,
+            code_challenge: codeChallenge,
+            code_challenge_method: "S256",
+        });
+        return `${CONFIG.authBaseUrl}/authorize?${params}`;
+    }
+
+    // Exchange the authorization code for tokens
+    function exchangeCodeForTokens(code, codeVerifier) {
+        return new Promise((resolve, reject) => {
+            const body = new URLSearchParams({
+                grant_type: "authorization_code",
+                client_id: CONFIG.clientId,
+                redirect_uri: CONFIG.redirectUri,
+                code,
+                code_verifier: codeVerifier,
+            }).toString();
+
+            const tokenUrl = new URL(`${CONFIG.authBaseUrl}/token`);
+
+            const options = {
+                hostname: tokenUrl.hostname,
+                port: tokenUrl.port || 443,
+                path: tokenUrl.pathname,
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    "Content-Length": Buffer.byteLength(body),
+                },
+                // Remove the line below if your Viya instance has a valid TLS cert
+                rejectUnauthorized: false,
+            };
+
+            const req = https.request(options, (res) => {
+                let data = "";
+                res.on("data", (chunk) => (data += chunk));
+                res.on("end", () => {
+                    try {
+                        const parsed = JSON.parse(data);
+                        if (res.statusCode >= 400) {
+                            reject(new Error(`Token error (${res.statusCode}): ${data}`));
+                        } else {
+                            resolve(parsed);
+                        }
+                    } catch {
+                        reject(new Error(`Failed to parse token response: ${data}`));
+                    }
+                });
+            });
+
+            req.on("error", reject);
+            req.write(body);
+            req.end();
+        });
+    }
+
+    // Wait for the browser redirect and extract code + state
+    function waitForCallback(expectedState) {
+        return new Promise((resolve, reject) => {
+            const server = http.createServer((req, res) => {
+                const parsed = url.parse(req.url, true);
+
+                if (parsed.pathname !== "/callback") {
+                    res.writeHead(404);
+                    res.end("Not found");
+                    return;
+                }
+
+                const { code, state, error, error_description } = parsed.query;
+
+                res.writeHead(200, { "Content-Type": "text/html" });
+                res.end(`
+        <html><body>
+          <h2>${error ? "Authorization failed" : "Authorization successful!"}</h2>
+          <p>You may close this tab.</p>
+        </body></html>
+      `);
+
+                server.close();
+
+                if (error) {
+                    reject(new Error(`OAuth error: ${error} — ${error_description}`));
+                    return;
+                }
+                if (state !== expectedState) {
+                    reject(new Error("State mismatch — possible CSRF attack"));
+                    return;
+                }
+
+                resolve(code);
+            });
+
+            server.listen(CONFIG.localPort, () => {
+                console.error(`Listening on http://localhost:${CONFIG.localPort}/callback`);
+            });
+
+            server.on("error", reject);
+        });
+    }
+
+    // Main flow
+    async function main() {
+        const codeVerifier = generateCodeVerifier();
+        const codeChallenge = generateCodeChallenge(codeVerifier);
+        const state = crypto.randomBytes(16).toString("hex");
+
+        const authUrl = buildAuthUrl(codeChallenge, state);
+
+        console.error("\nOpen this URL in your browser to log in:\n");
+        console.error(authUrl);
+        console.error();
+
+        // Try to auto-open in the default browser (best-effort)
+        try {
+            const { exec } = require("child_process");
+            const cmd =
+                process.platform === "win32"
+                    ? `start "" "${authUrl}"`
+                    : process.platform === "darwin"
+                        ? `open "${authUrl}"`
+                        : `xdg-open "${authUrl}"`;
+            exec(cmd);
+        } catch {
+            // ignore — user can open manually
+        }
+
+        let code;
+        try {
+            code = await waitForCallback(state);
+        } catch (err) {
+            console.error("Callback error:", err.message);
+            return null;
+        }
+
+        console.error("Authorization code received. Exchanging for tokens...");
+
+        let tokens;
+        try {
+            tokens = await exchangeCodeForTokens(code, codeVerifier);
+        } catch (err) {
+            console.error("Token exchange error:", err.message);
+            return null;
+        }
+
+        console.error("\nTokens received:");
+        console.error("  access_token :", tokens.access_token?.slice(0, 40) + "...");
+        console.error("  token_type   :", tokens.token_type);
+        console.error("  expires_in   :", tokens.expires_in, "seconds");
+        if (tokens.refresh_token) {
+            console.error("  refresh_token:", tokens.refresh_token.slice(0, 20) + "...");
+        }
+        if (tokens.id_token) {
+            console.error("  id_token     :", tokens.id_token.slice(0, 40) + "...");
+        }
+
+        // tokens.access_token is ready to use as a Bearer token for Viya REST APIs
+        return tokens.access_token
+    }
+
+
+  

package/src/createMcpServer.js

@@ -15,7 +15,14 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import makeTools from "./toolSet/makeTools.js";
 import getLogonPayload from "./toolHelpers/getLogonPayload.js";
 
+function getServerBaseUrl(appContext) {
+  const protocol = appContext.HTTPS === "TRUE" ? "https" : "http";
+  const host = appContext.contexts?.APPHOST || "localhost";
+  return `${protocol}://${host}:${appContext.PORT}`;
+}
+
 async function createMcpServer(cache, _appContext) {
+  const serverBaseUrl = getServerBaseUrl(_appContext);
 
   let mcpServer = new McpServer(
     {
@@ -39,13 +46,12 @@ async function createMcpServer(cache, _appContext) {
     let currentId = cache.get('currentId');
     let _appContext = cache.get(currentId);
     let params;
-    // get Viya token 
 
     let errorStatus = cache.get('errorStatus');
     if (errorStatus) {
       return { isError: true, content: [{ type: 'text', text: errorStatus }] }
     };
-    if (_appContext.AUTHFLOW === 'code' && _appContext.contexts.oauthInfo == null) {
+    if (/*_appContext.AUTHFLOW === 'code'*/ _appContext.useHapi === true && _appContext.contexts.oauthInfo == null) {
       return { isError: true, content: [{ type: 'text', text: 'Please visit https://localhost:8080/mcpserver to connect to Viya. Then try again.' }] }
     }
     console.error("Getting logon payload for tool with session ID:", currentId);
@@ -64,6 +70,7 @@ async function createMcpServer(cache, _appContext) {
 
     // call the actual tool handler
     debugger;
+    console.error("Calling tool handler with enhanced params");
     let r = await builtin(params);
     return r;
   }
@@ -73,18 +80,14 @@ async function createMcpServer(cache, _appContext) {
   let toolNames = [];
   toolSet.forEach((tool, i) => {
     let toolName = _appContext.brand + '-' + tool.name;
-    tool.inputSchema.additionalProperties = false; // disallow extra properties 
+    //tool.inputSchema.additionalProperties = false; // disallow extra properties 
     let config = {
-      title: toolName,
       description: tool.description,
       inputSchema: tool.inputSchema
     }
-    console.error(`[Note] Configuring tool ${toolName} with input schema: ${JSON.stringify(tool.inputSchema)}`);
-    console.error(`\n[Note] Registering tool ${i + 1} : ${toolName}`);
     let toolHandler = wrapf(cache, tool.handler);
-
+  //  console.error(`[Note] Registering tool ${toolName} with config: ${JSON.stringify(config)}`);
     let r = mcpServer.registerTool(toolName, config, toolHandler);
-    console.error(`[Note] Tool ${toolName} registered with result: ${JSON.stringify(r)}`);
     toolNames.push(toolName);
   });
   console.error(`[Note] Registered ${toolSet.length} tools: ${toolNames}`);