n8n-mcp-community 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,64 @@ All notable changes to this project will be documented here. The format follows
 
 ## [Unreleased]
 
+## [0.3.0] - Frozen release candidate
+
+Version 0.3.0 is a frozen release candidate. Availability is established only
+by matching npm provenance, GitHub Release assets and signatures, and MCP
+Registry readbacks; this immutable entry is not rewritten after publication.
+
+### Removed
+
+- **Breaking input-schema change:** `n8n_audit_generate` no longer publishes or
+  accepts `daysAbandonedWorkflow`. n8n Community 2.30.x stores that request
+  override in a legacy setting while the reporter reads typed instance
+  configuration, so the input could not reliably change the audit. Normal MCP
+  clients refresh the smaller schema after reconnecting; raw callers must stop
+  sending the removed field, omit empty category arrays, and deduplicate category
+  names. This incompatible `0.x` change is released as a new minor version.
+
+### Changed
+
+- `n8n_audit_generate` now publishes truthful read-only and idempotent safety
+  hints while retaining the conservative unsafe authorization gate for its
+  sensitive instance-wide report. It makes one request, accepts 1–5 unique
+  categories, treats n8n's empty-array clean result as an empty report, and
+  accepts nullable version metadata from n8n's version feed. It fails
+  explicitly instead of returning a partial audit when sanitizer or final
+  256 KiB result limits are exceeded; multi-category callers can retry with
+  fewer categories, while single-category callers can review the full report in
+  n8n.
+- Sanitized read results now distinguish content redaction from size reduction.
+  Audit reports use validated higher collection bounds within the same final
+  256 KiB envelope, while ordinary read tools keep safe bounded projections.
+- The generic 256 KiB ceiling now covers the complete serialized MCP result,
+  including text and structured content. Large reads that previously fit only
+  the text-side check now fail safely; already-applied mutations return a
+  bounded success summary with `truncated=true` and `redacted=true`.
+- Record parsing now preserves own `__proto__` keys through validation and
+  rewrites prototype-like output keys safely. Workflow updates retain those
+  graph entries instead of silently dropping them.
+- Development dependency `globals` was updated from 17.8.0 to 17.9.0.
+
+## [0.2.1] - Frozen release candidate
+
+Version 0.2.1 is a frozen release candidate. Availability is established only
+by matching npm provenance, GitHub Release assets and signatures, and MCP
+Registry readbacks; this immutable entry is not rewritten after publication.
+
+### Changed
+
+- Forty tool definitions now state their exact selector semantics, pagination
+  behavior, authorization or configuration boundary, side effects, and return
+  contract in shorter agent-facing language. The four definitions already
+  rated 5.0 by Glama remain unchanged.
+- The durable 44-tool definition matrix now checks parameter, authorization,
+  configuration, return, annotation, and task-support invariants independently.
+  Controlled mutations prove that every invariant rejects semantic drift.
+- Execution-stop documentation now names every stoppable state and the
+  terminal-race mapping. Health documentation now states the explicit opt-in
+  required for remote plaintext HTTP.
+
 ## [0.2.0] - Frozen release candidate
 
 Version 0.2.0 is a frozen release candidate. Availability is established only
@@ -285,6 +343,8 @@ Registry readbacks; this immutable entry is not rewritten after publication.
   publishable history; authenticated public release receipts remain supported.
 
 [Unreleased]: #unreleased
+[0.3.0]: #030---frozen-release-candidate
+[0.2.1]: #021---frozen-release-candidate
 [0.2.0]: #020---frozen-release-candidate
 [0.1.4]: #014---frozen-release-candidate
 [0.1.3]: #013---frozen-release-candidate

package/README.md

@@ -104,7 +104,7 @@ how to check the download.
 The current source candidate has been verified with:
 
 - exactly **44 tools**, **5 resources**, and **4 prompts** over real stdio;
-- **296 passing tests** locally on Node.js 24.18.1; CI and release gates require
+- **313 passing tests** locally on Node.js 24.19.0; CI and release gates require
   the pinned Node.js 22.23.1 and 24.18.0 matrix;
 - zero findings from Gitleaks, Semgrep, Trivy, and both project-root
   production/full `npm audit` runs; all three source scanners are reproduced in
@@ -170,13 +170,13 @@ failure, and security reference.
 
 ### Executions
 
