@fluentcommerce/fluent-mcp-extn 0.1.0

package/docs/HANDOVER_COPILOT_SETUP_STEPS.example.yml

@@ -0,0 +1,35 @@
+name: copilot-setup-steps
+
+on:
+  workflow_dispatch:
+  push:
+    # Change "main" if your default branch is different.
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: "fluent-mcp-extn/package-lock.json"
+
+      - name: Install dependencies
+        working-directory: fluent-mcp-extn
+        run: npm ci
+
+      - name: Build MCP extension server
+        working-directory: fluent-mcp-extn
+        run: npm run build

package/docs/HANDOVER_ENV.example

@@ -0,0 +1,29 @@
+# Choose one authentication strategy.
+# Strategy 1 (recommended for local dev): Fluent CLI profile
+# FLUENT_PROFILE=HMDEV
+# FLUENT_PROFILE_RETAILER=HM_TEST
+
+# Strategy 2 (recommended for CI/runtime): OAuth
+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
+
+# Strategy 3 (optional): Token command
+# FLUENT_BASE_URL=https://YOUR_ACCOUNT.sandbox.api.fluentretail.com
+# FLUENT_RETAILER_ID=YOUR_RETAILER_ID
+# TOKEN_COMMAND=vault read -field=token secret/fluent/client-dev
+
+# Strategy 4 (optional): Static token
+# FLUENT_BASE_URL=https://YOUR_ACCOUNT.sandbox.api.fluentretail.com
+# FLUENT_RETAILER_ID=YOUR_RETAILER_ID
+# FLUENT_ACCESS_TOKEN=YOUR_BEARER_TOKEN
+
+# Optional resilience tuning
+# FLUENT_REQUEST_TIMEOUT_MS=30000
+# FLUENT_RETRY_ATTEMPTS=3
+# FLUENT_RETRY_INITIAL_DELAY_MS=300
+# FLUENT_RETRY_MAX_DELAY_MS=5000
+# FLUENT_RETRY_FACTOR=2

package/docs/HANDOVER_GITHUB_COPILOT.md

