feat(workflow): add mode="filtered" to n8n_get_workflow for single-node reads by czlonkowski · Pull Request #848 · czlonkowski/n8n-mcp

czlonkowski · 2026-06-18T07:54:05Z

Summary

Adds a mode="filtered" to n8n_get_workflow that returns the full config of only the node(s) named in a new nodeNames parameter, instead of the entire workflow.

Closes #101.

Addresses the request in this comment from @MiRaIOMeZaSu: on large workflows with long Code-node source, mode="full"/mode="active" can return a payload big enough to be truncated client-side, leaving jsCode/pythonCode unreadable. There was previously no way to fetch a single node's full config — structure gives names cheaply but strips parameters, while full/active are exactly the payloads that get truncated. The original issue (hitting max conversation length while iterating on large workflows) has the same root cause: no way to pull just the node you need.

What it does

New mode="filtered" on n8n_get_workflow, requiring a nodeNames: string[] (min 1).
nodeNames entries match against node name OR node ID.
Returns only the matched nodes (full config) plus light metadata: id, name, active, isArchived, nodes[], nodeCount (total in workflow), returnedCount, and notFound (lookup keys that matched nothing — partial requests stay transparent).
Omits connections and the rest of the graph by design, so the response stays small even on large workflows.

Recommended flow: mode="structure" to discover node names → mode="filtered" to pull the specific heavy node.

// Discover node names cheaply
n8n_get_workflow({ id: "abc123", mode: "structure" })
// Read one heavy Code node without the whole workflow
n8n_get_workflow({ id: "abc123", mode: "filtered", nodeNames: ["Process Data"] })

Design notes

Mirrors the existing n8n_executions mode="filtered" + nodeNames precedent for consistency.
nodeNames is validated by the handler's Zod schema (.min(1)), which returns a graceful { success: false, error: "Invalid input" } — same pattern as every other mode. The dispatch layer only requires id. The JSON schema also encodes minItems: 1 so JSON-schema clients validate the same constraint.
Name and ID share one match namespace, so returnedCount can exceed nodeNames.length on an id/name collision or a workflow with duplicate node names — documented as a tool pitfall; callers disambiguate by the id on each returned node.

Changes

src/mcp/tools-n8n-manager.ts — add filtered to the mode enum, add nodeNames param (minItems: 1), update description.
src/mcp/handlers-n8n-manager.ts — new handleGetWorkflowFiltered.
src/mcp/server.ts — dispatch mode="filtered".
src/mcp/tool-docs/workflow_management/n8n-get-workflow.ts — document the new mode, param, returns shape, and pitfalls.
Version bumped 2.58.0 → 2.59.0 (package.json + package.runtime.json); CHANGELOG updated.

Testing

npm run build + npm run typecheck clean.
Unit tests for handleGetWorkflowFiltered (match by name, by ID, mixed name+id in one call, duplicate names, multi-node + notFound, all-unmatched, empty/missing nodeNames, API-error path) and mode-dispatch routing; schema test pins the enum and minItems. Full unit suite green (the only failure is the pre-existing flaky auth-timing-safe wall-clock variance test, unrelated — passes in isolation).
Live-verified against a real n8n instance (MCP tester): match-by-name, match-by-id, multi-node + notFound, all-unmatched, and missing/empty nodeNames (graceful "Invalid input") all pass, with full jsCode returned and no regression to structure/full.

Review

code-simplifier: collapsed the notFound computation to a single matchedKeys set.
code-reviewer: no Critical/High; applied the doc note on the name/id namespace and added the mixed-key and duplicate-name tests.
Copilot: added minItems: 1 to the JSON schema. (Its other suggestion — stripping activeVersion for memory — is a no-op here: the API client has already parsed the full payload before the handler runs, and the filtered response builds a fresh object that never includes activeVersion.)