-| Tool                                                           | Mode      | Purpose                                                            |
-| -------------------------------------------------------------- | --------- | ------------------------------------------------------------------ |
-| [`n8n_executions_list`](docs/tools.md#n8n_executions_list)     | Read-only | List execution metadata with value-free data-presence summaries.   |
-| [`n8n_executions_get`](docs/tools.md#n8n_executions_get)       | Read-only | Read one execution's metadata without returning workflow payloads. |
-| [`n8n_executions_delete`](docs/tools.md#n8n_executions_delete) | Unsafe    | Permanently delete a saved execution.                              |
-| [`n8n_executions_retry`](docs/tools.md#n8n_executions_retry)   | Unsafe    | Retry an eligible saved execution.                                 |
-| [`n8n_executions_stop`](docs/tools.md#n8n_executions_stop)     | Unsafe    | Stop one running execution and bind identity from validated input. |
+| Tool                                                           | Mode      | Purpose                                                              |
+| -------------------------------------------------------------- | --------- | -------------------------------------------------------------------- |
+| [`n8n_executions_list`](docs/tools.md#n8n_executions_list)     | Read-only | List execution metadata with value-free data-presence summaries.     |
+| [`n8n_executions_get`](docs/tools.md#n8n_executions_get)       | Read-only | Read one execution's metadata without returning workflow payloads.   |
+| [`n8n_executions_delete`](docs/tools.md#n8n_executions_delete) | Unsafe    | Permanently delete a saved execution.                                |
+| [`n8n_executions_retry`](docs/tools.md#n8n_executions_retry)   | Unsafe    | Retry an eligible saved execution.                                   |
+| [`n8n_executions_stop`](docs/tools.md#n8n_executions_stop)     | Unsafe    | Stop one stoppable execution and bind identity from validated input. |
 
 ### Credentials
 
@@ -291,7 +291,7 @@ API. The project does not redistribute the `n8n-nodes-base` catalog and does not
 use browser cookies, interactive session routes, or runtime package downloads to
 construct one.
 
-The v0.2.0 candidate surface intentionally excludes arbitrary workflow execution,
+The v0.3.0 candidate surface intentionally excludes arbitrary workflow execution,
 credential/workflow transfer, folders, data tables, beta evaluation endpoints,
 and execution annotations. See the [roadmap](ROADMAP.md) for the annotation
 proposal retained outside the release target.

package/ROADMAP.md

@@ -18,7 +18,7 @@ maintainer approval.
 
 ## Accepted backlog proposal
 
-Execution annotations remain a coherent two-tool proposal outside v0.2.0:
+Execution annotations remain a coherent two-tool proposal outside v0.3.0:
 
 - `n8n_executions_get_tags`
 - `n8n_executions_update_tags`

package/SECURITY.md

@@ -6,7 +6,7 @@ before public disclosure.
 
 ## Supported versions
 
-The latest maintained minor line — currently 0.2.x — receives security fixes.
+The latest maintained minor line — currently 0.3.x — receives security fixes.
 Older lines may be asked to upgrade when a safe backport is impractical.
 
 ## Report a vulnerability

package/dist/introspect/contracts.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { preservingRecord } from "../tools/schemas.js";
 import { INTROSPECT_RULE_IDS } from "./rule-ids.js";
 export const INTROSPECT_SCHEMA_VERSION = "1.0.0";
 export const INTROSPECT_ENGINE_VERSION = "2.0.0";
@@ -98,8 +99,8 @@ export const WorkflowNodeSchema = z
     onError: z.string().max(128).optional(),
     executeOnce: z.boolean().optional(),
     alwaysOutputData: z.boolean().optional(),
-    parameters: z.record(z.unknown()).optional(),
-    credentials: z.record(z.unknown()).optional(),
+    parameters: preservingRecord(z.unknown()).optional(),
+    credentials: preservingRecord(z.unknown()).optional(),
 })
     .passthrough();
 export const WorkflowResponseSchema = z
@@ -109,9 +110,9 @@ export const WorkflowResponseSchema = z
     active: z.boolean(),
     triggerCount: z.number().int().nonnegative().optional(),
     nodes: z.array(WorkflowNodeSchema).max(1_000).default([]),
-    connections: z.record(z.unknown()).default({}),
-    settings: z.record(z.unknown()).default({}),
-    pinData: z.record(z.unknown()).nullable().optional(),
+    connections: preservingRecord(z.unknown()).default({}),
+    settings: preservingRecord(z.unknown()).default({}),
+    pinData: preservingRecord(z.unknown()).nullable().optional(),
 })
     .passthrough();
 const ApiIdentifierSchema = z.union([z.string(), z.number()]).transform(String);
@@ -138,7 +139,7 @@ export const ExecutionListResponseSchema = z
 })
     .passthrough();
 export const ExecutionDetailResponseSchema = ExecutionMetadataSchema.extend({
-    data: z.record(z.unknown()).optional(),
+    data: preservingRecord(z.unknown()).optional(),
 }).passthrough();
 export const SeveritySchema = z.enum(["critical", "high", "medium", "low", "info"]);
 export const ConfidenceSchema = z.enum(["high", "medium", "low"]);
@@ -171,7 +172,7 @@ export const FindingSchema = z.object({
     }),
     evidence: z.object({
         summary: z.string(),
-        facts: z.record(FactValueSchema).optional(),
+        facts: preservingRecord(FactValueSchema).optional(),
     }),
     remediation: z.string(),
     documentationUrl: z

package/dist/security/redaction.js

@@ -54,6 +54,32 @@ export class OutputLimitError extends Error {
         this.name = "OutputLimitError";
     }
 }
+const DEFAULT_SANITIZATION_LIMITS = Object.freeze({
+    arrayLength: 1_000,
+    depth: 20,
+    nodes: 20_000,
+    objectEntries: 1_000,
+    stringInputLength: 131_072,
+    stringOutputLength: 32_768,
+});
+function resolvedLimit(value, fallback, name) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new RangeError(`${name} must be a positive safe integer.`);
+    }
+    return value;
+}
+function sanitizationLimits(options) {
+    return {
+        arrayLength: resolvedLimit(options.maxArrayLength, DEFAULT_SANITIZATION_LIMITS.arrayLength, "maxArrayLength"),
+        depth: resolvedLimit(options.maxDepth, DEFAULT_SANITIZATION_LIMITS.depth, "maxDepth"),
+        nodes: resolvedLimit(options.maxNodes, DEFAULT_SANITIZATION_LIMITS.nodes, "maxNodes"),
+        objectEntries: resolvedLimit(options.maxObjectEntries, DEFAULT_SANITIZATION_LIMITS.objectEntries, "maxObjectEntries"),
+        stringInputLength: resolvedLimit(options.maxStringInputLength, DEFAULT_SANITIZATION_LIMITS.stringInputLength, "maxStringInputLength"),
+        stringOutputLength: resolvedLimit(options.maxStringOutputLength, DEFAULT_SANITIZATION_LIMITS.stringOutputLength, "maxStringOutputLength"),
+    };
+}
 function compareStrings(left, right) {
     return left < right ? -1 : left > right ? 1 : 0;
 }
@@ -103,13 +129,16 @@ function looksLikeOpaquePathSegment(value) {
     }
     return entropy >= (value.length >= 32 ? 3.5 : 4);
 }
