Contributing Guidelines¶

Thank you for your interest in contributing to the n8n MCP Workflow Builder! This guide will help you get started.

Quick Start¶

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/mcp-n8n-workflow-builder.git
cd mcp-n8n-workflow-builder

# 2. Install dependencies
npm install

# 3. Build project
npm run build

# 4. Run tests
npm test

# 5. Start development server
npm run dev

Code of Conduct¶

Be respectful and constructive
Welcome newcomers and help others learn
Focus on what is best for the community
Show empathy and kindness

Report violations to project maintainers.

How to Contribute¶

Reporting Bugs¶

Search existing issues to avoid duplicates
Use bug report template (see Bug Reporting)
Include:
MCP server version
n8n version
Node.js version
Steps to reproduce
Expected vs actual behavior
Error messages with DEBUG=true
Configuration (sanitized)

Suggesting Features¶

Check existing feature requests
Describe use case and motivation
Propose solution with examples
Consider alternatives you've explored
Add context (mockups, related features)

Contributing Code¶

Find or create issue
Fork repository
Create feature branch: git checkout -b feature/your-feature
Make changes following code style
Write tests for new functionality
Run tests: npm test
Update documentation
Commit: git commit -m "feat: add your feature"
Push: git push origin feature/your-feature
Create pull request

Development Setup¶

Prerequisites¶

Node.js: v14 or higher
npm: Latest version
n8n instance: For testing (local or cloud)
Git: For version control

Environment Setup¶

# Install dependencies
npm install

# Create configuration
cp .env.example .env

# Edit .env with your n8n credentials
N8N_HOST=https://your-n8n-instance.com
N8N_API_KEY=your_api_key

# Build project
npm run build

# Run in development mode
npm run dev

Development Scripts¶

npm run clean        # Remove build artifacts
npm run build        # Compile TypeScript
npm run dev          # Watch mode for development
npm start            # Run compiled server
npm test             # Run unit tests
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Generate coverage report

Code Style¶

TypeScript¶

Strict mode enabled
ESLint for linting
Prettier for formatting

Naming Conventions¶

// Classes: PascalCase
class EnvironmentManager {}

// Functions/Methods: camelCase
function createWorkflow() {}

// Constants: UPPER_SNAKE_CASE
const DEFAULT_PORT = 3456;

// Interfaces: PascalCase with I prefix (optional)
interface WorkflowParams {}

// Files: kebab-case
// environment-manager.ts
// n8n-api-wrapper.ts

File Organization¶

src/
├── index.ts              # Entry point
├── services/             # Business logic
│   ├── environmentManager.ts
│   ├── n8nApiWrapper.ts
│   └── __tests__/        # Unit tests
├── types/                # TypeScript types
│   └── api.ts
└── utils/                # Utilities
    └── validation.ts

Code Patterns¶

Multi-Instance Tool Pattern¶

All MCP tools must support optional instance parameter:

interface ToolParams {
  instance?: string;  // Always optional
  // ... other parameters
}

Instance Resolution Pattern¶

private async callWithInstance<T>(
  instanceSlug: string | undefined,
  apiCall: () => Promise<T>
): Promise<T> {
  // Validate instance exists if provided
  // Use default if no instance specified
  // Execute API call
  // Provide helpful error messages
}

Error Handling Pattern¶

private handleApiError(context: string, error: unknown): never {
  logger.error(`API error during ${context}`);
  if (axios.isAxiosError(error)) {
    logger.error(`Status: ${error.response?.status}`);
    logger.error(`Response: ${JSON.stringify(error.response?.data)}`);
  }
  throw new Error(`API error ${context}: ${error.message}`);
}

Testing Requirements¶

Unit Tests¶

Coverage: Minimum 80%
Location: src/services/__tests__/
Framework: Jest
Run: npm test

// Example unit test
describe('EnvironmentManager', () => {
  it('should load configuration successfully', () => {
    const manager = EnvironmentManager.getInstance();
    expect(manager).toBeDefined();
  });
});

Integration Tests¶

Location: Project root (test-*.js)
Run: node test-mcp-tools.js
Cleanup: Always clean up test data

// Example integration test
async function testCreateWorkflow() {
  const workflow = await createWorkflow({
    name: 'Test Workflow',
    nodes: [...]
  });

  try {
    expect(workflow.id).toBeDefined();
    expect(workflow.name).toBe('Test Workflow');
  } finally {
    await deleteWorkflow(workflow.id);
  }
}

Documentation Standards¶

Code Documentation¶

/**
 * Creates a new workflow in the specified n8n instance.
 *
 * @param params - Workflow creation parameters
 * @param params.instance - Optional instance identifier
 * @param params.name - Workflow name
 * @param params.nodes - Array of workflow nodes
 * @returns Created workflow with ID
 * @throws {Error} If workflow creation fails
 */
async createWorkflow(params: CreateWorkflowParams): Promise<Workflow> {
  // Implementation
}

README Updates¶

Update README.md for user-facing changes:

New tools
New features
Breaking changes
Configuration changes

CHANGELOG Updates¶

Follow Keep a Changelog format:

## [Version] - YYYY-MM-DD

### Added
- New feature description

### Changed
- Changed behavior description

### Fixed
- Bug fix description

Pull Request Process¶

PR Checklist¶

Commit Message Format¶

Follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types: - feat: New feature - fix: Bug fix - docs: Documentation changes - style: Code style changes - refactor: Code refactoring - test: Test updates - chore: Build/tooling changes

Examples:

feat(api): add support for workflow templates
fix(auth): handle expired API keys gracefully
docs(readme): update installation instructions

PR Template¶

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing completed

## Screenshots (if applicable)

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] No breaking changes

Review Criteria¶

Pull requests will be reviewed for:

Functionality: Does it work as intended?
Code Quality: Is it maintainable and well-structured?
Tests: Are there adequate tests?
Documentation: Is it properly documented?
Performance: Are there performance implications?
Security: Are there security concerns?
Breaking Changes: Are they necessary and documented?

Adding New Features¶

Adding New MCP Tool¶

Define tool schema in src/index.ts:

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "new_tool",
      description: "Tool description",
      inputSchema: {
        type: "object",
        properties: {
          instance: {
            type: "string",
            description: "Instance identifier (optional)"
          },
          // ... other parameters
        },
        required: ["param1", "param2"]
      }
    }
  ]
}));

Implement handler:

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "new_tool") {
    const result = await n8nApi.newToolMethod(request.params.arguments);
    return {
      content: [{
        type: "text",
        text: JSON.stringify(result, null, 2)
      }]
    };
  }
});

Add to N8NApiWrapper:

async newToolMethod(params: NewToolParams): Promise<Result> {
  return this.callWithInstance(params.instance, async () => {
    // Implementation
  });
}

Write tests
Update documentation

Adding Workflow Template¶

Define in src/services/promptsService.ts:

const NEW_TEMPLATE: Prompt = {
  id: "new-template",
  name: "New Template",
  description: "Template description",
  template: {
    nodes: [...],
    connections: [...]
  },
  variables: [
    {
      name: "variable_name",
      description: "Variable description",
      type: "string",
      default: "default_value"
    }
  ]
};

Add to exports
Test with Claude Desktop
Update documentation

Getting Help¶

Documentation: Check docs/
Issues: Search GitHub Issues
Discussions: Ask in GitHub Discussions

License¶

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing! 🎉

Document Version: 1.0 Last Updated: December 2025