Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
314 lines (217 loc) · 6.66 KB

CONTRIBUTING.md

File metadata and controls

314 lines (217 loc) · 6.66 KB
Raw

Contributing to File Organizer MCP

Thank you for considering contributing to File Organizer MCP! This document provides guidelines and instructions for contributing.

🔒 Security First

This project prioritizes security. All contributions must maintain or improve the security posture of the application.

Reporting Security Vulnerabilities

⚠️ DO NOT open public issues for security vulnerabilities

Instead, email security concerns to: technocratix902@gmail.com

We will respond within 48 hours and work with you to address the issue.

📋 Code of Conduct

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Welcome newcomers and help them get started
  • Maintain professional communication

🚀 Getting Started

Prerequisites

  • Node.js v18.0.0 or higher
  • Git
  • A code editor (VSCode recommended)

Setting Up Development Environment

# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/File-Organizer-MCP.git
cd File-Organizer-MCP

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. Run tests
npm test

🏗️ Project Structure

File-Organizer-MCP/
├── src/
│   ├── services/      # Core business logic
│   ├── tools/         # MCP tool implementations
│   ├── utils/         # Helper functions
│   ├── schemas/       # Zod validation schemas
│   └── types.ts       # TypeScript type definitions
├── tests/
│   ├── unit/          # Unit tests
│   ├── integration/   # Integration tests
│   └── performance/   # Performance benchmarks
└── dist/              # Compiled output

📝 Development Guidelines

Code Style

We use ESLint and Prettier for code formatting:

# Run linter
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code
npm run format

TypeScript

  • Use strict type checking
  • Avoid any - use proper types
  • Document complex types with JSDoc comments
  • Use ESM imports with .js extensions

Naming Conventions

  • Files: kebab-case.ts (e.g., path-validator.service.ts)
  • Classes: PascalCase (e.g., PathValidatorService)
  • Functions: camelCase (e.g., validatePath)
  • Constants: SCREAMING_SNAKE_CASE (e.g., MAX_FILE_SIZE)

🧪 Testing

Writing Tests

All new features and bug fixes must include tests:

import { jest } from '@jest/globals';
import { YourService } from '../src/services/your-service.js';

describe('YourService', () => {
  it('should do something', () => {
    const service = new YourService();
    expect(service.doSomething()).toBe(expected);
  });
});

Running Tests

# Run all tests
npm test

# Run specific test file
npm test tests/unit/services/your-service.test.ts

# Run tests with coverage
npm run test:coverage

Test Requirements

  • ✅ Unit tests for all service methods
  • ✅ Integration tests for MCP tools
  • ✅ Security tests for validation logic
  • ✅ Edge case coverage

🔐 Security Guidelines

Input Validation

Always validate and sanitize user inputs:

// ✅ Good
const result = PathSchema.safeParse(inputPath);
if (!result.success) {
  throw new ValidationError('Invalid path');
}

// ❌ Bad
const filePath = userInput; // No validation

Path Traversal Prevention

Use the PathValidatorService for all path operations:

// ✅ Good
import { validateStrictPath } from './services/path-validator.service.js';
const validPath = await validateStrictPath(userPath, allowedRoots);

// ❌ Bad
const fullPath = path.join(baseDir, userPath); // Unsafe

Error Handling

Never expose internal paths in error messages:

// ✅ Good
throw new ValidationError('Path validation failed');

// ❌ Bad
throw new Error(`Invalid path: ${internalPath}`);

📤 Contribution Workflow

1. Create an Issue

Before starting work, create an issue describing:

  • The problem or feature request
  • Proposed solution (if applicable)
  • Any breaking changes

2. Fork and Branch

# Create a feature branch
git checkout -b feature/amazing-feature

# Or a bugfix branch
git checkout -b fix/issue-123

3. Make Changes

  • Write clean, documented code
  • Follow existing code style
  • Add tests for new features
  • Update documentation

4. Test Thoroughly

# Run all tests
npm test

# Check linting
npm run lint

# Build the project
npm run build

5. Commit

Use conventional commit messages:

# Features
git commit -m "feat: add new categorization rule"

# Bug fixes
git commit -m "fix: resolve path traversal issue"

# Documentation
git commit -m "docs: update API reference"

# Tests
git commit -m "test: add edge case for organizer"

6. Push and Create PR

git push origin feature/amazing-feature

Create a Pull Request with:

  • Clear description of changes
  • Link to related issue(s)
  • Screenshots (if UI changes)
  • Test results

🎯 Areas for Contribution

High Priority

  • 🔒 Security enhancements and audits
  • 🧪 Test coverage improvements
  • 📚 Documentation improvements
  • 🐛 Bug fixes

Feature Ideas

  • Custom categorization rules UI
  • Advanced duplicate detection algorithms
  • Cloud storage integration
  • Batch processing improvements
  • Performance optimizations

Good First Issues

Look for issues labeled good-first-issue - these are great starting points for new contributors.

📚 Documentation

Update relevant documentation when making changes:

  • README.md - User-facing documentation
  • ARCHITECTURE.md - Technical architecture
  • JSDoc comments - In-code documentation
  • CHANGELOG.md - Version history

✅ Pull Request Checklist

Before submitting your PR, ensure:

  • Code follows project style guidelines
  • All tests pass (npm test)
  • No linting errors (npm run lint)
  • New tests added for new features
  • Documentation updated
  • Commit messages follow conventions
  • PR description is clear and complete
  • No merge conflicts
  • Security implications considered

🤝 Review Process

  1. Automated Checks - CI runs tests and linting
  2. Code Review - Maintainers review your code
  3. Feedback - Address any requested changes
  4. Approval - Once approved, PR will be merged
  5. Release - Changes included in next release

📞 Getting Help

🙏 Recognition

Contributors will be recognized in:

  • README.md acknowledgments
  • CHANGELOG.md release notes
  • GitHub contributors page

Thank you for contributing to File Organizer MCP! 🎉