Requested by @MiRaIOMeZaSu (#101).

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

🤖 Generated with Claude Code

@MiRaIOMeZaSu

…de reads Large workflows with long Code-node source can produce a get_workflow response big enough to be truncated client-side, leaving jsCode/pythonCode unreadable (issue #101). The new mode="filtered" takes a nodeNames array (matched against node names or node IDs) and returns only those nodes with their full config, plus light metadata (nodeCount, returnedCount, and a notFound list for unmatched keys). Recommended flow: mode="structure" to discover node names, then mode="filtered" to pull the specific heavy node. Requested by @MiRaIOMeZaSu (#101). Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Adds a new mode="filtered" option to the n8n_get_workflow MCP tool to return the full config of only selected node(s) (matched by node name or node ID) via a new nodeNames: string[] parameter. This targets large-workflow scenarios where fetching the entire workflow can exceed client response limits and truncate heavy Code node source.

Changes:

Added mode="filtered" + nodeNames parameter to the n8n_get_workflow tool schema and documentation.
Implemented handleGetWorkflowFiltered and routed mode="filtered" through the MCP server dispatcher.
Added unit tests for filtered-node selection behavior and for server mode dispatch; bumped version and updated changelog.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/unit/mcp/handlers-n8n-manager.test.ts	Adds unit tests covering filtered node matching, `notFound`, and validation/error paths.
tests/unit/mcp/get-workflow-tool.test.ts	Verifies tool schema exposes `filtered` mode and a `nodeNames` parameter.
tests/unit/mcp/get-workflow-mode-dispatch.test.ts	Ensures server routes `mode="filtered"` to the correct handler.
src/mcp/tools-n8n-manager.ts	Extends tool definition with `filtered` mode and `nodeNames` input.
src/mcp/tool-docs/workflow_management/n8n-get-workflow.ts	Documents the new mode, parameters, return shape, and recommended usage flow.
src/mcp/server.ts	Adds dispatch case for `mode="filtered"`.
src/mcp/handlers-n8n-manager.ts	Implements `handleGetWorkflowFiltered` to return matched nodes + light metadata.
package.runtime.json	Bumps runtime package version to 2.59.0.
package.json	Bumps package version to 2.59.0.
CHANGELOG.md	Adds 2.59.0 entry describing the new filtered workflow read capability.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+      nodeNames: z.array(z.string()).min(1)
+    }).parse(args);
+
+    const workflow = await client.getWorkflow(id);


+        nodeNames: {
+          type: 'array',
+          items: { type: 'string' },
+          description: "For mode='filtered': node names or node IDs to return with full config. Returns only matching nodes (avoids client-side truncation on large workflows with long Code-node source). Discover names with mode='structure' first."
        }


github-actions · 2026-06-18T08:02:17Z

Test Results Summary

📊 Artifacts

Generated at Thu, 18 Jun 2026 09:11:53 GMT
Commit: d67c399
Run: #1150

- Simplify notFound computation to a single matchedKeys set (code-simplifier). - Document the name/id single-namespace match: returnedCount can exceed nodeNames.length on id collisions or duplicate node names; disambiguate by the id on each returned node. - Add tests for a mixed name+id lookup in one call and for duplicate node names; rename an awkwardly worded test. Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

codecov · 2026-06-18T08:13:30Z

Codecov Report

❌ Patch coverage is 94.02985% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/mcp/handlers-n8n-manager.ts	91.66%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

Add `minItems: 1` to the n8n_get_workflow `nodeNames` JSON schema so JSON-schema clients validate the same non-empty constraint the handler's Zod `.min(1)` already enforces (Copilot review). Pinned by a schema test. Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

Copilot AI review requested due to automatic review settings June 18, 2026 07:54

Copilot started reviewing on behalf of czlonkowski June 18, 2026 07:54 View session

Copilot AI reviewed Jun 18, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings June 18, 2026 09:03

Copilot started reviewing on behalf of czlonkowski June 18, 2026 09:03 View session

Copilot AI reviewed Jun 18, 2026

View reviewed changes

czlonkowski merged commit c8ff28a into main Jun 18, 2026
15 checks passed

czlonkowski deleted the feat/get-workflow-filtered-mode branch June 18, 2026 09:16

czlonkowski mentioned this pull request Jun 19, 2026

chore: stop tracking build output (untrack dist/) #851

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(workflow): add mode="filtered" to n8n_get_workflow for single-node reads#848

feat(workflow): add mode="filtered" to n8n_get_workflow for single-node reads#848
czlonkowski merged 3 commits into
mainfrom
feat/get-workflow-filtered-mode

czlonkowski commented Jun 18, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions Bot commented Jun 18, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Jun 18, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

czlonkowski commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What it does

Design notes

Changes

Testing

Review

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

github-actions Bot commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results Summary

📊 Artifacts

Uh oh!

codecov Bot commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

czlonkowski commented Jun 18, 2026 •

edited

Loading

github-actions Bot commented Jun 18, 2026 •

edited

Loading

codecov Bot commented Jun 18, 2026 •

edited

Loading