@pmoses-s1/s1-secops-mcp 1.3.7 → 1.3.9

package/CHANGELOG.md

@@ -1,5 +1,114 @@
 # Changelog
 
+## 1.3.9
+
+Three defects from a field smoke test, plus the delivery-channel fault that kept
+the last two releases from reaching the person who reported them. Tool count
+stays 32.
+
+### The image tag now tracks the npm version
+
+`IMAGE_VERSION` was a third free-running number, and the cost was a reused tag.
+`s1-mcps:1.3.3` shipped npm 1.3.3, then 1.3.7, then 1.3.8, and the image version
+once moved **backwards**, 1.3.7 to 1.3.3. With the documented `--pull=missing`
+against a tag string that never changes, Docker has nothing to notice, so anyone
+who pulled in August kept an August build while believing they were current. A
+report of "sdl_list_files 500s at default scope" turned out to be exactly that:
+a build from before the 1.3.4 and 1.3.5 scope work.
+
+`IMAGE_VERSION` now defaults to `${S1_MCP_VERSION}`, so changing what is inside
+the image always changes the tag. The documented Docker config moves to `:latest`
+with **`--pull=always`**. Version tags remain published and immutable, for
+reproducible demos and support.
+
+The CI bump guard had two holes and both are closed. It tested that the
+`IMAGE_VERSION` line *changed* rather than that the version *increased*, which
+is how the backwards move passed; it now requires a strict semver increase. And
+it permitted a publish whenever the tag was absent from the registry, which made
+"delete the tag, republish different bytes" a supported route; that escape hatch
+is gone. A tag someone already pulled does not become safe to reuse by being
+deleted.
+
+### Fixed
+
+- **`ha_import_workflow` double-wrapped the payload.** The endpoint's body is
+  `{"data": {...}}`, the hyperautomation skill's smoke-test example showed that
+  correctly, and this tool adds the envelope itself, so pasting the documented
+  example sent `{"data":{"data":{...}}}` and the API answered
+  `422 body.data.name Field required`, which reads like a broken workflow rather
+  than one extra level of nesting. Both artifacts were right in isolation and
+  nothing ever executed one against the other.
+
+  The tool now unwraps a wrapped payload when it is unambiguous, a `data` object
+  present and no top-level `name`, and says so in the response rather than
+  silently accepting both shapes. A workflow that legitimately owns a `data` key
+  keeps it. The skill now prints both forms, labelled: Form A the raw API body,
+  Form B the bare object this tool wants.
+
+- **`sdl_list_dashboards` had no limit.** Measured on an MSSP account it returned
+  442,581 characters across 17,111 lines, past any usable context budget. It now
+  takes `limit` (default 100, clamped to 1000), `offset` and `namesOnly`, and
+  reports `totalCount`, `hasMore` and `nextOffset`. `namesOnly` returns `{id,
+  name}` and is about four times smaller, measured, which covers the common case
+  of resolving a name to an id. `sdl_list_files` gets the same treatment,
+  default 500, with `count` still reporting the full post-filter total so
+  existing callers read the number they expect.
+
+- **`ha_export_workflow` could not be scoped.** It sent no scope parameter, while
+  `ha_import_workflow` already documents that an unscoped call on a scoped tenant
+  returns a misleading `403 Insufficient permissions`. It now accepts
+  `accountIds` / `siteIds`, and an unscoped 403 names scope as a possible cause
+  instead of leaving the reader to conclude "missing role" and stop.
+
+### Documented, not fixed here
+
+**Omitted parameters that declare a default are rejected by the client.** Calling
+`powerquery_run`, `uam_list_alerts`, `ha_list_workflows` and four others without
+passing every argument fails with `expected nonoptional, received undefined`
+before the request reaches this server. That is not this package: it has no
+dependencies and does not use zod, those are Zod v4 codes from the host, and the
+error arrives pre-dispatch. The host maps a JSON-Schema property carrying
+`default` to a non-optional field, validating against the schema's output type
+rather than its input type. 7 of 32 tools and 16 parameters are affected, listed
+in the README with the pass-every-parameter workaround. Reported upstream.
+
+**A dashboard `id` is often null, and that is its age, not a fault.** Only
+dashboards created through the `dashboardsV2` surface carry a udoId; ones created
+the older name-addressed way do not. On an established account most predate it,
+measured 397 of 1,555 with an id, and `sdl_list_files` reports exactly the same
+397. Address a legacy dashboard by its `/dashboards/<name>` path. Recorded in the
+`sdl_list_dashboards` description, along with the fact that results are ordered by
+name and that order is stable across calls, so page on `name` and not on `id`.
+
+The `limit`, `offset` and `namesOnly` parameters added above deliberately carry
+no `default` keyword for this reason; their defaults live in the handler and are
+stated in the descriptions. A new test pins the set of default-bearing
+properties so the blast radius cannot grow by accident.
+
+### Tests
+
+132 JS (+14). The 1.3.8 suite asserted structure, tool count, names, description
+keywords, with the HTTP layer mocked, and all four defects lived in the space
+that left uncovered. Four new classes:
+
+- **Executable doc examples.** Both JSON blocks in the hyperautomation skill's
+  smoke-test section are parsed out of the markdown and run through
+  `ha_import_workflow`, asserting the outbound body carries exactly one `data`
+  envelope. A documented payload that cannot survive the tool beside it now fails
+  the build.
+- **Outbound wire shape.** Assert the body that is sent, not merely that a call
+  was made.
+- **Client-parity schema lint.** Every tool must be callable with only its
+  `required` fields; no property may be both required and defaulted; and the set
+  of default-bearing properties is frozen against the known list.
+- **Response budget.** List tools are driven with MSSP-scale fixtures, 1,200
+  dashboards and 2,000 config files, and must stay under 200,000 characters.
+  Cardinality is a property of the tenant, so only a fixture can supply it.
+
+### Docker
+
+Bundle image **1.3.9**, pinning npm 1.3.9. Image version now derived, not chosen.
+
 ## 1.3.7
 
 Minor, not patch: a tool is gone and the log-ingest credential changed. Both