@@ -0,0 +1,165 @@
+# fluent-mcp-extn Handover for GitHub Copilot
+
+This handover pack explains how to run `fluent-mcp-extn` with:
+
+1. GitHub Copilot in VS Code (local MCP server)
+2. GitHub Copilot coding agent on GitHub.com (repository MCP configuration)
+
+Use the checklists below exactly in order for first-time setup.
+
+## Dependencies
+
+`fluent-mcp-extn` talks directly to Fluent APIs through `@fluentcommerce/fc-connect-sdk`.
+
+- Runtime dependency on Fluent CLI: **No**
+- Runtime dependency on the official `fluent mcp server --stdio`: **No**
+- Optional Fluent CLI usage: **Yes**, only if your team chooses CLI-based helpers (for example profile workflows or smoke test shortcuts) — not required for normal MCP runtime
+
+## What colleagues need locally
+
+- Node.js 20+
+- npm
+- Access to Fluent credentials (profile, OAuth, token command, or static token)
+- This repository checked out locally
+
+## A) VS Code Copilot (local MCP server)
+
+### Step-by-step setup
+
+1) Build the server (from repository root):
+
+```bash
+cd fluent-mcp-extn
+npm install
+npm run build
+```
+
+2) Create local env file:
+
+Copy `fluent-mcp-extn/docs/HANDOVER_ENV.example` to `fluent-mcp-extn/.env.local` and fill real values.
+Both paths are relative to the repository root.
+
+3) Configure MCP in VS Code workspace:
+
+Copy `fluent-mcp-extn/docs/HANDOVER_VSCODE_MCP_JSON.example.json` to `.vscode/mcp.json` (relative to the repository root).
+
+4) Restart VS Code window (or reload) so MCP config is re-read.
+
+5) Start the MCP server in VS Code:
+
+1. Run `MCP: List Servers`
+2. Start `fluentMcpExtn`
+3. Accept trust prompt
+4. Run `MCP: Reset Cached Tools` if tools are stale after upgrades
+
+6) Verify in Copilot chat (agent mode), run:
+
+1. `config.validate`
+2. `health.ping`
+3. `graphql.query` with `query { __typename }`
+
+Expected minimum:
+
+- `config.validate` returns `ok: true`
+- `health.ping` returns `status: "ok"`
+- GraphQL test returns data without auth/config errors
+
+If these pass, local setup is complete.
+
+Operational behavior to know:
+
+- read operations use retry/backoff for transient failures
+- non-idempotent write operations do not auto-retry
+- `graphql.query` disables retries automatically when the request is a mutation
+
+### Updating after code changes
+
+When `fluent-mcp-extn` is updated (new tools, bug fixes), rebuild from the repository root:
+
+```bash
+cd fluent-mcp-extn
+npm install
+npm run build
+```
+
+Then restart the MCP server in VS Code (`MCP: List Servers` → stop → start).
+
+## B) GitHub Copilot coding agent (GitHub.com)
+
+### Step-by-step setup
+
+1) Create/use repository environment (for example `copilot`).
+
+2) Add environment secrets/variables in that environment with names beginning `COPILOT_MCP_`, such as:
+
+- `COPILOT_MCP_FLUENT_BASE_URL`
+- `COPILOT_MCP_FLUENT_RETAILER_ID`
+- `COPILOT_MCP_FLUENT_CLIENT_ID`
+- `COPILOT_MCP_FLUENT_CLIENT_SECRET`
+- `COPILOT_MCP_FLUENT_USERNAME`
+- `COPILOT_MCP_FLUENT_PASSWORD`
+
+The MCP config maps these names as bare strings in the `env` block. The Copilot coding agent automatically resolves each string value from the repository environment secret/variable of the same name — no `${{ secrets.X }}` syntax is needed.
+
+3) Ensure build runs in agent environment:
+
+Use `.github/workflows/copilot-setup-steps.yml` based on
+`docs/HANDOVER_COPILOT_SETUP_STEPS.example.yml`.
+
+The example includes both `workflow_dispatch` and `push` on `main` so setup can
+be run manually and also pre-built on default-branch pushes. If your default
+branch is not `main`, change it in the workflow file.
+
+4) Add MCP configuration in repository Copilot coding agent settings:
+
+Use the JSON in `docs/HANDOVER_GITHUB_REPO_MCP_CONFIG.example.json`.
+
+This configuration uses `type: "local"` and explicitly allowlists tools.
+
+5) Validate in a Copilot coding agent session:
+
+- trigger an agent task in the repository
+- open session logs and confirm MCP server start step succeeds
+- confirm tools are discovered (for example `config.validate`, `graphql.query`)
+
+### Updating after code changes
+
+The `copilot-setup-steps.yml` workflow runs `npm ci && npm run build` automatically, so the agent always uses the latest committed code. No manual rebuild is needed on GitHub — just push the updated `fluent-mcp-extn/` source.
+
+## Synchronous fulfilment options support
+
+`graphql.query` supports live checkout-style synchronous fulfilment options calls, for example:
+
+- `createFulfilmentOption(..., executionMode: AWAIT_ORCHESTRATION)`
+
+Important runtime requirement:
+
+- The target environment must have matching workflow(s), e.g. `FULFILMENT_OPTIONS::<type>`.
+- If missing, you will get:
+  - `Workflow [FULFILMENT_OPTIONS::<type>] not found`
+
+## Common first-run issues
+
+- `sdk adapter: not configured`
+  - check env values are present and mapped correctly
+- `AUTH_ERROR`
+  - verify client credentials/user password/token source
+  - `FLUENT_CLIENT_ID` is the Fluent **Account ID** (the same value used as `client_id` in the OAuth token request). Do not confuse it with a separate application client identifier.
+- `Workflow [FULFILMENT_OPTIONS::<type>] not found`
+  - deploy matching fulfilment options workflow for the selected retailer/type
+- webhook signature mismatch
+  - provide exact `rawBody` to `webhook.validate` (signature checks are byte-sensitive)
+
+## Security notes
+
+- Never commit real secrets to `.mcp.json`, `mcp.json`, or docs.
+- Prefer `envFile` locally (`.env.local`) and secret-backed values in GitHub environments.
+- Rotate credentials immediately if accidentally exposed.
+
+## Files in this handover pack
+
+- `HANDOVER_GITHUB_COPILOT.md` (this guide)
+- `HANDOVER_ENV.example`
+- `HANDOVER_VSCODE_MCP_JSON.example.json`
+- `HANDOVER_GITHUB_REPO_MCP_CONFIG.example.json`
+- `HANDOVER_COPILOT_SETUP_STEPS.example.yml`

package/docs/HANDOVER_GITHUB_REPO_MCP_CONFIG.example.json

