n8n-mcp-community 0.1.0

package/dist/tools/common.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { cursor } 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),
+    nextCursor: cursor.nullable().optional(),
+})
+    .passthrough();
+export function booleanQuery(value) {
+    return value === undefined ? undefined : String(value);
+}
+export function numberQuery(value) {
+    return value === undefined ? undefined : String(value);
+}
+export function requireSafeAscii(value, label, maximumLength = 256) {
+    if (value.length < 1 ||
+        value.length > maximumLength ||
+        !/^[\x20-\x7e]+$/.test(value) ||
+        value !== value.trim()) {
+        throw new Error(`${label} must contain 1-${maximumLength} trimmed printable ASCII characters.`);
+    }
+    return value;
+}
+export function projectMetadata(value) {
+    const source = z.record(z.unknown()).parse(value);
+    const allowed = [
+        "id",
+        "name",
+        "type",
+        "active",
+        "isArchived",
+        "createdAt",
+        "updatedAt",
+        "versionId",
+        "workflowId",
+        "status",
+        "startedAt",
+        "stoppedAt",
+        "mode",
+        "finished",
+        "retryOf",
+        "retrySuccessId",
+        "role",
+        "disabled",
+    ];
+    const output = {};
+    for (const key of allowed) {
+        if (Object.hasOwn(source, key))
+            output[key] = source[key];
+    }
+    return output;
+}

package/dist/tools/credentials.js

