@fluentcommerce/fluent-mcp-extn 0.1.0 → 0.2.1

package/dist/fluent-client.js

@@ -149,19 +149,19 @@ export class FluentClientAdapter {
     async queryPrometheus(payload) {
         const isRange = payload.type === "range";
         const query = isRange
-            ? `query MetricRange($query: String!, $start: DateTime!, $end: DateTime!, $step: String!) {
-          metricRange(query: $query, start: $start, end: $end, step: $step) {
-            status
-            data { resultType result { metric values } }
-            errorType error warnings
-          }
+            ? `query MetricRange($query: String!, $start: DateTime!, $end: DateTime!, $step: String!) {
+          metricRange(query: $query, start: $start, end: $end, step: $step) {
+            status
+            data { resultType result { metric values } }
+            errorType error warnings
+          }
         }`
-            : `query MetricInstant($query: String!${payload.time ? ", $time: DateTime" : ""}) {
-          metricInstant(query: $query${payload.time ? ", time: $time" : ""}) {
-            status
-            data { resultType result { metric value } }
-            errorType error warnings
-          }
+            : `query MetricInstant($query: String!${payload.time ? ", $time: DateTime" : ""}) {
+          metricInstant(query: $query${payload.time ? ", time: $time" : ""}) {
+            status
+            data { resultType result { metric value } }
+            errorType error warnings
+          }
         }`;
         const variables = { query: payload.query };
         if (isRange) {

package/dist/tools.js

@@ -193,6 +193,7 @@ const GraphQLBatchMutateInputSchema = z.object({
     inputs: z.array(z.record(z.string(), z.unknown())).min(1).max(50),
     returnFields: z.array(z.string()).optional(),
     operationName: z.string().optional(),
+    dryRun: z.boolean().default(false),
 });
 const GraphQLIntrospectInputSchema = z.object({
     type: z.string().optional(),
@@ -888,6 +889,10 @@ const TOOL_DEFINITIONS = [
                     type: "string",
                     description: "Custom GraphQL operation name (default: Batch<MutationName>s).",
                 },
+                dryRun: {
+                    type: "boolean",
+                    description: "If true, builds and validates the mutation query without executing it. Returns the query, variables, and input count for review. Default: false.",
+                },
             },
             required: ["mutation", "inputs"],
             additionalProperties: false,
@@ -2540,6 +2545,18 @@ export function registerToolHandlers(server, ctx) {
                 for (let i = 0; i < batchSize; i++) {
                     variables[`input${i + 1}`] = parsed.inputs[i];
                 }
+                // Dry-run: return query + variables without executing
+                if (parsed.dryRun) {
+                    return json({
+                        ok: true,
+                        dryRun: true,
+                        mutation: parsed.mutation,
+                        inputCount: batchSize,
+                        query,
+                        variables,
+                        note: "No API call made. Set dryRun=false to execute.",
+                    });
+                }
                 const gqlPayload = {
                     query,
                     variables: toSdkVariables(variables),

package/docs/CONTRIBUTING.md

@@ -1,100 +1,100 @@
-# Contributing Guide
-
-This guide defines how to safely change `fluent-mcp-extn` while keeping
-behavior predictable for all clients.
-
-## 1) Core principles
-
-- Keep the extension **client-agnostic** (no client-specific names in code/docs).
-- Prefer **typed boundaries** and avoid unscoped `any`.
-- Keep tool responses consistent:
-  - success: `{ "ok": true, ... }`
-  - failure: `{ "ok": false, "error": { ... } }`
-- Route Fluent API calls through `FluentClientAdapter` only.
-
-## 2) Local setup
-
-```bash
-npm install
-npm run build
-npm test
-```
-
-## 3) Change workflow
-
-1. Make focused changes.
-2. Add or update tests.
-3. Run `npm run build`.
-4. Run `npm test`.
-5. Run `npm run e2e:smoke -- --skip-real-send` when touching tool runtime (requires `FLUENT_BASE_URL` + auth env, or `--profile`).
-6. Update docs if tool behavior/config changed.
-
-## 4) Adding a new tool (required checklist)
-
-When adding a tool, update all of the following:
-
-1. `src/tools.ts`
-   - add zod schema
-   - add `TOOL_DEFINITIONS` entry
-   - add handler branch
-2. `src/index.ts`
-   - add tool name to startup log list
-3. tests
-   - add/adjust unit tests in `test/`
-4. docs
-   - update `docs/TOOL_REFERENCE.md`
-   - update `docs/E2E_TESTING.md` if smoke flow changes
-
-## 5) Error handling standards
-
-- Throw `ToolError` for domain/runtime failures.
-- Do not return raw thrown errors directly.
-- Let `toToolFailure()` convert unknown errors into normalized error payloads.
-- Use specific error codes where possible (`AUTH_ERROR`, `VALIDATION_ERROR`, etc.).
-
-## 6) Resilience standards
-
-- Keep retry/timeout policy centralized via:
-  - `withTimeout()`
-  - `withRetry()`
-- Avoid per-tool custom retry loops.
-- Use config-driven values (`FLUENT_REQUEST_TIMEOUT_MS`, retry env vars).
-- Preserve idempotency boundaries:
-  - read operations can use retry/backoff
-  - non-idempotent write operations must not auto-retry
-- Keep SDK retry disabled and adapter retry as the single control plane.
-
-## 7) Security and secrets
-
-- Never log secrets or token values.
-- Use redacted summaries via `toSafeConfigSummary()`.
-- Prefer profile, `TOKEN_COMMAND`, or OAuth over static tokens in shared environments.
-
-## 8) Documentation standards
-
-- Keep docs concise and task-oriented.
-- Include at least one valid request example when changing tool inputs.
-- Update all cross-links in `README.md` when adding new docs.
-- For behavior changes, update all affected docs end-to-end:
-  - `README.md`
-  - `docs/TOOL_REFERENCE.md`
-  - `docs/RUNBOOK.md`
-  - `docs/E2E_TESTING.md`
-
-## 9) Pull request quality bar
-
-A change is ready only if:
-
-- build passes
-- tests pass
-- smoke runner passes (or is intentionally skipped with rationale)
-- no lint errors introduced
-- docs updated for behavior/interface changes
-- no client-specific wording added
-
-## 10) CI expectations
-
-- CI workflow file: `.github/workflows/ci.yml`
-- `build-and-test` must pass for every PR.
-- `e2e-smoke` is manual (`workflow_dispatch`) and requires repository secrets.
-
+# Contributing Guide
+
+This guide defines how to safely change `fluent-mcp-extn` while keeping
+behavior predictable for all clients.
+
+## 1) Core principles
+
+- Keep the extension **client-agnostic** (no client-specific names in code/docs).
+- Prefer **typed boundaries** and avoid unscoped `any`.
+- Keep tool responses consistent:
+  - success: `{ "ok": true, ... }`
+  - failure: `{ "ok": false, "error": { ... } }`
+- Route Fluent API calls through `FluentClientAdapter` only.
+
+## 2) Local setup
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## 3) Change workflow
+
+1. Make focused changes.
+2. Add or update tests.
+3. Run `npm run build`.
+4. Run `npm test`.
+5. Run `npm run e2e:smoke -- --skip-real-send` when touching tool runtime (requires `FLUENT_BASE_URL` + auth env, or `--profile`).
+6. Update docs if tool behavior/config changed.
+
+## 4) Adding a new tool (required checklist)
+
+When adding a tool, update all of the following:
+
+1. `src/tools.ts`
+   - add zod schema
+   - add `TOOL_DEFINITIONS` entry
+   - add handler branch
+2. `src/index.ts`
+   - add tool name to startup log list
+3. tests
+   - add/adjust unit tests in `test/`
+4. docs
+   - update `docs/TOOL_REFERENCE.md`
+   - update `docs/E2E_TESTING.md` if smoke flow changes
+
+## 5) Error handling standards
+
+- Throw `ToolError` for domain/runtime failures.
+- Do not return raw thrown errors directly.
+- Let `toToolFailure()` convert unknown errors into normalized error payloads.
+- Use specific error codes where possible (`AUTH_ERROR`, `VALIDATION_ERROR`, etc.).
+
+## 6) Resilience standards
+
+- Keep retry/timeout policy centralized via:
+  - `withTimeout()`
+  - `withRetry()`
+- Avoid per-tool custom retry loops.
+- Use config-driven values (`FLUENT_REQUEST_TIMEOUT_MS`, retry env vars).
+- Preserve idempotency boundaries:
+  - read operations can use retry/backoff
+  - non-idempotent write operations must not auto-retry
+- Keep SDK retry disabled and adapter retry as the single control plane.
+
+## 7) Security and secrets
+
+- Never log secrets or token values.
+- Use redacted summaries via `toSafeConfigSummary()`.
+- Prefer profile, `TOKEN_COMMAND`, or OAuth over static tokens in shared environments.
+
+## 8) Documentation standards
+
+- Keep docs concise and task-oriented.
+- Include at least one valid request example when changing tool inputs.
+- Update all cross-links in `README.md` when adding new docs.
+- For behavior changes, update all affected docs end-to-end:
+  - `README.md`
+  - `docs/TOOL_REFERENCE.md`
+  - `docs/RUNBOOK.md`
+  - `docs/E2E_TESTING.md`
+
+## 9) Pull request quality bar
+
+A change is ready only if:
+
+- build passes
+- tests pass
+- smoke runner passes (or is intentionally skipped with rationale)
+- no lint errors introduced
+- docs updated for behavior/interface changes
+- no client-specific wording added
+
+## 10) CI expectations
+
+- CI workflow file: `.github/workflows/ci.yml`
+- `build-and-test` must pass for every PR.
+- `e2e-smoke` is manual (`workflow_dispatch`) and requires repository secrets.
+