Development Guide

August 27, 2025 · View on GitHub

This guide covers how to set up, develop, and contribute to the pref-editor-mcp-server project.

Prerequisites

  • Node.js: Version 20.0.0 or higher (see engines in package.json)
  • npm: Comes with Node.js
  • Git: For version control

Getting Started

1. Clone the Repository

git clone https://github.com/charlesmuchene/pref-editor-mcp-server.git
cd pref-editor-mcp-server

2. Install Dependencies

npm install

3. Verify Setup

Run the full verification suite to ensure everything works:

npm run verify

This runs: clean → lint → build → test → coverage

Development Workflow

Available Scripts

# Development
npm run dev          # Run in development mode with ts-node
npm run watch        # Watch mode for TypeScript compilation

# Building
npm run build        # Compile TypeScript to dist/
npm run clean        # Remove dist/ directory

# Testing
npm test             # Run tests once
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Run tests with coverage report

# Quality Checks
npm run lint         # Run ESLint
npm run verify       # Run all checks (recommended before commits)

# Production
npm start            # Run the compiled server

Project Structure

├── src/
│   ├── index.ts          # Main entry point
│   ├── schema.ts         # Zod validation schemas
│   ├── utils.ts          # Utility functions
│   └── tools/
│       ├── common.ts     # Common MCP tools
│       └── prefs.ts      # Preference management tools
├── tests/                # Test files
├── .github/
│   ├── workflows/        # CI/CD workflows
│   ├── CODEOWNERS        # Code ownership
│   └── pull_request_template.md
└── dist/                 # Compiled output (generated)

Before Opening a Pull Request

1. Code Quality Checks

Run the verification suite locally:

npm run verify

This ensures:

  • ✅ No lint errors
  • ✅ TypeScript compiles successfully
  • ✅ All tests pass
  • ✅ Test coverage ≥ 80%

2. PR Title Format

Your PR title must follow this format (case-insensitive):

BREAKING: Description of breaking changes (or breaking:)
feat: Description of new features (or FEAT:)
fix: Description of bug fixes (or FIX:)

Examples:

  • BREAKING: Remove deprecated tools (→ major version bump)
  • feat: Add new preference validation feature (→ minor version bump)
  • fix: Fix memory leak in connection handling (→ patch version bump)

❌ Invalid titles will fail CI:

  • Add new feature (missing prefix)
  • Feat: Breaking change (wrong case)
  • major: Remove API (wrong prefix)

3. Test Coverage

  • All new code must have tests
  • Maintain ≥ 80% coverage across lines, functions, branches, and statements
  • Run npm run test:coverage to check coverage locally

4. Code Standards

  • Follow existing code patterns
  • Use TypeScript strict mode
  • Add JSDoc comments for public APIs
  • Follow the existing import/export patterns

After Opening a Pull Request

1. CI Checks Must Pass

The following automated checks will run:

  • PR Title Validation - Ensures proper format
  • Linting - Code style and quality checks
  • Build - TypeScript compilation
  • Tests - All test suites must pass
  • Coverage - Must maintain ≥ 80% threshold

2. Ready for Review Process

  1. Wait for CI - All checks must be green ✅
  2. Add "READY-FOR-REVIEW" label - This notifies code owners
  3. Address feedback - Respond to review comments
  4. Update as needed - Push additional commits if required

3. Automatic Processes

When your PR is approved and merged:

  • Auto-versioning - Version bumped based on your PR title prefix
  • Auto-tagging - Git tag created (e.g., v0.8.0)
  • Auto-release - GitHub release created with changelog
  • Branch cleanup - Feature branch automatically deleted

Troubleshooting

Common Issues

CI failing on PR title:

# Fix your PR title format (case-insensitive)
BREAKING: Your description here  # or breaking:
feat: Your description here      # or FEAT:
fix: Your description here       # or FIX:

Lint errors:

npm run lint           # See errors
npm run lint -- --fix  # Auto-fix some issues

Test failures:

npm test              # Run tests
npm run test:watch    # Debug in watch mode

Coverage too low:

npm run test:coverage # See coverage report
# Add tests for uncovered code

Build errors:

npm run build         # See TypeScript errors
# Fix type issues and imports

Getting Help

  1. Check CI logs - Click on failed checks for details
  2. Run locally - Use npm run verify to reproduce issues
  3. Review existing code - Follow established patterns
  4. Ask questions - Comment on your PR if stuck

Code Review Guidelines

For Contributors

  • Keep PRs focused and small when possible
  • Write clear commit messages
  • Add tests for new functionality
  • Update documentation if needed
  • Respond promptly to review feedback

For Reviewers

  • Check the automated PR comment for CI status
  • Verify test coverage for new code
  • Ensure code follows project conventions
  • Test functionality if significant changes
  • Provide constructive feedback

Release Process

Releases are fully automated:

  1. Merge PR with proper title prefix
  2. Auto-version bumps version in package.json
  3. Auto-tag creates git tag
  4. Auto-release creates GitHub release
  5. Changelog generated from commit history

No manual intervention required! 🚀

Quick Reference

# Setup
git clone https://github.com/charlesmuchene/pref-editor-mcp-server.git && cd pref-editor-mcp-server && npm install

# Before PR
npm run verify

# PR title format (case-insensitive)
BREAKING|feat|fix: Description

# After PR merged
# → Automatic versioning and release