@@ -0,0 +1,259 @@
+import { z } from "zod";
+import { defineTool } from "./definition.js";
+import { booleanQuery, numberQuery } from "./common.js";
+import { assertSafeJson, confirmation, cursor, identifier, pageLimit, pathSegment, safeJsonValue, } from "./schemas.js";
+const credentialMetadataSchema = z.object({
+    id: identifier(),
+    name: z.string().min(1).max(256),
+    type: z.string().min(1).max(256),
+    createdAt: z.string().optional(),
+    updatedAt: z.string().optional(),
+    isManaged: z.boolean().optional(),
+    isGlobal: z.boolean().optional(),
+    isResolvable: z.boolean().optional(),
+});
+const credentialListSchema = z.object({
+    data: z.array(credentialMetadataSchema).max(100),
+    nextCursor: cursor.nullable().optional(),
+});
+// n8n's canonical node credential reference is { id: string | null; name: string }, and legacy
+// imports can carry name-only strings or unresolved null ids. Coerce any shape to a bounded
+// { id } so a single unresolved reference can never abort the whole page scan; unresolved
+// references (null/absent/non-scalar id, or a legacy string form) are counted but never matched.
+const workflowCredentialReferenceSchema = z
+    .unknown()
+    .transform((reference) => {
+    if (reference !== null && typeof reference === "object" && !Array.isArray(reference)) {
+        const { id } = reference;
+        if (typeof id === "string" || typeof id === "number")
+            return { id: String(id) };
+    }
+    return { id: null };
+});
+const usageWorkflowSchema = z.object({
+    id: identifier(),
+    name: z.string().min(1).max(256),
+    active: z.boolean(),
+    nodes: z
+        .array(z.object({
+        id: identifier().optional(),
+        name: z.string().min(1).max(256),
+        type: z.string().min(1).max(256),
+        credentials: z.record(workflowCredentialReferenceSchema).optional(),
+    }))
+        .max(1_000),
+});
+const usageListSchema = z.object({
+    data: z.array(usageWorkflowSchema).max(100),
+    nextCursor: cursor.nullable().optional(),
+});
+export const credentialTools = Object.freeze([
+    defineTool({
+        name: "n8n_credentials_create",
+        title: "Create credential",
+        description: "Create a credential while keeping credential values out of output and logs.",
+        operation: "write",
+        input: {
+            name: z.string().min(1).max(128),
+            type: z.string().regex(/^[A-Za-z0-9_.-]{1,128}$/),
+            data: z.record(safeJsonValue),
+            isResolvable: z.boolean().optional(),
+        },
+        handler: async (input, context) => {
+            assertSafeJson(input.data);
+            return credentialMetadataSchema.parse(await context.client().request({ method: "POST", path: "/credentials", body: input }));
+        },
+    }),
+    defineTool({
+        name: "n8n_credentials_delete",
+        title: "Delete credential",
+        description: "Permanently delete one stored credential after exact confirmation.",
+        operation: "unsafe",
+        input: { credentialId: identifier(), confirmation },
+        confirmation: (input) => ({
+            supplied: input.confirmation,
+            expected: `DELETE ${input.credentialId}`,
+        }),
+        handler: async (input, context) => {
+            await context
+                .client()
+                .request({ method: "DELETE", path: `/credentials/${pathSegment(input.credentialId)}` });
+            return { credentialId: input.credentialId, deleted: true };
+        },
+    }),
+    defineTool({
+        name: "n8n_credentials_schema",
+        title: "Get credential schema",
+        description: "Get the supported public schema for one credential type.",
+        operation: "read-only",
+        input: { credentialType: identifier() },
+        handler: async (input, context) => z.record(z.unknown()).parse(await context.client().request({
+            path: `/credentials/schema/${pathSegment(input.credentialType)}`,
+        })),
+    }),
+    defineTool({
+        name: "n8n_credentials_list",
+        title: "List credentials",
+        description: "List credential metadata through the public endpoint verified in n8n Community 2.30.5 and 2.30.7. Credential values are never returned.",
+        operation: "read-only",
+        input: { limit: pageLimit(), cursor: cursor.optional() },
+        handler: async (input, context) => credentialListSchema.parse(await context.client().request({
+            path: "/credentials",
+            query: { limit: numberQuery(input.limit), cursor: input.cursor },
+        })),
+    }),
+    defineTool({
+        name: "n8n_credentials_get",
+        title: "Get credential",
+        description: "Get public metadata for one credential without retrieving secret values.",
+        operation: "read-only",
+        input: { credentialId: identifier() },
+        handler: async (input, context) => credentialMetadataSchema.parse(await context.client().request({ path: `/credentials/${pathSegment(input.credentialId)}` })),
+    }),
+    defineTool({
+        name: "n8n_credentials_update",
+        title: "Update credential",
+        description: "Update credential metadata or values while keeping secret material out of output and logs.",
+        operation: "write",
+        destructive: true,
+        input: {
+            credentialId: identifier(),
+            name: z.string().min(1).max(128).optional(),
+            type: z
+                .string()
+                .regex(/^[A-Za-z0-9_.-]{1,128}$/)
+                .optional(),
+            data: z.record(safeJsonValue).optional(),
+            isGlobal: z.boolean().optional(),
+            isResolvable: z.boolean().optional(),
+            isPartialData: z.boolean().default(false),
+        },
+        handler: async (input, context) => {
+            if (input.name === undefined &&
+                input.type === undefined &&
+                input.data === undefined &&
+                input.isGlobal === undefined &&
+                input.isResolvable === undefined) {
+                throw new Error("Provide at least one credential field to update.");
+            }
+            if (input.type !== undefined && input.data === undefined) {
+                throw new Error("Changing a credential type also requires replacement credential data.");
+            }
+            if (input.data !== undefined)
+                assertSafeJson(input.data);
+            return credentialMetadataSchema.parse(await context.client().request({
+                method: "PATCH",
+                path: `/credentials/${pathSegment(input.credentialId)}`,
+                body: {
+                    ...(input.name === undefined ? {} : { name: input.name }),
+                    ...(input.type === undefined ? {} : { type: input.type }),
+                    ...(input.data === undefined ? {} : { data: input.data }),
+                    ...(input.isGlobal === undefined ? {} : { isGlobal: input.isGlobal }),
+                    ...(input.isResolvable === undefined ? {} : { isResolvable: input.isResolvable }),
+                    isPartialData: input.isPartialData,
+                },
+            }));
+        },
+    }),
+    defineTool({
+        name: "n8n_credentials_test",
+        title: "Test credential",
+        description: "Test one stored credential. This may contact the credential's external service.",
+        operation: "unsafe",
+        openWorld: true,
+        input: { credentialId: identifier(), confirmation },
+        confirmation: (input) => ({
+            supplied: input.confirmation,
+            expected: `TEST ${input.credentialId}`,
+        }),
+        handler: async (input, context) => {
+            // The external test already ran by the time this response arrives, so an over-long
+            // status/message must be truncated rather than rejected: discarding a completed outcome
+            // would report a generic error for a side effect that genuinely happened.
+            const raw = z.object({ status: z.string(), message: z.string().optional() }).parse(await context.client().request({
+                method: "POST",
+                path: `/credentials/${pathSegment(input.credentialId)}/test`,
+            }));
+            const status = raw.status.slice(0, 64);
+            const message = raw.message === undefined ? undefined : raw.message.slice(0, 512);
+            const truncated = status.length < raw.status.length ||
+                (raw.message !== undefined && message !== undefined && message.length < raw.message.length);
+            return {
+                credentialId: input.credentialId,
+                status,
+                ...(message === undefined ? {} : { message }),
+                ...(truncated ? { truncated: true } : {}),
+            };
+        },
+    }),
+    defineTool({
+        name: "n8n_credentials_usage",
+        title: "Find credential usage",
+        description: "Scan one bounded workflow page for exact references to one credential ID.",
+        operation: "read-only",
+        input: {
+            credentialId: identifier(),
+            cursor: cursor.optional(),
+            limit: pageLimit(100, 50),
+            active: z.boolean().optional(),
+        },
+        handler: async (input, context) => {
+            const page = usageListSchema.parse(await context.client().request({
+                path: "/workflows",
+                query: {
+                    cursor: input.cursor,
+                    limit: numberQuery(input.limit),
+                    active: booleanQuery(input.active),
+                    excludePinnedData: "true",
+                },
+            }));
+            const matches = [];
+            let matchingWorkflowCount = 0;
+            let omittedNodeDetails = 0;
+            let retainedNodeDetails = 0;
+            let referencesScanned = 0;
+            let referencesUnresolved = 0;
+            for (const workflow of page.data) {
+                for (const node of workflow.nodes) {
+                    for (const reference of Object.values(node.credentials ?? {})) {
+                        referencesScanned += 1;
+                        if (reference.id === null)
+                            referencesUnresolved += 1;
+                    }
+                }
+                const nodes = workflow.nodes.filter((node) => Object.values(node.credentials ?? {}).some((reference) => reference.id === input.credentialId));
+                if (nodes.length === 0)
+                    continue;
+                matchingWorkflowCount += 1;
+                const available = Math.max(0, 200 - retainedNodeDetails);
+                const details = nodes.slice(0, Math.min(20, available));
+                retainedNodeDetails += details.length;
+                omittedNodeDetails += nodes.length - details.length;
+                matches.push({
+                    workflowId: workflow.id,
+                    workflowName: workflow.name,
+                    active: workflow.active,
+                    matchingNodeCount: nodes.length,
+                    nodes: details.map((node) => ({
+                        nodeId: node.id ?? null,
+                        nodeName: node.name,
+                        nodeType: node.type,
+                    })),
+                    detailsTruncated: details.length < nodes.length,
+                });
+            }
+            return {
+                credentialId: input.credentialId,
+                workflowsExamined: page.data.length,
+                matchingWorkflowCount,
+                workflows: matches,
+                nextCursor: page.nextCursor ?? null,
+                scanComplete: page.nextCursor === undefined || page.nextCursor === null,
+                truncated: omittedNodeDetails > 0,
+                omittedNodeDetails,
+                referencesScanned,
+                referencesUnresolved,
+            };
+        },
+    }),
+]);

