@pmoses-s1/s1-secops-mcp 1.3.0

package/scripts/smoke-test-http.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+#
+# smoke-test-http.sh -- generic HTTP smoke test for s1-secops-mcp.
+#
+# Exercises the public contract end-to-end:
+#   1. healthz returns 200 (no auth)
+#   2. initialize returns the expected protocol version and server info
+#   3. tools/list returns 26 tools
+#   4. tools/call s1_api_get works (uses /agents/count as a cheap probe)
+#   5. bad bearer returns HTTP 401
+#   6. unknown method returns JSON-RPC error -32601 inside a 200 envelope
+#
+# Useful for new team members verifying their setup, or for re-checking the
+# deployment after a config change, a cert rotation, or an MCP version bump.
+#
+# Run as:
+#   MCP_HOST=mcp.s1.internal:8764 \
+#   MCP_BEARER=your-bearer-token \
+#     bash s1-secops-mcp/scripts/smoke-test-http.sh
+#
+# Or set defaults at the top of the script and run with no args.
+
+set -uo pipefail
+
+HOST="${MCP_HOST:-}"
+TOKEN="${MCP_BEARER:-}"
+
+if [[ -z "$HOST" || -z "$TOKEN" ]]; then
+  cat >&2 <<EOF
+Usage:
+  MCP_HOST=<host:port> MCP_BEARER=<token> bash $0
+
+Both env vars are required.
+EOF
+  exit 2
+fi
+
+for tool in curl jq; do
+  if ! command -v "$tool" >/dev/null 2>&1; then
+    echo "Missing dependency: $tool" >&2
+    exit 3
+  fi
+done
+
+URL="https://$HOST/mcp"
+AUTH="Authorization: Bearer $TOKEN"
+JSON="Content-Type: application/json"
+
+FAILED=0
+fail() {
+  echo "  FAIL: $*" >&2
+  FAILED=$((FAILED + 1))
+}
+pass() { echo "  PASS: $*"; }
+
+echo "=== 1. healthz (no auth) ==="
+HEALTHZ_CODE=$(curl -s -o /dev/null -w "%{http_code}" "https://$HOST/healthz")
+[[ "$HEALTHZ_CODE" == "200" ]] && pass "healthz returned 200" || fail "healthz returned $HEALTHZ_CODE (expected 200)"
+
+echo
+echo "=== 2. initialize ==="
+INIT_BODY=$(curl -s -X POST "$URL" -H "$AUTH" -H "$JSON" -d '{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2024-11-05",
+    "capabilities": {},
+    "clientInfo": { "name": "smoke-test", "version": "1" }
+  }
+}')
+PROTO=$(echo "$INIT_BODY" | jq -r '.result.protocolVersion // "missing"')
+NAME=$(echo "$INIT_BODY" | jq -r '.result.serverInfo.name    // "missing"')
+VER=$(echo "$INIT_BODY" | jq -r '.result.serverInfo.version // "missing"')
+[[ "$PROTO" == "2024-11-05" ]] && pass "protocolVersion=$PROTO" || fail "protocolVersion=$PROTO"
+[[ "$NAME" == "s1-secops-mcp-server" ]] && pass "serverInfo.name=$NAME" || fail "serverInfo.name=$NAME"
+[[ "$VER" != "missing" ]] && pass "serverInfo.version=$VER" || fail "serverInfo.version missing"
+
+echo
+echo "=== 3. tools/list count ==="
+TOOLS_COUNT=$(curl -s -X POST "$URL" -H "$AUTH" -H "$JSON" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' |
+  jq '.result.tools | length')
+[[ "$TOOLS_COUNT" == "26" ]] && pass "tools/list returned 26 tools" || fail "tools/list returned $TOOLS_COUNT"
+
+echo
+echo "=== 4. tools/call s1_api_get on /agents/count ==="
+AGENTS_TOTAL=$(curl -s -X POST "$URL" -H "$AUTH" -H "$JSON" -d '{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "s1_api_get",
+    "arguments": { "path": "/web/api/v2.1/agents/count" }
+  }
+}' | jq -r '.result.content[0].text' | jq -r '.data.total // "missing"')
+if [[ "$AGENTS_TOTAL" =~ ^[0-9]+$ ]]; then
+  pass "s1_api_get returned $AGENTS_TOTAL agents"
+else
+  fail "s1_api_get returned data.total=$AGENTS_TOTAL"
+fi
+
+echo
+echo "=== 5. bad bearer (expect HTTP 401) ==="
+BAD_CODE=$(curl -s -o /dev/null -w "%{http_code}" -X POST "$URL" \
+  -H "Authorization: Bearer wrong-token-of-sufficient-length-1234567890" -H "$JSON" \
+  -d '{"jsonrpc":"2.0","id":99,"method":"tools/list"}')
+[[ "$BAD_CODE" == "401" ]] && pass "bad bearer rejected with 401" || fail "bad bearer returned $BAD_CODE (expected 401)"
+
+echo
+echo "=== 6. method not found (expect -32601) ==="
+ERR_CODE=$(curl -s -X POST "$URL" -H "$AUTH" -H "$JSON" \
+  -d '{"jsonrpc":"2.0","id":4,"method":"does/not/exist"}' |
+  jq -r '.error.code // "missing"')
+[[ "$ERR_CODE" == "-32601" ]] && pass "unknown method returned -32601" || fail "unknown method returned code=$ERR_CODE"
+
+echo
+echo "=== Summary ==="
+if [[ "$FAILED" -eq 0 ]]; then
+  echo "All checks passed."
+  exit 0
+else
+  echo "$FAILED check(s) failed."
+  exit 1
+fi