package/README.md

@@ -73,11 +73,12 @@ Add this to `claude_desktop_config.json` (or `.mcp.json` for Claude Code):
   "mcpServers": {
     "s1-secops-mcp": {
       "command": "npx",
-      "args": ["-y", "@pmoses-s1/s1-secops-mcp@1.3.7"],
+      "args": ["-y", "@pmoses-s1/s1-secops-mcp@1.3.9"],
       "env": {
         "S1_CONSOLE_URL":       "https://usea1-yourorg.sentinelone.net",
         "S1_CONSOLE_API_TOKEN": "eyJ...",
-        "S1_HEC_INGEST_URL":    "https://ingest.us1.sentinelone.net"
+        "S1_HEC_INGEST_URL":    "https://ingest.us1.sentinelone.net",
+        "S1_HEC_TOKEN":         "<SDL Log Write Key, optional; hec_ingest needs it>"
       }
     }
   }
@@ -522,6 +523,49 @@ The `sentinelone://soc-context` resource and `soc_analyst` prompt load `CLAUDE.m
 
 For npx installs without a CLAUDE.md nearby, set `S1_CLAUDE_MD_PATH` in the `env` block of `claude_desktop_config.json` to point at the one in your Cowork project folder. Restart Claude Desktop to pick up edits.
 
+## Known client issue: omitted parameters that declare a default are rejected
+
+On affected Claude Code / Claude Desktop builds, calling one of the tools below without
+passing **every** parameter fails before the request reaches this server:
+
+```
+MCP error -32602: Input validation error: Invalid arguments for tool powerquery_run: [
+  { "code": "invalid_type", "expected": "nonoptional", "path": ["maxRows"],
+    "message": "Invalid input: expected nonoptional, received undefined" } ]
+```
+
+**This is not a defect in this server, and upgrading it will not fix it.** This package
+has no dependencies and does not use zod; those are Zod v4 error codes, emitted by the
+host, and the error arrives before dispatch. The host converts a tool's JSON Schema into
+a validator and maps a property carrying `default` to a non-optional field, so an absent
+value raises an error instead of taking the default. It validates against the schema's
+*output* type rather than its *input* type. Any MCP server that declares defaults is
+affected.
+
+**Workaround:** pass every parameter explicitly, including the ones you want at their
+default value.
+
+**Affected tools and parameters**, 7 of 32:
+
+| Tool | Parameters carrying a `default` |
+|---|---|
+| `ha_list_workflows` | `limit`, `skip`, `sortBy`, `sortOrder` |
+| `uam_list_alerts` | `first`, `viewType` |
+| `powerquery_run` | `hours`, `maxRows` |
+| `powerquery_schema_discover` | `maxEvents`, `startTime` |
+| `powerquery_enumerate_sources` | `hours` |
+| `sdl_create_dashboard` | `isPublic` |
+| `uam_ingest_alert` | `title`, `hostname`, `filename`, `inline` |
+
+Every other tool is unaffected, and within these tools only the listed parameters are
+rejected. Parameters without a default (`query`, `scope`, `startTime` on
+`powerquery_run`, `status`, `severity`, `siteIds`) work when omitted.
+
+Tools added in 1.3.9 (`limit`, `offset`, `namesOnly` on `sdl_list_dashboards` and
+`sdl_list_files`) deliberately omit the `default` keyword and document their defaults in
+the parameter description instead, so they are not affected. Reported upstream; when the
+host is fixed, the defaults can go back into the schemas.
+
 ## Removed tools
 
 `purple_ai_query` and `purple_ai_investigate` were removed on 2026-05-03. Both required a browser-session `teamToken` from `/sdl/v2/graphql` that service-account API tokens never obtain (returns `AsimovError` / `SERVICE_ERROR`). Use `mcp__purple-mcp__purple_ai` instead, which holds the right credentials.

package/deploy/README.md

@@ -34,7 +34,8 @@ Then edit `~/.config/sentinelone/credentials.json` with your real values:
 {
   "S1_CONSOLE_URL":       "https://usea1-yourorg.sentinelone.net",
   "S1_CONSOLE_API_TOKEN": "eyJ...",
-  "S1_HEC_INGEST_URL":    "https://ingest.us1.sentinelone.net"
+  "S1_HEC_INGEST_URL":    "https://ingest.us1.sentinelone.net",
+  "S1_HEC_TOKEN":         "<SDL Log Write Key, optional; hec_ingest needs it>"
 }
 ```
 