@@ -0,0 +1,31 @@
+{
+  "mcpServers": {
+    "fluent-mcp-extn": {
+      "type": "local",
+      "command": "node",
+      "args": ["fluent-mcp-extn/dist/index.js"],
+      "tools": [
+        "config.validate",
+        "health.ping",
+        "event.build",
+        "event.send",
+        "event.get",
+        "event.list",
+        "graphql.query",
+        "batch.create",
+        "batch.send",
+        "batch.status",
+        "batch.batchStatus",
+        "batch.results"
+      ],
+      "env": {
+        "FLUENT_BASE_URL": "COPILOT_MCP_FLUENT_BASE_URL",
+        "FLUENT_RETAILER_ID": "COPILOT_MCP_FLUENT_RETAILER_ID",
+        "FLUENT_CLIENT_ID": "COPILOT_MCP_FLUENT_CLIENT_ID",
+        "FLUENT_CLIENT_SECRET": "COPILOT_MCP_FLUENT_CLIENT_SECRET",
+        "FLUENT_USERNAME": "COPILOT_MCP_FLUENT_USERNAME",
+        "FLUENT_PASSWORD": "COPILOT_MCP_FLUENT_PASSWORD"
+      }
+    }
+  }
+}

package/docs/HANDOVER_VSCODE_MCP_JSON.example.json

@@ -0,0 +1,10 @@
+{
+  "servers": {
+    "fluentMcpExtn": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${workspaceFolder}/fluent-mcp-extn/dist/index.js"],
+      "envFile": "${workspaceFolder}/fluent-mcp-extn/.env.local"
+    }
+  }
+}

