@fluentcommerce/fluent-mcp-extn 0.7.0 → 0.7.2

package/README.md

@@ -13,13 +13,15 @@
 
 MCP ([Model Context Protocol](https://modelcontextprotocol.io)) extension server for [Fluent Commerce](https://fluentcommerce.com).
 
-Exposes 59 Fluent Commerce MCP tools for event forensics, workflow transitions, GraphQL execution and planning, batch ingestion plus payload planning, entity CRUD plus mutation planning, metrics, time-window resolution, settings, workflows, environment discovery, and test automation — powered by [`@fluentcommerce/fc-connect-sdk`](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk).
+Exposes 59 Fluent Commerce MCP tools for event forensics, workflow transitions, GraphQL execution and planning, batch ingestion plus payload planning, entity CRUD plus mutation planning, metrics, time-window resolution, settings, workflow management, environment discovery, and test automation — 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 plus read-only planning and scaffolding helpers, so it can inspect schemas, plan GraphQL/entity/batch requests, execute the right call, and keep large responses summarized before they hit model context.
 
+**Tool naming note:** canonical tool names use underscore form such as `health_ping` and `graphql_query`. This is a compatibility choice for stricter MCP clients, not a requirement of the MCP spec. The server still accepts legacy dotted calls such as `health.ping` for backward compatibility.
+
 ---
 
-> **Already using [`@fluentcommerce/ai-skills`](https://www.npmjs.com/package/@fluentcommerce/ai-skills)?** You're already set up — `ai-skills install --profile` auto-configures this server in your `.mcp.json`. Skip to [Verify connection](#3-verify-connection) or [Tools (59)](#tools-59) to see what's available.
+> **Already using [`@fluentcommerce/ai-skills`](https://www.npmjs.com/package/@fluentcommerce/ai-skills)?** You're already set up — `ai-skills install --profile` auto-configures this server in your `.mcp.json`. Skip to [Verify connection](#3-verify-connection) or [Tools (59)](#tools-59) to see what's available.
 
 ---
 
@@ -27,7 +29,7 @@ Exposes 59 Fluent Commerce MCP tools for event forensics, workflow transitions,
 
 - [Quick Start](#quick-start)
 - [Why This Extension](#why-this-extension)
-- [Tools (59)](#tools-59)
+- [Tools (59)](#tools-59)
 - [Configuration](#configuration)
 - [Error Handling](#error-handling)
 - [Support Scripts](#support-scripts-debugging-and-validation)
@@ -42,32 +44,32 @@ The official `fluent mcp server` (bundled with Fluent CLI) covers core GraphQL a
 
 | 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 |
-| GraphQL planning helpers (`graphql.planOperation` / `graphql.buildQuery` / `graphql.generateFull`) | | Yes |
-| Batch mutations (`graphql.batchMutate`) | | Yes |
+| 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 |
+| GraphQL planning helpers (`graphql_planOperation` / `graphql_buildQuery` / `graphql_generateFull`) | | Yes |
+| Batch mutations (`graphql_batchMutate`) | | Yes |
 | Batch ingestion (`batch.*`) | | Yes |
-| Batch payload planning (`batch.describePayload`) | | Yes |
-| Prometheus metrics (`metrics.query`) | | Yes |
-| Metrics health assessment (`metrics.healthCheck`) | | Yes |
-| Managed SLO snapshot (`metrics.sloReport`) | | Yes |
-| Metric label discovery (`metrics.labelCatalog`) | | Yes |
-| Mutation traffic audit by domain/subdomain (`metrics.mutationAudit`) | | Yes |
-| Natural-language time window resolution (`time.resolveWindow`) | | Yes |
-| Event analytics rankings (`metrics.topEvents`) | | Yes |
+| Batch payload planning (`batch_describePayload`) | | Yes |
+| Prometheus metrics (`metrics_query`) | | Yes |
+| Metrics health assessment (`metrics_healthCheck`) | | Yes |
+| Managed SLO snapshot (`metrics_sloReport`) | | Yes |
+| Metric label discovery (`metrics_labelCatalog`) | | Yes |
+| Mutation traffic audit by domain/subdomain (`metrics_mutationAudit`) | | Yes |
+| Natural-language time window resolution (`time_resolveWindow`) | | Yes |
+| Event analytics rankings (`metrics_topEvents`) | | Yes |
 | Webhook signature validation | | Yes |
-| Schema introspection (`graphql.introspect`) | | Yes |
+| Schema introspection (`graphql_introspect`) | | Yes |
 | Multi-strategy auth (profile, OAuth, token command, static token) | | Yes |
 | Multi-profile connections (dev/staging/prod simultaneously) | | Yes |
-| Runtime connection management (`connection.add` / `switch` / `remove`) | | Yes |
-| Entity CRUD (`entity.create` / `entity.update` / `entity.get`) | | Yes |
-| Entity mutation planning (`entity.planCreate` / `entity.planUpdate`) | | Yes |
-| Workflow management (`workflow.get` / `workflow.list` / `workflow.upload` / `workflow.diff` / `workflow.simulate`) | | Yes |
-| Settings management (`setting.get` / `setting.upsert` / `setting.bulkUpsert`) | | Yes |
-| Environment snapshot (`environment.discover` / `environment.validate`) | | Yes |
-| Test assertions with polling (`test.assert`) | | Yes |
+| Runtime connection management (`connection_add` / `connection_switch` / `connection_remove`) | | Yes |
+| Entity CRUD (`entity_create` / `entity_update` / `entity_get`) | | Yes |
+| Entity mutation planning (`entity_planCreate` / `entity_planUpdate`) | | Yes |
+| Workflow management (`workflow_get` / `workflow_list` / `workflow_upload` / `workflow_diff` / `workflow_simulate`) | | Yes |
+| Settings management (`setting_get` / `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.
 
@@ -243,7 +245,7 @@ This priority is evaluated per connection slot, not once for the whole server. I
 
 When a tool call includes `profile: "PROD_READONLY"`, it uses that slot's OAuth config. When it includes `profile: "QUICK_TEST"`, it uses that slot's static token config.
 
-Runtime-added slots currently support CLI profile auth, explicit OAuth, and explicit static bearer tokens. `TOKEN_COMMAND` remains a startup environment configuration, not a per-slot `connection.add` option.
+Runtime-added slots currently support CLI profile auth, explicit OAuth, and explicit static bearer tokens. `TOKEN_COMMAND` remains a startup environment configuration, not a per-slot `connection_add` option.
 
 ### 2. Restart your IDE
 
@@ -253,26 +255,26 @@ Restart so the MCP client picks up the new server.
 
 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
+1. `config_validate` — should return `ok: true`
+2. `health_ping` — should return `status: "ok"`
+3. `connection_test` — should return `ok: true` with your user/account details
 
 If any returns `ok: false`, see [Troubleshooting](#troubleshooting).
 
 ### 4. Start with read-only planners
 
 ```
-graphql.planOperation  →  inspect args, variables, and execution strategy
-entity.planCreate      →  scaffold a create mutation locally
-batch.describePayload  →  inspect batch row shape before creating a job
-event.build            →  build a payload (no API call)
+graphql_planOperation  →  inspect args, variables, and execution strategy
+entity_planCreate      →  scaffold a create mutation locally
+batch_describePayload  →  inspect batch row shape before creating a job
+event_build            →  build a payload (no API call)
 ```
 
 ### 5. Try a live call
 
 ```
-event.send with dryRun: true   →  validate without sending
-event.send with dryRun: false  →  send for real
+event_send with dryRun: true   →  validate without sending
+event_send with dryRun: false  →  send for real
 ```
 
 ## Requirements
@@ -515,7 +517,7 @@ Then reference it in `.mcp.json`:
 - Profiles can also be added/removed/switched at runtime via `connection.*` tools (see [Connection Management](#connection-management))
 - **Mixed auth strategies:** each profile slot resolves its own auth strategy independently — you can mix CLI profiles, OAuth credentials, and static tokens in the same server session. For example, `DEV/RETAILER_A` can use profile auth while `PROD_READONLY` uses OAuth and `QUICK_TEST` uses a static bearer token. The auth priority (profile → OAuth → token command → static token) applies per slot, not globally.
 
-> **Note:** `connection.add` supports CLI profile, explicit OAuth, and static token. Per-connection `TOKEN_COMMAND` is not supported at runtime — use env vars for token-command auth on the primary connection.
+> **Note:** `connection_add` supports CLI profile, explicit OAuth, and static token. Per-connection `TOKEN_COMMAND` is not supported at runtime — use env vars for token-command auth on the primary connection.
 
 #### Examples
 
@@ -523,7 +525,7 @@ Query orders from a specific environment:
 
 ```json
 {
-  "tool": "graphql.query",
+  "tool": "graphql_query",
   "arguments": {
     "query": "{ orders(first: 5) { edges { node { id ref status } } } }",
     "profile": "STAGING/UK"
@@ -534,9 +536,9 @@ Query orders from a specific environment:
 Compare workflow versions across retailers:
 
 ```
-1. workflow.get { entityType: "ORDER", entitySubtype: "HD", profile: "STAGING/UK" }
-2. workflow.get { entityType: "ORDER", entitySubtype: "HD", profile: "STAGING/US" }
-3. workflow.diff { left: <uk-workflow>, right: <us-workflow> }
+1. workflow_get { entityType: "ORDER", entitySubtype: "HD", profile: "STAGING/UK" }
+2. workflow_get { entityType: "ORDER", entitySubtype: "HD", profile: "STAGING/US" }
+3. workflow_diff { left: <uk-workflow>, right: <us-workflow> }
 ```
 
 ### Cache
@@ -554,82 +556,82 @@ Filesystem-based cache for near-static read responses (schema introspection, wor
 
 **Behavior:**
 - **Per-profile isolation** — each profile gets its own cache directory under `accounts/<PROFILE>/.cache`
-- **Cached tools:** `graphql.introspect`, `plugin.list`, `workflow.get`, `workflow.list`, `setting.get`
-- **Write-through invalidation** — write operations auto-invalidate related cache entries: `workflow.upload` clears `workflow:*`, `setting.upsert`/`setting.bulkUpsert` clears matching `setting:get:*` entries, `graphql.introspect` with `force: true` clears `introspect:*`
+- **Cached tools:** `graphql_introspect`, `plugin_list`, `workflow_get`, `workflow_list`, `setting_get`
+- **Write-through invalidation** — write operations auto-invalidate related cache entries: `workflow_upload` clears `workflow:get:*` and `workflow:list:*`, `setting_upsert`/`setting_bulkUpsert` clears matching `setting:get:*` entries, `graphql_introspect` with `force: true` clears `introspect:*`
 - **`_cache` metadata** — all cached tool responses include a `_cache` field (`{ hit, ageMs }` on cache hit, `{ hit: false, stored: true }` on cache miss) so the AI can reason about data freshness
 - **baseUrl fingerprint** — cache auto-clears if the profile is re-pointed to a different environment, preventing cross-environment contamination
 - **Fail-open** — cache errors (corrupt files, permission issues) become cache misses; the tool continues with a live API call
 - **Requires `FLUENT_PROFILE`** — no profile means no safe namespace, so caching is disabled
 
-## Tools (59)
-
-### 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) |
-
-### Time
-
-| Tool | Description |
-|---|---|
-| `time.resolveWindow` | Resolve phrases like `last month`, `1h30m`, `now-7d/d`, or `now-7d to now` into exact ISO `from` / `to` timestamps |
-
-Use `time.resolveWindow` before `graphql.query`, `graphql.queryAll`, `event.list`, `event.flowInspect`, or any other tool that expects explicit dates. For ambiguous phrases such as `last month`, the tool returns candidates and a clarification question instead of silently guessing. For metrics-style asks it also understands shorthand and datemath expressions so the same shared resolver can be reused across tools.
-
-**Example** — detect ambiguity:
-
-```json
-{
-  "tool": "time.resolveWindow",
-  "arguments": {
-    "phrase": "last month",
-    "timezone": "Asia/Calcutta"
-  }
-}
-```
-
-**Example** — force calendar interpretation:
-
-```json
-{
-  "tool": "time.resolveWindow",
-  "arguments": {
-    "phrase": "last month",
-    "timezone": "Asia/Calcutta",
-    "mode": "calendar"
-  }
-}
-```
-
-**Example** — resolve datemath for a metrics or GraphQL range:
-
-```json
-{
-  "tool": "time.resolveWindow",
-  "arguments": {
-    "phrase": "now-7d/d",
-    "timezone": "Asia/Calcutta"
-  }
-}
-```
+## Tools (59)
+
+### 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) |
+
+### Time
+
+| Tool | Description |
+|---|---|
+| `time_resolveWindow` | Resolve phrases like `last month`, `1h30m`, `now-7d/d`, or `now-7d to now` into exact ISO `from` / `to` timestamps |
+
+Use `time_resolveWindow` before `graphql_query`, `graphql_queryAll`, `event_list`, `event_flowInspect`, or any other tool that expects explicit dates. For ambiguous phrases such as `last month`, the tool returns candidates and a clarification question instead of silently guessing. For metrics-style asks it also understands shorthand and datemath expressions so the same shared resolver can be reused across tools.
+
+**Example** — detect ambiguity:
+
+```json
+{
+  "tool": "time_resolveWindow",
+  "arguments": {
+    "phrase": "last month",
+    "timezone": "Asia/Calcutta"
+  }
+}
+```
+
+**Example** — force calendar interpretation:
+
+```json
+{
+  "tool": "time_resolveWindow",
+  "arguments": {
+    "phrase": "last month",
+    "timezone": "Asia/Calcutta",
+    "mode": "calendar"
+  }
+}
+```
+
+**Example** — resolve datemath for a metrics or GraphQL range:
+
+```json
+{
+  "tool": "time_resolveWindow",
+  "arguments": {
+    "phrase": "now-7d/d",
+    "timezone": "Asia/Calcutta"
+  }
+}
+```
 
 ### Connection Management
 
 | Tool | Description |
 |---|---|
-| `connection.list` | List all registered profiles with auth strategy, init status, and default marker |
-| `connection.add` | Add a new profile at runtime — by CLI profile name or explicit credentials (baseUrl + OAuth/static token) |
-| `connection.remove` | Remove a non-default profile |
-| `connection.switch` | Switch the default profile (affects all subsequent tool calls that omit `profile`) |
+| `connection_list` | List all registered profiles with auth strategy, init status, and default marker |
+| `connection_add` | Add a new profile at runtime — by CLI profile name or explicit credentials (baseUrl + OAuth/static token) |
+| `connection_remove` | Remove a non-default profile |
+| `connection_switch` | Switch the default profile (affects all subsequent tool calls that omit `profile`) |
 
 **Example** — add a profile by CLI profile name:
 
 ```json
 {
-  "tool": "connection.add",
+  "tool": "connection_add",
   "arguments": {
     "name": "staging",
     "fluentProfile": "STAGING",
@@ -642,7 +644,7 @@ Use `time.resolveWindow` before `graphql.query`, `graphql.queryAll`, `event.list
 
 ```json
 {
-  "tool": "connection.add",
+  "tool": "connection_add",
   "arguments": {
     "name": "partner-sandbox",
     "baseUrl": "https://partner.sandbox.api.fluentretail.com",
@@ -657,7 +659,7 @@ Use `time.resolveWindow` before `graphql.query`, `graphql.queryAll`, `event.list
 
 ```json
 {
-  "tool": "connection.add",
+  "tool": "connection_add",
   "arguments": {
     "name": "quick-test",
     "baseUrl": "https://partner.sandbox.api.fluentretail.com",
@@ -667,13 +669,13 @@ Use `time.resolveWindow` before `graphql.query`, `graphql.queryAll`, `event.list
 }
 ```
 
-`connection.add` does not currently accept `TOKEN_COMMAND`; token-command auth is configured at server startup via environment variables.
+`connection_add` does not currently accept `TOKEN_COMMAND`; token-command auth is configured at server startup via environment variables.
 
 **Example** — switch the default:
 
 ```json
 {
-  "tool": "connection.switch",
+  "tool": "connection_switch",
   "arguments": { "name": "staging" }
 }
 ```
@@ -682,13 +684,13 @@ Use `time.resolveWindow` before `graphql.query`, `graphql.queryAll`, `event.list
 
 | Tool | Description |
 |---|---|
-| `event.build` | Build event payload without sending (validation only) |
-| `event.send` | Build and send event (supports `dryRun: true` with `_workflowPreview` showing predicted target status, matching rulesets, webhook/custom-rule detection) |
-| `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_build` | Build event payload without sending (validation only) |
+| `event_send` | Build and send event (supports `dryRun: true` with `_workflowPreview` showing predicted target status, matching rulesets, webhook/custom-rule detection) |
+| `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.
+`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).
 
@@ -739,7 +741,7 @@ Use `time.resolveWindow` before `graphql.query`, `graphql.queryAll`, `event.list
 
 ### Local-First LLM Reduction (flowInspect)
 
-If `event.flowInspect` returns large JSON, run local analysis first and only send compact artifacts to an LLM:
+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>
@@ -749,14 +751,14 @@ 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>.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` / `--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
@@ -766,27 +768,27 @@ Useful flags:
 
 | 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.metricCatalog` | Show documented Fluent metric families, labels, safe groupings, and live-discovered metric names |
-| `metrics.planQuery` | Build safe PromQL for rate, increase, delta, breakdown, topk, p95, avg, and recency use cases |
-| `metrics.snapshot` | Return a compact dashboard snapshot with volume, failures, latency, and breakdowns in one call |
-| `metrics.compare` | Compare a metric across two adjacent windows and highlight what changed |
-| `metrics.mutationAudit` | Audit GraphQL create/update mutation traffic by domain/subdomain and split counts by operation name |
-| `metrics.topEvents` | Aggregate and rank top events by name/entity/status in a time window |
-
-`metrics.mutationAudit` is intentionally opinionated: it discovers mutation names locally, then queries each operation explicitly instead of relying on `sum by (operation)`. Treat the output as GraphQL mutation traffic, not guaranteed business-truth entity counts.
-
-`metrics.planQuery` now reuses the shared window parser, so compound windows like `1h30m` work consistently and the tool returns an auto-calculated `recommendedStep` / `estimatedPoints` hint for `metrics.query type=range`, snapped upward to stay within the LLM-safe point budget.
+| `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_metricCatalog` | Show documented Fluent metric families, labels, safe groupings, and live-discovered metric names |
+| `metrics_planQuery` | Build safe PromQL for rate, increase, delta, breakdown, topk, p95, avg, and recency use cases |
+| `metrics_snapshot` | Return a compact dashboard snapshot with volume, failures, latency, and breakdowns in one call |
+| `metrics_compare` | Compare a metric across two adjacent windows and highlight what changed |
+| `metrics_mutationAudit` | Audit GraphQL create/update mutation traffic by domain/subdomain and split counts by operation name |
+| `metrics_topEvents` | Aggregate and rank top events by name/entity/status in a time window |
+
+`metrics_mutationAudit` is intentionally opinionated: it discovers mutation names locally, then queries each operation explicitly instead of relying on `sum by (operation)`. Treat the output as GraphQL mutation traffic, not guaranteed business-truth entity counts.
+
+`metrics_planQuery` now reuses the shared window parser, so compound windows like `1h30m` work consistently and the tool returns an auto-calculated `recommendedStep` / `estimatedPoints` hint for `metrics_query type=range`, snapped upward to stay within the LLM-safe point budget.
 
 ### Orchestration
 
 | Tool | Description |
 |---|---|
-| `workflow.transitions` | Query available user actions/transitions with workflow-aware enrichment: action predictions (`_predictions`), attribute templates, recommended next action (`_recommended`), and multi-step lookahead (`nextSteps`). Auto-fetches workflow when not cached. |
-| `plugin.list` | List all registered rules with metadata (`GET /orchestration/rest/v1/plugin`). Supports optional name filter. |
+| `workflow_transitions` | Query available user actions/transitions with workflow-aware enrichment: action predictions (`_predictions`), attribute templates, recommended next action (`_recommended`), and multi-step lookahead (`nextSteps`). Auto-fetches workflow when not cached. |
+| `plugin_list` | List all registered rules with metadata (`GET /orchestration/rest/v1/plugin`). Supports optional name filter. |
 
 **`flexType` auto-derive:** When `type` and `subtype` are provided but `flexType` is omitted, it is auto-derived as `TYPE::SUBTYPE`. All three params (`module`, `flexType`, `flexVersion`) are required by the Transition API — omitting any one silently returns empty results.
 
@@ -836,15 +838,15 @@ Useful flags:
 
 | 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, queries, mutations, nested input fields, and field-level args |
-| `graphql.listRoots` | List all query and mutation root fields from the live schema |
-| `graphql.planOperation` | Plan a query or mutation before execution — returns arg requirements, variables skeleton, selection template, and execution guidance |
-| `graphql.buildQuery` | Generate a query or mutation from structured inputs |
-| `graphql.validate` | Validate a GraphQL document against the live schema |
-| `graphql.generateFull` | Generate a maximal-selection query for a root field with configurable depth |
+| `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, queries, mutations, nested input fields, and field-level args |
+| `graphql_listRoots` | List all query and mutation root fields from the live schema |
+| `graphql_planOperation` | Plan a query or mutation before execution — returns arg requirements, variables skeleton, selection template, and execution guidance |
+| `graphql_buildQuery` | Generate a query or mutation from structured inputs |
+| `graphql_validate` | Validate a GraphQL document against the live schema |
+| `graphql_generateFull` | Generate a maximal-selection query for a root field with configurable depth |
 
 **Example** — query orders:
 
@@ -900,36 +902,36 @@ With `dryRun: true`, returns the generated aliased mutation query and variables
 }
 ```
 
-Use `graphql.planOperation` when you want the server to tell the AI which args are required, what the variables shape should look like, and which execution tool (`graphql.query` vs `graphql.queryAll`) makes sense.
+Use `graphql_planOperation` when you want the server to tell the AI which args are required, what the variables shape should look like, and which execution tool (`graphql_query` vs `graphql_queryAll`) makes sense.
 
 ### Batch Ingestion
 
 | Tool | Description |
 |---|---|
-| `batch.create` | Create an ingestion job |
-| `batch.describePayload` | Return entity-type-specific field requirements, example rows, and hints for `batch.send` without making an API call |
-| `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 |
+| `batch_create` | Create an ingestion job |
+| `batch_describePayload` | Return entity-type-specific field requirements, example rows, and hints for `batch_send` without making an API call |
+| `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.describePayload` → `batch.create` → `batch.send` → `batch.status` (poll) → `batch.results`
+Typical flow: `batch_describePayload` → `batch_create` → `batch_send` → `batch_status` (poll) → `batch_results`
 
 ### Webhook
 
 | Tool | Description |
 |---|---|
-| `webhook.validate` | Validate payload fields and optionally verify cryptographic signature |
+| `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 |
-| `entity.planCreate` | Plan an entity create call locally — returns required fields, variables skeleton, mutation shape, gotchas, and auto-injected retailer context |
-| `entity.planUpdate` | Plan an entity update call locally — returns updatable fields, variables skeleton, mutation shape, and status-change guidance |
+| `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 |
+| `entity_planCreate` | Plan an entity_create call locally — returns required fields, variables skeleton, mutation shape, gotchas, and auto-injected retailer context |
+| `entity_planUpdate` | Plan an entity_update call locally — returns updatable fields, variables skeleton, mutation shape, and status-change guidance |
 
 **Supported types:** ORDER, FULFILMENT, LOCATION, NETWORK, CUSTOMER, PRODUCT, INVENTORY_POSITION, VIRTUAL_CATALOGUE, VIRTUAL_POSITION, CATEGORY, CARRIER, SETTING
 
@@ -952,11 +954,11 @@ Typical flow: `batch.describePayload` → `batch.create` → `batch.send` → `b
 
 | Tool | Description |
 |---|---|
-| `workflow.get` | Fetch a specific workflow by entity type and subtype via REST API. Works even when the list endpoint returns 401. |
-| `workflow.list` | List all workflows for a retailer. Deduplicates to latest version per workflow name. |
-| `workflow.upload` | Deploy workflow JSON via REST API with structure validation plus preflight safety analysis (no-match zones, webhook setting dependencies, and live diff when available). 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. |
+| `workflow_get` | Fetch a specific workflow by entity type and subtype via REST API. Works even when the list endpoint returns 401. |
+| `workflow_list` | List all workflows for a retailer. Deduplicates to latest version per workflow name. |
+| `workflow_upload` | Deploy workflow JSON via REST API (`PUT /api/v4.1/workflow/{retailerId}`). Idempotent upsert — same JSON twice does not create duplicate versions. Includes structure validation, preflight safety analysis (no-match zones, webhook setting dependencies, live diff). Does NOT update CLI workflowlog. |
+| `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. |
 
 **Example** — fetch a workflow and save to file:
 
@@ -986,9 +988,9 @@ With `outputDir`, each workflow is saved as `{TYPE}-{SUBTYPE}.json` (e.g., `ORDE
 
 | Tool | Description |
 |---|---|
-| `setting.get` | Fetch settings by name (`%` wildcards supported), optionally save to local file to keep large JSON out of LLM context |
-| `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 |
+| `setting_get` | Fetch settings by name (`%` wildcards supported), optionally save to local file to keep large JSON out of LLM context |
+| `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
 
@@ -1023,14 +1025,14 @@ Provide either `value` (for small strings ≤255 chars) or `lobValue` (for large
 
 | 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 |
+| `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. |
+| `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:
 
@@ -1051,17 +1053,17 @@ Provide either `value` (for small strings ≤255 chars) or `lobValue` (for large
 
 | Tool | Description |
 |---|---|
-| `cache.status` | Show local cache statistics — entry count, size, hit/miss rate, per-category breakdown. No API call. |
-| `cache.clear` | Clear cached entries by pattern (e.g. `workflow:*`) or all. No API call, operates on local filesystem only. |
+| `cache_status` | Show local cache statistics — entry count, size, hit/miss rate, per-category breakdown. No API call. |
+| `cache_clear` | Clear cached entries by pattern (e.g. `workflow:*`) or all. No API call, operates on local filesystem only. |
 
 See [Cache configuration](#cache) for env vars, TTLs, and behavior details. Write operations auto-invalidate related cache entries, so manual clearing is only needed after out-of-band changes (CLI deployments, REST API calls, admin console edits).
 
 | Pattern | Clears |
 |---|---|
-| `workflow:*` | All cached workflow list/get responses |
+| `workflow:get:*` / `workflow:list:*` | All cached workflow get/list responses |
 | `setting:get:fc.mystique.*` | Cached manifest and setting lookups |
 | `introspect:*` | GraphQL schema introspection cache |
-| `plugin:list` | Cached plugin metadata |
+| `plugin:list:*` | Cached plugin metadata |
 | *(omit pattern)* | Everything |
 
 **Example** — check cache health:
@@ -1140,7 +1142,7 @@ npx tsx scripts/measure-tool-tokens.ts
 # 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
+# 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>
 ```
 
@@ -1154,11 +1156,11 @@ Recommended operator flow:
 
 | Symptom | Likely Cause | Fix |
 |---|---|---|
-| `config.validate` fails | Missing or invalid env vars | Check `FLUENT_BASE_URL` and at least one complete auth method |
+| `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 |
+| `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` |
@@ -1183,7 +1185,7 @@ accounts/
     analysis/         # generated analysis artifacts
 ```
 
-Skills use this server's tools (`plugin.list`, `graphql.query`, `connection.test`, etc.) to:
+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
@@ -1207,7 +1209,7 @@ npm run dev                                # hot-reload via tsx
 3. `npm run e2e:smoke -- --profile <PROFILE> --retailer <RETAILER>` (requires live API)
 4. `npm pack` — inspect contents
 5. `npm publish --access public`
-6. Post-publish: start via MCP client, run `config.validate`, `health.ping`, `connection.test`
+6. Post-publish: start via MCP client, run `config_validate`, `health_ping`, `connection_test`
 
 > `prepublishOnly` enforces `build && test` automatically. Keep credentials out of `.mcp.json` and docs.