@fluentcommerce/fluent-mcp-extn 0.1.0 → 0.2.0

package/package.json

@@ -1,10 +1,9 @@
 {
   "name": "@fluentcommerce/fluent-mcp-extn",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP (Model Context Protocol) extension server for Fluent Commerce. Exposes event dispatch, transition actions, GraphQL execution, Prometheus metrics, batch ingestion, and webhook validation as MCP tools.",
   "type": "module",
   "main": "dist/index.js",
-  "types": "dist/index.d.ts",
   "bin": {
     "fluent-mcp-extn": "dist/index.js"
   },
@@ -56,9 +55,6 @@
     "@modelcontextprotocol/sdk": "^1.26.0",
     "zod": "^4.3.6"
   },
-  "publishConfig": {
-    "access": "public"
-  },
   "devDependencies": {
     "@types/node": "^25.2.3",
     "tsx": "^4.21.0",

package/docs/IMPLEMENTATION_GUIDE.md

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