package/dist/tools/definition.js

@@ -0,0 +1,169 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { readN8nConnection } from "../config.js";
+import { N8nClient } from "../n8n/client.js";
+import { authorizeOperation } from "../security/operation-policy.js";
+import { boundedJson, sanitizeForOutput } from "../security/redaction.js";
+import { TOOL_ENDPOINT_CONTRACTS } from "./endpoint-contracts.js";
+import { confirmation as confirmationField } from "./schemas.js";
+function annotationsFor(spec) {
+    return {
+        title: spec.title,
+        readOnlyHint: spec.operation === "read-only",
+        destructiveHint: spec.destructive ?? spec.operation !== "read-only",
+        idempotentHint: spec.idempotent ?? spec.operation === "read-only",
+        openWorldHint: spec.openWorld ?? true,
+    };
+}
+function errorResult(error, correlationId, toolName) {
+    // A Zod failure reaching here is a RESPONSE-schema failure (older/newer n8n shape drift): the
+    // per-tool inputs are validated by the SDK before the handler runs, and local invariants —
+    // including the introspect input and output contracts — are thrown as plain coded Errors, not
+    // raw ZodErrors. Map it to a stable, distinct code with a bounded message that names only the
+    // tool, so the raw ZodError issue dump (paths/expectations) can never surface.
+    if (error instanceof z.ZodError) {
+        const safe = sanitizeForOutput({
+            error: {
+                code: "upstream_shape_mismatch",
+                message: `The ${toolName} response did not match the supported n8n API schema.`,
+                correlationId,
+            },
+        });
+        return { isError: true, content: [{ type: "text", text: boundedJson(safe) }] };
+    }
+    const candidate = error && typeof error === "object" && "code" in error && typeof error.code === "string"
+        ? error.code
+        : "tool_error";
+    const message = error instanceof Error ? error.message : "The tool could not complete safely.";
+    const safe = sanitizeForOutput({ error: { code: candidate, message, correlationId } });
+    return { isError: true, content: [{ type: "text", text: boundedJson(safe) }] };
+}
+function successResult(value) {
+    const safe = sanitizeForOutput(value);
+    return {
+        content: [{ type: "text", text: boundedJson(safe) }],
+        structuredContent: { ...safe },
+    };
+}
+// 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
+// reporting an error that would induce a retry of an applied mutation.
+function truncatedMutationResult(value) {
+    const identity = {};
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        let retained = 0;
+        for (const [key, entry] of Object.entries(value)) {
+            if (retained >= 32)
+                break;
+            if (entry === null ||
+                typeof entry === "boolean" ||
+                typeof entry === "number" ||
+                (typeof entry === "string" && entry.length <= 512)) {
+                identity[key] = entry;
+                retained += 1;
+            }
+        }
+    }
+    return {
+        truncated: true,
+        outcome: "success",
+        detail: "The mutation completed upstream, but its full result exceeded the output size limit and was summarized to the identity fields below.",
+        identity,
+    };
+}
+function buildSuccessResult(value, operation) {
+    try {
+        return successResult(value);
+    }
+    catch (error) {
+        // boundedJson's output-size cap is the only throw here. Read-only tools keep the existing
+        // cap 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.
+        if (operation === "read-only")
+            throw error;
+        return successResult(truncatedMutationResult(value));
+    }
+}
+export function createToolContext(startup) {
+    const connection = () => readN8nConnection(startup);
+    return {
+        startup,
+        connection,
+        client: () => new N8nClient(connection()),
+    };
+}
+export function defineTool(spec) {
+    const annotations = annotationsFor(spec);
+    const endpointContract = TOOL_ENDPOINT_CONTRACTS[spec.name];
+    if (endpointContract === undefined) {
+        throw new Error(`Tool ${spec.name} is missing its endpoint documentation contract.`);
+    }
+    // Make the required confirmation phrase discoverable in the tool schema by deriving it from the
+    // tool's own confirmation function (single source of truth, so the documented phrase can never
+    // drift from the enforced one). A placeholder proxy turns `DELETE ${input.workflowId}` into the
+    // template `DELETE <workflowId>`. The phrase is documented on the field but is deliberately never
+    // echoed back on a mismatch, so the guard still demands a deliberate, constructed confirmation.
+    const inputShape = { ...spec.input };
+    let confirmationPhrase;
+    if (spec.confirmation && "confirmation" in inputShape) {
+        const placeholder = new Proxy({}, { get: (_target, property) => (typeof property === "string" ? `<${property}>` : undefined) });
+        confirmationPhrase = spec.confirmation(placeholder).expected;
+        const substitution = confirmationPhrase.includes("<") ? " — substitute the real value(s)" : "";
+        inputShape.confirmation = confirmationField.describe(`Deliberate-action guard. Must equal exactly: ${confirmationPhrase}${substitution}. A mismatch is rejected without echoing the expected phrase.`);
+    }
+    const inputSchema = z.object(inputShape).strict();
+    return Object.freeze({
+        name: spec.name,
+        title: spec.title,
+        description: spec.description,
+        operation: spec.operation,
+        annotations,
+        endpointContract: Object.freeze([...endpointContract]),
+        ...(confirmationPhrase === undefined ? {} : { confirmationPhrase }),
+        validateInput: (input) => inputSchema.parse(input),
+        register(server, context) {
+            server.registerTool(spec.name, {
+                title: spec.title,
+                description: spec.description,
+                inputSchema,
+                outputSchema: spec.outputSchema ??
+                    z.object({
+                        data: z.unknown(),
+                        redacted: z.boolean(),
+                        untrusted: z.literal(true),
+                    }),
+                annotations,
+            }, async (input) => {
+                const correlationId = randomUUID();
+                try {
+                    authorizeOperation(context.startup.mode, spec.operation, spec.confirmation?.(input));
+                    const value = await spec.handler(input, context);
+                    if (spec.operation !== "read-only") {
+                        console.error(JSON.stringify({
+                            timestamp: new Date().toISOString(),
+                            event: "security_operation",
+                            tool: spec.name,
+                            outcome: "success",
+                            correlationId,
+                        }));
+                    }
+                    if (spec.formatResult)
+                        return spec.formatResult(value);
+                    return buildSuccessResult(value, spec.operation);
+                }
+                catch (error) {
+                    if (spec.operation !== "read-only") {
+                        console.error(JSON.stringify({
+                            timestamp: new Date().toISOString(),
+                            event: "security_operation",
+                            tool: spec.name,
+                            outcome: "failure",
+                            correlationId,
+                        }));
+                    }
+                    return errorResult(error, correlationId, spec.name);
+                }
+            });
+        },
+    });
+}