package/scripts/test-mac.sh

@@ -0,0 +1,187 @@
+#!/usr/bin/env bash
+#
+# Mac validation script for s1-secops-mcp (version read from package.json).
+#
+# Runs the same test matrix as Linux:
+#   - syntax-check every .js/.mjs file
+#   - npm test (smoke + stdio + HTTP + regression suites)
+#   - regen:readme --check (no doc drift)
+#   - sanity-run the server in stdio and HTTP modes
+#
+# Run this from the s1-secops-mcp/ directory on your Mac:
+#
+#   cd ~/path/to/claude-skills/s1-secops-mcp
+#   bash scripts/test-mac.sh
+#
+# All checks should pass with green PASS markers. Any FAIL line should be
+# reported back so the issue can be diagnosed.
+
+set -uo pipefail
+
+PASS_COUNT=0
+FAIL_COUNT=0
+
+green() { printf '\033[32m%s\033[0m' "$*"; }
+red() { printf '\033[31m%s\033[0m' "$*"; }
+bold() { printf '\033[1m%s\033[0m' "$*"; }
+
+pass() {
+  printf '  %s %s\n' "$(green PASS)" "$1"
+  PASS_COUNT=$((PASS_COUNT + 1))
+}
+fail() {
+  printf '  %s %s\n  %s\n' "$(red FAIL)" "$1" "${2:-}"
+  FAIL_COUNT=$((FAIL_COUNT + 1))
+}
+step() { printf '\n%s\n' "$(bold "$1")"; }
+
+# ─── 1. Environment ───────────────────────────────────────────────────────────
+
+step "1. Environment"
+if [[ "$(uname -s)" != "Darwin" ]]; then
+  echo "  WARNING: this script targets macOS but you're on $(uname -s). Continuing anyway."
+fi
+if ! command -v node >/dev/null 2>&1; then
+  fail "node not on PATH" "Install Node 18+: brew install node@20"
+  exit 1
+fi
+NODE_MAJOR="$(node --version | sed 's/^v\([0-9]*\).*/\1/')"
+if [[ "$NODE_MAJOR" -lt 18 ]]; then
+  fail "Node $(node --version) is too old" "Need Node 18+"
+  exit 1
+fi
+pass "Node $(node --version) on $(uname -srm)"
+
+if [[ ! -f "index.js" ]]; then
+  fail "Not in the s1-secops-mcp directory" "cd to .../claude-skills/s1-secops-mcp first"
+  exit 1
+fi
+pass "running from s1-secops-mcp directory"
+
+# ─── 2. Syntax check ──────────────────────────────────────────────────────────
+
+step "2. Syntax check"
+for f in index.js lib/*.js tests/*.mjs scripts/*.mjs; do
+  [[ -f "$f" ]] || continue
+  if node --check "$f" 2>/dev/null; then
+    pass "$f"
+  else
+    out="$(node --check "$f" 2>&1)"
+    fail "$f" "$out"
+  fi
+done
+
+# ─── 3. npm test (22 assertions across smoke + stdio + HTTP) ─────────────────
+
+step "3. Test suite (npm test)"
+# Node 18-22 default to the TAP reporter, Node 23+ default to spec. Both
+# reporters print the same passing assertions but with different summary
+# lines. We check exit code first (authoritative) and then count assertions.
+TEST_LOG="/tmp/mcp-test-mac.npm-test.log"
+if npm test >"$TEST_LOG" 2>&1; then
+  # Count passing assertions across both reporter formats:
+  #   TAP:   "ok 1 - <name>"
+  #   spec:  "✔ <name>" (U+2714 HEAVY CHECK MARK)
+  TAP_OKS="$(grep -cE '^ok [0-9]+' "$TEST_LOG" || true)"
+  SPEC_OKS="$(grep -cE '^[[:space:]]*✔' "$TEST_LOG" || true)"
+  TOTAL=$((TAP_OKS + SPEC_OKS))
+  if [[ "$TOTAL" -ge 22 ]]; then
+    pass "$TOTAL passing assertions (npm test exit 0)"
+  else
+    fail "npm test exited 0 but only $TOTAL passing lines found" "$(tail -30 "$TEST_LOG")"
+  fi
+else
+  fail "npm test exited non-zero" "$(tail -30 "$TEST_LOG")"
+fi
+
+# ─── 4. README/code drift check ───────────────────────────────────────────────
+
+step "4. README/code drift check"
+if npm run regen:readme -- --check >/dev/null 2>&1; then
+  pass "README tools table in sync with ALL_TOOLS"
+else
+  fail "README tools table is stale" "Run: npm run regen:readme"
+fi
+
+# ─── 5. CLI flag sanity ───────────────────────────────────────────────────────
+
+step "5. CLI flag sanity"
+# Read the expected version from package.json so this check never goes stale.
+PKG_VERSION="$(node -p "require('./package.json').version")"
+if [[ "$(node index.js --version 2>/dev/null)" == "$PKG_VERSION" ]]; then
+  pass "--version returns $PKG_VERSION"
+else
+  fail "--version did not return $PKG_VERSION" "Got: $(node index.js --version 2>&1)"
+fi
+if node index.js --help 2>&1 | grep -q "s1-secops-mcp $PKG_VERSION"; then
+  pass "--help renders"
+else
+  fail "--help broken" "$(node index.js --help 2>&1 | head -5)"
+fi
+
+# ─── 6. stdio round-trip ──────────────────────────────────────────────────────
+
+step "6. stdio round-trip"
+STDIO_REPLY="$(printf '%s\n%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"mac-test","version":"1"}}}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' |
+  node index.js 2>/dev/null)"
+
+TOOL_COUNT="$(echo "$STDIO_REPLY" | tail -n 1 | node -e 'let s=""; process.stdin.on("data",d=>s+=d); process.stdin.on("end",()=>{try{console.log(JSON.parse(s).result.tools.length)}catch(e){console.log("ERR")}})')"
+if [[ "$TOOL_COUNT" == "26" ]]; then
+  pass "stdio tools/list returned 26 tools"
+else
+  fail "stdio tools/list returned $TOOL_COUNT (expected 26)" "$STDIO_REPLY"
+fi
+
+# ─── 7. HTTP transport round-trip ─────────────────────────────────────────────
+
+step "7. HTTP transport round-trip"
+PORT=$((10000 + RANDOM % 1000))
+node index.js --transport http --port "$PORT" --host 127.0.0.1 >/tmp/mcp-test-mac.log 2>&1 &
+SERVER_PID=$!
+trap 'kill $SERVER_PID 2>/dev/null || true' EXIT
+
+# Wait for healthz
+for i in $(seq 1 30); do
+  if curl -sf "http://127.0.0.1:$PORT/healthz" >/dev/null 2>&1; then
+    pass "HTTP server up on port $PORT"
+    break
+  fi
+  sleep 0.2
+  if [[ "$i" -eq 30 ]]; then
+    fail "HTTP server did not start within 6s" "$(cat /tmp/mcp-test-mac.log)"
+    exit 1
+  fi
+done
+
+HTTP_REPLY="$(curl -sf -X POST "http://127.0.0.1:$PORT/mcp" \
+  -H 'Content-Type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}')"
+HTTP_COUNT="$(echo "$HTTP_REPLY" | node -e 'let s=""; process.stdin.on("data",d=>s+=d); process.stdin.on("end",()=>{try{console.log(JSON.parse(s).result.tools.length)}catch(e){console.log("ERR")}})')"
+if [[ "$HTTP_COUNT" == "26" ]]; then
+  pass "HTTP tools/list returned 26 tools"
+else
+  fail "HTTP tools/list returned $HTTP_COUNT" "$HTTP_REPLY"
+fi
+
+# Auth: with no token loaded the server should accept unauthenticated requests
+# (single-user local-only mode). Confirmed by the 26-tools response above.
+pass "no-auth mode allows requests (single-user local)"
+
+kill $SERVER_PID 2>/dev/null || true
+trap - EXIT
+
+# ─── Summary ──────────────────────────────────────────────────────────────────
+
+step "Summary"
+printf "  Passed: %s\n" "$(green "$PASS_COUNT")"
+if [[ "$FAIL_COUNT" -gt 0 ]]; then
+  printf "  Failed: %s\n\n" "$(red "$FAIL_COUNT")"
+  echo "If any FAILs above, paste them so the issue can be diagnosed."
+  exit 1
+else
+  printf "  Failed: %s\n\n" "$FAIL_COUNT"
+  echo "$(green 'All checks passed on macOS.')"
+  exit 0
+fi

package/tools/hyperautomation.js

@@ -0,0 +1,284 @@
+/**
+ * Hyperautomation tools: hyperautomation skill
+ *
+ * Tools:
+ *   ha_list_workflows     List Hyperautomation workflows (with scope/state/sort filters)
+ *   ha_get_workflow       Get a single workflow by ID (+ optional revisionId)
+ *   ha_delete_workflow    Delete (soft, recoverable) a workflow via REST DELETE
+ *   ha_import_workflow    Import (create) a workflow from JSON (account- or site-scoped)
+ *   ha_export_workflow    Export all workflows as a ZIP archive
+ *
+ * API root (confirmed via live network capture 2026-05-03):
+ *   /web/api/v2.1/hyper-automate/api/v1
+ *
+ * Single-workflow fetch requires BOTH workflowId AND revisionId:
+ *   GET /workflows/single/{workflowId}/{revisionId}
+ * The revisionId is workflow.version_id in the list response.
+ *
+ * Deletion is a soft, recoverable HTTP DELETE (validated 2026-06-13):
+ *   DELETE /workflows/{id}?accountIds=<acct>   (or ?siteIds=<site>)
+ * The older POST /workflows/archive returns 500 on this tenant: do not use it.
+ *
+ * Import scope: the public import endpoint accepts ?accountIds=<acct> or
+ * ?siteIds=<site>; with no scope it returns a misleading 403 on a scoped tenant.
+ */
+
+import { apiGet, apiPost, apiDelete } from '../lib/s1.js';
+
+// Confirmed base path from live network monitor (2026-05-03).
+const HA_BASE = '/web/api/v2.1/hyper-automate/api/v1';
+
+// Export/import confirmed on /public path during backtest; not re-captured under /v1.
+const HA_PUBLIC = '/web/api/v2.1/hyper-automate/api/public';
+
+export const tools = [
+  // ─── ha_list_workflows ────────────────────────────────────────────────────
+  {
+    name: 'ha_list_workflows',
+    description: `List SentinelOne Hyperautomation workflows. Returns workflow ID, version_id (revisionId for ha_get_workflow), name, state, status, trigger types, action types, scope, and timestamps. Supports filtering by siteId, state, and sorting. Use siteIds to scope to a specific site. State values: active, inactive, deactivated, draft. Requires Hyper Automate.view permission.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: {
+          type: 'number',
+          description: 'Max workflows per page (default 50, max 200).',
+          default: 50,
+        },
+        skip: {
+          type: 'number',
+          description: 'Offset for pagination (default 0).',
+          default: 0,
+        },
+        siteIds: {
+          type: 'string',
+          description: 'Comma-separated site IDs to scope results to (e.g. "<site-id-1>,<site-id-2>"). Omit for all accessible scopes.',
+        },
+        sortBy: {
+          type: 'string',
+          description: 'Sort field. Default: updated_at.',
+          enum: ['updated_at', 'created_at', 'name'],
+          default: 'updated_at',
+        },
+        sortOrder: {
+          type: 'string',
+          description: 'Sort direction.',
+          enum: ['asc', 'desc'],
+          default: 'desc',
+        },
+      },
+      required: [],
+    },
+    async handler({ limit = 50, skip = 0, siteIds, sortBy = 'updated_at', sortOrder = 'desc' } = {}) {
+      const params = {
+        limit: Math.min(limit, 200),
+        skip,
+        sortBy,
+        sortOrder,
+      };
+      if (siteIds) params.siteIds = siteIds;
+      const result = await apiGet(`${HA_BASE}/workflows`, params);
+      // Summarise for readability: include key fields the LLM needs for follow-up calls.
+      const items = (result?.data || []).map(item => ({
+        id:          item.id,
+        revisionId:  item.workflow?.version_id,     // needed for ha_get_workflow
+        name:        item.workflow?.name,
+        state:       item.workflow?.state,           // active | inactive | deactivated | draft
+        status:      item.workflow?.status,          // idle | running | etc.
+        scopeLevel:  item.workflow?.scope_level,     // account | site
+        scopeId:     item.workflow?.scope_id,
+        siteName:    item.workflow?.site_name,
+        createdAt:   item.workflow?.created_at,
+        updatedAt:   item.workflow?.updated_at,
+        versionCount: item.workflow?.version_count,
+        triggerTypes: [...new Set((item.actions || [])
+          .filter(a => a.type?.endsWith('_trigger'))
+          .map(a => a.type))],
+        actionTypes:  [...new Set((item.actions || [])
+          .filter(a => !a.type?.endsWith('_trigger'))
+          .map(a => a.type))],
+        integrationIds: [...new Set((item.actions || [])
+          .filter(a => a.integration_id)
+          .map(a => a.integration_id))],
+      }));
+      return JSON.stringify({
+        workflows: items,
+        totalItems: result?.pagination?.totalItems ?? null,
+        skip,
+        limit: params.limit,
+      }, null, 2);
+    },
+  },
+
+  // ─── ha_get_workflow ──────────────────────────────────────────────────────
+  {
+    name: 'ha_get_workflow',
+    description: `Get a single Hyperautomation workflow by workflowId and revisionId. The revisionId (= workflow.version_id) is returned by ha_list_workflows; always pass both IDs for a direct fetch. If revisionId is omitted, the tool will scan the first page of workflows to find the current revision, which is slower. Returns the full workflow object including trigger configuration, action steps, integration dependencies, scope, and version metadata.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        workflowId: {
+          type: 'string',
+          description: 'Hyperautomation workflow UUID (from ha_list_workflows).',
+        },
+        revisionId: {
+          type: 'string',
+          description: 'Workflow version/revision UUID (= workflow.version_id from ha_list_workflows). Provide this to avoid an extra list call.',
+        },
+      },
+      required: ['workflowId'],
+    },
+    async handler({ workflowId, revisionId }) {
+      let resolvedRevisionId = revisionId;
+
+      // If revisionId not supplied, resolve it from the list endpoint.
+      if (!resolvedRevisionId) {
+        // The list endpoint does not support filtering by workflowId, so we scan
+        // up to 200 workflows sorted by updated_at desc (most recently touched first).
+        // Confirmed: GET /workflows/single/{id} alone returns 404; revisionId is required.
+        const listResult = await apiGet(`${HA_BASE}/workflows`, {
+          limit: 200,
+          skip: 0,
+          sortBy: 'updated_at',
+          sortOrder: 'desc',
+        });
+        const found = (listResult?.data || []).find(item => item.id === workflowId);
+        if (!found) {
+          return JSON.stringify({
+            error: `Workflow ${workflowId} not found in the first 200 results. ` +
+              'Provide revisionId directly (from ha_list_workflows) for an exact fetch.',
+          });
+        }
+        resolvedRevisionId = found.workflow?.version_id;
+      }
+
+      // Confirmed endpoint: GET /workflows/single/{workflowId}/{revisionId}
+      const result = await apiGet(`${HA_BASE}/workflows/single/${workflowId}/${resolvedRevisionId}`);
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── ha_delete_workflow ───────────────────────────────────────────────────
+  {
+    name: 'ha_delete_workflow',
+    description: `Delete one or more Hyperautomation workflows. Uses the REST DELETE /hyper-automate/api/v1/workflows/{id} endpoint (validated 2026-06-13), a soft, recoverable delete (the console offers a "Restore workflow" action), equivalent to clicking Delete in the Hyperautomation UI. Scope the call to where the workflow lives with accountIds (account-scoped workflow) or siteIds (site-scoped); a 404 "Object not found" means the id is not under that scope or is already deleted. Requires Hyper Automate.write permission. NOTE: do NOT use the older POST /workflows/archive path; it returns 500 on this tenant.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        workflowIds: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'One or more workflow UUIDs to delete (from ha_list_workflows).',
+        },
+        accountIds: {
+          type: 'string',
+          description: 'Account scope for an account-level workflow (e.g. "2046190533732727925"). Provide this OR siteIds.',
+        },
+        siteIds: {
+          type: 'string',
+          description: 'Site scope for a site-level workflow. Provide this OR accountIds.',
+        },
+      },
+      required: ['workflowIds'],
+    },
+    async handler({ workflowIds, accountIds, siteIds } = {}) {
+      if (!Array.isArray(workflowIds) || workflowIds.length === 0) {
+        return JSON.stringify({ error: 'workflowIds must be a non-empty array of UUIDs.' });
+      }
+      if (!accountIds && !siteIds) {
+        return JSON.stringify({ error: 'Provide accountIds or siteIds to scope the delete to where the workflow lives (a workflow created at a site must be deleted with siteIds; an account-scoped one with accountIds).' });
+      }
+      const scope = accountIds
+        ? `accountIds=${encodeURIComponent(accountIds)}`
+        : `siteIds=${encodeURIComponent(siteIds)}`;
+      const results = [];
+      for (const id of workflowIds) {
+        try {
+          // DELETE returns 204 No Content on success.
+          await apiDelete(`${HA_BASE}/workflows/${encodeURIComponent(id)}?${scope}`);
+          results.push({ id, status: 'deleted' });
+        } catch (e) {
+          results.push({ id, status: 'error', error: e.message });
+        }
+      }
+      return JSON.stringify({ deleted: results }, null, 2);
+    },
+  },
+
+  // ─── ha_import_workflow ───────────────────────────────────────────────────
+  {
+    name: 'ha_import_workflow',
+    description: `Import a Hyperautomation workflow JSON into the SentinelOne console. Scope the import with accountIds (account-level) or siteIds (site-level); on a scoped tenant a bare import with no scope returns a misleading 403 "Insufficient permissions". The workflow JSON must follow the Hyperautomation schema (use the hyperautomation skill to generate valid JSON). Integration-backed actions (type=http_request with an integration_id) require pre-configured connections in Hyperautomation > Integrations before the workflow will run, and an imported flow lands as a private draft until published (publish endpoint) or activated. Returns the created workflow ID on success. Requires Hyper Automate.write permission.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        workflowJson: {
+          type: 'string',
+          description: 'Full Hyperautomation workflow JSON as a string. Must be valid Hyperautomation schema. Generate this using the hyperautomation skill.',
+        },
+        accountIds: {
+          type: 'string',
+          description: 'Account scope for an account-level import (e.g. "2046190533732727925"). Provide this OR siteIds.',
+        },
+        siteIds: {
+          type: 'string',
+          description: 'Site scope for a site-level import. Provide this OR accountIds.',
+        },
+      },
+      required: ['workflowJson'],
+    },
+    async handler({ workflowJson, accountIds, siteIds }) {
+      let parsed;
+      try {
+        parsed = JSON.parse(workflowJson);
+      } catch (e) {
+        return JSON.stringify({ error: `Invalid JSON: ${e.message}` });
+      }
+      // 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).
+      let qs = '';
+      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 });
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── 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.`,
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+    },
+    async handler() {
+      // 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.
+      const { getCreds } = await import('../lib/credentials.js');
+      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`;
+
+      const res = await fetch(url, {
+        method: 'GET',
+        headers: { Authorization: `ApiToken ${tok}` },
+      });
+      if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`ha_export_workflow → ${res.status}: ${text}`);
+      }
+      const buf    = await res.arrayBuffer();
+      const base64 = Buffer.from(buf).toString('base64');
+      return JSON.stringify({
+        note: 'Export returns all workflows as a binary ZIP. Per-workflow filtering is not supported. METADATA ONLY: this tool does not return or persist the ZIP content; use the console UI or a direct API call with file output if you need the archive itself.',
+        contentType: res.headers.get('Content-Type') || 'application/zip',
+        sizeBytes: buf.byteLength,
+        base64Preview: base64.slice(0, 200) + '… [truncated]',
+      }, null, 2);
+    },
+  },
+];