-function sanitizeString(value, structuralKey) {
-    const boundedInput = value.length > 131_072 ? value.slice(0, 131_072) : value;
+function sanitizeString(value, structuralKey, limits = DEFAULT_SANITIZATION_LIMITS) {
+    const boundedInput = value.length > limits.stringInputLength ? value.slice(0, limits.stringInputLength) : value;
     const normalizedInput = boundedInput.normalize("NFKC");
     let output = normalizedInput
-        .slice(0, 131_072)
+        .slice(0, limits.stringInputLength)
         .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, "");
-    let redacted = boundedInput !== value || normalizedInput.length > 131_072 || output !== boundedInput;
+    let redacted = boundedInput !== value ||
+        normalizedInput.length > limits.stringInputLength ||
+        output !== boundedInput;
+    let sizeReduced = boundedInput !== value || normalizedInput.length > limits.stringInputLength;
     for (const [pattern, replacement] of HIGH_CONFIDENCE_CREDENTIAL_REDACTIONS) {
         pattern.lastIndex = 0;
         const filtered = output.replace(pattern, replacement);
@@ -132,7 +161,7 @@ function sanitizeString(value, structuralKey) {
         ((structuralKey === "documentationUrl" || structuralKey === "officialUrl") &&
             isOfficialN8nDocumentationUrl(output));
     if (validatedInternalValueIsSafe)
-        return { value: output, redacted };
+        return { value: output, redacted, sizeReduced };
     for (const [pattern, replacement] of MANDATORY_VALUE_REDACTIONS) {
         pattern.lastIndex = 0;
         const filtered = output.replace(pattern, replacement);
@@ -151,7 +180,7 @@ function sanitizeString(value, structuralKey) {
             STRUCTURAL_IDENTIFIER_KEY.test(structuralKey) &&
             SAFE_IDENTIFIER_VALUE.test(output);
     if (structuralValueIsSafe)
-        return { value: output, redacted };
+        return { value: output, redacted, sizeReduced };
     for (const [pattern, replacement] of TOKEN_REDACTIONS) {
         pattern.lastIndex = 0;
         const filtered = output.replace(pattern, replacement);
@@ -170,31 +199,35 @@ function sanitizeString(value, structuralKey) {
     const withPhone = redactPhone(output);
     redacted ||= withPhone !== output;
     output = withPhone;
-    if (output.length > 32_768) {
-        output = `${output.slice(0, 32_767)}\u2026`;
+    if (output.length > limits.stringOutputLength) {
+        output = `${output.slice(0, Math.max(0, limits.stringOutputLength - 1))}\u2026`;
         redacted = true;
+        sizeReduced = true;
     }
-    return { value: output, redacted };
+    return { value: output, redacted, sizeReduced };
 }
 function sanitizeValue(value, state, depth, structuralKey, preserveChildKeys = false, sensitiveDescriptor = false, treatSensitiveKeyAsStructural = false) {
     state.nodes += 1;
-    if (state.nodes > 20_000 || depth > 20) {
+    if (state.nodes > state.limits.nodes || depth > state.limits.depth) {
         state.redacted = true;
         state.structurallyReduced = true;
+        state.sizeReduced = true;
         return "[TRUNCATED]";
     }
     if (typeof value === "string") {
-        const result = sanitizeString(value, structuralKey);
+        const result = sanitizeString(value, structuralKey, state.limits);
         state.redacted ||= result.redacted;
+        state.sizeReduced ||= result.sizeReduced;
         return result.value;
     }
     if (value === null || typeof value === "boolean" || typeof value === "number")
         return value;
     if (Array.isArray(value)) {
-        const limit = Math.min(value.length, 1_000);
+        const limit = Math.min(value.length, state.limits.arrayLength);
         if (limit < value.length) {
             state.redacted = true;
             state.structurallyReduced = true;
+            state.sizeReduced = true;
         }
         return value
             .slice(0, limit)
@@ -225,14 +258,11 @@ function sanitizeValue(value, state, depth, structuralKey, preserveChildKeys = f
         typeof candidate === "string" &&
         SENSITIVE_KEY.test(candidate));
     const originalKeys = new Set(entries.map(([key]) => key));
-    for (const [entryIndex, [key, child]] of entries.slice(0, 1_000).entries()) {
-        if (PROTOTYPE_KEY.test(key)) {
-            state.redacted = true;
-            continue;
-        }
-        const sanitizedKey = sanitizeString(key);
+    for (const [entryIndex, [key, child]] of entries.slice(0, state.limits.objectEntries).entries()) {
+        const sanitizedKey = sanitizeString(key, undefined, state.limits);
+        state.sizeReduced ||= sanitizedKey.sizeReduced;
         let outputKey = key;
-        if (sanitizedKey.redacted) {
+        if (PROTOTYPE_KEY.test(key) || sanitizedKey.redacted) {
             let placeholderIndex = entryIndex + 1;
             do {
                 outputKey = `[REDACTED_KEY_${placeholderIndex}]`;
@@ -277,18 +307,26 @@ function sanitizeValue(value, state, depth, structuralKey, preserveChildKeys = f
         }
         output[outputKey] = sanitizeValue(child, state, depth + 1, key, STRUCTURAL_MAP_KEY.test(key), false);
     }
-    if (entries.length > 1_000) {
+    if (entries.length > state.limits.objectEntries) {
         state.redacted = true;
         state.structurallyReduced = true;
+        state.sizeReduced = true;
     }
     return output;
 }
 export function sanitizeForOutputDetailed(value, options = {}) {
-    const state = { nodes: 0, redacted: false, structurallyReduced: false };
+    const state = {
+        nodes: 0,
+        redacted: false,
+        structurallyReduced: false,
+        sizeReduced: false,
+        limits: sanitizationLimits(options),
+    };
     const data = sanitizeValue(value, state, 0, undefined, false, false, options.preserveValidatedRootRecordValues ?? false);
     return {
         output: { data, redacted: state.redacted, untrusted: true },
         structurallyReduced: state.structurallyReduced,
+        sizeReduced: state.sizeReduced,
     };
 }
 export function sanitizeForOutput(value, options = {}) {

package/dist/tools/common.js

@@ -1,10 +1,10 @@
 import { z } from "zod";
-import { cursor } from "./schemas.js";
+import { cursor, preservingRecord } from "./schemas.js";
 export const apiIdentifier = z.union([z.string(), z.number()]).transform(String);
 export const entitySchema = z.object({ id: apiIdentifier }).passthrough();
 export const listEnvelopeSchema = z
     .object({
-    data: z.array(z.record(z.unknown())).max(100),
+    data: z.array(preservingRecord(z.unknown())).max(100),
     nextCursor: cursor.nullable().optional(),
 })
     .passthrough();

package/dist/tools/credentials.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { defineTool } from "./definition.js";
 import { booleanQuery, numberQuery } from "./common.js";
-import { assertSafeJson, cursor, identifier, pageLimit, pathSegment, safeJsonValue, } from "./schemas.js";
+import { assertSafeJson, cursor, identifier, pageLimit, pathSegment, preservingRecord, safeJsonValue, } from "./schemas.js";
 import { credentialTypeSchema } from "./response-contracts.js";
 const credentialMetadataSchema = z.object({
     id: identifier(),
@@ -47,7 +47,7 @@ const usageWorkflowSchema = z.object({
         id: identifier().optional(),
         name: z.string().min(1).max(256),
         type: z.string().min(1).max(256),
-        credentials: z.record(workflowCredentialReferenceSchema).optional(),
+        credentials: preservingRecord(workflowCredentialReferenceSchema).optional(),
     }))
         .max(1_000),
 });
@@ -59,7 +59,7 @@ export const credentialTools = Object.freeze([
     defineTool({
         name: "n8n_credentials_create",
         title: "Create credential",
-        description: "Create and persist one credential as an additive write. Use n8n_credentials_schema first; use n8n_credentials_update when the credential exists. type selects the schema the caller should use to construct data, and isResolvable is sent only when supplied. Requires write/unsafe mode plus credential-create permission. Secret values belong only in input and are excluded from logs and output; returns metadata only.",
+        description: "Create and persist one credential as an additive write. First call n8n_credentials_schema with the planned type, then build data from its field contract; name is only the stored label. isResolvable is forwarded only when supplied. Use n8n_credentials_update for an existing credential. Requires write/unsafe mode plus create permission. Secret values belong only in data input and are excluded from logs and output; returns metadata only.",
         operation: "write",
         outputDataDescription: "Validated credential metadata with id, name, type, optional timestamps, managed/global flags, and resolvability. Stored credential values are never returned.",
         destructive: false,
@@ -73,9 +73,7 @@ export const credentialTools = Object.freeze([
                 .string()
                 .regex(/^[A-Za-z0-9_.-]{1,128}$/)
                 .describe("Public n8n credential type returned by n8n_credentials_schema."),
-            data: z
-                .record(safeJsonValue)
-                .describe("Credential field values matching the selected public schema; never returned."),
+            data: preservingRecord(safeJsonValue).describe("Credential field values matching the selected public schema; never returned."),
             isResolvable: z
                 .boolean()
                 .optional()
@@ -89,7 +87,7 @@ export const credentialTools = Object.freeze([
     defineTool({
         name: "n8n_credentials_delete",
         title: "Delete credential",
-        description: "Permanently delete one stored credential, which can break every referencing workflow. Use n8n_credentials_usage across all pages first; use n8n_credentials_update when replacement is sufficient. No secret or rollback is returned. Requires unsafe mode plus credential-delete permission; returns the request-bound ID with deleted=true.",
+        description: "Permanently delete one stored credential, which can break every referencing workflow. credentialId must be the stable ID from n8n_credentials_list, get, or create; a credential name or type is not accepted. Scan all n8n_credentials_usage pages first, or update when replacement is enough. No secret or rollback is returned. Requires unsafe mode plus credential-delete permission; returns the request-bound credentialId with deleted=true.",
         operation: "unsafe",
         outputDataDescription: "Object with the validated input credentialId and deleted=true. Identity is bound to the request because n8n does not consistently return the deleted credential ID.",
         input: { credentialId: identifier("Stable ID of the credential to delete.") },
@@ -103,7 +101,7 @@ export const credentialTools = Object.freeze([
     defineTool({
         name: "n8n_credentials_schema",
         title: "Get credential schema",
-        description: "Get n8n's Public API field schema for one credential type. Use it before n8n_credentials_create or replacement-data updates; use n8n_credentials_get for stored metadata. credentialType is a route selector, not a stored credential ID, so this call never reads credential values. Requires schema-read permission; returns the validated upstream field contract without testing credentials.",
+        description: "Get n8n's Public API field contract for one credential type. credentialType is the public type name used by create/update, not a stored credential ID, name, or secret. Its result tells the caller which keys belong in data; it does not read or test a stored credential. Use n8n_credentials_get for stored metadata. Requires schema-read permission; returns the validated upstream field contract.",
         operation: "read-only",
         outputDataDescription: "Validated Public API schema object for the requested credential type. It describes accepted fields and constraints but never contains stored credential values.",
         input: {
@@ -116,7 +114,7 @@ export const credentialTools = Object.freeze([
     defineTool({
         name: "n8n_credentials_list",
         title: "List credentials",
-        description: "List one Public API page of credential metadata using the endpoint supported from n8n Community 2.30.5. Use it for discovery; use n8n_credentials_get when the ID is known. cursor resumes a prior page and limit bounds that single request; this call never auto-paginates. Requires credential-list permission; returns metadata and nextCursor, never stored values.",
+        description: "List one Public API page of credential metadata; the endpoint is supported from n8n Community 2.30.5. Omit cursor for page one. For later pages, pass nextCursor back unchanged; limit sizes only that request, and the tool never auto-paginates. Use n8n_credentials_get when an ID is known. Requires credential-list permission; returns metadata and nextCursor, never stored values.",
         operation: "read-only",
         outputDataDescription: "Object with data (up to 100 credential metadata records) and nextCursor (string or null). Records contain allowlisted metadata only; credential values are rejected.",
         input: { limit: pageLimit(), cursor: cursor.optional() },
@@ -131,7 +129,7 @@ export const credentialTools = Object.freeze([
     defineTool({
         name: "n8n_credentials_get",
         title: "Get credential",
-        description: "Get public metadata for one stored credential by stable ID. Use it for a known target; use n8n_credentials_list for discovery and n8n_credentials_schema for type fields. credentialId identifies stored metadata only: the endpoint and output contract do not retrieve credential values or test the external service. Requires credential-read permission; returns validated identity, type, flags, and timestamps.",
+        description: "Get public metadata for one stored credential. credentialId is the stable ID from n8n_credentials_list or create, not its name, type, or secret data. Use n8n_credentials_schema for type fields. The endpoint does not retrieve credential values or test the external service. Requires credential-read permission; returns validated identity, type, flags, and timestamps.",
         operation: "read-only",
         outputDataDescription: "One validated credential metadata record with id, name, type, optional timestamps, managed/global flags, and resolvability; no stored credential values.",
         input: { credentialId: identifier("Stable ID of the credential metadata to retrieve.") },
@@ -140,7 +138,7 @@ export const credentialTools = Object.freeze([
     defineTool({
         name: "n8n_credentials_update",
         title: "Update credential",
-        description: "Update selected metadata or values on one stored credential, potentially breaking dependent workflows. Use n8n_credentials_schema for data fields and n8n_credentials_create for a new credential. Supply at least one field; changing type also requires data. isPartialData=false treats data as replacement, while true requests a partial merge. Requires write/unsafe mode plus update permission; returns metadata without secret values.",
+        description: "Update one stored credential, potentially breaking dependent workflows. credentialId selects the record; omit fields to keep them and supply at least one change. If type changes, data is also required and must match n8n_credentials_schema. With data, isPartialData=false replaces the saved field set, while true requests a partial merge. Use create for a new credential. Requires write/unsafe mode plus update permission; returns metadata without secret values.",
         operation: "write",
         outputDataDescription: "Updated credential metadata with id, name, type, optional timestamps, managed/global flags, and resolvability. Supplied credential values are never echoed.",
         destructive: true,
@@ -157,8 +155,7 @@ export const credentialTools = Object.freeze([
                 .regex(/^[A-Za-z0-9_.-]{1,128}$/)
                 .optional()
                 .describe("Replacement public credential type; requires replacement data when supplied."),
-            data: z
-                .record(safeJsonValue)
+            data: preservingRecord(safeJsonValue)
                 .optional()
                 .describe("Replacement or partial credential field values; never returned."),
             isGlobal: z.boolean().optional().describe("Optional replacement for the n8n global flag."),
@@ -201,7 +198,7 @@ export const credentialTools = Object.freeze([
     defineTool({
         name: "n8n_credentials_test",
         title: "Test credential",
-        description: "Test one stored credential by allowing n8n to contact its external service, which receives and may log the attempt. Use n8n_credentials_get for metadata-only inspection and do not call this when network contact is unwanted. Requires unsafe mode plus test permission; returns only the target-bound OK/Error outcome and withholds the upstream diagnostic message because it may contain secrets.",
+        description: "Test one already stored credential by allowing n8n to contact its external service, which receives and may log the attempt. credentialId is the stable ID from n8n_credentials_list or get; inline credential data, names, and types are not accepted. Use get for metadata-only inspection and skip this tool when network contact is unwanted. Requires unsafe mode plus test permission; returns only the target-bound OK/Error outcome and withholds the upstream diagnostic message.",
         operation: "unsafe",
         outputDataDescription: "Object with credentialId, status OK or Error, and a server-authored message that discloses only whether the test succeeded. The untrusted upstream diagnostic message is never returned.",
         openWorld: true,
@@ -221,7 +218,7 @@ export const credentialTools = Object.freeze([
     defineTool({
         name: "n8n_credentials_usage",
         title: "Find credential usage",
-        description: "Scan one bounded workflow page for exact references to a credential ID. Use it before n8n_credentials_update or deletion; use n8n_credentials_get for metadata only. active filters upstream, cursor resumes the scan, and unresolved legacy references are counted but never matched; coverage is complete only when nextCursor is null. Requires workflow-list permission; returns bounded workflow/node matches and omission counts.",
+        description: "Scan one workflow page for exact references to a credential. credentialId is the stable ID from n8n_credentials_list or get. Omit cursor for page one; keep credentialId, active, and limit unchanged when passing nextCursor. Unresolved legacy references are counted but never matched, and coverage is complete only when nextCursor is null. Use this before update/delete. Requires workflow-list permission; returns bounded workflow/node matches and omission counts.",
         operation: "read-only",
         outputDataDescription: "Object with credentialId, workflowsExamined, matchingWorkflowCount, workflows with at most 200 total node details and 20 per workflow, nextCursor, scanComplete, truncation counts, referencesScanned, and referencesUnresolved.",
         input: {

package/dist/tools/definition.js

@@ -6,12 +6,15 @@ import { authorizeOperation } from "../security/operation-policy.js";
 import { boundedJson, OutputLimitError, sanitizeForOutput, sanitizeForOutputDetailed, } from "../security/redaction.js";
 import { TOOL_ENDPOINT_CONTRACTS } from "./endpoint-contracts.js";
 import { genericToolOutputContract, MUTATION_IDENTITY_KEYS } from "./output-contracts.js";
+const MAX_SERIALIZED_TOOL_RESULT_BYTES = 256 * 1024;
+const DEFAULT_READ_ONLY_OUTPUT_LIMIT_MESSAGE = "The sanitized result exceeded safe output limits. Use narrower inputs when available; otherwise inspect the full object in n8n.";
 function annotationsFor(spec) {
+    const readOnly = spec.readOnly ?? spec.operation === "read-only";
     return {
         title: spec.title,
-        readOnlyHint: spec.operation === "read-only",
+        readOnlyHint: readOnly,
         destructiveHint: spec.destructive ?? spec.operation !== "read-only",
-        idempotentHint: spec.idempotent ?? spec.operation === "read-only",
+        idempotentHint: spec.idempotent ?? readOnly,
         openWorldHint: spec.openWorld ?? true,
     };
 }
@@ -40,8 +43,8 @@ function errorResult(error, correlationId, toolName) {
 }
 class ToolOutputError extends Error {
     code = "invalid_output";
-    constructor() {
-        super("The tool produced a result that did not match its published output contract.");
+    constructor(message = "The tool produced a result that did not match its published output contract.") {
+        super(message);
         this.name = "ToolOutputError";
     }
 }
@@ -52,13 +55,21 @@ function validatedOutput(value, outputSchema) {
     return parsed.data;
 }
 function resultFromValidatedOutput(safe) {
-    return {
+    const result = {
         content: [{ type: "text", text: boundedJson(safe) }],
         structuredContent: { ...safe },
     };
+    // The MCP result carries both the compatibility text and structured content. Bound their
+    // combined serialized form so consumers never receive a nominally successful result above
+    // the documented 256 KiB envelope.
+    if (Buffer.byteLength(JSON.stringify(result)) > MAX_SERIALIZED_TOOL_RESULT_BYTES) {
+        throw new OutputLimitError();
+    }
+    return result;
 }
 function fallbackResult(value, outputSchema) {
-    return resultFromValidatedOutput(validatedOutput(sanitizeForOutput(value), outputSchema));
+    const sanitized = sanitizeForOutput(value);
+    return resultFromValidatedOutput(validatedOutput({ ...sanitized, redacted: true }, outputSchema));
 }
 // When a mutation's full result exceeds the output cap, the write already landed upstream, so
 // summarize it to a bounded, stable shape (truncated + the scalar identity fields) instead of
@@ -84,11 +95,17 @@ function truncatedMutationResult(value) {
         identity,
     };
 }
-function buildSuccessResult(value, operation, primaryDataSchema, outputSchema, preserveValidatedRootRecordValues = false) {
+function buildSuccessResult(value, readOnly, primaryDataSchema, outputSchema, preserveValidatedRootRecordValues = false, sanitizationOptions = {}, failOnSanitizerLimit = false, readOnlyOutputLimitMessage) {
     // A handler may return only its official primary shape. The public mutation fallback is a
     // server-generated recovery form and can never be supplied directly by an upstream handler.
     validatedOutput(value, primaryDataSchema);
-    const sanitized = sanitizeForOutputDetailed(value, { preserveValidatedRootRecordValues });
+    const sanitized = sanitizeForOutputDetailed(value, {
+        ...sanitizationOptions,
+        preserveValidatedRootRecordValues,
+    });
+    if (failOnSanitizerLimit && sanitized.sizeReduced) {
+        throw new ToolOutputError(readOnlyOutputLimitMessage ?? DEFAULT_READ_ONLY_OUTPUT_LIMIT_MESSAGE);
+    }
     let safe;
     try {
         safe = validatedOutput(sanitized.output, outputSchema);
@@ -96,9 +113,7 @@ function buildSuccessResult(value, operation, primaryDataSchema, outputSchema, p
     catch (error) {
         // A completed mutation falls back only when the sanitizer explicitly reduced structure
         // because of its depth/node/breadth bounds. Ordinary post-sanitization schema drift must fail.
-        if (operation === "read-only" ||
-            !(error instanceof ToolOutputError) ||
-            !sanitized.structurallyReduced) {
+        if (readOnly || !(error instanceof ToolOutputError) || !sanitized.structurallyReduced) {
             throw error;
         }
         return fallbackResult(truncatedMutationResult(value), outputSchema);
@@ -107,7 +122,10 @@ function buildSuccessResult(value, operation, primaryDataSchema, outputSchema, p
         return resultFromValidatedOutput(safe);
     }
     catch (error) {
-        if (operation === "read-only" || !(error instanceof OutputLimitError))
+        if (readOnly && error instanceof OutputLimitError) {
+            throw new ToolOutputError(readOnlyOutputLimitMessage ?? DEFAULT_READ_ONLY_OUTPUT_LIMIT_MESSAGE);
+        }
+        if (readOnly || !(error instanceof OutputLimitError))
             throw error;
         // A mutating tool has already applied its write, so an over-cap result is a
         // truthful, bounded success summary rather than a misleading failure.
@@ -124,6 +142,12 @@ export function createToolContext(startup) {
 }
 export function defineTool(spec) {
     const annotations = annotationsFor(spec);
+    if (annotations.readOnlyHint === true && annotations.destructiveHint === true) {
+        throw new Error(`Tool ${spec.name} cannot be both read-only and destructive.`);
+    }
+    if (spec.failOnSanitizerLimit === true && annotations.readOnlyHint !== true) {
+        throw new Error(`Tool ${spec.name} can fail on sanitizer limits only when it is read-only.`);
+    }
     const endpointContract = TOOL_ENDPOINT_CONTRACTS[spec.name];
     if (endpointContract === undefined) {
         throw new Error(`Tool ${spec.name} is missing its endpoint documentation contract.`);
@@ -131,7 +155,7 @@ export function defineTool(spec) {
     const inputShape = { ...spec.input };
     const inputSchema = z.object(inputShape).strict();
     const genericOutput = spec.outputSchema === undefined
-        ? genericToolOutputContract(spec.name, spec.operation, spec.outputDataDescription)
+        ? genericToolOutputContract(spec.name, annotations.readOnlyHint === true, spec.outputDataDescription)
         : undefined;
     const outputSchema = spec.outputSchema ?? genericOutput?.outputSchema;
     if (outputSchema === undefined) {
@@ -166,7 +190,7 @@ export function defineTool(spec) {
                         if (genericOutput === undefined) {
                             throw new Error(`Tool ${spec.name} is missing its primary output contract.`);
                         }
-                        result = buildSuccessResult(value, spec.operation, genericOutput.primaryDataSchema, outputSchema, spec.preserveValidatedRootRecordValues);
+                        result = buildSuccessResult(value, annotations.readOnlyHint === true, genericOutput.primaryDataSchema, outputSchema, spec.preserveValidatedRootRecordValues, spec.sanitizationOptions, spec.failOnSanitizerLimit, spec.readOnlyOutputLimitMessage);
                     }
                     if (spec.operation !== "read-only") {
                         console.error(JSON.stringify({