package/docs/IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,299 @@
+# Fluent MCP Extension - Implementation Guide
+
+## 1) Why this project exists
+
+This repository exists to provide a **client-agnostic extension layer** on top
+of Fluent MCP capabilities without changing official Fluent tooling.
+
+Key goals:
+
+- keep `fluent-mcp` and Fluent CLI untouched (upgrade-safe)
+- centralize custom tooling in one reusable service
+- support multiple authentication strategies across environments
+- improve reliability and observability for production usage
+
+## 2) Why this should stay in its own repository
+
+Keeping this extension separate from application/client repos is intentional.
+
+- **Separation of concerns**: MCP tool runtime logic is independent from client
+  business workflows.
+- **Independent release cadence**: auth/resilience/tooling updates can ship
+  without coupling to client app releases.
+- **Multi-client reuse**: one codebase, environment-only customization.
+- **Lower upgrade risk**: no forking or patching official SDK/CLI internals.
+
+## 3) High-level architecture
+
+The runtime is split into explicit layers across 15 source files:
+
+### Core infrastructure
+
+- `src/index.ts`
+  - entry point: loads config, initializes SDK client, starts MCP server
+- `src/config.ts`
+  - reads env config
+  - applies defaults for timeout/retry values
+  - validates readiness (`config.validate`)
+- `src/sdk-client.ts`
+  - creates SDK client
+  - resolves auth strategy (profile -> OAuth -> token command -> static token)
+  - includes temporary token bridge for command-based token refresh
+- `src/fluent-client.ts`
+  - typed adapter over SDK client
+  - central execution path with idempotency-aware timeout/retry behavior
+- `src/errors.ts`
+  - standard tool error codes and response format
+  - 9 typed error codes: `CONFIG_ERROR`, `AUTH_ERROR`, `VALIDATION_ERROR`,
+    `TIMEOUT_ERROR`, `RATE_LIMIT`, `UPSTREAM_UNAVAILABLE`, `NETWORK_ERROR`,
+    `SDK_ERROR`, `UNKNOWN_ERROR`
+- `src/resilience.ts`
+  - `withTimeout` and `withRetry` primitives used by adapter
+- `src/event-payload.ts`
+  - deterministic event payload builder
+- `src/response-shaper.ts`
+  - auto-summarization engine for large API responses
+  - budget-based enforcement: prune nulls, cap arrays, summarize with record
+    counts, field inventories, value distributions, and sample records
+
+### Tool definitions and handlers
+
+- `src/tools.ts`
+  - MCP tool schemas and handlers (36 tools total: 25 core + 11 agentic)
+  - safe input parsing with `zod`
+  - normalized error responses
+  - all 36 tools registered in a single `TOOL_DEFINITIONS` array
+
+### Entity layer (agentic)
+
+- `src/entity-registry.ts`
+  - 12 entity types: ORDER, FULFILMENT, LOCATION, NETWORK, CUSTOMER, PRODUCT,
+    INVENTORY_POSITION, VIRTUAL_CATALOGUE, VIRTUAL_POSITION, CATEGORY, CARRIER,
+    SETTING
+  - required fields, compound keys, gotchas per entity type
+- `src/entity-tools.ts`
+  - `entity.create`, `entity.update`, `entity.get` handlers
+  - status-aware updates with optional transition validation
+
+### Workflow layer (agentic)
+
+- `src/workflow-tools.ts`
+  - `workflow.upload` — deploy workflow JSON with structure validation
+  - `workflow.diff` — compare two workflow definitions (summary, detailed, mermaid)
+  - `workflow.simulate` — static prediction of event outcomes from workflow JSON
+
+### Settings layer (agentic)
+
+- `src/settings-tools.ts`
+  - `setting.upsert` — create-or-update with upsert semantics
+  - `setting.bulkUpsert` — batch upsert up to 50 settings
+
+### Environment layer (agentic)
+
+- `src/environment-tools.ts`
+  - `environment.discover` — full environment snapshot (retailer, locations,
+    networks, catalogues, workflows, settings, modules, users)
+  - `environment.validate` — pre-flight checks (auth, retailer, locations,
+    inventory, workflows, settings, modules)
+
+### Test layer (agentic)
+
+- `src/test-tools.ts`
+  - `test.assert` — entity state assertions with optional polling mode
+
+## 4) End-to-end execution flow
+
+### Startup flow
+
+1. `src/index.ts` loads runtime config.
+2. `initSDKClient()` creates SDK adapter using best auth strategy.
+3. MCP server starts and registers all 36 tool handlers.
+
+### Tool invocation flow
+
+1. Tool input is validated by `zod` schema.
+2. Business payload is built (for example, event payload assembly).
+3. If API call is needed, tool goes through typed adapter.
+4. Adapter applies policy by operation type:
+   - read paths: `withTimeout` + `withRetry`
+   - non-idempotent write paths: `withTimeout` only
+5. Response is shaped through `response-shaper.ts` when budget is active.
+6. Errors are normalized into a consistent payload format.
+
+## 5) Authentication strategy and rationale
+
+Auth strategy order is:
+
+1. Fluent profile (`FLUENT_PROFILE`, optional `FLUENT_PROFILE_RETAILER`)
+2. OAuth (`FLUENT_CLIENT_ID` + `FLUENT_CLIENT_SECRET`)
+3. `TOKEN_COMMAND`
+4. `FLUENT_ACCESS_TOKEN`
+
+Why this order:
+
+- Profile auth is preferred for local dev because it reuses Fluent CLI profile state.
+- OAuth is preferred for CI/runtime because token lifecycle is managed by SDK.
+- Command-based token retrieval supports vault and enterprise secret flows.
+- Static token is a fallback for local/dev or temporary setups.
+
+### Token command behavior
+
+- accepts plain token output
+- accepts JSON output with `access_token` or `token`
+- enforces timeout via `TOKEN_COMMAND_TIMEOUT_MS`
+- temporary bridge refreshes token when expiry window is reached
+
+### Static token behavior
+
+- static token mode (`FLUENT_ACCESS_TOKEN`) does not refresh automatically
+- local expiry is intentionally long to avoid premature client-side invalidation
+- true token validity remains enforced by Fluent API
+
+## 6) Reliability model
+
+Reliability settings are centralized in config:
+
+- request timeout: `FLUENT_REQUEST_TIMEOUT_MS`
+- retry attempts: `FLUENT_RETRY_ATTEMPTS`
+- retry backoff:
+  - initial delay: `FLUENT_RETRY_INITIAL_DELAY_MS`
+  - max delay: `FLUENT_RETRY_MAX_DELAY_MS`
+  - factor: `FLUENT_RETRY_FACTOR`
+
+This avoids per-tool custom retry logic and keeps behavior consistent.
+
+Execution model:
+
+- read operations retry transient failures using exponential backoff
+- non-idempotent write operations are timeout-only (no automatic retry)
+- `graphql.query` detects mutation operations and disables retries when needed
+- `graphql.queryAll` uses pagination `timeoutMs` for whole-run timeout control
+- SDK internal retries are disabled so adapter policy is authoritative
+
+## 7) Response shaping model
+
+Response shaping is controlled by three env vars:
+
+- `FLUENT_RESPONSE_BUDGET_CHARS` (default 50000, ~12.5k tokens)
+- `FLUENT_RESPONSE_MAX_ARRAY` (default 50)
+- `FLUENT_RESPONSE_SAMPLE_SIZE` (default 3)
+
+When a response exceeds the budget:
+1. Null/empty values are stripped (protected keys like `ok`, `error`, `id`,
+   `ref`, `status` are preserved)
+2. Arrays exceeding `maxArrayElements` are replaced with summaries containing
+   record count, field inventory, value distributions, and sample records
+3. A `_responseMeta` object is attached with `originalChars`, `shapedChars`,
+   `reductionPercent`, and `summarizedArrays`
+
+Design rationale: auto-summarize rather than truncate. Truncated arrays give
+the LLM incomplete data it might trust. Summaries give a complete analytical
+picture that is safe to reason from.
+
+## 8) Error model
+
+Tool responses standardize failures as:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid tool arguments.",
+    "retryable": false,
+    "details": {}
+  }
+}
+```
+
+Supported codes include:
+
+- `CONFIG_ERROR`
+- `AUTH_ERROR`
+- `VALIDATION_ERROR`
+- `TIMEOUT_ERROR`
+- `RATE_LIMIT`
+- `UPSTREAM_UNAVAILABLE`
+- `NETWORK_ERROR`
+- `SDK_ERROR`
+- `UNKNOWN_ERROR`
+
+Error classification uses HTTP status codes from error object properties first,
+then Node.js error codes, then conservative keyword matching (never bare
+substring matching on messages).
+
+## 9) Tool inventory
+
+36 tools across 12 categories:
+
+| Category | Tools | Count |
+|----------|-------|-------|
+| Diagnostics | `config.validate`, `health.ping`, `connection.test` | 3 |
+| Events | `event.build`, `event.send`, `event.get`, `event.list`, `event.flowInspect` | 5 |
+| Metrics | `metrics.query`, `metrics.healthCheck`, `metrics.sloReport`, `metrics.labelCatalog`, `metrics.topEvents` | 5 |
+| Orchestration | `workflow.transitions`, `plugin.list` | 2 |
+| GraphQL | `graphql.query`, `graphql.queryAll`, `graphql.batchMutate`, `graphql.introspect` | 4 |
+| Batch | `batch.create`, `batch.send`, `batch.status`, `batch.batchStatus`, `batch.results` | 5 |
+| Webhook | `webhook.validate` | 1 |
+| Entity | `entity.create`, `entity.update`, `entity.get` | 3 |
+| Workflow | `workflow.upload`, `workflow.diff`, `workflow.simulate` | 3 |
+| Settings | `setting.upsert`, `setting.bulkUpsert` | 2 |
+| Environment | `environment.discover`, `environment.validate` | 2 |
+| Test | `test.assert` | 1 |
+
+## 10) Test coverage
+
+256 tests across 14 test files (Vitest):
+
+| Test file | Coverage area |
+|-----------|--------------|
+| `config.test.ts` | auth detection, validation, safe summary |
+| `errors.test.ts` | error classification, HTTP status mapping, normalization |
+| `event-payload.test.ts` | event payload builder defaults/overrides |
+| `fluent-client.test.ts` | retry/no-retry idempotency, pagination, client validation |
+| `metrics.test.ts` | metrics query, topEvents, sloReport, labelCatalog tools |
+| `metrics-healthcheck.test.ts` | healthCheck anomaly detection and fallback logic |
+| `resilience.test.ts` | withTimeout, withRetry, integration of both |
+| `sdk-client.test.ts` | profile, OAuth, and null auth paths |
+| `token-parser.test.ts` | command output token extraction |
+| `tools-handlers.test.ts` | tool handler registration, input validation, error envelopes, flowInspect flag gating/cross-entity |
+| `tools-helpers.test.ts` | event query params, transition request, mutation detection |
+| `response-shaper.test.ts` | auto-summarization, null pruning, budget enforcement, connection summarizer |
+| `simulation-tools.test.ts` | workflow.simulate direct handler tests, workflow.diff mermaid output |
+| `agentic-tools.test.ts` | entity registry, entity CRUD, workflow upload/diff/simulate, settings upsert, environment discover/validate, test.assert |
+
+Run with:
+
+```bash
+npm test
+```
+
+## 11) How to add a new tool safely
+
+Recommended pattern:
+
+1. add `zod` input schema in `src/tools.ts`
+2. add tool metadata entry in `TOOL_DEFINITIONS`
+3. implement handler in the appropriate module:
+   - entity operations: `src/entity-tools.ts`
+   - workflow operations: `src/workflow-tools.ts`
+   - settings operations: `src/settings-tools.ts`
+   - environment operations: `src/environment-tools.ts`
+   - test operations: `src/test-tools.ts`
+   - core operations: directly in `src/tools.ts` handler switch
+4. for entity tools, add entity type to `src/entity-registry.ts` if new
+5. return success payload via `json(...)`
+6. rely on shared catch block for normalized errors
+7. add focused unit tests for new logic
+8. run `npm run build` and `npm test`
+
+## 12) Known constraints and next improvements
+
+Current bridge for `TOKEN_COMMAND` token injection is intentionally temporary
+until the SDK exposes a first-class command/vault auth provider.
+
+Next recommended enhancements:
+
+- adopt SDK-native bearer/command auth provider once available
+- add request correlation IDs in tool logs
+- expand CI to enforce documentation integrity checks