@fluentcommerce/fluent-mcp-extn 0.2.0 → 0.3.0

package/docs/RUNBOOK.md

@@ -1,233 +1,315 @@
-# Operations Runbook
-
-This runbook explains how to configure, verify, and troubleshoot
-`fluent-mcp-extn` in day-to-day usage.
-
-## 1) Prerequisites
-
-- Node.js 20+
-- npm available
-- valid Fluent credentials (profile, OAuth, token command, or static token)
-
-## 2) Local setup
-
-```bash
-npm install
-npm run build
-npm test
-npm run e2e:smoke
-```
-
-Profile-based shortcuts:
-
-```bash
-npm run e2e:smoke -- --wizard
-npm run e2e:smoke -- --profile CLIENT_PROFILE
-npm run e2e:smoke -- --profile CLIENT_PROFILE --retailer RETAILER_REF_OR_ID
-npm run e2e:smoke -- --profile CLIENT_PROFILE --all-retailers
-```
-
-Notes:
-- `--wizard` is interactive (TTY required).
-- For CI/non-interactive runs, use explicit flags (`--profile <name> --retailer <id|ref>` or `--profile <name> --all-retailers`).
-- `--profile` only mode may fall back to a retailer that has candidate orders for real-send validation; use `--retailer` for strict retailer scope.
-
-## 3) MCP registration
-
-Add server in your workspace `.mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "fluent-mcp-extn": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["fluent-mcp-extn/dist/index.js"],
-      "env": {
-        "FLUENT_BASE_URL": "https://YOUR_ACCOUNT.sandbox.api.fluentretail.com",
-        "FLUENT_RETAILER_ID": "YOUR_RETAILER_ID",
-        "TOKEN_COMMAND": "vault read -field=token secret/fluent/client-dev"
-      }
-    }
-  }
-}
-```
-
-Reload Cursor after editing `.mcp.json`.
-
-## 4) Startup verification checklist
-
-Run tools in this order:
-
-1. `config.validate`
-2. `health.ping`
-3. `connection.test`
-4. `event.build`
-5. `event.send` with `dryRun: true`
-6. `event.send` with `dryRun: false`
-7. `event.get` using ID returned by send
-8. `graphql.query` simple read
-9. `workflow.transitions` (optional) — verify User Action API access for a known trigger
-10. `graphql.queryAll` — verify auto-pagination and run-level timeout
-11. `graphql.introspect` with `listMutations: true` — verify schema access
-12. (optional) `graphql.query` synchronous fulfilment options call
-    (`createFulfilmentOption` with `executionMode: AWAIT_ORCHESTRATION`)
-    for live checkout readiness checks
-
-If all steps pass, runtime wiring is healthy.
-
-Write-safety note:
-- non-idempotent write tools do not auto-retry
-- callers should confirm failures before manual re-submission
-
-## 5) Troubleshooting by symptom
-
-### `sdk adapter: not configured`
-
-Likely causes:
-
-- `FLUENT_BASE_URL` missing
-- auth vars missing or invalid
-- `TOKEN_COMMAND` failing
-
-Actions:
-
-1. call `config.validate`
-2. inspect `errors` and `warnings`
-3. verify env vars in `.mcp.json`
-4. reload Cursor MCP process
-
-### `AUTH_ERROR`
-
-Likely causes:
-
-- invalid client credentials
-- expired static token
-- vault command returning stale/empty token
-
-Actions:
-
-1. test auth source directly (OAuth or command output)
-2. ensure token command output is either raw token or JSON with
-   `access_token`/`token`
-3. confirm account permissions for target APIs
-4. for static token mode, rotate token at source (API still enforces true expiry)
-
-### `FLUENT_PROFILE` could not be loaded
-
-Likely causes:
-
-- profile name is wrong
-- retailer ref in `FLUENT_PROFILE_RETAILER` does not match `retailer.<ref>.json`
-- profile files are missing in `~/.fluentcommerce/<profile>/`
-
-Actions:
-
-1. run `fluent profile list`
-2. verify `FLUENT_PROFILE` value and active profile files
-3. if using `FLUENT_PROFILE_RETAILER`, confirm it matches retailer **ref** (not ID)
-4. set `FLUENT_PROFILE_DIR` only if profiles are stored outside default path
-
-### `TIMEOUT_ERROR` / `NETWORK_ERROR`
-
-Likely causes:
-
-- temporary upstream instability
-- strict timeout/retry values
-- DNS/proxy/firewall constraints
-
-Actions:
-
-1. increase `FLUENT_REQUEST_TIMEOUT_MS`
-2. increase `FLUENT_RETRY_ATTEMPTS`
-3. verify base URL and outbound connectivity
-4. for `graphql.queryAll`, increase tool-level `timeoutMs` (controls whole pagination run)
-
-### `VALIDATION_ERROR`
-
-Likely causes:
-
-- missing required tool fields
-- wrong payload shape
-
-Actions:
-
-1. follow examples in `docs/TOOL_REFERENCE.md`
-2. check `error.details.issues` path/message pairs
-
-### Webhook signature validation mismatches
-
-Likely causes:
-
-- validating a re-serialized JSON object rather than original webhook body bytes
-- incorrect or incomplete public key
-
-Actions:
-
-1. pass exact raw HTTP body via `rawBody` in `webhook.validate`
-2. verify signature header value is unchanged
-3. confirm algorithm (`SHA512withRSA` default)
-
-### `SDK_ERROR` with `Request failed: 400` on `event.send`
-
-Likely causes:
-
-- event payload `retailerId` does not match the target entity's retailer
-- sending with only `entityRef` when workflow expects ID-aware routing
-
-Actions:
-
-1. query the target entity via `graphql.query` and capture `id`, `ref`, and retailer
-2. send event with matching `retailerId`
-3. include `entityId` and `rootEntityId` when available
-
-### `SDK_ERROR` with `Workflow [FULFILMENT_OPTIONS::<type>] not found`
-
-Likely causes:
-
-- fulfilment options workflow not deployed for this retailer
-- `type` / `orderType` does not map to a deployed workflow subtype
-- mutation is sent to the wrong retailer ID/environment
-
-Actions:
-
-1. list workflows for target context and confirm `FULFILMENT_OPTIONS::<type>`
-   exists
-2. deploy/merge the required fulfilment options workflow for checkout
-3. re-run mutation with matching `retailerId`, `type`, and `orderType`
-4. verify synchronous response includes `plans`/`fulfilments`
-
-## 6) Reliability tuning guidance
-
-Start with defaults and adjust only when needed.
-
-- low latency APIs: keep defaults
-- slower integrations: increase timeout to 45-60s
-- intermittent networks: increase retries to 4-5
-- write operations are timeout-only; retries apply to read paths only
-- SDK internal retries are disabled; adapter policy is the single retry control
-
-Example:
-
-```json
-{
-  "FLUENT_REQUEST_TIMEOUT_MS": "45000",
-  "FLUENT_RETRY_ATTEMPTS": "4",
-  "FLUENT_RETRY_INITIAL_DELAY_MS": "400",
-  "FLUENT_RETRY_MAX_DELAY_MS": "6000",
-  "FLUENT_RETRY_FACTOR": "2"
-}
-```
-
-## 7) Safe extension workflow
-
-When adding or changing a tool:
-
-1. update schema in `src/tools.ts`
-2. keep response envelopes consistent
-3. route API calls via `FluentClientAdapter`
-4. add unit tests
-5. run:
-   - `npm run build`
-   - `npm test`
-
+# Operations Runbook
+
+This runbook explains how to configure, verify, and troubleshoot
+`fluent-mcp-extn` in day-to-day usage.
+
+## 1) Prerequisites
+
+- Node.js 20+
+- npm available
+- valid Fluent credentials (profile, OAuth, token command, or static token)
+
+## 2) Local setup
+
+```bash
+npm install
+npm run build
+npm test
+npm run e2e:smoke
+```
+
+Profile-based shortcuts:
+
+```bash
+npm run e2e:smoke -- --wizard
+npm run e2e:smoke -- --profile CLIENT_PROFILE
+npm run e2e:smoke -- --profile CLIENT_PROFILE --retailer RETAILER_REF_OR_ID
+npm run e2e:smoke -- --profile CLIENT_PROFILE --all-retailers
+```
+
+Notes:
+- `--wizard` is interactive (TTY required).
+- For CI/non-interactive runs, use explicit flags (`--profile <name> --retailer <id|ref>` or `--profile <name> --all-retailers`).
+- `--profile` only mode may fall back to a retailer that has candidate orders for real-send validation; use `--retailer` for strict retailer scope.
+
+## 3) MCP registration
+
+Add server in your workspace `.mcp.json`.
+
+### OAuth / Token Command mode
+
+```json
+{
+  "mcpServers": {
+    "fluent-mcp-extn": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["fluent-mcp-extn/dist/index.js"],
+      "env": {
+        "FLUENT_BASE_URL": "https://YOUR_ACCOUNT.sandbox.api.fluentretail.com",
+        "FLUENT_RETAILER_ID": "YOUR_RETAILER_ID",
+        "TOKEN_COMMAND": "vault read -field=token secret/fluent/client-dev"
+      }
+    }
+  }
+}
+```
+
+### Profile mode (recommended)
+
+```json
+{
+  "mcpServers": {
+    "fluent-mcp-extn": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["fluent-mcp-extn/dist/index.js"],
+      "env": {
+        "FLUENT_PROFILE": "HMDEV",
+        "FLUENT_PROFILE_RETAILER": "HM_TEST"
+      }
+    }
+  }
+}
+```
+
+Profile mode reads credentials from `~/.fluentcommerce/<profile>/` and
+auto-resolves the retailer ID from the retailer ref. No base URL, client ID,
+or secrets are needed in `.mcp.json`.
+
+Reload your IDE after editing `.mcp.json`.
+
+## 4) Startup verification checklist
+
+Run tools in this order:
+
+1. `config.validate`
+2. `health.ping`
+3. `connection.test`
+4. `event.build`
+5. `event.send` with `dryRun: true`
+6. `event.send` with `dryRun: false`
+7. `event.get` using ID returned by send
+8. `graphql.query` simple read
+9. `entity.get` — verify entity lookup works (e.g., look up a known order by ref)
+10. `setting.get` with `name: "fc.mystique.manifest.%"` — verify settings read access and wildcard support
+11. `workflow.list` — verify REST workflow API access (list all workflows for a retailer)
+12. `workflow.get` with `entityType: "ORDER", entitySubtype: "HD"` — verify specific workflow fetch
+13. `workflow.transitions` (optional) — verify User Action API access for a known trigger
+14. `graphql.queryAll` — verify auto-pagination and run-level timeout
+12. `graphql.introspect` with `listMutations: true` — verify schema access
+13. `environment.discover` with `include: ["retailer", "locations"]` — verify environment snapshot
+14. `environment.validate` with `checks: ["auth", "retailer", "locations"]` — verify pre-flight checks
+15. (optional) `graphql.query` synchronous fulfilment options call
+    (`createFulfilmentOption` with `executionMode: AWAIT_ORCHESTRATION`)
+    for live checkout readiness checks
+
+If all steps pass, runtime wiring is healthy.
+
+Write-safety note:
+- non-idempotent write tools do not auto-retry
+- callers should confirm failures before manual re-submission
+
+## 5) Response shaping configuration
+
+Response shaping controls how large API responses are processed before being
+returned to the LLM. When a response exceeds the budget, arrays are
+auto-summarized (not truncated) with record counts, field inventories, value
+distributions, and sample records.
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `FLUENT_RESPONSE_BUDGET_CHARS` | `50000` (~12.5k tokens) | Max serialized response size. Set to `0` to disable (unlimited). |
+| `FLUENT_RESPONSE_MAX_ARRAY` | `50` | Arrays exceeding this size are auto-summarized. Only active when budget > 0. |
+| `FLUENT_RESPONSE_SAMPLE_SIZE` | `3` | Number of sample records included in array summaries. |
+
+Set these in the `env` block of your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "fluent-mcp-extn": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["fluent-mcp-extn/dist/index.js"],
+      "env": {
+        "FLUENT_PROFILE": "HMDEV",
+        "FLUENT_RESPONSE_BUDGET_CHARS": "80000",
+        "FLUENT_RESPONSE_MAX_ARRAY": "100",
+        "FLUENT_RESPONSE_SAMPLE_SIZE": "5"
+      }
+    }
+  }
+}
+```
+
+When shaping is active, responses include a `_responseMeta` object with
+`originalChars`, `shapedChars`, `reductionPercent`, and `summarizedArrays`.
+
+## 6) Troubleshooting by symptom
+
+### `sdk adapter: not configured`
+
+Likely causes:
+
+- `FLUENT_BASE_URL` missing
+- auth vars missing or invalid
+- `TOKEN_COMMAND` failing
+
+Actions:
+
+1. call `config.validate`
+2. inspect `errors` and `warnings`
+3. verify env vars in `.mcp.json`
+4. reload your IDE's MCP process
+
+### `AUTH_ERROR`
+
+Likely causes:
+
+- invalid client credentials
+- expired static token
+- vault command returning stale/empty token
+
+Actions:
+
+1. test auth source directly (OAuth or command output)
+2. ensure token command output is either raw token or JSON with
+   `access_token`/`token`
+3. confirm account permissions for target APIs
+4. for static token mode, rotate token at source (API still enforces true expiry)
+
+### `FLUENT_PROFILE` could not be loaded
+
+Likely causes:
+
+- profile name is wrong
+- retailer ref in `FLUENT_PROFILE_RETAILER` does not match `retailer.<ref>.json`
+- profile files are missing in `~/.fluentcommerce/<profile>/`
+
+Actions:
+
+1. run `fluent profile list`
+2. verify `FLUENT_PROFILE` value and active profile files
+3. if using `FLUENT_PROFILE_RETAILER`, confirm it matches retailer **ref** (not ID)
+4. set `FLUENT_PROFILE_DIR` only if profiles are stored outside default path
+
+### `TIMEOUT_ERROR` / `NETWORK_ERROR`
+
+Likely causes:
+
+- temporary upstream instability
+- strict timeout/retry values
+- DNS/proxy/firewall constraints
+
+Actions:
+
+1. increase `FLUENT_REQUEST_TIMEOUT_MS`
+2. increase `FLUENT_RETRY_ATTEMPTS`
+3. verify base URL and outbound connectivity
+4. for `graphql.queryAll`, increase tool-level `timeoutMs` (controls whole pagination run)
+
+### `VALIDATION_ERROR`
+
+Likely causes:
+
+- missing required tool fields
+- wrong payload shape
+
+Actions:
+
+1. follow examples in `docs/TOOL_REFERENCE.md`
+2. check `error.details.issues` path/message pairs
+
+### Webhook signature validation mismatches
+
+Likely causes:
+
+- validating a re-serialized JSON object rather than original webhook body bytes
+- incorrect or incomplete public key
+
+Actions:
+
+1. pass exact raw HTTP body via `rawBody` in `webhook.validate`
+2. verify signature header value is unchanged
+3. confirm algorithm (`SHA512withRSA` default)
+
+### `SDK_ERROR` with `Request failed: 400` on `event.send`
+
+Likely causes:
+
+- event payload `retailerId` does not match the target entity's retailer
+- sending with only `entityRef` when workflow expects ID-aware routing
+
+Actions:
+
+1. query the target entity via `graphql.query` and capture `id`, `ref`, and retailer
+2. send event with matching `retailerId`
+3. include `entityId` and `rootEntityId` when available
+
+### `SDK_ERROR` with `Workflow [FULFILMENT_OPTIONS::<type>] not found`
+
+Likely causes:
+
+- fulfilment options workflow not deployed for this retailer
+- `type` / `orderType` does not map to a deployed workflow subtype
+- mutation is sent to the wrong retailer ID/environment
+
+Actions:
+
+1. list workflows for target context and confirm `FULFILMENT_OPTIONS::<type>`
+   exists
+2. deploy/merge the required fulfilment options workflow for checkout
+3. re-run mutation with matching `retailerId`, `type`, and `orderType`
+4. verify synchronous response includes `plans`/`fulfilments`
+
+### Response appears truncated or incomplete
+
+Likely causes:
+
+- `FLUENT_RESPONSE_BUDGET_CHARS` is set too low for the query
+- large arrays are being auto-summarized (check for `_responseMeta` in response)
+
+Actions:
+
+1. check the `_responseMeta` object — if `reductionPercent` is high, the budget
+   is actively shaping the response
+2. increase `FLUENT_RESPONSE_BUDGET_CHARS` (e.g., `80000` or `100000`)
+3. increase `FLUENT_RESPONSE_MAX_ARRAY` if specific arrays are being summarized
+4. set `FLUENT_RESPONSE_BUDGET_CHARS=0` to disable shaping entirely
+5. for `event.flowInspect`, use `compact: true` (default) to get a pre-analyzed
+   summary instead of raw arrays
+
+## 7) Reliability tuning guidance
+
+Start with defaults and adjust only when needed.
+
+- low latency APIs: keep defaults
+- slower integrations: increase timeout to 45-60s
+- intermittent networks: increase retries to 4-5
+- write operations are timeout-only; retries apply to read paths only
+- SDK internal retries are disabled; adapter policy is the single retry control
+
+Example:
+
+```json
+{
+  "FLUENT_REQUEST_TIMEOUT_MS": "45000",
+  "FLUENT_RETRY_ATTEMPTS": "4",
+  "FLUENT_RETRY_INITIAL_DELAY_MS": "400",
+  "FLUENT_RETRY_MAX_DELAY_MS": "6000",
+  "FLUENT_RETRY_FACTOR": "2"
+}
+```
+
+## 8) Safe extension workflow
+
+When adding or changing a tool:
+
+1. update schema in `src/tools.ts`
+2. keep response envelopes consistent
+3. route API calls via `FluentClientAdapter`
+4. add unit tests
+5. run:
+   - `npm run build`
+   - `npm test`