@@ -57,7 +58,7 @@ Or, equivalently, by package name without the install:
   "mcpServers": {
     "s1-secops-mcp": {
       "command": "npx",
-      "args": ["-y", "@pmoses-s1/s1-secops-mcp@1.3.7"]
+      "args": ["-y", "@pmoses-s1/s1-secops-mcp@1.3.9"]
     }
   }
 }
@@ -376,7 +377,7 @@ Both block the W+X memory mappings V8 needs to JIT JavaScript. Adding them cause
 
 These are supported but not first-class:
 
-- **Docker / docker-compose.** Not shipped in this version. The single-file Node binary doesn't need it. If you want a container, the install is `FROM node:20-alpine` + `RUN npm install -g @pmoses-s1/s1-secops-mcp@1.3.7` + `CMD ["s1-secops-mcp", "--transport", "http", "--host", "0.0.0.0"]`. Mount creds at `/etc/s1-secops-mcp/credentials.json` and tokens at `/etc/s1-secops-mcp/bearer-tokens.json`.
+- **Docker / docker-compose.** Not shipped in this version. The single-file Node binary doesn't need it. If you want a container, the install is `FROM node:20-alpine` + `RUN npm install -g @pmoses-s1/s1-secops-mcp@1.3.9` + `CMD ["s1-secops-mcp", "--transport", "http", "--host", "0.0.0.0"]`. Mount creds at `/etc/s1-secops-mcp/credentials.json` and tokens at `/etc/s1-secops-mcp/bearer-tokens.json`.
 
 - **External bridge (`supergateway`, `mcp-proxy`).** Pre-1.1.0 deployments used these to wrap the stdio-only server. They still work; this server's native HTTP mode is functionally equivalent and removes the extra process. Prefer native unless you have a specific reason.
 

