@fluentcommerce/ai-skills 0.1.0

package/content/mcp-extn/skills/fluent-mcp-tools/SKILL.md

@@ -0,0 +1,461 @@
+---
+name: fluent-mcp-tools
+description: Fluent Commerce MCP tools reference. Use when working with the Fluent MCP extension server for event dispatch, event flow forensics, GraphQL operations, batch ingestion, or webhook validation. Triggers on "mcp tools", "send fluent event", "event flow inspect", "trace event payloads", "fluent graphql", "batch ingestion".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: <operation> [entity-type] [entity-ref]
+---
+
+# Fluent MCP Tools
+
+Quick reference for Fluent Commerce MCP extension server tools.
+
+## When to Use
+
+- Sending events to Fluent Commerce (order lifecycle, fulfilment transitions)
+- Retrieving UI/user-action transitions from workflow trigger contexts
+- Running GraphQL queries or mutations
+- Bulk data operations via batch ingestion
+- Validating inbound webhook payloads
+
+This skill is the canonical MCP tool contract reference. Other skills should link here for payload syntax and limits instead of redefining tool schemas.
+
+## Event API Semantics
+
+For event data model, types, categories, statuses, execution model, event contracts, and query patterns — see `/fluent-event-api`. This skill focuses on MCP tool syntax and payload contracts only.
+
+## Event Operations
+
+### Recommended Flow
+
+1. `config.validate` - Verify connection
+2. `event.build` - Preview payload
+3. `event.send` (dryRun: true) - Validate without sending
+4. `event.send` (dryRun: false) - Actually send
+5. `event.list` / `event.get` - Verify delivery
+6. `event.flowInspect` - One-call runtime forensics for root entity
+
+### Common Events
+
+| Event | Entity Type | Description |
+|-------|-------------|-------------|
+| `ConfirmValidation` | ORDER | Confirm order passed validation |
+| `ConfirmAllocation` | FULFILMENT | Confirm stock allocation |
+| `CreateInvoice` | FULFILMENT | Invoice created |
+| `ConfirmPick` | FULFILMENT | Items picked (attrs: pickedAt, pickedItems) |
+| `ConfirmShipment` | FULFILMENT | Shipment dispatched (attrs: trackingNumber, carrierRef) |
+| `ConfirmDelivery` | FULFILMENT | Delivery completed (attrs: deliveredAt) |
+| `CancelOrder` | ORDER | Cancel an order |
+
+### Runtime Forensics (`event.flowInspect`)
+
+Use `event.flowInspect` when you need the full runtime evidence bundle in one call for any entity type.
+
+> **MANDATORY: Always use compact mode first.** Call with default parameters (no `compact: false`). The ~2-3k token compact summary is sufficient for 90% of use cases. Only add targeted detail flags (`includeRuleDetails`, `includeCustomLogs`, `includeSnapshots`, `includeCrossEntity`) one at a time when compact findings reveal specific issues. Setting `compact: false` returns ~24-30k tokens and WILL fill context — use only as a last resort after identifying exactly what raw data you need.
+
+**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. Audit arrays are stripped to essentials.
+
+Collects ORCHESTRATION events (plus ORCHESTRATION_AUDIT when `includeAudit=true`, and SCHEDULED when `includeScheduled=true`) for a root entity, then extracts:
+
+**Always included (both modes):**
+- **Orchestration timeline** — status/entity type counts, top event names
+- **Auto-recommendations** — contextual findings based on status counts, webhook failures, exceptions
+- **Totals** — raw event counts for all categories
+
+**Compact mode additions (`compact: true`):**
+- `analysis.statusFlow` — ordered unique statuses seen (e.g., `["CREATED", "BOOKED", "SHIPPED"]`)
+- `analysis.findings[]` — anomaly detection: NO_MATCH (CRITICAL), FAILED (HIGH), webhook errors (HIGH), exceptions (HIGH), PENDING (MEDIUM), slow rulesets (MEDIUM)
+- `analysis.failedWebhookEndpoints` — URLs that returned >= 400
+- `analysis.slowestRulesets` — top 3 slowest
+- `analysis.timespan` — first/last event timestamps with durationMs
+- `audit.webhookActions` — **only failures** (responseCode >= 400)
+- `audit.mutationActions` — **top 5 by queryName** (name + count only, no payloads)
+- `audit.sendEventActions` — count + scheduledCount only
+- `diagnostics.inspectedEvents` — summary (id, name, status, closeMatchCount)
+
+**Full mode additions (`compact: false`):**
+- **Mutation payloads** — full GraphQL mutations with `input`, `response`, `durationMs`
+- **Webhook diagnostics** — all webhooks with `Request Endpoint`, `Response code`, `Response Body`
+- **Scheduled dispatches** — future-dated SendEvent evidence with full event payload
+- **Ruleset durations** — all rulesets ranked by processing time
+- **Cross-entity events** — full events array per child entity type
+
+**Default-on flags:**
+- `compact: true` — pre-analyzed summary response
+- `includeAudit: true` — parse ORCHESTRATION_AUDIT action evidence
+- `includeExceptions: true` — rule exceptions with class, message, ruleset context
+- `includeNoMatchDetails: true` — enhanced NO_MATCH diagnostics from ruleSet audit events
+- `includeEventDetails: true` — compact orchestration events in response (full mode only)
+- `includeScheduled: true` — separate SCHEDULED event fetch
+
+**Opt-in flags (default false):**
+- `includeRuleDetails: true` — per-rule execution trace (full mode only)
+- `includeCustomLogs: true` — custom plugin log messages (full mode only)
+- `includeSnapshots: true` — entity state snapshots (full mode only)
+- `includeCrossEntity: true` — fetches child entity events
+
+**Drilldown control:**
+- `inspectStatuses: ["NO_MATCH", "PENDING", "FAILED"]` — auto-fetches `event.get` for these statuses
+- `maxDrilldowns: 50` — cap on individual event.get calls
+- `actionSampleLimit: 100` — max rows per extraction section
+
+**Response sections (compact mode):**
+
+| Section | Key Fields | Condition |
+|---------|------------|-----------|
+| `totals` | orchestrationCount, auditCount, all category counts | Always |
+| `analysis` | statusFlow, entityTypes, timespan, failedWebhookEndpoints, slowestRulesets, findings[] | Always (compact only) |
+| `orchestration` | statusCounts, entityTypeCounts, topNames (top 10) | Always |
+| `audit.webhookActions` | Only failures (responseCode >= 400) | When includeAudit and failures exist |
+| `audit.mutationActions` | Top 5 queryName + count | When includeAudit and mutations exist |
+| `audit.sendEventActions` | { count, scheduledCount } | When includeAudit |
+| `audit.exceptions` | id, ruleset, rule, exceptionClass, message | When includeExceptions |
+| `diagnostics.inspectedEvents` | eventId, name, eventStatus, closeMatchCount | When inspectStatuses has entries |
+
+**Response sections (full mode, compact: false):**
+
+| Section | Key Fields | Condition |
+|---------|------------|-----------|
+| `totals` | orchestrationCount, auditCount, all category counts | Always |
+| `orchestration` | statusCounts, entityTypeCounts, topNames (top 30), events? | Always |
+| `scheduled` | SCHEDULED events with compact view | When includeScheduled and events exist |
+| `audit.mutationActions` | queryName, queryType, input, response, durationMs | When includeAudit |
+| `audit.webhookActions` | endpoint, responseCode, responseBody | When includeAudit |
+| `audit.sendEventActions` | eventName, futureDated, scheduledOn, event payload | When includeAudit |
+| `audit.rulesetDurations` | name, durationMs (sorted slowest first) | When includeAudit |
+| `audit.exceptions` | id, ruleset, rule, exceptionClass, message | When includeExceptions |
+| `audit.snapshots` | status, items, attributes, customer, toAddress, deliveryType | When includeSnapshots |
+| `audit.customLogs` | source, logs[] (from LogCollection) | When includeCustomLogs |
+| `audit.ruleEvents` | name, ruleSet, props, durationMs | When includeRuleDetails |
+| `diagnostics.inspectedEvents` | closeMatches, entityStatus, message, full event | When inspectStatuses has entries |
+| `diagnostics.noMatchAuditDetails` | rulesetName, entityStatus, message, closeMatches | When includeNoMatchDetails |
+| `crossEntity` | entityType, orchestrationCount, statusCounts, events | When includeCrossEntity |
+
+Example (compact — the default, recommended first call):
+
+```json
+{
+  "rootEntityRef": "E2E_MULTI_202602221343",
+  "rootEntityType": "ORDER"
+}
+```
+
+Example (entity-agnostic by ref only):
+
+```json
+{
+  "rootEntityRef": "STORE-001",
+  "includeScheduled": false
+}
+```
+
+Example (deep analysis with all sections):
+
+```json
+{
+  "rootEntityRef": "ORD-001",
+  "rootEntityType": "ORDER",
+  "includeRuleDetails": true,
+  "includeCustomLogs": true,
+  "includeSnapshots": true,
+  "includeCrossEntity": true
+}
+```
+
+Example (lightweight — minimal output):
+
+```json
+{
+  "rootEntityRef": "ORD-001",
+  "rootEntityType": "ORDER",
+  "includeEventDetails": false,
+  "includeScheduled": false,
+  "includeExceptions": false,
+  "includeNoMatchDetails": false,
+  "maxDrilldowns": 0
+}
+```
+
+## GraphQL Operations
+
+### Single Query
+Use `graphql.query` for one-off queries with manual pagination.
+
+### Auto-Paginated Query
+Use `graphql.queryAll` when you need ALL records. Automatically follows cursors.
+
+### Batch Mutations
+Use `graphql.batchMutate` for bulk updates (up to 50 mutations per request).
+
+### Schema Discovery
+Use `graphql.introspect` to discover mutations, input types, and field requirements:
+- `listMutations: true` - Get all mutation names
+- `mutation: 'updateOrder'` - Inspect specific mutation
+- `type: 'UpdateOrderInput'` - See input type fields
+
+## Batch Ingestion
+
+### Flow
+1. `batch.create` - Create job (name, entityType, action)
+2. `batch.send` - Send records (jobId, payload)
+3. `batch.status` - Poll until terminal state
+4. `batch.results` - Get per-record outcomes
+
+## Event Analytics
+
+### Metrics Tools (Planned -- Not Yet Implemented)
+
+> The following tools are planned for a future release. They are documented here for reference but are not currently available in the MCP extension server.
+
+#### Health Check (Single Call)
+
+Use `metrics.healthCheck` for a one-call health assessment. Runs multiple Prometheus queries locally, applies anomaly thresholds, and returns findings + recommendations. Falls back to Event API if Prometheus is unavailable.
+
+```json
+{ "window": "1h", "includeTopEvents": true }
+```
+
+For custom PromQL queries, use `metrics.query`. For pre-aggregated Event API rankings, use `metrics.topEvents`.
+
+#### SLO Report (Managed Services)
+
+Use `metrics.sloReport` when you need an operational KPI snapshot in one call:
+- failure/no-match/pending rates
+- p95 runtime + p95 inflight latency
+- threshold findings + recommendations
+- optional top failing events
+
+```json
+{
+  "window": "1h",
+  "includeTopFailingEvents": true,
+  "topN": 10
+}
+```
+
+`metrics.sloReport` is preferred for release checks and incident triage handoffs where you need explicit SLI fields, not just raw PromQL output.
+
+#### Label Discovery (Metric -> Labels)
+
+Use `metrics.labelCatalog` before writing grouped PromQL to discover valid labels for a metric:
+- samples live series via `last_over_time(metric[window])`
+- extracts label keys + cardinality + sample values
+- merges known Fluent label hints for common metrics
+
+```json
+{
+  "metric": "core_event_received_total",
+  "window": "1h",
+  "maxValuesPerLabel": 10
+}
+```
+
+Recommended workflow:
+1. `metrics.labelCatalog` (discover labels)
+2. `metrics.query` (write correct `sum by (...)` / `histogram_quantile(...)`)
+3. `metrics.sloReport` (operational KPI snapshot)
+
+#### Prometheus Metrics
+Use `metrics.query` to execute PromQL queries via the Fluent GraphQL `metricInstant` / `metricRange` proxy:
+- **Instant**: Evaluate at a single point in time — `{ query: "sum(rubix_event_runtime_seconds_count)", type: "instant" }`
+- **Range**: Evaluate over a time window — `{ query: "...", type: "range", start: "ISO", end: "ISO", step: "1h" }`
+
+The MCP tool routes PromQL through the GraphQL API (not raw Prometheus REST endpoints, which are not exposed by the platform). The `time`, `start`, and `end` parameters accept ISO-8601 timestamps (mapped to GraphQL `DateTime` type).
+
+Access is permission-gated. If metrics calls fail for auth/authorization, verify the user/token has `METRICS_VIEW`.
+
+#### Counter Delta Pattern (`last_over_time`)
+
+For accurate daily/hourly counter deltas over wider windows, use:
+
+```promql
+(last_over_time(metric[window]) - metric offset <period>)
+or
+last_over_time(metric[window])
+```
+
+Use this when offset samples can be missing (scrape gaps, resets). For short-window trend estimates, `increase()`/`rate()` is usually sufficient.
+
+#### Label Hygiene (Critical)
+
+Do not assume labels are shared across all metrics. Common mappings:
+
+| Metric | Key Labels |
+|---|---|
+| `core_event_received_total` | `account_id`, `retailer_id`, `event_name`, `entity_type`, `source` |
+| `rubix_event_runtime_seconds_count` | `account_id`, `retailer_id`, `event_name`, `entity_type`, `source`, `status` |
+| `rubix_event_inflight_latency_seconds_count` | `account_id`, `retailer_id`, `event_name`, `entity_type`, `source` |
+| `rubix_event_runtime_seconds_bucket` | `account_id`, `retailer_id`, `event_name`, `entity_type`, `source`, `status`, `le` |
+
+Example pitfall: `status` is **not** a label on `core_event_received_total`; including it in `sum by (...)` will produce misleading/null label outputs.
+
+#### Event Volume Analytics
+Use `metrics.topEvents` for aggregate event analytics within a time window:
+- Paginates through `event.list` results, groups by (name + entityType + status)
+- Returns top-N rankings, failure rates, and status breakdown
+- Supports `eventStatus` filter for server-side pre-filtering (e.g., `"FAILED"`, `"NO_MATCH"`)
+- Example: `{ from: "2026-02-22T07:00:00Z", topN: 20 }`
+- Example (failures only): `{ from: "2026-02-22T07:00:00Z", eventStatus: "FAILED", topN: 10 }`
+
+For event model/filter semantics → `/fluent-event-api`.
+For diagnostic decision trees → `/fluent-trace`.
+
+### Event Analysis via Filters
+Use `event.list` with targeted filters (`eventStatus`, `category`, `eventType`, `from`/`to`) to find patterns. Combine with `graphql.query` to correlate entity state with event history.
+
+### Status/Category Alias Normalization
+
+When translating user input into `event.list` filters, normalize common aliases:
+
+| User/doc term | Canonical filter value |
+|---|---|
+| `ERROR` | `FAILED` |
+| `PROCESSING` | `PENDING` (or `SCHEDULED` depending on lifecycle stage) |
+| `ORDER_WORKFLOW` | `ORDER WORKFLOW` |
+
+Prefer canonical values in requests; keep aliases only for interpretation.
+
+## JOB/BATCH Entities vs Batch Ingestion
+
+The MCP `batch.*` tools and JOB/BATCH workflow entities are **different concepts** that share terminology:
+
+| Concept | What It Is | MCP Tools | Event API |
+|---------|-----------|-----------|-----------|
+| **Batch Ingestion** | Data loading mechanism (bulk create/update entities) | `batch.create`, `batch.send`, `batch.status`, `batch.results` | Not event-driven; uses dedicated ingestion API |
+| **JOB/BATCH Entities** | Workflow-driven processing entities (orchestrated execution) | Query via `graphql.query`, trace via `event.list` | `entityType=JOB` or `entityType=BATCH`; linked by `rootEntityType=JOB` |
+
+### Diagnosing JOB/BATCH Workflow Issues
+
+JOB and BATCH are orchestratable entities with their own workflows. To trace them:
+
+```
+event.list({ "context.entityType": "JOB", "context.entityRef": "<JOB_REF>", "count": 100 })
+event.list({ "context.entityType": "BATCH", "context.rootEntityRef": "<JOB_REF>", "count": 100 })
+```
+
+BATCH entities link to their parent JOB via `rootEntityType=JOB` / `rootEntityRef`. The `BATCH_COMPLETE` event signals batch processing completion.
+
+For event model semantics and query patterns → `/fluent-event-api`.
+For diagnostic decision trees → `/fluent-trace`.
+
+## Orchestration
+
+### Rule Registry
+
+Use `plugin.list` to fetch all registered orchestration rules (standard + custom) with metadata from `GET /orchestration/rest/v1/plugin`. Returns rule name, description, accepted entity types, produced events, and parameters.
+
+- List all rules: `{}` (no params)
+- Filter by name: `{ "name": "SendEvent" }` (case-insensitive substring match)
+
+### Workflow Transitions
+
+Use `workflow.transitions` to discover available user actions at any entity state
+(backed by `POST /api/v4.1/transition`).
+
+**When to use:**
+- Discover what events can be fired at a given status without reading workflow JSON
+- Build dynamic E2E test sequences that adapt to workflow changes
+- Validate that expected user actions exist after deployment
+- Get required attributes for each action (avoids missing-attribute errors on `event.send`)
+
+**Example — ORDER at a specific status:**
+
+```json
+{
+  "triggers": [
+    {
+      "type": "ORDER",
+      "subtype": "HD",
+      "status": "CREATED",
+      "retailerId": "5",
+      "flexType": "ORDER::HD"
+    }
+  ]
+}
+```
+
+**Example — Module-scoped trigger:**
+
+```json
+{
+  "triggers": [
+    {
+      "type": "MANIFEST",
+      "subtype": "DEFAULT",
+      "status": "PENDING",
+      "module": "servicepoint",
+      "flexType": "CARRIER::DEFAULT",
+      "retailerId": "2"
+    }
+  ]
+}
+```
+
+**Integration with event.send:** The `eventName` from each `userAction` maps directly to
+`event.send`'s `name` parameter. The `attributes[]` tell you what to include in `event.send`'s
+`attributes` parameter.
+
+Notes:
+- `retailerId` is required per trigger (falls back to `FLUENT_RETAILER_ID`)
+- `module`, `flexType`, `status` are optional filters
+- Response includes `userActions` with `eventName`, `context`, and `attributes`
+
+### Workflow Analysis Flow
+
+For end-to-end workflow understanding:
+1. Download workflow JSON (via Fluent CLI or `workflow_download`)
+2. `plugin.list` — look up rules referenced in rulesets to understand what each does
+3. `workflow.transitions` — query user actions for each entity state to see what UI buttons appear
+
+## Response Optimization
+
+High-volume tools support response shaping to reduce token consumption:
+
+### event.list — Field Projection
+
+Pass `fields` (array of strings) to return only selected fields per event. Reduces token usage by 7-8x for typical queries.
+
+```json
+{
+  "context.entityRef": "ORDER_REF",
+  "context.entityType": "ORDER",
+  "count": 50,
+  "fields": ["id", "name", "eventStatus", "category", "generatedOn", "context.entityRef", "context.entityType"]
+}
+```
+
+Common field sets by use case:
+- **Trace/debug:** `["id", "name", "eventStatus", "category", "context.entityRef", "context.entityType", "generatedOn", "source", "context.sourceEvents"]`
+- **E2E status check:** `["id", "name", "eventStatus", "context.entityRef"]`
+- **Exception analysis:** `["id", "name", "eventStatus", "category", "attributes", "context.entityRef", "generatedOn"]`
+
+Omit `fields` for full event data (when you need attributes, source, timing, etc.).
+
+### plugin.list — Compact Mode
+
+Pass `compact: true` to return only `ruleInfo` (name, description, entity types) per rule, stripping `parameters` and `eventAttributes`. Reduces token usage by 40-60x for unfiltered queries.
+
+```json
+{ "compact": true }
+{ "name": "SendEvent", "compact": true }
+```
+
+Use full mode (default) when you need rule parameters or event attribute contracts.
+
+## Pagination Pattern
+
+Fluent uses Relay-style connections. Cursors live on each **edge**, not on pageInfo:
+
+```graphql
+{
+  orders(first: 50, after: $cursor) {
+    edges {
+      cursor
+      node { id ref status }
+    }
+    pageInfo { hasNextPage }
+  }
+}
+```
+
+Take cursor from the LAST edge, pass as `after` in next call.

