Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
219 lines (151 loc) · 5.06 KB

CONTRIBUTING.md

File metadata and controls

219 lines (151 loc) · 5.06 KB
Raw

Contributing to faf-mcp

Thank you for your interest in contributing to faf-mcp. This document provides guidelines for contributing to the project.

Development Philosophy

This project follows F1-inspired engineering standards:

  • Championship-grade quality - No compromises on reliability or performance
  • Sub-50ms performance targets - Speed matters
  • 100% TypeScript strict mode - Type safety is non-negotiable
  • Zero errors - Every build must be clean
  • Test everything - If it's not tested, it doesn't work

Before You Start

Getting Started

Prerequisites

  • Node.js 18 or higher
  • npm or yarn
  • Git
  • your MCP client (for testing)

Setup

# Clone the repository
git clone https://github.com/Wolfe-Jam/faf-mcp.git
cd faf-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Link for local testing
npm link

Development Workflow

  1. Create a branch from main:

    git checkout -b feature/your-feature-name

  2. Make your changes following our coding standards

  3. Test thoroughly:

    npm test
npm run build

  4. Commit your changes using our commit format:

    <type>: <what changed>

- <specific detail>
- <specific detail>

    Types: feat, fix, docs, test, refactor, perf, chore

    Example:

    feat: add faf_enhance tool for context optimization

- Implements scoring algorithm with 21-slot system
- Adds TypeScript interfaces for tool parameters
- Includes test coverage for edge cases

  5. Push to your fork and submit a pull request

Code Standards

TypeScript

  • Use TypeScript strict mode (already configured)
  • All functions must have explicit return types
  • No any types (use unknown if truly needed)
  • Prefer interfaces over types for object shapes

Testing

  • All new features require tests
  • Maintain or improve code coverage
  • Test both success and error cases
  • Include edge case testing

Performance

  • Profile performance-critical code
  • Target sub-50ms for operations
  • No blocking operations in hot paths
  • Document any performance considerations

Documentation

  • Update README.md for user-facing changes
  • Add JSDoc comments for exported functions
  • Update CHANGELOG.md following Keep a Changelog format
  • Include examples for new features

Pull Request Process

  1. Ensure tests pass:

    npm test
npm run build

  2. Update documentation as needed

  3. Add your changes to CHANGELOG.md under "Unreleased"

  4. Fill out the PR template completely

  5. Request review from maintainers

PR Guidelines

  • One feature or fix per PR
  • Keep PRs focused and small when possible
  • Link related issues
  • Include screenshots for UI changes
  • Respond to review feedback promptly

Testing with your MCP client

To test your changes locally with your MCP client:

  1. Link your local build:

    npm link

  2. Update your MCP client config:

    {
  "mcpServers": {
    "faf-mcp": {
      "command": "node",
      "args": ["/path/to/your/local/faf-mcp/build/index.js"]
    }
  }
}

  3. Restart your MCP client

  4. Test your changes in conversation

What We're Looking For

High Priority

  • Performance improvements
  • Bug fixes with reproducible test cases
  • Enhanced error handling
  • Better TypeScript types
  • Documentation improvements

Welcome Contributions

  • New tool implementations
  • Test coverage improvements
  • Example use cases
  • Integration guides
  • Bug reports with detailed reproduction steps

Not Accepting

  • Changes that increase dependencies unnecessarily
  • Breaking changes without migration path
  • Performance regressions
  • Code that doesn't pass TypeScript strict checks

Getting Help

Recognition

Contributors are recognized in several ways:

  • Listed in CHANGELOG.md for their contributions
  • Mentioned in release notes for significant features
  • Added to package.json contributors list

License

By contributing, you agree that your contributions will be licensed under the MIT License. See LICENSE file for details.

Questions?

If you have questions about contributing, open a discussion or reach out to team@faf.one.

Built with championship standards by the FAF community

Created by Wolfe James (ORCID: 0009-0007-0801-3841)