# Contributing Guidelines

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

---

## Quick Start

```bash
# 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

1. **Search existing issues** to avoid duplicates
2. **Use bug report template** (see [Bug Reporting](../troubleshooting/error-reference.md#getting-additional-help))
3. **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

1. **Check existing feature requests**
2. **Describe use case** and motivation
3. **Propose solution** with examples
4. **Consider alternatives** you've explored
5. **Add context** (mockups, related features)

### Contributing Code

1. **Find or create issue**
2. **Fork repository**
3. **Create feature branch:** `git checkout -b feature/your-feature`
4. **Make changes** following code style
5. **Write tests** for new functionality
6. **Run tests:** `npm test`
7. **Update documentation**
8. **Commit:** `git commit -m "feat: add your feature"`
9. **Push:** `git push origin feature/your-feature`
10. **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

```bash
# 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

```bash
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

```typescript
// 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:

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

### Instance Resolution Pattern

```typescript
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

```typescript
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`

```typescript
// 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

```javascript
// 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

```typescript
/**
 * 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](https://keepachangelog.com/) format:

```markdown
## [Version] - YYYY-MM-DD

### Added
- New feature description

### Changed
- Changed behavior description

### Fixed
- Bug fix description
```

---

## Pull Request Process

### PR Checklist

- [ ] Tests pass (`npm test`)
- [ ] Code follows style guidelines
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] No breaking changes (or documented)
- [ ] Commits follow conventional commits
- [ ] PR description complete

### Commit Message Format

Follow [Conventional Commits](https://www.conventionalcommits.org/):

```
<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

```markdown
## 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:

1. **Functionality:** Does it work as intended?
2. **Code Quality:** Is it maintainable and well-structured?
3. **Tests:** Are there adequate tests?
4. **Documentation:** Is it properly documented?
5. **Performance:** Are there performance implications?
6. **Security:** Are there security concerns?
7. **Breaking Changes:** Are they necessary and documented?

---

## Adding New Features

### Adding New MCP Tool

1. **Define tool schema** in `src/index.ts`:
```typescript
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"]
      }
    }
  ]
}));
```

2. **Implement handler**:
```typescript
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)
      }]
    };
  }
});
```

3. **Add to N8NApiWrapper**:
```typescript
async newToolMethod(params: NewToolParams): Promise<Result> {
  return this.callWithInstance(params.instance, async () => {
    // Implementation
  });
}
```

4. **Write tests**
5. **Update documentation**

### Adding Workflow Template

1. **Define in `src/services/promptsService.ts`**:
```typescript
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"
    }
  ]
};
```

2. **Add to exports**
3. **Test with Claude Desktop**
4. **Update documentation**

---

## Getting Help

- **Documentation:** Check [docs/](../)
- **Issues:** Search [GitHub Issues](https://github.com/salacoste/mcp-n8n-workflow-builder/issues)
- **Discussions:** Ask in [GitHub Discussions](https://github.com/salacoste/mcp-n8n-workflow-builder/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