package/dist/tools/endpoint-contracts.js

@@ -0,0 +1,53 @@
+export const TOOL_ENDPOINT_CONTRACTS = Object.freeze({
+    n8n_workflows_list: ["GET /workflows"],
+    n8n_workflows_get: ["GET /workflows/{workflowId}"],
+    n8n_workflows_create: ["POST /workflows"],
+    n8n_workflows_update: ["GET /workflows/{workflowId}", "PUT /workflows/{workflowId}"],
+    n8n_update_node: ["GET /workflows/{workflowId}", "PUT /workflows/{workflowId}"],
+    n8n_workflows_delete: ["DELETE /workflows/{workflowId}"],
+    n8n_workflows_activate: ["POST /workflows/{workflowId}/activate"],
+    n8n_workflows_deactivate: ["POST /workflows/{workflowId}/deactivate"],
+    n8n_workflows_get_version: ["GET /workflows/{workflowId}/{versionId}"],
+    n8n_workflows_get_tags: ["GET /workflows/{workflowId}/tags"],
+    n8n_workflows_update_tags: ["PUT /workflows/{workflowId}/tags"],
+    n8n_workflows_archive: ["POST /workflows/{workflowId}/archive"],
+    n8n_workflows_unarchive: ["POST /workflows/{workflowId}/unarchive"],
+    n8n_workflows_diff: [
+        "GET /workflows/{workflowId}/{versionId}",
+        "GET /workflows/{workflowId}?excludePinnedData=true",
+    ],
+    n8n_executions_list: ["GET /executions"],
+    n8n_executions_get: ["GET /executions/{executionId}"],
+    n8n_executions_delete: ["DELETE /executions/{executionId}"],
+    n8n_executions_retry: ["POST /executions/{executionId}/retry"],
+    n8n_executions_stop: ["POST /executions/{executionId}/stop"],
+    n8n_credentials_create: ["POST /credentials"],
+    n8n_credentials_delete: ["DELETE /credentials/{credentialId}"],
+    n8n_credentials_schema: ["GET /credentials/schema/{credentialType}"],
+    n8n_credentials_list: ["GET /credentials"],
+    n8n_credentials_get: ["GET /credentials/{credentialId}"],
+    n8n_credentials_update: ["PATCH /credentials/{credentialId}"],
+    n8n_credentials_test: ["POST /credentials/{credentialId}/test"],
+    n8n_credentials_usage: ["GET /workflows?excludePinnedData=true"],
+    n8n_tags_list: ["GET /tags"],
+    n8n_tags_get: ["GET /tags/{tagId}"],
+    n8n_tags_create: ["POST /tags"],
+    n8n_tags_update: ["PUT /tags/{tagId}"],
+    n8n_tags_delete: ["DELETE /tags/{tagId}"],
+    n8n_users_list: ["GET /users"],
+    n8n_users_get: ["GET /users/{id-or-email}"],
+    n8n_users_create: ["POST /users"],
+    n8n_users_delete: ["DELETE /users/{userId}"],
+    n8n_health: ["GET /healthz"],
+    n8n_insights_summary: ["GET /insights/summary"],
+    n8n_audit_generate: ["POST /audit"],
+    n8n_search_workflows: ["GET /workflows?excludePinnedData=true"],
+    n8n_get_node_docs: [],
+    n8n_list_node_types: ["GET /workflows?excludePinnedData=true"],
+    n8n_introspect: [
+        "GET /workflows/{workflowId}?excludePinnedData=true",
+        "GET /executions",
+        "GET /executions/{executionId}?redactExecutionData=true",
+    ],
+    n8n_community_packages_list: ["GET /community-packages"],
+});