# n8n-flow-auditor

> Deterministic validator for n8n workflows. Ports `@n8n/workflow-sdk` to plain JavaScript and runs on Cloudflare Workers. Exposed as a remote MCP server (Model Context Protocol) so any LLM agent (Claude Desktop, Cursor, GPT, etc.) can use it as ground truth when reading or generating n8n workflows. Zero LLM tokens consumed — same input always produces the same output.

Service URL: https://n8n-auditor.automators.work

Key facts:
- 21 deterministic validators
- 66 node types covering 245 versions in the embedded catalog
- 5 MCP tools exposed at `/mcp`
- 35/36 exact match against the official `@n8n/workflow-sdk` on a 36-workflow real-world regression suite
- Pure JavaScript, runs on Cloudflare Workers (no `isolated-vm` native build required)
- Authentication: OAuth 2.1 self-hosted with GitHub as upstream IdP
- Public REST endpoint (`/validate`) is rate-limited at the edge by Cloudflare WAF
- Free to use, no signup for one-off validation

## API reference

- [Swagger UI](https://n8n-auditor.automators.work/docs): interactive API explorer
- [OpenAPI 3.1 spec](https://n8n-auditor.automators.work/openapi.yaml): machine-readable spec
- [Health](https://n8n-auditor.automators.work/health): worker status, version, counters

## MCP tools

- `validate_workflow`: full validation pass over a workflow JSON; returns errors + warnings with codes, severities, exact parameter paths
- `validate_workflow_by_id`: fetch a workflow from a user-supplied n8n instance and validate it; per-call credentials, never stored
- `list_known_node_types`: returns the 66 node types in the catalog with their available versions
- `get_node_schema`: canonical shape (inputs, outputs, properties with required/displayOptions/defaults) for a type+version
- `analyze_sticky_notes`: heuristic prompt-injection detection in sticky notes; 12 regex patterns; returns flags + suspicionScore + recommendation

## REST endpoints

- `POST /validate`: validate a workflow inline (public, WAF rate-limited)
- `POST /validate/by-id`: fetch + validate by ID (auth required)
- `GET /n8n/workflows`: list workflows from the configured n8n (auth required)
- `GET /health`: worker status, version, counters
- `GET /openapi.yaml`: OpenAPI 3.1 spec
- `GET /docs`: Swagger UI
- `POST /mcp`: MCP server (Streamable HTTP, JSON-RPC 2.0, protocol `2025-06-18`)

## OAuth 2.1 endpoints

- `GET /.well-known/oauth-authorization-server`: RFC 8414 Authorization Server metadata
- `GET /.well-known/oauth-protected-resource`: MCP-spec protected-resource metadata
- `POST /oauth/register`: Dynamic Client Registration (RFC 7591)
- `GET /oauth/authorize`: starts OAuth flow
- `GET /oauth/callback`: GitHub redirect URI
- `POST /oauth/token`: exchanges authorization code for access token (PKCE-verified)

## Connect from Claude Desktop / Cursor

Add to `~/.claude/claude_desktop_config.json` (or the equivalent for your client):

```json
{
  "mcpServers": {
    "n8n-flow-auditor": {
      "url": "https://n8n-auditor.automators.work/mcp"
    }
  }
}
```

The first call opens GitHub OAuth in a browser. Authorize once; the 30-day token is cached after that.

## Validator codes

Errors and warnings emitted by `validate_workflow`:

NO_NODES, MISSING_TRIGGER, DISCONNECTED_NODE, INVALID_CONNECTION, MERGE_SINGLE_INPUT, SUBNODE_NOT_CONNECTED, SET_CREDENTIAL_FIELD, FILTER_MISSING_OPTIONS, FILTER_MISSING_CONDITIONS, FILTER_MISSING_COMBINATOR, SWITCH_WRONG_RULES_KEY, HARDCODED_CREDENTIALS, AGENT_STATIC_PROMPT, AGENT_NO_SYSTEM_MESSAGE, INVALID_DATE_METHOD, MISSING_EXPRESSION_PREFIX, INVALID_EXPRESSION_PATH, PARTIAL_EXPRESSION_PATH, FROM_AI_IN_NON_TOOL, TOOL_NO_PARAMETERS, INVALID_INPUT_INDEX, MISSING_REQUIRED_INPUT, UNSUPPORTED_SUBNODE_INPUT, MISSING_PARAMETER, INVALID_PARAMETER, MAX_NODES_EXCEEDED.

## Limits

- Workflow size: max 50 nodes per request (HTTP 413 beyond)
- Body size: max 1 MB (HTTP 413)
- n8n REST timeout: 10 seconds for `/validate/by-id` (HTTP 504 if the user's n8n is slower)
- Rate limit: 10 requests per 10-second window per IP on the public endpoints (Cloudflare WAF, free-tier limit). MCP authenticated calls have a per-user 60 req/min budget.

## See also

- [Full reference (llms-full.txt)](https://n8n-auditor.automators.work/llms-full.txt): expanded version of this document including request/response schemas
- [@n8n/workflow-sdk](https://www.npmjs.com/package/@n8n/workflow-sdk): the official SDK we port from
- [Model Context Protocol spec](https://modelcontextprotocol.io/specification/2025-06-18): the MCP standard