package/lib/s1.js

@@ -643,21 +643,18 @@ export async function uamSetStatus(alertId, status) {
   }
   if (action.failure?.length) {
     const f = action.failure[0];
-    // errorMessage says WHAT failed, not WHY. `Missing UAM manage permissions`
-    // is also what a not-offered action returns: alerts ingested via the UAM
-    // Alert Interface (/v1/alerts) expose only addNote and eventSearch, while
-    // the same token sets status on a native alert successfully (measured).
-    // So ask alertAvailableActions before reporting a cause, and never let the
-    // caller conclude "the token lacks permission" from the string alone.
+    // errorMessage names the failure, not the cause. Ask alertAvailableActions,
+    // which is filtered by the caller's permissions AND the alert type.
     let hint = '';
     try {
       const avail = await uamAvailableActions(alertId);
       const ids = avail.map((a) => a.id);
       if (!ids.includes('S1/alert/statusUpdate')) {
-        hint = ' | alertAvailableActions: statusUpdate is NOT OFFERED for this '
-             + `alert type (available: ${ids.join(', ') || 'none'}). This is a `
-             + 'capability limit of the alert, not a token scope; a new token '
-             + 'will not help.';
+        hint = ' | alertAvailableActions: statusUpdate is NOT OFFERED to this '
+             + `caller for this alert (available: ${ids.join(', ') || 'none'}). `
+             + 'Availability is filtered by the caller\'s permissions and the '
+             + 'alert type: check the service user\'s UAM permissions. A '
+             + 'console user session may still be able to perform it.';
       } else {
         const a = avail.find((x) => x.id === 'S1/alert/statusUpdate');
         hint = a?.isDisabled

package/lib/server-core.js

@@ -94,7 +94,7 @@ const PROMPTS = [
 
 export const SERVER_INFO = {
   name: 's1-secops-mcp-server',
-  version: '1.3.7',
+  version: '1.3.9',
 };
 
 export const PROTOCOL_VERSION = '2024-11-05';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmoses-s1/s1-secops-mcp",
-  "version": "1.3.7",
+  "version": "1.3.9",
   "description": "MCP server orchestrating SentinelOne skills, APIs, and SOC analyst context. Stdio or Streamable HTTP transport with per-user bearer auth for team deployments.",
   "type": "module",
   "main": "index.js",
@@ -20,7 +20,7 @@
     "start": "node index.js",
     "start:http": "node index.js --transport http",
     "dev": "node --watch index.js",
-    "test": "node --test tests/smoke.test.mjs tests/stdio-transport.test.mjs tests/http-transport.test.mjs tests/ssrf-path.test.mjs tests/http-origin-guard.test.mjs tests/sdl-graphql.test.mjs tests/regressions-2026-07-29.test.mjs tests/regressions-2026-07-31.test.mjs",
+    "test": "node --test tests/smoke.test.mjs tests/stdio-transport.test.mjs tests/http-transport.test.mjs tests/ssrf-path.test.mjs tests/http-origin-guard.test.mjs tests/sdl-graphql.test.mjs tests/regressions-2026-07-29.test.mjs tests/regressions-2026-07-31.test.mjs tests/contracts-1.3.9.test.mjs",
     "regen:readme": "node scripts/regen-readme-tools-table.mjs"
   },
   "engines": {

package/scripts/regen-readme-tools-table.mjs

@@ -39,6 +39,7 @@ const TOOL_SKILL = {
   uam_get_alert:                 'mgmt-console-api',
   uam_add_note:                  'mgmt-console-api',
   uam_set_status:                'mgmt-console-api',
+  uam_available_actions:         'mgmt-console-api',
   // SDL API
   sdl_list_files:                'sdl-api / sdl-dashboard / sdl-log-parser',
   sdl_get_file:                  'sdl-api / sdl-dashboard / sdl-log-parser',
@@ -65,7 +66,7 @@ const TOOL_SKILL = {
 
 const GROUPS = [
   { label: 'PowerQuery',       prefix: 'powerquery_' },
-  { label: 'Mgmt Console',     test: n => /^(s1_api_|purple_ai_|uam_(list|get|add|set))/.test(n) },
+  { label: 'Mgmt Console',     test: n => /^(s1_api_|purple_ai_|uam_(list|get|add|set|available))/.test(n) },
   { label: 'SDL API',          test: n => n.startsWith('sdl_') || n === 'hec_ingest' },
   { label: 'Hyperautomation',  prefix: 'ha_' },
   { label: 'UAM Ingest',       test: n => /^(uam_ingest_|uam_post_)/.test(n) },

package/tools/hyperautomation.js

@@ -213,7 +213,7 @@ export const tools = [
       properties: {
         workflowJson: {
           type: 'string',
-          description: 'Full Hyperautomation workflow JSON as a string. Must be valid Hyperautomation schema. Generate this using the hyperautomation skill.',
+          description: 'The workflow object as a JSON string: {"name": ..., "description": ..., "actions": [...]}. Pass the BARE workflow, not the {"data": {...}} request envelope; this tool adds the envelope itself. A data-wrapped payload is unwrapped automatically and noted in the response, because the raw-API examples in the hyperautomation skill show the on-the-wire body, which already includes that envelope. Generate the workflow using the hyperautomation skill.',
         },
         accountIds: {
           type: 'string',
@@ -233,6 +233,26 @@ export const tools = [
       } catch (e) {
         return JSON.stringify({ error: `Invalid JSON: ${e.message}` });
       }
+      // Accept the wire-shaped payload as well as the bare workflow.
+      //
+      // The import endpoint's body is {"data": {...}} and the skill's raw-API examples
+      // show it that way, correctly. This tool supplies that envelope, so pasting a
+      // documented example sent {"data":{"data":{...}}} and the API answered 422
+      // `body.data.name Field required`, which reads like a schema problem in the
+      // workflow rather than one extra level of nesting.
+      //
+      // Unwrap only when it is unambiguous: a `data` object present AND no top-level
+      // `name`. A bare workflow legitimately carrying its own `data` key keeps it.
+      let unwrapped = false;
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+          && parsed.data && typeof parsed.data === 'object' && !Array.isArray(parsed.data)
+          && parsed.name === undefined) {
+        parsed = parsed.data;
+        unwrapped = true;
+        process.stderr.write(
+          '[ha_import_workflow] payload arrived wrapped in {"data": ...}; unwrapped before sending. ' +
+          'Pass the bare workflow object to this tool; the "data" envelope is for raw API calls.\n');
+      }
       // Public import endpoint. Append the scope query param: account-level imports use
       // ?accountIds=, site-level use ?siteIds=. A bare import (no scope) returns a misleading
       // 403 on a scoped tenant (validated 2026-06-13).
@@ -240,6 +260,13 @@ export const tools = [
       if (accountIds) qs = `?accountIds=${encodeURIComponent(accountIds)}`;
       else if (siteIds) qs = `?siteIds=${encodeURIComponent(siteIds)}`;
       const result = await apiPost(`${HA_PUBLIC}/workflow-import-export/import${qs}`, { data: parsed });
+      if (unwrapped) {
+        return JSON.stringify({
+          importNote: 'The payload arrived wrapped in {"data": ...} and was unwrapped before sending. ' +
+                      'That envelope belongs to raw API calls; pass the bare workflow object to this tool.',
+          ...result,
+        }, null, 2);
+      }
       return JSON.stringify(result, null, 2);
     },
   },
@@ -247,13 +274,22 @@ export const tools = [
   // ─── ha_export_workflow ───────────────────────────────────────────────────
   {
     name: 'ha_export_workflow',
-    description: `Export all Hyperautomation workflows as a ZIP archive. Returns metadata about the ZIP (size, content-type) plus the first 200 bytes of the base64-encoded content. NOTE: The export API (confirmed via live backtest) returns ALL workflows; there is no per-workflow filter. Use ha_get_workflow to read a specific workflow's JSON definition instead. Export/import endpoints were not captured in the v1 network trace; this tool uses the confirmed /public path.`,
+    description: `Export Hyperautomation workflows as a ZIP archive. Returns metadata about the ZIP (size, content-type) plus the first 200 bytes of the base64-encoded content. NOTE: there is no per-workflow filter; the API returns every workflow in scope. Use ha_get_workflow to read a specific workflow's JSON definition instead. Scope with accountIds or siteIds: on a scoped tenant an unscoped call can return a 403 "Insufficient permissions" that is really a scoping problem, the same misleading failure ha_import_workflow documents. Requires Hyper Automate.view permission.`,
     inputSchema: {
       type: 'object',
-      properties: {},
+      properties: {
+        accountIds: {
+          type: 'string',
+          description: 'Account scope for an account-level export (e.g. "2046190533732727925"). Provide this OR siteIds. Omit to use the token default.',
+        },
+        siteIds: {
+          type: 'string',
+          description: 'Site scope for a site-level export. Provide this OR accountIds.',
+        },
+      },
       required: [],
     },
-    async handler() {
+    async handler({ accountIds, siteIds } = {}) {
       // Export path confirmed working during backtest at /public path.
       // GET returns binary ZIP of ALL workflows; POST returns 405.
       // Per-workflow filter is not supported by this API version.
@@ -261,7 +297,10 @@ export const tools = [
       const creds = getCreds();
       const base = creds.S1_CONSOLE_URL.replace(/\/+$/, '');
       const tok  = creds.S1_CONSOLE_API_TOKEN;
-      const url  = `${base}${HA_PUBLIC}/workflow-import-export/export`;
+      let qs = '';
+      if (accountIds) qs = `?accountIds=${encodeURIComponent(accountIds)}`;
+      else if (siteIds) qs = `?siteIds=${encodeURIComponent(siteIds)}`;
+      const url  = `${base}${HA_PUBLIC}/workflow-import-export/export${qs}`;
 
       const res = await fetch(url, {
         method: 'GET',
@@ -269,7 +308,14 @@ export const tools = [
       });
       if (!res.ok) {
         const text = await res.text();
-        throw new Error(`ha_export_workflow → ${res.status}: ${text}`);
+        // A 403 here has two causes and the message does not distinguish them, so name
+        // both rather than letting the reader assume it is only about roles.
+        const hint = res.status === 403 && !qs
+          ? '. Two possible causes: the token lacks Hyper Automate.view, OR this is a' +
+            ' scoped tenant and the call needs accountIds/siteIds. Retry with a scope' +
+            ' before concluding it is a permission problem.'
+          : '';
+        throw new Error(`ha_export_workflow → ${res.status}: ${text}${hint}`);
       }
       const buf    = await res.arrayBuffer();
       const base64 = Buffer.from(buf).toString('base64');

package/tools/mgmt-console.js

@@ -346,7 +346,7 @@ export const tools = [
   // ─── uam_available_actions ────────────────────────────────────────────────
   {
     name: 'uam_available_actions',
-    description: `Ask the API which actions can be triggered on a UAM alert, with isDisabled and disabledReason per action. This is the authoritative capability answer and the ONLY correct way to explain a refused write. A refused action returns errorMessage "Missing UAM manage permissions" whether the token lacks a scope OR the action is simply not offered for that alert type, and those need opposite responses. Measured on one tenant with one token: an alert ingested via the UAM Alert Interface (/v1/alerts) offers only S1/alert/addNote and S1/alert/eventSearch, so uam_set_status can never work on it and no token change helps; a native STAR / third-party / correlation alert offers S1/alert/statusUpdate and S1/alert/analystVerdictUpdate and the same token applies them successfully. Call this before concluding anything about permissions, and before a bulk write you cannot undo. Availability is also scope-sensitive: the S1/incident/* actions report INCIDENT_ACTIONS_ONLY_AVAILABLE_FROM_SITE_VIEW under ACCOUNT scope and are enabled under SITE, so pass scopeIds/scopeType when you care about a site-scoped action. Read-only.`,
+    description: `Ask the API which actions can be triggered on a UAM alert, with isDisabled and disabledReason per action. This is the authoritative capability answer and the ONLY correct way to explain a refused write. Availability is filtered by the caller's permissions AND the alert type: one service-user token is offered S1/alert/statusUpdate on a native STAR alert and not on an alert ingested via the UAM Alert Interface (/v1/alerts), where only S1/alert/addNote and S1/alert/eventSearch are listed, while a console user session performs the identical mutation on either. So an action missing here means this identity lacks the permission for this alert type, not that it is impossible: check the service user's UAM permissions. Call this before concluding anything about permissions, and before a bulk write you cannot undo. Availability is also scope-sensitive: the S1/incident/* actions report INCIDENT_ACTIONS_ONLY_AVAILABLE_FROM_SITE_VIEW under ACCOUNT scope and are enabled under SITE, so pass scopeIds/scopeType when you care about a site-scoped action. Read-only.`,
     inputSchema: {
       type: 'object',
       properties: {

package/tools/sdl-api.js

@@ -65,13 +65,38 @@ export const tools = [
           description: 'Optional filter, e.g. "/dashboards/" or "/logParsers/". Applied client-side to the full listing.',
         },
         scope: scopeProp,
+        // See the note in sdl_list_dashboards: no `default:` keywords, because the host
+        // currently rejects any omitted property that declares one.
+        limit: {
+          type: 'number',
+          description: 'Maximum files to return. Defaults to 500, clamped to 5000. Narrow with pathPrefix first; paging a filtered list is cheaper than paging everything.',
+        },
+        offset: {
+          type: 'number',
+          description: 'Index to start from. Defaults to 0. Page with offset += limit while offset is less than totalCount.',
+        },
       },
       required: [],
     },
-    async handler({ pathPrefix, scope } = {}) {
+    async handler({ pathPrefix, scope, limit = 500, offset = 0 } = {}) {
       let files = await configFiles({ scope });
       if (pathPrefix) files = files.filter(f => (f.name || '').startsWith(pathPrefix));
-      return JSON.stringify({ count: files.length, scope: scope ?? null, files }, null, 2);
+      const lim = Math.max(1, Math.min(Number(limit) || 500, 5000));
+      const off = Math.max(0, Number(offset) || 0);
+      const page = files.slice(off, off + lim);
+      const returnedEnd = off + page.length;
+      return JSON.stringify({
+        // `count` kept as the full post-filter total so existing callers that read it
+        // still get the number they expect; `returned` is the size of this page.
+        count: files.length,
+        returned: page.length,
+        offset: off,
+        limit: lim,
+        hasMore: returnedEnd < files.length,
+        nextOffset: returnedEnd < files.length ? returnedEnd : null,
+        scope: scope ?? null,
+        files: page,
+      }, null, 2);
     },
   },
 
@@ -172,15 +197,54 @@ export const tools = [
   // ─── sdl_list_dashboards ──────────────────────────────────────────────────
   {
     name: 'sdl_list_dashboards',
-    description: `List dashboards visible at the given scope via the GraphQL dashboardsV2 query, returning {id, name, description, configType, access:{public, users, owner}} each. Prefer this over sdl_list_files when you need the owner or the sharing state; use sdl_list_files when you need the config-file version for optimistic locking. The "id" here IS the "udoId" in sdl_list_files, they address the same object. ${SCOPE_NOTE}`,
+    description: `List dashboards visible at the given scope via the GraphQL dashboardsV2 query, returning {id, name, description, configType, access:{public, users, owner}} each. Prefer this over sdl_list_files when you need the owner or the sharing state; use sdl_list_files when you need the config-file version for optimistic locking. The "id" here IS the "udoId" in sdl_list_files, they address the same object. PAGINATED: the full listing is unbounded and on a large tenant it is enormous (measured on an MSSP account: 442,581 characters, 17,111 lines, far past any usable context budget), so this returns at most "limit" dashboards starting at "offset", newest API order preserved. totalCount always reports the full number so you can tell when you are seeing a page. Use namesOnly to get just {id, name} when you are resolving a name to an id, which is the common case and roughly four times smaller. NOTE that "id" is null for dashboards created the old, name-addressed way, before udoIds existed; only dashboards created through the dashboardsV2 surface carry one. On an established account most predate it: measured 397 of 1,555 with an id, and sdl_list_files reports exactly the same 397, so a null is the object's age and not a gap in this tool. Address a legacy dashboard by its "/dashboards/<name>" path. Results come back ordered by name and that order is stable across calls, so offset paging is safe; page on "name", not on "id". ${SCOPE_NOTE}`,
     inputSchema: {
       type: 'object',
-      properties: { scope: scopeProp },
+      properties: {
+        scope: scopeProp,
+        // No `default:` keywords here deliberately. The Claude Code host currently
+        // converts a JSON-Schema `default` into a non-optional Zod field, so a property
+        // carrying one is REJECTED when omitted ("expected nonoptional, received
+        // undefined") before the call ever reaches this server. Declaring defaults here
+        // would make sdl_list_dashboards unusable without passing every argument, which
+        // is the bug this release documents. Defaults live in the handler signature and
+        // are stated in these descriptions instead.
+        limit: {
+          type: 'number',
+          description: 'Maximum dashboards to return. Defaults to 100, clamped to 1000. The full listing is unbounded; this cap is what stops a large tenant blowing the context budget.',
+        },
+        offset: {
+          type: 'number',
+          description: 'Index to start from. Defaults to 0. Page with offset += limit while offset is less than totalCount.',
+        },
+        namesOnly: {
+          type: 'boolean',
+          description: 'Return only {id, name} per dashboard. Defaults to false. Much smaller; use when resolving a name to an id.',
+        },
+      },
       required: [],
     },
-    async handler({ scope } = {}) {
-      const dashboards = await listDashboards({ scope });
-      return JSON.stringify({ count: dashboards.length, scope: scope ?? null, dashboards }, null, 2);
+    async handler({ scope, limit = 100, offset = 0, namesOnly = false } = {}) {
+      const all = await listDashboards({ scope });
+      // Clamp rather than reject: a caller asking for 100000 wants "all of them", and
+      // failing the call teaches nothing. The cap is what protects the context budget.
+      const lim = Math.max(1, Math.min(Number(limit) || 100, 1000));
+      const off = Math.max(0, Number(offset) || 0);
+      const page = all.slice(off, off + lim);
+      const dashboards = namesOnly
+        ? page.map(d => ({ id: d.id, name: d.name }))
+        : page;
+      const returnedEnd = off + dashboards.length;
+      return JSON.stringify({
+        totalCount: all.length,
+        returned: dashboards.length,
+        offset: off,
+        limit: lim,
+        hasMore: returnedEnd < all.length,
+        nextOffset: returnedEnd < all.length ? returnedEnd : null,
+        scope: scope ?? null,
+        dashboards,
+      }, null, 2);
     },
   },