@fluentcommerce/fluent-mcp-extn 0.1.0 → 0.2.1

package/docs/HANDOVER_ENV.example

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

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