@fluentcommerce/fluent-mcp-extn 0.1.0 → 0.2.0

package/README.md

@@ -1,9 +1,5 @@
 # @fluentcommerce/fluent-mcp-extn
 
-[![npm version](https://img.shields.io/npm/v/@fluentcommerce/fluent-mcp-extn.svg)](https://www.npmjs.com/package/@fluentcommerce/fluent-mcp-extn)
-[![license](https://img.shields.io/npm/l/@fluentcommerce/fluent-mcp-extn.svg)](https://opensource.org/licenses/MIT)
-[![node](https://img.shields.io/node/v/@fluentcommerce/fluent-mcp-extn.svg)](https://nodejs.org/)
-
 > **Alpha** — This package is under active development. APIs, tool signatures, and configuration may change between releases without notice. Use in non-production environments and pin to a specific version if stability matters.
 
 MCP ([Model Context Protocol](https://modelcontextprotocol.io)) extension server for [Fluent Commerce](https://fluentcommerce.com).
@@ -408,16 +404,6 @@ Plus at least one auth method below.
 | `FLUENT_RETRY_MAX_DELAY_MS` | `5000` | Max backoff delay |
 | `FLUENT_RETRY_FACTOR` | `2` | Backoff multiplier |
 
-### Response Shaping
-
-Controls how large responses are handled before returning to the AI. When a response exceeds the budget, arrays are auto-summarized (not truncated) with record counts, field inventory, value distributions, and sample records — giving the AI a complete analytical picture instead of cut-off data.
-
-| Variable | Default | Description |
-|---|---|---|
-| `FLUENT_RESPONSE_BUDGET_CHARS` | `50000` | Max serialized response size (~12.5k tokens). `0` disables (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. |
-
 ## Tools (36)
 
 ### Diagnostics

package/docs/E2E_TESTING.md

@@ -3,23 +3,6 @@
 This guide walks through full validation of `fluent-mcp-extn` from startup to
 real Fluent API operations.
 
-## Script inventory
-
-| Script | Type | Purpose |
-|--------|------|---------|
-| `e2e-smoke.ts` | E2E | Full MCP smoke cycle: tool discovery, config, health, events, GraphQL |
-| `e2e-negative.ts` | E2E | Validation error and malformed input handling |
-| `e2e-profile-test.mjs` | E2E | Quick FLUENT_PROFILE integration check |
-| `e2e-full-order.ts` | E2E | Single order lifecycle: create, validate, fulfil, ship, deliver |
-| `e2e-full-multi.ts` | E2E | ORDER::MULTI lifecycle with discovery and fulfilment event sequence |
-| `e2e-agentic.ts` | E2E | All 11 agentic tools: entity CRUD, workflow, settings, environment |
-| `e2e-response-shaping.ts` | E2E | Response budget enforcement and auto-summarization proof |
-| `run-flow-inspect.ts` | Utility | FlowInspect forensics with local analysis, LLM packet, and drilldowns |
-| `order-event-inspect.ts` | Utility | Order-specific event deep dive with audit trail extraction |
-| `check-event-status.ts` | Utility | Event status polling by ID, name, or entity ref |
-
-All scripts require a built server (`npm run build`) and valid Fluent credentials.
-
 ## 1) Test levels
 
 - **Level 1: local quality gate** (no network)
@@ -70,7 +53,7 @@ Use this as a baseline:
 }
 ```
 
-After editing `.mcp.json`, reload your IDE so MCP servers restart with new env.
+After editing `.mcp.json`, reload Cursor so MCP servers restart with new env.
 
 Profile-first setup via AI Skills:
 
@@ -142,301 +125,7 @@ only when non-skipped steps fail.
 | `SKIP` | Step was intentionally not executed (for example, no candidate order in `--all-retailers` mode). | Verify preconditions only if you expected execution. |
 | `FAIL` | Step executed and returned an error or unexpected result. | Investigate payload/error details and fix before relying on run output. |
 
-## 5) E2E script reference
-
-### `e2e-smoke.ts`
-
-Full MCP client smoke cycle that exercises the core tool chain end to end.
-
-**What it tests:** tool discovery, `config.validate`, `health.ping`, `event.build`,
-`event.send` (dry-run and real), `graphql.query`, `graphql.queryAll`, order lookup,
-`event.get` by ID.
-
-**How to run:**
-
-```bash
-npm run e2e:smoke
-npm run e2e:smoke -- --profile HMDEV
-npm run e2e:smoke -- --profile HMDEV --retailer HM_TEST
-npm run e2e:smoke -- --profile HMDEV --all-retailers
-npm run e2e:smoke -- --skip-real-send
-```
-
-**Environment:** requires `FLUENT_BASE_URL` + auth env vars, or `--profile`.
-
----
-
-### `e2e-negative.ts`
-
-Validates that the server returns correct error envelopes for invalid inputs.
-
-**What it tests:**
-- `event.send` with missing required `entityRef` field
-- `graphql.query` with malformed GraphQL syntax
-- `event.get` with a nonexistent event ID
-- `graphql.introspect` with a nonexistent mutation name
-- `webhook.validate` with an invalid signature and public key
-
-Each test case asserts: `ok: false`, standard error envelope shape
-(`code` + `message` + `retryable`), and expected error code where applicable
-(e.g., `VALIDATION_ERROR`).
-
-**How to run:**
-
-```bash
-npx tsx scripts/e2e-negative.ts
-npx tsx scripts/e2e-negative.ts --profile HMDEV
-npx tsx scripts/e2e-negative.ts --profile HMDEV --retailer HM_TEST
-```
-
-**Environment:** requires `FLUENT_BASE_URL` + auth env vars, or `--profile`.
-
----
-
-### `e2e-profile-test.mjs`
-
-Minimal FLUENT_PROFILE integration check. Loads config, creates SDK client, and
-runs four quick API calls to verify profile-based auth works end to end.
-
-**What it tests:**
-1. Config loads correctly with profile auth strategy
-2. GraphQL `me` query returns user and retailer info
-3. `getEvents` returns event results
-4. `getPlugins` returns the plugin registry
-5. `getTransitions` returns user actions for ORDER::HD at CREATED status
-
-**How to run:**
-
-```bash
-FLUENT_PROFILE=HMDEV FLUENT_PROFILE_RETAILER=HM_TEST node scripts/e2e-profile-test.mjs
-```
-
-**Environment:** requires `FLUENT_PROFILE` and optionally `FLUENT_PROFILE_RETAILER`
-set as env vars. Uses compiled `dist/` output directly (not MCP stdio transport).
-
----
-
-### `e2e-full-order.ts`
-
-Discovery-first single order lifecycle test. Creates an order with
-`sourcingLocationRef`, then drives it through the full fulfilment workflow.
-
-**What it tests:**
-1. Config validation
-2. Discovery: locations, catalogues, products, customers, settings
-3. `createOrder` mutation with sourcing attributes
-4. `ConfirmValidation` event on order
-5. Query order + fulfilments post-validation
-6. Fulfilment events: `ConfirmAllocation`, `CreateInvoice`, `ConfirmPick`,
-   `ConfirmShipment`, `ConfirmDelivery`
-7. Final order/fulfilment state verification
-8. Event trace: counts SUCCESS vs FAILED events for the order
-
-**How to run:**
-
-```bash
-npx tsx scripts/e2e-full-order.ts --profile SAGIRISH --retailer 2
-FLUENT_PROFILE=SAGIRISH FLUENT_RETAILER_ID=2 npx tsx scripts/e2e-full-order.ts
-```
-
-**Environment:** requires `FLUENT_PROFILE` + `FLUENT_RETAILER_ID`, or `--profile`
-and `--retailer` flags. Environment must have warehouse locations, product
-catalogue with active products, and at least one customer entity.
-
-**Note:** this script creates real orders and fires real events. Use a sandbox.
-
----
-
-### `e2e-full-multi.ts`
-
-ORDER::MULTI lifecycle test. Similar to `e2e-full-order.ts` but targets the
-MULTI order type workflow and includes workflow transition discovery.
-
-**What it tests:**
-1. Config validation
-2. Discovery: retailer, locations, catalogues, products, customers, settings
-3. `workflow.transitions` for ORDER::MULTI at ON_VALIDATION status
-4. `createOrder` mutation with MULTI type
-5. `ConfirmValidation` event
-6. Fulfilment creation verification
-7. Fulfilment event sequence: `ConfirmAllocation`, `CreateInvoice`,
-   `ConfirmPick`, `ConfirmShipment`, `ConfirmDelivery`
-8. Event trace on failure
-
-**How to run:**
-
-```bash
-npx tsx scripts/e2e-full-multi.ts
-```
-
-**Environment:** defaults to `FLUENT_BASE_URL=https://sagirish.test.api.fluentretail.com`
-and `FLUENT_RETAILER_ID=2`. Override with env vars. Requires OAuth or profile
-credentials.
-
-**Note:** creates real orders and fires real events. Use a sandbox.
-
----
-
-### `e2e-agentic.ts`
-
-Comprehensive smoke test for all 11 agentic tools against a live environment.
-
-**What it tests:**
-- `environment.discover` (retailer + locations, catalogues)
-- `environment.validate` (auth, retailer, locations checks)
-- `entity.create` (dryRun validation, required field rejection, live creation)
-- `entity.get` (by ID, by ref, nonexistent ref)
-- `entity.update` (attribute update)
-- `test.assert` (status match, status mismatch)
-- `setting.upsert` (create new, update existing with previous value)
-- `workflow.diff` (summary format, mermaid format)
-- `workflow.simulate` (status matching, custom rule confidence, no-match)
-- `workflow.upload` (dryRun structure validation)
-
-**How to run:**
-
-```bash
-npx tsx scripts/e2e-agentic.ts --profile SAGIRISH
-```
-
-**Environment:** requires `FLUENT_PROFILE` or `--profile` flag. Defaults to
-`FLUENT_RETAILER_ID=2`.
-
-**Note:** creates real orders and settings. Use a sandbox.
-
----
-
-### `e2e-response-shaping.ts`
-
-Proves that response shaping (auto-summarization) works correctly on real API
-responses.
-
-**What it proves:**
-1. `event.flowInspect` compact response stays within budget (50k chars)
-2. `event.flowInspect` full mode (`compact: false`) gets auto-summarized, not truncated
-3. `plugin.list` (unfiltered, 500+ rules) gets shaped when large
-4. `event.list` (500 events) gets shaped when large
-5. `_responseMeta` appears with accurate stats (originalChars, shapedChars, reductionPercent)
-6. No `_truncated` markers anywhere (replaced by `_summarized`)
-
-**How to run:**
-
-```bash
-npx tsx scripts/e2e-response-shaping.ts --profile SAGIRISH
-```
-
-**Environment:** requires `FLUENT_PROFILE` or `--profile`. Uses default budget
-(50k chars). The environment must have enough events and plugins to exceed the
-budget threshold.
-
----
-
-### `run-flow-inspect.ts`
-
-Advanced FlowInspect forensics runner. Calls `event.flowInspect`, then performs
-local analysis: risk scoring, finding extraction, evidence ranking, and optional
-per-event drilldowns via `event.get`.
-
-**Outputs:**
-- Raw JSON: full flowInspect response
-- Summary JSON: risk score, status/entity distributions, anomaly counts, webhook
-  failure breakdown, exception classes, slow rulesets, mismatch reasons
-- LLM packet (Markdown): compact handoff document for AI consumption
-- Drilldown JSON: classified event details (webhook, mutation, sendEvent, mismatch)
-
-**How to run:**
-
-```bash
-npx tsx scripts/run-flow-inspect.ts <ROOT_ENTITY_REF> --profile SAGIRISH
-npx tsx scripts/run-flow-inspect.ts HD-001 --root-type ORDER --profile HMDEV
-npx tsx scripts/run-flow-inspect.ts HD-001 --root-id 12345 --light --no-drilldown
-npx tsx scripts/run-flow-inspect.ts HD-001 --drilldown-classes webhook,mutation --drilldown-limit 20
-```
-
-**Options:**
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--profile <name>` | `SAGIRISH` | Fluent CLI profile |
-| `--root-type <type>` | any | Root entity type (ORDER, FULFILMENT, etc.) |
-| `--root-id <id>` | - | Root entity ID for disambiguation |
-| `--out <path>` | `accounts/<profile>/analysis/EVENT_FLOW_INSPECT_<ref>.json` | Raw output path |
-| `--summary-out <path>` | `<base>.summary.json` | Summary output path |
-| `--packet-out <path>` | `<base>.llm-packet.md` | LLM packet output path |
-| `--drilldown-out <path>` | `<base>.drilldown.json` | Drilldown output path |
-| `--light` | false | Compact mode (fewer audit details) |
-| `--no-drilldown` | false | Skip per-event drilldowns |
-| `--drilldown-limit <n>` | 15 | Max events to drill into |
-| `--drilldown-classes <list>` | all | Comma-separated: webhook,mutation,sendEvent,mismatch,exception,scheduled,slow,status |
-| `--top-n <n>` | 10 | Top-N items per section |
-| `--evidence-limit <n>` | 20 | Max evidence event IDs |
-| `--truncate <n>` | 220 | Max chars for text fields |
-| `--max-pages <n>` | 10 | Max 500-event pages to fetch |
-| `--no-llm-pack` | false | Skip LLM packet generation |
-
-**Environment:** requires `FLUENT_PROFILE` or env vars.
-
----
-
-### `order-event-inspect.ts`
-
-Order-specific event deep dive. Looks up an order by ref, then fetches all
-ORCHESTRATION and ORCHESTRATION_AUDIT events, classifying them into webhooks,
-mutations, sendEvent actions, scheduled actions, and ruleset durations.
-
-**Outputs:** a single JSON file with:
-- Order entity details (status, attributes, fulfilment choices)
-- Orchestration events (status counts, entity type counts, top event names)
-- Audit trail (webhook actions, mutation actions, sendEvent actions, scheduled
-  actions, ruleset durations, exceptions)
-- Drilldown details for NO_MATCH and PENDING events
-
-**How to run:**
-
-```bash
-npx tsx scripts/order-event-inspect.ts <ORDER_REF> --profile SAGIRISH
-npx tsx scripts/order-event-inspect.ts HD-001 --profile HMDEV --out /tmp/inspect.json
-```
-
-**Environment:** requires `FLUENT_PROFILE` or env vars.
-
----
-
-### `check-event-status.ts`
-
-Lightweight event status checker. Fetches events by ID or lists events by name
-and entity ref.
-
-**How to run:**
-
-```bash
-# Fetch specific events by ID
-npx tsx scripts/check-event-status.ts --event-id <uuid> --profile SAGIRISH
-
-# List events by name
-npx tsx scripts/check-event-status.ts --event-name ConfirmValidation --profile SAGIRISH
-
-# List events by entity ref
-npx tsx scripts/check-event-status.ts --entity-ref HD-001 --profile SAGIRISH
-
-# Combine filters
-npx tsx scripts/check-event-status.ts --event-name ConfirmValidation --entity-ref HD-001 --count 20 --profile SAGIRISH
-```
-
-**Options:**
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--profile <name>` | - | Fluent CLI profile |
-| `--retailer <id\|ref>` | from profile/env | Retailer filter |
-| `--event-id <uuid>` | - | Fetch specific event (repeatable) |
-| `--event-name <name>` | - | Event name filter for list |
-| `--entity-ref <ref>` | - | Entity ref filter for list |
-| `--count <n>` | 10 | Max list size (max 500) |
-
-**Environment:** requires `FLUENT_BASE_URL` + auth, or `--profile`.
-
-## 6) MCP smoke sequence in your IDE
+## 5) MCP smoke sequence in Cursor
 
 Run these tools in order from the assistant:
 
@@ -635,7 +324,7 @@ Expected:
 - `mutations` array returned
 - `count` reflects available mutations in the schema
 
-## 7) Optional webhook signature validation
+## 6) Optional webhook signature validation
 
 Use this when validating webhook integration cryptography:
 
@@ -657,7 +346,7 @@ Expected:
 - `ok: true` when payload and signature are valid
 - `signatureValidation.payloadSource` confirms whether `rawBody` was used
 
-## 8) Optional batch E2E
+## 7) Optional batch E2E
 
 ### `batch.create`
 
@@ -698,7 +387,7 @@ Expected:
 }
 ```
 
-## 9) Failure triage quick map
+## 8) Failure triage quick map
 
 - `CONFIG_ERROR`: missing env values -> run `config.validate`
 - `AUTH_ERROR`: invalid creds/token -> verify OAuth or `TOKEN_COMMAND`
@@ -706,7 +395,7 @@ Expected:
 - `TIMEOUT_ERROR` / `NETWORK_ERROR`: tune timeout/retry; verify connectivity
 - `RATE_LIMIT` / `UPSTREAM_UNAVAILABLE`: retry later (built-in retries are applied for read operations; write retries are manual by design)
 
-## 10) Exit criteria for successful E2E
+## 9) Exit criteria for successful E2E
 
 Mark E2E successful only when:
 
@@ -719,7 +408,7 @@ Mark E2E successful only when:
 - (optional) `graphql.introspect` schema access confirmed
 - (optional) batch cycle completed
 
-## 11) CI-triggered smoke (GitHub Actions)
+## 10) CI-triggered smoke (GitHub Actions)
 
 Workflow: `.github/workflows/ci.yml`
 
@@ -737,3 +426,4 @@ Set repository or environment secrets before running `e2e-smoke`:
 
 CI smoke runs are typically env-driven (no `--profile` required). For profile-based runs in CI, pass explicit flags (`--profile <name> --retailer <id|ref>` or `--profile <name> --all-retailers`).
 If real event side effects are not desired, run with `--skip-real-send`.
+

package/docs/RUNBOOK.md

@@ -34,9 +34,7 @@ Notes:
 
 ## 3) MCP registration
 
-Add server in your workspace `.mcp.json`.
-
-### OAuth / Token Command mode
+Add server in your workspace `.mcp.json`:
 
 ```json
 {
@@ -55,29 +53,7 @@ Add server in your workspace `.mcp.json`.
 }
 ```
 
-### 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`.
+Reload Cursor after editing `.mcp.json`.
 
 ## 4) Startup verification checklist
 
@@ -91,13 +67,10 @@ Run tools in this order:
 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. `workflow.transitions` (optional) — verify User Action API access for a known trigger
-11. `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
+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
 
@@ -107,43 +80,7 @@ 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
+## 5) Troubleshooting by symptom
 
 ### `sdk adapter: not configured`
 
@@ -158,7 +95,7 @@ Actions:
 1. call `config.validate`
 2. inspect `errors` and `warnings`
 3. verify env vars in `.mcp.json`
-4. reload your IDE's MCP process
+4. reload Cursor MCP process
 
 ### `AUTH_ERROR`
 
@@ -260,24 +197,7 @@ Actions:
 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
+## 6) Reliability tuning guidance
 
 Start with defaults and adjust only when needed.
 
@@ -299,7 +219,7 @@ Example:
 }
 ```
 
-## 8) Safe extension workflow
+## 7) Safe extension workflow
 
 When adding or changing a tool:
 
@@ -310,3 +230,4 @@ When adding or changing a tool:
 5. run:
    - `npm run build`
    - `npm test`
+