package/content/mcp-official/agents/fluent-mcp-core.md

@@ -0,0 +1,91 @@
+---
+name: fluent-mcp-core
+description: Official Fluent Commerce CLI MCP server agent. Provides GraphQL query building, schema validation, workflow listing/downloading, and health diagnostics via the built-in MCP server. Triggers on "fluent mcp core", "mcp server", "graphql build", "workflow list".
+tools: Bash, Read, Write, Edit, Glob, Grep
+model: inherit
+skills: fluent-mcp-core
+---
+
+# Fluent MCP Core Agent
+
+You are a specialist for the official Fluent Commerce CLI MCP server. This is the built-in MCP server shipped with the Fluent CLI, started via `fluent mcp server --stdio`.
+
+## Setup
+
+The server is configured in `.mcp.json` at the project root:
+
+```json
+{
+  "mcpServers": {
+    "fluent-mcp": {
+      "command": "fluent",
+      "args": ["mcp", "server", "--stdio"],
+      "env": {
+        "FLUENT_PROFILE": "<profile-name>"
+      }
+    }
+  }
+}
+```
+
+Requires an active Fluent CLI profile (`fluent profile active`).
+
+## Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| `health.ping` | Confirm SDK adapter connection and config readiness |
+| `graphql.execute` | Execute a GraphQL query or mutation against the Fluent endpoint |
+| `graphql.listRoots` | List all query and mutation root fields from the schema |
+| `graphql.validate` | Validate a GraphQL document against the cached schema |
+| `graphql.generateFull` | Generate a maximal-selection query for a root field (depth-limited) |
+| `graphql.buildQuery` | Generate a query/mutation string from field selections and args |
+| `workflow.list` | List all workflows for a retailer (names, versions, types) |
+| `workflow.download` | Download a specific workflow definition (complete JSON) |
+
+## Key Behaviors
+
+1. **Check health first**: Run `health.ping` to verify the server is connected
+2. **Use `graphql.buildQuery`** to construct queries from field selections
+3. **Use `graphql.validate`** to check queries before execution
+4. **Use `graphql.generateFull`** to explore types at configurable depth
+5. **Prefer `graphql.listRoots`** to discover available queries and mutations
+
+## Workflow Operations
+
+```
+workflow.list(profile: "YOUR_PROFILE", retailer: "YOUR_RETAILER_REF")
+workflow.download(profile: "YOUR_PROFILE", retailer: "YOUR_RETAILER_REF", workflow: "ORDER::MULTI")
+```
+
+## GraphQL Operations
+
+```
+graphql.listRoots()
+graphql.buildQuery(rootField: "orders", fields: ["id", "ref", "status", "type"])
+graphql.validate(query: "{ orders(first: 10) { edges { node { id ref } } } }")
+graphql.execute(query: "{ orders(first: 10) { edges { node { id ref status } } } }")
+```
+
+## Differences from MCP Extension
+
+| Feature | MCP Core | MCP Extension |
+|---------|----------|---------------|
+| Server | Built-in CLI (`fluent mcp server`) | Custom (`fluent-mcp-extn`) |
+| Auth | CLI profile | Profile / OAuth / Token Command / Static Token |
+| Events | Not supported | Full event API |
+| Batch ingestion | Not supported | Full batch API |
+| Webhooks | Not supported | Webhook validation |
+| Auto-pagination | Not supported | `graphql.queryAll` |
+| Batch mutations | Not supported | `graphql.batchMutate` (up to 50) |
+| Schema tools | `generateFull`, `listRoots`, `validate`, `buildQuery` | `graphql.introspect` |
+| Workflows | `workflow.list`, `workflow.download` | Not supported |
+
+## Event Operations
+
+Event dispatch and querying are handled by the **MCP Extension server** (`fluent-mcp-extn`), not this official CLI MCP server.
+
+For event operations, redirect to:
+- Event dispatch and queries → `/fluent-mcp-tools`
+- Event model and semantics → `/fluent-event-api`
+- Event debugging → `/fluent-trace`

