@pagelines/n8n-mcp 0.3.1 → 0.3.2

package/plans/ai-guidelines.md

@@ -1,233 +0,0 @@
-# AI Guidelines for @pagelines/n8n-mcp
-
-Entry point for AI assistants working on this codebase.
-
-## Quick Start
-
-```bash
-npm run dev      # Watch mode
-npm run test     # Run tests
-npm run build    # Compile TypeScript
-```
-
-## Codebase Map
-
-| File | Purpose | When to modify |
-|------|---------|----------------|
-| `src/index.ts` | MCP server, tool dispatch | Adding new tools |
-| `src/types.ts` | Type definitions | New data structures |
-| `src/tools.ts` | Tool JSON schemas | New tool definitions |
-| `src/n8n-client.ts` | n8n REST API calls | New API operations |
-| `src/validators.ts` | Validation rules | New lint rules |
-| `src/expressions.ts` | Expression parsing | Expression handling |
-| `src/autofix.ts` | Auto-fix transforms | New auto-fixes |
-| `src/versions.ts` | Version control | Version features |
-
-## Coding Standards
-
-### Do
-- Write pure functions that return values
-- Use async/await, never callbacks
-- Add types for all parameters and returns
-- Keep functions under 50 lines
-- Name variables descriptively
-- Write tests for new validators
-
-### Don't
-- Use `any` type
-- Mutate input parameters
-- Add external dependencies without strong justification
-- Create abstraction before duplication (rule of 3)
-- Add features not explicitly requested
-
-## Adding a New Tool
-
-1. **Define type** in `types.ts` (if needed)
-2. **Add schema** in `tools.ts`:
-```typescript
-{
-  name: 'my_tool',
-  description: 'What it does',
-  inputSchema: {
-    type: 'object',
-    properties: { /* ... */ },
-    required: ['param1']
-  }
-}
-```
-3. **Add handler** in `index.ts`:
-```typescript
-case 'my_tool':
-  return await handleMyTool(args);
-```
-4. **Implement logic** in appropriate module
-5. **Add test** in `*.test.ts`
-
-## Adding a Validation Rule
-
-1. **Add rule function** in `validators.ts`:
-```typescript
-function checkMyRule(workflow: N8nWorkflow): ValidationWarning[] {
-  const warnings: ValidationWarning[] = [];
-  // validation logic
-  if (problem) {
-    warnings.push({
-      rule: 'my_rule',
-      severity: 'warning', // or 'error' | 'info'
-      message: 'Description of issue',
-      nodeId: node.id,
-      nodeName: node.name,
-      suggestion: 'How to fix'
-    });
-  }
-  return warnings;
-}
-```
-
-2. **Add to composition** in `validateWorkflow()`:
-```typescript
-...checkMyRule(workflow),
-```
-
-3. **Add test** in `validators.test.ts`:
-```typescript
-it('detects my_rule violations', () => {
-  const workflow = createWorkflow({
-    // problematic config
-  });
-  const warnings = validateWorkflow(workflow);
-  expect(warnings).toContainEqual(
-    expect.objectContaining({ rule: 'my_rule' })
-  );
-});
-```
-
-## Adding an Auto-Fix
-
-1. **Check if fixable** - some issues require human judgment
-2. **Add fix logic** in `autofix.ts`:
-```typescript
-if (warning.rule === 'my_rule') {
-  // transform workflow
-  fixed.push(warning);
-} else {
-  unfixed.push(warning);
-}
-```
-3. **Update references** if renaming anything
-4. **Test both dry-run and apply modes**
-
-## Patterns to Follow
-
-### Safe Mutations
-```typescript
-// Always clone before mutating
-const copy = JSON.parse(JSON.stringify(original));
-// Modify copy, return copy
-```
-
-### Async Operations
-```typescript
-// All file/network operations are async
-async function doThing(): Promise<Result> {
-  const data = await fetchData();
-  return transform(data);
-}
-```
-
-### Error Responses
-```typescript
-// MCP error format
-return {
-  content: [{ type: 'text', text: 'Error message' }],
-  isError: true
-};
-```
-
-### Validation Returns
-```typescript
-// Always return array (empty if valid)
-function validate(): ValidationWarning[] {
-  const warnings: ValidationWarning[] = [];
-  // ... checks ...
-  return warnings;
-}
-```
-
-## Testing Patterns
-
-### Fixture Factory
-```typescript
-function createWorkflow(overrides: Partial<N8nWorkflow> = {}): N8nWorkflow {
-  return {
-    id: 'test-id',
-    name: 'test_workflow',
-    nodes: [],
-    connections: {},
-    ...overrides
-  };
-}
-```
-
-### Assertion Patterns
-```typescript
-// Check warning exists
-expect(warnings).toContainEqual(
-  expect.objectContaining({ rule: 'rule_name' })
-);
-
-// Check no warnings
-expect(warnings).toHaveLength(0);
-
-// Check severity
-expect(warnings[0].severity).toBe('error');
-```
-
-## Out of Scope
-
-Do not implement:
-- Node documentation/search (use web search)
-- Template marketplace features
-- Credential management
-- Multi-instance sync
-- Real-time execution monitoring
-
-These are either security risks or solved problems (Google, n8n UI).
-
-## Questions to Ask
-
-Before adding a feature:
-1. Does this serve workflow editing/validation/versioning?
-2. Can this be solved with existing web search?
-3. Does this add runtime dependencies?
-4. Is there duplication that justifies abstraction?
-
-If any answer suggests bloat, reconsider.
-
-## File Locations
-
-```
-~/.n8n-mcp/versions/     # Version control storage
-  {workflowId}/
-    {timestamp}_{hash}.json
-```
-
-## Environment Variables
-
-```bash
-N8N_API_URL=http://localhost:5678  # n8n instance URL
-N8N_API_KEY=your-api-key           # n8n API key
-```
-
-## Debugging
-
-```bash
-# Run with verbose output
-DEBUG=* npm run dev
-
-# Test single file
-npx vitest run src/validators.test.ts
-
-# Watch single test
-npx vitest watch src/validators.test.ts
-```

