docs: reposition README around the production-operations direction (#900)

[czlonkowski]

Context

Discussion #900 announced the project's direction: the official n8n MCP server is becoming the way workflows get written; n8n-mcp focuses on the production side of the lifecycle (validation, testing, deployment, diagnosis, multi-instance, coverage). The July 2026 competitive analysis documents the measurements behind this.

The README and docs still partially tell the old story. They should be brought in line with the announced positioning.

Tasks

• Audit README + docs for stale claims — in particular any remaining "n8n-mcp is N× cheaper per edit" framing, which is retired for current n8n versions (see the July analysis §3.1). Surviving, accurate claims: surgical in-field edits via patchNodeField (measured 5.3× on a ~1 KB Code node, scales with field size), strict validation, community-node coverage.
• Add a "Which MCP server should I use?" section near the top of the README: run both — the official server for drafting workflows on a current instance, n8n-mcp for honest validation, community/custom nodes, execution debugging, version history, and older n8n versions. Link Discussion Where n8n-mcp goes from here — now that n8n ships its own MCP server #900 and the July analysis.
• Reorder the feature presentation to lead with the production-lifecycle tools (validation, versions, executions, autofix, audit) rather than node documentation.
• Add the maintainer consulting link/CTA.
• Pin Discussion Where n8n-mcp goes from here — now that n8n ships its own MCP server #900 so it's the first thing visitors see.

Acceptance

A first-time visitor should understand within one screen: what this project is for today, how it relates to the official MCP server, and where the project is going.

[github-actions]

🎯 Agentic Issue Triage

This is a well-scoped documentation repositioning task, raised by the maintainer, tied directly to Discussion #900. The README and docs still lead with the "node documentation / AI workflow builder" framing rather than the production-operations angle announced as the project's new direction. Five concrete sub-tasks are listed with a clear acceptance criterion.

📋 Issue Summary

Type: Documentation improvement / strategic repositioning
Scope: README + surrounding docs
Trigger: Official n8n MCP server now covers workflow drafting; n8n-mcp's differentiated value is production-lifecycle tooling (validation, execution debugging, community-node coverage, multi-instance, version history).
Acceptance: A first-time visitor understands within one screen what the project does today, how it relates to the official MCP server, and where it is going.

🔍 Current README State

A quick audit of the current README shows:

• The headline still describes n8n-MCP primarily as a "comprehensive access to n8n node documentation" bridge, not a production-operations layer.
• No "Which MCP server should I use?" section exists near the top.
• Feature presentation leads with node counts and documentation coverage statistics; production-lifecycle tools (validation, deployment, execution debugging) appear later.
• No maintainer consulting CTA is present in the visible sections.
• The "n8n-mcp is N× cheaper per edit" framing does not appear verbatim in the current README (a grep found no such phrasing), though the node-doc/AI-bridge framing is still the lead story — consistent with the issue's intent.

✅ Sub-task Checklist

• Audit for stale claims — grep README and docs for any remaining cost-per-edit / token-efficiency multipliers that are no longer accurate for current n8n versions. The July 2026 analysis §3.1 defines which claims survive (patchNodeField 5.3× for large fields; strict validation; community-node coverage).
• Add "Which MCP server should I use?" section near the top of the README — "run both" framing; link Discussion Where n8n-mcp goes from here — now that n8n ships its own MCP server #900 and the July 2026 competitive analysis.
• Reorder feature presentation — lead with production-lifecycle tools (validation, versions, executions, autofix, audit); move node-doc stats to a secondary section.
• Add maintainer consulting link/CTA in an appropriate position (e.g., alongside the sponsor block).
• Pin Discussion Where n8n-mcp goes from here — now that n8n ships its own MCP server #900 via GitHub repository settings so it is the first thing repository visitors see in the Discussions tab.

🛠️ Implementation Notes

• The README is the primary target; secondary files to check: docs/, CHANGELOG.md, and any docs linked from the README intro (e.g., README_ANALYSIS.md, ANALYSIS_QUICK_REFERENCE.md).

• The "Which MCP server should I use?" section works well as a comparison table:

  Use case	Official n8n MCP	n8n-mcp
  Drafting new workflows	✅ Recommended	✓ Works
  Strict pre-deploy validation	✗ valid:true on broken configs	✅ Catches all five probe classes
  Community / custom nodes	✗ Not covered	✅ 1,247 community nodes
  Execution debugging	✗	✅
  Older n8n versions	✗	✅
  Multi-instance	✗	✅

• The patchNodeField 5.3× claim is size-dependent; it should be scoped ("on a ~1 KB Code node; scales with field size") to remain accurate.

• Pinning Discussion Where n8n-mcp goes from here — now that n8n ships its own MCP server #900 is a GitHub UI action (no code change needed).

🔗 Useful References

• Discussion #900 — announced direction
• July 2026 competitive analysis — measurements backing the repositioning
• Issue #904 — companion issue: public validation benchmark (also roadmap)
• GitHub docs on pinning a discussion

Generated by Agentic Triage for issue #902 · ● 234.5K · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/issue-triage.md@13377ddf7e35c2b6e47aa58f45acb228fba902c8