package/content/mcp-official/skills/fluent-mcp-core/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: fluent-mcp-core
+description: Official Fluent Commerce CLI MCP server setup and operations. Configure the built-in MCP server, run health checks, build/validate GraphQL queries, and manage workflows. Triggers on "mcp core setup", "fluent mcp server", "graphql validate", "workflow download".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: <operation> [--profile name] [--retailer ref]
+---
+
+# Fluent MCP Core
+
+Setup and operations guide for the official Fluent Commerce CLI MCP server.
+
+## When to Use
+
+- Setting up the built-in MCP server for a project
+- Building and validating GraphQL queries against the schema
+- Listing or downloading workflow definitions
+- Diagnosing MCP server connectivity issues
+
+## Setup
+
+### 1. Ensure CLI Profile Exists
+
+```bash
+fluent profile active
+fluent profile list
+```
+
+### 2. Configure `.mcp.json`
+
+Add to your project root:
+
+```json
+{
+  "mcpServers": {
+    "fluent-mcp": {
+      "command": "fluent",
+      "args": ["mcp", "server", "--stdio"],
+      "env": {
+        "FLUENT_PROFILE": "YOUR_PROFILE"
+      }
+    }
+  }
+}
+```
+
+### 3. Verify Connection
+
+Use `health.ping` tool to confirm the server is connected and the profile is valid.
+
+## Operations
+
+### Health Check
+
+Run `health.ping` to confirm config readiness and SDK adapter status.
+
+### GraphQL
+
+| Operation | Tool | Description |
+|-----------|------|-------------|
+| Discover fields | `graphql.listRoots` | List all query/mutation root fields |
+| Explore type | `graphql.generateFull` | Generate maximal query for a root field |
+| Build query | `graphql.buildQuery` | Create query from field selections |
+| Validate | `graphql.validate` | Check query against schema |
+| Execute | `graphql.execute` | Run query/mutation |
+
+### Workflows
+
+| Operation | Tool | Description |
+|-----------|------|-------------|
+| List | `workflow.list` | All workflows for a retailer |
+| Download | `workflow.download` | Full workflow JSON with rulesets |
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `health.ping` fails | No active profile | Run `fluent profile active` |
+| Auth error | Expired token | Run `fluent auth login -p <PROFILE>` |
+| Empty workflow list | Wrong retailer ref | Check `fluent retailer list -p <PROFILE>` |
+| Server won't start | CLI not in PATH | `npm i -g @fluentcommerce/cli` |
+
+## MCP Core vs MCP Extension
+
+Use **MCP Core** when you need:
+- Query building and schema validation
+- Workflow listing and downloading
+- Simple GraphQL with CLI profile auth
+
+Use **MCP Extension** (`mcp` group) when you need:
+- Event dispatch (build, send, verify)
+- Auto-paginated queries
+- Batch mutations and data ingestion
+- Webhook validation