package/plans/architecture.md

@@ -1,220 +0,0 @@
-# Architecture
-
-**Opinionated** n8n workflow automation. Enforces conventions, blocks mistakes, auto-fixes issues.
-
-## vs czlonkowski/n8n-mcp
-
-| Concern | czlonkowski | @pagelines |
-|---------|-------------|------------|
-| Philosophy | Permissive | Opinionated |
-| Node docs | 70MB SQLite, 1084 nodes | None (use Google) |
-| Templates | 2,709 indexed | None (use n8n.io) |
-| Update mode | Full replace | Patch (preserves params) |
-| After mutations | Nothing | Auto-validate, auto-fix, format |
-| Invalid node types | API error | Blocked with suggestions |
-| Version control | Limited | Auto-snapshot, diff, rollback |
-| Validation | Basic | Rules + expressions + circular refs |
-| Auto-fix | No | Yes (automatic) |
-| Dependencies | SQLite, heavy | Zero runtime |
-| Lines of code | ~10k+ | ~1,500 |
-
-## Modules
-
-```
-src/
-├── index.ts           # MCP server, tool dispatch
-├── types.ts           # Type definitions
-├── tools.ts           # Tool schemas (JSON Schema)
-├── n8n-client.ts      # n8n REST API client
-├── validators.ts      # Validation rules + node type validation
-├── expressions.ts     # Expression parsing ({{ }})
-├── autofix.ts         # Auto-fix transforms
-├── versions.ts        # Version control (local fs)
-└── response-format.ts # Token-efficient response formatting
-```
-
-## Data Flow
-
-```
-Claude Request
-    ↓
-MCP Server (stdio)
-    ↓
-Tool Handler
-    ↓
-┌─────────────────────────────────┐
-│  n8n-client     validators      │
-│  expressions    autofix         │
-│  versions       response-format │
-└─────────────────────────────────┘
-    ↓
-JSON Response → Claude
-```
-
-## Auto-Cleanup Pipeline
-
-Every `workflow_create` and `workflow_update` runs this automatically:
-
-```
-1. Validate node types → Block if invalid (with suggestions)
-2. Execute operation
-3. Validate workflow → Get warnings
-4. Auto-fix fixable issues → snake_case, $json refs, AI settings
-5. Format workflow → Sort nodes, remove nulls
-6. Update if changes → Apply cleanup to n8n
-7. Return result → Only unfixable warnings shown
-```
-
-## Tools (20 total)
-
-### Workflow (8)
-| Tool | Description |
-|------|-------------|
-| `workflow_list` | List workflows, filter by active |
-| `workflow_get` | Get full workflow |
-| `workflow_create` | Create with nodes/connections (auto-validates, auto-fixes) |
-| `workflow_update` | Patch operations (auto-validates, auto-fixes) |
-| `workflow_delete` | Delete workflow |
-| `workflow_activate` | Enable triggers |
-| `workflow_deactivate` | Disable triggers |
-| `workflow_execute` | Trigger via webhook |
-
-### Execution (2)
-| Tool | Description |
-|------|-------------|
-| `execution_list` | List executions, filter by status |
-| `execution_get` | Get execution with run data |
-
-### Validation (3)
-| Tool | Description |
-|------|-------------|
-| `workflow_validate` | Check rules + expressions + circular refs |
-| `workflow_autofix` | Fix auto-fixable issues (dry-run default) |
-| `workflow_format` | Sort nodes, clean nulls |
-
-### Discovery (1)
-| Tool | Description |
-|------|-------------|
-| `node_types_list` | Search available node types by name/category |
-
-### Version Control (6)
-| Tool | Description |
-|------|-------------|
-| `version_list` | List snapshots for workflow |
-| `version_get` | Get specific version |
-| `version_save` | Manual snapshot with reason |
-| `version_rollback` | Restore previous (auto-saves current first) |
-| `version_diff` | Compare versions |
-| `version_stats` | Version control statistics |
-
-## Patch Operations
-
-`workflow_update` accepts these operation types:
-
-```
-addNode, removeNode, updateNode
-addConnection, removeConnection
-updateSettings, updateName
-```
-
-Key: Preserves unmodified parameters.
-
-## Node Type Validation
-
-Before `workflow_create` or `workflow_update` with `addNode`:
-
-1. Fetch available types from n8n API
-2. Validate all node types exist
-3. **Block** if invalid with suggestions (fuzzy matching)
-
-```
-Error: Invalid node types detected:
-Invalid node type "n8n-nodes-base.webhok" for node "trigger".
-Did you mean: n8n-nodes-base.webhook?
-
-Use node_types_list to discover available node types.
-```
-
-## Validation Rules
-
-All rules are checked automatically on every `workflow_create` and `workflow_update`:
-
-| Rule | Severity | Auto-fix | Description |
-|------|----------|----------|-------------|
-| `snake_case` | warning | Yes | Names should be snake_case |
-| `explicit_reference` | warning | Yes | Use `$('node')` not `$json` |
-| `ai_structured_output` | warning | Yes | AI node missing structured output |
-| `no_hardcoded_ids` | info | No | Avoid hardcoded IDs |
-| `no_hardcoded_secrets` | info | No | Consider using $env vars |
-| `code_node_usage` | info | No | Code node detected |
-| `in_memory_storage` | warning | No | Non-persistent storage |
-| `orphan_node` | warning | No | Node has no connections |
-| `node_exists` | error | No | Node doesn't exist (for updates) |
-| `parameter_preservation` | error | No | Update would lose parameters |
-
-## Expression Validation
-
-| Issue | Severity | Pattern |
-|-------|----------|---------|
-| Uses `$json` | warning | `$json.` without `$('` prefix |
-| Uses `$input` | info | `$input.` usage |
-| Missing node reference | error | `$('node')` where node doesn't exist |
-| Unclosed `}}` | error | Unmatched delimiters |
-| Unbalanced parens/brackets | error | `(` vs `)`, `[` vs `]` |
-| Deprecated `$node` | warning | `$node.` pattern |
-| Deep property without `?.` | info | Missing optional chaining |
-
-Plus: **Circular reference detection** across all expressions.
-
-## Auto-Fix
-
-| Rule | Transform |
-|------|-----------|
-| `snake_case` | Rename + update all references |
-| `explicit_reference` | `$json.x` → `$('prev_node').item.json.x` |
-| `ai_structured_output` | Add `promptType: "define"`, `hasOutputParser: true` |
-
-**Not fixable** (require judgment): secrets, hardcoded IDs, orphan nodes, code nodes, memory storage.
-
-## Version Control
-
-Storage: `~/.n8n-mcp/versions/{workflowId}/{timestamp}_{hash}.json`
-
-```json
-{
-  "id": "1704067200000_abc123",
-  "workflowId": "123",
-  "timestamp": "2024-01-01T00:00:00.000Z",
-  "reason": "before update",
-  "metadata": {
-    "name": "my_workflow",
-    "nodeCount": 5,
-    "contentHash": "abc123"
-  },
-  "workflow": { /* full snapshot */ }
-}
-```
-
-Features:
-- Hash-based deduplication (no duplicate saves)
-- Max versions pruning (default: 20)
-- Auto-save before `workflow_update` and `version_rollback`
-
-## Extension
-
-Add validation rule:
-```typescript
-// validators.ts
-function checkMyRule(workflow: N8nWorkflow): ValidationWarning[] {
-  // return warnings
-}
-// Add to validateWorkflow()
-```
-
-Add auto-fix:
-```typescript
-// autofix.ts
-if (warning.rule === 'my_rule' && fixable) {
-  // transform workflow
-}
-```

