@fluentcommerce/fluent-mcp-extn 0.1.0

package/README.md

@@ -0,0 +1,818 @@
+# @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).
+
+Exposes event dispatch, transition actions, GraphQL operations, Prometheus metrics queries, batch ingestion, webhook validation, entity lifecycle management, workflow management, settings management, environment discovery, and test automation as MCP tools — powered by [`@fluentcommerce/fc-connect-sdk`](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk).
+
+**What this does:** This server runs as a background process inside your AI coding assistant (Claude Code, Cursor, VS Code Copilot, Windsurf, etc.). It gives the AI direct, authenticated access to Fluent Commerce APIs — so the AI can query orders, send events, inspect workflows, check metrics, and run diagnostics on your behalf, using natural language.
+
+## Table of Contents
+
+- [End-User Setup Checklist (First 15 Minutes)](#end-user-setup-checklist-first-15-minutes)
+- [MCP Config File Locations](#mcp-config-file-locations)
+- [Why This Extension](#why-this-extension)
+- [Quick Start](#quick-start)
+- [End-to-End Validation](#end-to-end-validation)
+- [Compatibility](#compatibility)
+- [Requirements](#requirements)
+- [Install](#install)
+- [Configuration](#configuration)
+- [Tools (36)](#tools-36)
+- [Error Handling](#error-handling)
+- [Support Scripts (Debugging and Validation)](#support-scripts-debugging-and-validation)
+- [Troubleshooting](#troubleshooting)
+- [Development Workflow](#development-workflow)
+- [Workspace Integration](#workspace-integration)
+- [Companion Packages](#companion-packages)
+- [NPM Publish Checklist (Maintainers)](#npm-publish-checklist-maintainers)
+- [License](#license)
+
+## End-User Setup Checklist (First 15 Minutes)
+
+Follow this exact order for the smoothest first run:
+
+1. Confirm prerequisites:
+   - `node -v` (must be `>=20`)
+   - if using profile auth: `fluent profile list`
+2. Add one `fluent-mcp-extn` server entry in your workspace MCP config (see [MCP Config File Locations](#mcp-config-file-locations)).
+3. Prefer **Option A (profile auth)** first for local usage, because it avoids copying secrets into `.mcp.json`.
+4. Restart your IDE/agent session so MCP servers reload.
+5. Run these tools in order:
+   - `config.validate`
+   - `health.ping`
+   - `connection.test`
+6. Run a safe event validation:
+   - `event.build`
+   - `event.send` with `dryRun: true`
+7. Only then run `event.send` with `dryRun: false` when you are ready for a real event.
+
+If any step fails, jump to [Troubleshooting](#troubleshooting).
+
+## MCP Config File Locations
+
+| Client | Recommended MCP config file |
+|---|---|
+| Claude Code | `.mcp.json` (workspace root) |
+| Cursor | `.mcp.json` (workspace root) or `.cursor/mcp.json` |
+| VS Code Copilot | `.vscode/mcp.json` |
+| GitHub Copilot Agent | Repository MCP settings |
+| Windsurf | Workspace/app MCP settings |
+
+## Why This Extension
+
+The official `fluent mcp server` (bundled with Fluent CLI) covers core GraphQL and workflow operations. This extension adds capabilities typically needed for implementation and diagnostics:
+
+| Capability | Official MCP | This Extension |
+|---|:---:|:---:|
+| Event dispatch (`event.build` / `event.send` / `event.list` / `event.get`) | | Yes |
+| Event runtime forensics (`event.flowInspect`) | | Yes |
+| Workflow transitions (`workflow.transitions`) | | Yes |
+| Auto-paginated GraphQL (`graphql.queryAll`) | | Yes |
+| Batch mutations (`graphql.batchMutate`) | | Yes |
+| Batch ingestion (`batch.*`) | | Yes |
+| Prometheus metrics (`metrics.query`) | | Yes |
+| Metrics health assessment (`metrics.healthCheck`) | | Yes |
+| Managed SLO snapshot (`metrics.sloReport`) | | Yes |
+| Metric label discovery (`metrics.labelCatalog`) | | Yes |
+| Event analytics rankings (`metrics.topEvents`) | | Yes |
+| Webhook signature validation | | Yes |
+| Schema introspection (`graphql.introspect`) | | Yes |
+| Multi-strategy auth (profile, OAuth, token command, static token) | | Yes |
+| Entity CRUD (`entity.create` / `entity.update` / `entity.get`) | | Yes |
+| Workflow management (`workflow.upload` / `workflow.diff` / `workflow.simulate`) | | Yes |
+| Settings management (`setting.upsert` / `setting.bulkUpsert`) | | Yes |
+| Environment snapshot (`environment.discover` / `environment.validate`) | | Yes |
+| Test assertions with polling (`test.assert`) | | Yes |
+
+Best practice: run both the official MCP server and this extension together.
+
+## Quick Start
+
+### 1. Add MCP server entry
+
+Add to your project's `.mcp.json` (merge with existing servers, don't overwrite). Pick one of the options below.
+
+#### Option A: Fluent CLI Profile (recommended)
+
+Reuses your existing Fluent CLI profile — no credentials in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "fluent-mcp-extn": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@fluentcommerce/fluent-mcp-extn"],
+      "env": {
+        "FLUENT_PROFILE": "YOUR_PROFILE",
+        "FLUENT_PROFILE_RETAILER": "YOUR_RETAILER_REF"
+      }
+    }
+  }
+}
+```
+
+Use retailer **ref** in `FLUENT_PROFILE_RETAILER` (for example `RETAILER_REF`), not retailer ID.
+
+Reads base URL, client ID/secret, username/password, and retailer ID from `~/.fluentcommerce/YOUR_PROFILE/`. Requires Fluent CLI to be installed with at least one profile configured (`fluent profile list`).
+
+#### Option B: Explicit OAuth credentials
+
+Pass all credentials directly in env vars:
+
+```json
+{
+  "mcpServers": {
+    "fluent-mcp-extn": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@fluentcommerce/fluent-mcp-extn"],
+      "env": {
+        "FLUENT_BASE_URL": "https://YOUR_ACCOUNT.sandbox.api.fluentretail.com",
+        "FLUENT_RETAILER_ID": "YOUR_RETAILER_ID",
+        "FLUENT_CLIENT_ID": "YOUR_CLIENT_ID",
+        "FLUENT_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
+        "FLUENT_USERNAME": "YOUR_USERNAME",
+        "FLUENT_PASSWORD": "YOUR_PASSWORD"
+      }
+    }
+  }
+}
+```
+
+#### Option C: Profile + overrides (hybrid)
+
+Use a profile as the base, override specific values via env vars:
+
+```json
+{
+  "mcpServers": {
+    "fluent-mcp-extn": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@fluentcommerce/fluent-mcp-extn"],
+      "env": {
+        "FLUENT_PROFILE": "YOUR_PROFILE",
+        "FLUENT_PROFILE_RETAILER": "YOUR_RETAILER_REF",
+        "FLUENT_RETAILER_ID": "YOUR_RETAILER_ID"
+      }
+    }
+  }
+}
+```
+
+Any explicit `FLUENT_*` env var overrides the value from the profile. Setting `FLUENT_BASE_URL` or OAuth env vars disables `createClientFromProfile` and falls back to standard OAuth (profile values still used as defaults for unset vars).
+
+#### Option D: Token command (vault / CI integration)
+
+For CI pipelines or environments where credentials come from a vault or external process:
+
+```json
+{
+  "mcpServers": {
+    "fluent-mcp-extn": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@fluentcommerce/fluent-mcp-extn"],
+      "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/api",
+        "TOKEN_COMMAND_TIMEOUT_MS": "10000"
+      }
+    }
+  }
+}
+```
+
+The command must print a valid bearer token to stdout. Token is cached for 55 minutes before re-executing the command.
+
+#### Option E: Static bearer token
+
+For quick testing with a pre-obtained token:
+
+```json
+{
+  "mcpServers": {
+    "fluent-mcp-extn": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@fluentcommerce/fluent-mcp-extn"],
+      "env": {
+        "FLUENT_BASE_URL": "https://YOUR_ACCOUNT.sandbox.api.fluentretail.com",
+        "FLUENT_RETAILER_ID": "YOUR_RETAILER_ID",
+        "FLUENT_ACCESS_TOKEN": "YOUR_BEARER_TOKEN"
+      }
+    }
+  }
+}
+```
+
+No automatic refresh — the token will expire according to its original grant TTL.
+
+#### Auth priority order
+
+When multiple auth methods are configured, the first valid method wins:
+
+1. **Profile** — `FLUENT_PROFILE` set → uses SDK `createClientFromProfile`
+2. **OAuth** — `FLUENT_CLIENT_ID` + `FLUENT_CLIENT_SECRET` → SDK-native OAuth with automatic refresh
+3. **Token command** — `TOKEN_COMMAND` → executes shell command, caches token for 55 min
+4. **Static token** — `FLUENT_ACCESS_TOKEN` → no refresh, dev fallback only
+
+### 2. Restart your IDE
+
+Restart so the MCP client picks up the new server.
+
+### 3. Verify connection
+
+Run these tools in order to confirm everything works:
+
+1. `config.validate` — should return `ok: true`
+2. `health.ping` — should return `ok: true`
+3. `connection.test` — should return `ok: true` with your user/account details
+
+If any returns `ok: false`, see [Troubleshooting](#troubleshooting).
+
+### 4. Try a real call
+
+```
+event.build  →  build a payload (no API call)
+event.send with dryRun: true  →  validate without sending
+event.send with dryRun: false  →  send for real
+```
+
+### Automated setup via AI Skills
+
+If you use `@fluentcommerce/ai-skills`, it can generate `.mcp.json` for both servers:
+
+```bash
+npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE
+npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE --profile-retailer YOUR_RETAILER_REF
+```
+
+## End-to-End Validation
+
+Run this sequence after setup to verify runtime + real API integration:
+
+```bash
+cd fluent-mcp-extn
+npm install
+npm run build
+npm test
+npm run e2e:smoke -- --wizard
+npm run e2e:smoke -- --profile YOUR_PROFILE
+npm run e2e:smoke -- --profile YOUR_PROFILE --retailer YOUR_RETAILER_REF_OR_ID
+npm run e2e:smoke -- --profile YOUR_PROFILE --all-retailers
+```
+
+What this smoke test validates:
+
+- tools are discoverable (`tools.list`)
+- config is valid (`config.validate`)
+- runtime starts cleanly (`health.ping`)
+- event payload build and dry-run send
+- GraphQL connectivity (`__typename` and order lookup)
+- real `event.send` on a candidate order
+- event retrieval via `event.get`
+
+Notes:
+
+- `--wizard` provides guided profile/account and retailer selection for interactive runs
+- `--wizard` requires an interactive terminal (TTY); in CI/non-interactive shells use explicit flags (`--profile <name> --retailer <id|ref>` or `--profile <name> --all-retailers`)
+- `--retailer` accepts retailer ID or retailer ref
+- `--all-retailers` requires `--profile` and runs one cycle per profile retailer file (`retailer.<ref>.json`), labeled as `retailer-<id>`
+- use `--skip-real-send` to avoid real event side effects
+- for profile-based setup, prefer retailer ref in `FLUENT_PROFILE_RETAILER`
+- in `--all-retailers` mode, retailers without a candidate order are reported as skipped (not failed)
+- with `--profile` only (no `--retailer` / `--all-retailers`), smoke may fall back to a retailer that has candidate orders for real-send validation; use `--retailer` for strict retailer scope
+
+## Compatibility
+
+Works with any MCP client that supports stdio servers:
+
+| Client | MCP config location |
+|---|---|
+| Claude Code | `.mcp.json` (workspace root) |
+| Cursor | `.mcp.json` (workspace root) or `.cursor/mcp.json` |
+| VS Code Copilot | `.vscode/mcp.json` |
+| GitHub Copilot Agent | Repository MCP settings |
+| Windsurf | Workspace/app MCP settings |
+
+## Requirements
+
+- Node.js 20+
+- Fluent CLI installed when using profile auth (`FLUENT_PROFILE`)
+- Fluent Commerce API credentials (see [Configuration](#configuration))
+
+## Install
+
+### From npm (recommended)
+
+No install needed — `npx` runs it directly from the npm registry:
+
+```bash
+npx @fluentcommerce/fluent-mcp-extn
+```
+
+This starts the MCP stdio server process. In a plain terminal it appears idle because it is waiting for MCP JSON-RPC input from your IDE/agent.
+
+Or install as a project dependency:
+
+```bash
+npm install @fluentcommerce/fluent-mcp-extn
+```
+
+### From source
+
+```bash
+git clone https://bitbucket.org/fluentcommerce/fluent-mcp-extn.git
+cd fluent-mcp-extn
+npm install && npm run build
+```
+
+Then use in `.mcp.json`:
+
+```json
+{
+  "command": "node",
+  "args": ["path/to/fluent-mcp-extn/dist/index.js"]
+}
+```
+
+## Configuration
+
+All configuration is via environment variables in your `.mcp.json` `env` block. Never commit credentials to git.
+
+### Required
+
+| Variable | Description |
+|---|---|
+| `FLUENT_BASE_URL` | Fluent Commerce API base URL |
+
+Plus at least one auth method below.
+
+### Authentication (first valid method wins)
+
+#### 1. Fluent CLI profile (recommended for local development)
+
+| Variable | Required | Description |
+|---|---|---|
+| `FLUENT_PROFILE` | Yes | Fluent CLI profile name (`~/.fluentcommerce/<profile>`) |
+| `FLUENT_PROFILE_RETAILER` | No | Retailer **ref** (matches `retailer.<ref>.json`) |
+| `FLUENT_PROFILE_DIR` | No | Override profile base directory (defaults to `~/.fluentcommerce`) |
+
+`FLUENT_PROFILE_RETAILER` allows retailer-scoped user credential overrides from profile files.
+
+#### 2. OAuth
+
+| Variable | Required | Description |
+|---|---|---|
+| `FLUENT_CLIENT_ID` | Yes | OAuth client ID |
+| `FLUENT_CLIENT_SECRET` | Yes | OAuth client secret |
+| `FLUENT_USERNAME` | No | Username (for password grant) |
+| `FLUENT_PASSWORD` | No | Password (for password grant) |
+
+#### 3. Token command
+
+| Variable | Default | Description |
+|---|---|---|
+| `TOKEN_COMMAND` | — | Shell command that prints a bearer token to stdout |
+| `TOKEN_COMMAND_TIMEOUT_MS` | `10000` | Timeout for the command |
+
+#### 4. Static token
+
+| Variable | Description |
+|---|---|
+| `FLUENT_ACCESS_TOKEN` | Pre-obtained bearer token |
+
+### Optional
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLUENT_RETAILER_ID` | — | Default retailer for events and batch operations |
+| `FLUENT_ACCOUNT_ID` | — | Default account for events |
+
+### Resilience Tuning
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLUENT_REQUEST_TIMEOUT_MS` | `30000` | Request timeout |
+| `FLUENT_RETRY_ATTEMPTS` | `3` | Retry attempts for read operations |
+| `FLUENT_RETRY_INITIAL_DELAY_MS` | `300` | Initial backoff delay |
+| `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
+
+| Tool | Description |
+|---|---|
+| `config.validate` | Validate auth and base URL configuration |
+| `health.ping` | Quick connectivity check |
+| `connection.test` | Full auth + GraphQL end-to-end test (returns user/account context) |
+
+### Events
+
+| Tool | Description |
+|---|---|
+| `event.build` | Build event payload without sending (validation only) |
+| `event.send` | Build and send event (supports `dryRun: true`) |
+| `event.get` | Fetch a single event by ID |
+| `event.list` | List/filter events with pagination |
+| `event.flowInspect` | One-call root-entity flow forensics — works for ORDER/FULFILMENT/LOCATION/WAVE/PRODUCT and more |
+
+`event.flowInspect` supports any entity type. Pass `rootEntityType` when you want strict filtering; omit it to inspect by root ref only. Use `rootEntityId` when refs are reused and you need exact disambiguation.
+
+**Compact mode (default `compact: true`):** Returns a pre-analyzed summary (~2-3k tokens) with an `analysis` section containing anomaly findings, status flow, failed webhook endpoints, and slowest rulesets. Set `compact: false` for full raw data (~24k tokens).
+
+**Default-on flags:** `compact`, `includeAudit`, `includeExceptions`, `includeNoMatchDetails`, `includeEventDetails`, `includeScheduled`
+
+**Opt-in flags (default false):**
+- `includeRuleDetails` — per-rule execution trace with class name, props, and timing
+- `includeCustomLogs` — custom plugin log messages (LogCollection)
+- `includeSnapshots` — entity state snapshots at each processing point
+- `includeCrossEntity` — child entity events (FULFILMENT_CHOICE, FULFILMENT)
+
+**Example** — compact forensics (recommended first call):
+
+```json
+{
+  "rootEntityRef": "ORD-001",
+  "rootEntityType": "ORDER"
+}
+```
+
+**Example** — full data with all sections:
+
+```json
+{
+  "rootEntityRef": "ORD-001",
+  "rootEntityType": "ORDER",
+  "compact": false,
+  "includeRuleDetails": true,
+  "includeCustomLogs": true,
+  "includeSnapshots": true,
+  "includeCrossEntity": true
+}
+```
+
+**Example** — lightweight (minimal output):
+
+```json
+{
+  "rootEntityRef": "ORD-001",
+  "rootEntityType": "ORDER",
+  "includeAudit": false,
+  "includeEventDetails": false,
+  "includeExceptions": false,
+  "includeNoMatchDetails": false,
+  "maxDrilldowns": 0
+}
+```
+
+### Local-First LLM Reduction (flowInspect)
+
+If `event.flowInspect` returns large JSON, run local analysis first and only send compact artifacts to an LLM:
+
+```bash
+npx tsx scripts/run-flow-inspect.ts <ROOT_ENTITY_REF> --profile <PROFILE>
+```
+
+This writes:
+
+- `EVENT_FLOW_INSPECT_<ref>.json` (raw)
+- `EVENT_FLOW_INSPECT_<ref>.summary.json` (local anomaly + metrics summary)
+- `EVENT_FLOW_INSPECT_<ref>.drilldown.json` (focused `event.get` extraction for top evidence IDs)
+- `EVENT_FLOW_INSPECT_<ref>.llm-packet.md` (small LLM handoff packet)
+
+Useful flags:
+
+- `--light` uses compact fetch mode for faster runs
+- `--root-type ...` and `--root-id ...` tighten entity matching
+- `--drilldown` / `--no-drilldown` toggle focused `event.get` enrichment
+- `--drilldown-limit` controls how many top evidence IDs get enriched
+- `--drilldown-classes webhook,mutation,sendEvent,mismatch,exception,scheduled,slow,status` limits enrichment to selected evidence classes
+- `--top-n`, `--evidence-limit`, `--truncate` control summary/packet compactness
+- `--no-llm-pack` skips markdown packet output
+
+### Metrics
+
+| Tool | Description |
+|---|---|
+| `metrics.query` | Query Prometheus metrics using instant or range mode |
+| `metrics.healthCheck` | One-call anomaly check with Prometheus-first + Event API fallback |
+| `metrics.sloReport` | Managed-services SLO snapshot (rates + p95 latency + findings) |
+| `metrics.labelCatalog` | Discover supported metric labels from live series + known Fluent hints |
+| `metrics.topEvents` | Aggregate and rank top events by name/entity/status in a time window |
+
+### Orchestration
+
+| Tool | Description |
+|---|---|
+| `workflow.transitions` | Query available user actions/transitions for provided triggers (`POST /api/v4.1/transition`) |
+| `plugin.list` | List all registered rules with metadata (`GET /orchestration/rest/v1/plugin`). Supports optional name filter. |
+
+**Example** — get actions for a ServicePoint manifest trigger:
+
+```json
+{
+  "triggers": [
+    {
+      "type": "MANIFEST",
+      "subtype": "DEFAULT",
+      "status": "PENDING",
+      "module": "servicepoint",
+      "flexType": "CARRIER::DEFAULT",
+      "retailerId": "2"
+    }
+  ]
+}
+```
+
+**Example** — list all rules matching "SendEvent":
+
+```json
+{
+  "name": "SendEvent"
+}
+```
+
+### GraphQL
+
+| Tool | Description |
+|---|---|
+| `graphql.query` | Execute any query or mutation |
+| `graphql.queryAll` | Auto-paginated query — follows cursors across all pages |
+| `graphql.batchMutate` | Execute up to 50 mutations in one request |
+| `graphql.introspect` | Inspect schema types, mutations, and input fields |
+
+**Example** — query orders:
+
+```json
+{
+  "query": "{ orders(first: 5) { edges { cursor node { id ref status } } pageInfo { hasNextPage } } }"
+}
+```
+
+**Example** — auto-paginate all active orders:
+
+```json
+{
+  "query": "{ orders(first: 100, after: $cursor) { edges { cursor node { id ref status } } pageInfo { hasNextPage } } }",
+  "variables": { "cursor": null },
+  "maxRecords": 5000
+}
+```
+
+**Example** — batch update 3 orders:
+
+```json
+{
+  "mutation": "updateOrder",
+  "inputs": [
+    { "id": "1", "status": "SHIPPED" },
+    { "id": "2", "status": "SHIPPED" },
+    { "id": "3", "status": "SHIPPED" }
+  ],
+  "returnFields": ["id", "ref", "status"]
+}
+```
+
+### Batch Ingestion
+
+| Tool | Description |
+|---|---|
+| `batch.create` | Create an ingestion job |
+| `batch.send` | Send records to a job |
+| `batch.status` | Check job status |
+| `batch.batchStatus` | Check a specific batch within a job |
+| `batch.results` | Get per-record outcomes |
+
+Typical flow: `batch.create` → `batch.send` → `batch.status` (poll) → `batch.results`
+
+### Webhook
+
+| Tool | Description |
+|---|---|
+| `webhook.validate` | Validate payload fields and optionally verify cryptographic signature |
+
+### Entity Lifecycle
+
+| Tool | Description |
+|---|---|
+| `entity.create` | Type-safe entity creation with field validation, compound key encoding, and retailer auto-injection. Supports 12 entity types. |
+| `entity.update` | Status-aware entity updates with optional transition validation via `workflow.transitions` |
+| `entity.get` | Unified entity lookup by ID or ref with optional edge inclusion |
+
+**Supported types:** ORDER, FULFILMENT, LOCATION, NETWORK, CUSTOMER, PRODUCT, INVENTORY_POSITION, VIRTUAL_CATALOGUE, VIRTUAL_POSITION, CATEGORY, CARRIER, SETTING
+
+**Example** — create a location:
+
+```json
+{
+  "entityType": "LOCATION",
+  "data": {
+    "ref": "LOC_WH_01",
+    "type": "WAREHOUSE",
+    "name": "Main Warehouse",
+    "openingSchedule": { "allHours": true }
+  },
+  "dryRun": true
+}
+```
+
+### Workflow Management
+
+| Tool | Description |
+|---|---|
+| `workflow.upload` | Deploy workflow JSON via REST API with structure validation. For production, prefer `fluent module install` via CLI. |
+| `workflow.diff` | Compare two workflow definitions — returns added/removed/modified rulesets with risk assessment. Supports `summary`, `detailed`, and `mermaid` formats. |
+| `workflow.simulate` | Static analysis prediction of which rulesets would fire for a given status + event name. Does NOT execute Java rules or check runtime state — use `workflow.transitions` for authoritative live validation. |
+
+### Settings Management
+
+| Tool | Description |
+|---|---|
+| `setting.upsert` | Create or update a setting with upsert semantics — queries existing by name + context + contextId first |
+| `setting.bulkUpsert` | Batch create/update up to 50 settings with per-setting error handling |
+
+**Contexts:** RETAILER, ACCOUNT, LOCATION, NETWORK, AGENT, CUSTOMER
+
+### Environment
+
+| Tool | Description |
+|---|---|
+| `environment.discover` | Full environment snapshot — retailer, locations, networks, catalogues, workflows, settings, modules, users. Each section is opt-in via `include` array. |
+| `environment.validate` | Pre-flight validation checks: auth, retailer, locations, inventory, workflows, settings, modules |
+
+### Test Automation
+
+| Tool | Description |
+|---|---|
+| `test.assert` | Assert entity state matches expectations. Supports status, type, attribute, and edge assertions. Optional polling mode retries until pass or timeout. |
+
+**Example** — assert an order reached BOOKED with at least 1 fulfilment:
+
+```json
+{
+  "entityType": "ORDER",
+  "ref": "HD-001",
+  "assertions": {
+    "status": "BOOKED",
+    "edges": { "fulfilments": { "minCount": 1 } }
+  },
+  "poll": true,
+  "timeoutMs": 60000
+}
+```
+
+## Error Handling
+
+All tools return a consistent envelope:
+
+**Success:**
+
+```json
+{
+  "ok": true,
+  "response": { }
+}
+```
+
+**Failure:**
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "AUTH_ERROR",
+    "message": "OAuth token request failed.",
+    "retryable": false,
+    "details": {}
+  }
+}
+```
+
+| Error Code | Meaning | Retryable |
+|---|---|---|
+| `CONFIG_ERROR` | Missing or invalid environment variables | No |
+| `AUTH_ERROR` | Authentication failed | No |
+| `VALIDATION_ERROR` | Invalid tool arguments | No |
+| `TIMEOUT_ERROR` | Request timed out | Yes |
+| `RATE_LIMIT` | API rate limit hit | Yes |
+| `UPSTREAM_UNAVAILABLE` | Fluent API unreachable | Yes |
+| `NETWORK_ERROR` | Network connectivity issue | Yes |
+| `SDK_ERROR` | Unexpected SDK error | Varies |
+| `UNKNOWN_ERROR` | Unclassified error | No |
+
+## Support Scripts (Debugging and Validation)
+
+These scripts are useful during tenant validation, support, and failure triage:
+
+```bash
+# Positive smoke test
+npm run e2e:smoke -- --profile YOUR_PROFILE --retailer YOUR_RETAILER_REF_OR_ID
+
+# Interactive smoke setup
+npm run e2e:smoke -- --wizard
+
+# Negative-path validation (bad payloads, schema failures, error envelopes)
+npx tsx scripts/e2e-negative.ts --profile YOUR_PROFILE --retailer YOUR_RETAILER_REF_OR_ID
+
+# Check status of specific events and filtered event lists
+npx tsx scripts/check-event-status.ts --profile YOUR_PROFILE --retailer YOUR_RETAILER_REF_OR_ID --event-id <EVENT_ID>
+```
+
+Recommended operator flow:
+
+1. Run positive smoke (`e2e:smoke`).
+2. Run negative validation (`e2e-negative.ts`) to verify expected error handling.
+3. Use `check-event-status.ts` to trace real event outcomes when diagnosing failures.
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+|---|---|---|
+| `config.validate` fails | Missing or invalid env vars | Check `FLUENT_BASE_URL` and at least one complete auth method |
+| `FLUENT_PROFILE` auth fails | Profile/retailer ref mismatch or missing files | Verify `fluent profile list`, profile name, and `FLUENT_PROFILE_RETAILER` ref |
+| `AUTH_ERROR` on any tool | Bad credentials or expired token | Verify OAuth values or regenerate token |
+| `connection.test` fails | Network or URL mismatch | Verify API URL, check VPN/proxy, confirm tenant is reachable |
+| `event.send` succeeds but workflow doesn't trigger | Event name not mapped in workflow | Check workflow event handlers and ruleset conditions |
+| Server doesn't appear in MCP client | Config not reloaded | Restart IDE/client after editing `.mcp.json` |
+| Events sent to wrong tenant | Wrong `FLUENT_BASE_URL` | Confirm the API URL and retailer ID |
+| `RATE_LIMIT` errors | Too many requests | Reduce request frequency; retryable errors auto-retry up to `FLUENT_RETRY_ATTEMPTS` |
+
+## Development Workflow
+
+For a step-by-step guide on using these MCP tools to add functionality and test end-to-end (scaffold rules, build modules, fire events, assert state transitions, debug failures), see the [Development Workflow Guide](../fluent-ai-skills/docs/DEV_WORKFLOW.md) in the companion `@fluentcommerce/ai-skills` package.
+
+## Workspace Integration
+
+When used alongside `@fluentcommerce/ai-skills`, this extension server integrates with a workspace convention for managing source code, workflows, and analysis artifacts across multiple Fluent accounts:
+
+```
+accounts/
+  <PROFILE>/
+    SOURCE/           # custom plugin repos and JAR files
+    workflows/        # downloaded workflow JSONs (scoped by retailer)
+    analysis/         # generated analysis artifacts
+```
+
+Skills use this server's tools (`plugin.list`, `graphql.query`, `connection.test`, etc.) to:
+- Build a deployed rule inventory by cross-referencing live registered rules with local source
+- Validate connectivity during guided onboarding (`/fluent-connect`)
+- Run entity count discovery queries during workspace setup
+- Power end-to-end test flows with event dispatch and state assertions
+
+See the [Workspace Setup](https://www.npmjs.com/package/@fluentcommerce/ai-skills#workspace-setup) section in `@fluentcommerce/ai-skills` for the full directory layout, how to place source code and JAR files, and how the guided onboarding wizard works.
+
+## Companion Packages
+
+| Package | Purpose |
+|---|---|
+| [`@fluentcommerce/ai-skills`](https://www.npmjs.com/package/@fluentcommerce/ai-skills) | Install Fluent domain skills across AI coding assistants |
+| Fluent CLI (`@fluentcommerce/cli`) | Official CLI and built-in MCP server |
+
+## NPM Publish Checklist (Maintainers)
+
+Use this sequence before publishing:
+
+1. Confirm version and metadata in `package.json`.
+2. Build and test:
+   - `npm run build`
+   - `npm test`
+3. Run smoke checks:
+   - `npm run e2e:smoke -- --profile <PROFILE> --retailer <RETAILER>`
+   - `npx tsx scripts/e2e-negative.ts --profile <PROFILE> --retailer <RETAILER>`
+4. Validate package contents:
+   - `npm pack`
+5. Publish:
+   - `npm publish --access public`
+6. Post-publish sanity:
+   - start via MCP client and run `config.validate`, `health.ping`, `connection.test`
+
+Notes:
+
+- `prepublishOnly` already enforces `npm run build && npm test`.
+- Keep credentials out of committed `.mcp.json` and docs examples.
+
+## License
+
+[MIT](LICENSE)