@fluentcommerce/ai-skills 0.1.0 → 0.3.0

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

@@ -1,91 +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`
+---
+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

@@ -1,94 +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
+---
+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