package/server.json

@@ -1,66 +0,0 @@
-{
-  "$schema": "https://registry.modelcontextprotocol.io/schema/server.json",
-  "name": "io.github.pagelines/n8n-mcp",
-  "displayName": "pl-n8n-mcp",
-  "description": "Opinionated MCP server for n8n workflow automation with built-in validation and safety features",
-  "version": "0.2.0",
-  "author": {
-    "name": "PageLines",
-    "url": "https://github.com/pagelines"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/PageLines/n8n-mcp"
-  },
-  "license": "MIT",
-  "packages": {
-    "npm": "@pagelines/n8n-mcp"
-  },
-  "runtime": {
-    "command": "npx",
-    "args": ["-y", "@pagelines/n8n-mcp"],
-    "env": {
-      "N8N_API_URL": {
-        "description": "n8n instance URL",
-        "required": true
-      },
-      "N8N_API_KEY": {
-        "description": "n8n API key",
-        "required": true,
-        "secret": true
-      }
-    }
-  },
-  "capabilities": {
-    "tools": true,
-    "resources": false,
-    "prompts": false
-  },
-  "tools": [
-    "workflow_list",
-    "workflow_get",
-    "workflow_create",
-    "workflow_update",
-    "workflow_delete",
-    "workflow_activate",
-    "workflow_deactivate",
-    "workflow_execute",
-    "workflow_validate",
-    "workflow_autofix",
-    "workflow_format",
-    "execution_list",
-    "execution_get",
-    "version_list",
-    "version_get",
-    "version_save",
-    "version_rollback",
-    "version_diff",
-    "version_stats"
-  ],
-  "keywords": [
-    "n8n",
-    "workflow",
-    "automation",
-    "mcp"
-  ]
-}