Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
324 lines (248 loc) · 6.34 KB

CONTRIBUTING.md

File metadata and controls

324 lines (248 loc) · 6.34 KB
Raw

Contributing to UTCP Documentation MCP Server

Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to the project.

Table of Contents

  1. Code of Conduct
  2. Getting Started
  3. Development Setup
  4. Making Changes
  5. Testing
  6. Submitting Changes
  7. Style Guidelines

Code of Conduct

This project adheres to a Code of Conduct that all contributors are expected to follow:

  • Be respectful and inclusive
  • Welcome newcomers
  • Focus on constructive feedback
  • Respect differing viewpoints and experiences

Getting Started

Prerequisites

  • Node.js 20.x or higher
  • npm 9.x or higher
  • Git
  • TypeScript knowledge
  • Familiarity with MCP and UTCP

Development Setup

  1. Fork the repository

    # Click "Fork" on GitHub

  2. Clone your fork

    git clone https://github.com/your-username/utcp-docs-mcp-server.git
cd utcp-docs-mcp-server

  3. Install dependencies

    npm install

  4. Build the project

    npm run build

  5. Run tests

    npm test

  6. Set up development environment

    # Link for local testing
npm link

# Run in watch mode
npm run watch

Making Changes

Branch Naming

Use descriptive branch names:

  • feature/add-semantic-search - New features
  • fix/validation-error - Bug fixes
  • docs/update-readme - Documentation
  • refactor/improve-generator - Code improvements
  • test/add-converter-tests - Test additions

Commit Messages

Follow conventional commits:

type(scope): description

[optional body]

[optional footer]

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • style: Code style (formatting)
  • refactor: Code refactoring
  • test: Tests
  • chore: Maintenance

Examples:

git commit -m "feat(validator): add support for SSE protocol validation"
git commit -m "fix(converter): handle OpenAPI path parameters correctly"
git commit -m "docs(readme): add troubleshooting section"

Testing

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run specific test file
npm test tests/services/validator.test.ts

# Generate coverage report
npm run test:coverage

Writing Tests

  1. Create test files in tests/ directory matching source structure
  2. Name test files with .test.ts suffix
  3. Use descriptive test names
  4. Cover edge cases

Example:

import { describe, it, expect } from 'vitest';
import { YourService } from '../src/services/your-service.js';

describe('YourService', () => {
  describe('methodName', () => {
    it('should handle valid input', () => {
      const service = new YourService();
      const result = service.methodName('valid input');
      expect(result).toBe('expected output');
    });

    it('should throw error on invalid input', () => {
      const service = new YourService();
      expect(() => service.methodName('')).toThrow();
    });
  });
});

Submitting Changes

Pull Request Process

  1. Update your fork

    git remote add upstream https://github.com/original/utcp-docs-mcp-server.git
git fetch upstream
git rebase upstream/main

  2. Make your changes

    git checkout -b feature/your-feature
# Make changes
git add .
git commit -m "feat: your feature description"

  3. Run tests

    npm test
npm run build

  4. Push changes

    git push origin feature/your-feature

  5. Create Pull Request

    • Go to GitHub
    • Click "New Pull Request"
    • Fill in the template
    • Link related issues

Pull Request Template

## Description
Brief description of changes

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

## Testing
- [ ] Tests pass locally
- [ ] Added new tests
- [ ] Updated existing tests

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No new warnings
- [ ] Tests added/updated
- [ ] Changelog updated

Style Guidelines

TypeScript

// Use explicit types
function processData(input: string): ProcessedData {
  // ...
}

// Use interfaces for objects
interface ToolConfig {
  name: string;
  protocol: Protocol;
}

// Use enums for constants
enum Protocol {
  HTTP = 'http',
  CLI = 'cli',
  MCP = 'mcp',
}

// Document complex functions
/**
 * Validates a UTCP manual against the specification
 * @param manual - The UTCP manual to validate
 * @returns Validation result with errors
 */
function validate(manual: UtcpManual): ValidationResult {
  // ...
}

Code Organization

  • One class per file
  • Group related functions
  • Use meaningful names
  • Keep functions small (< 50 lines)
  • Extract complex logic

Documentation

// Good: Clear, explains why
// Convert {param} to ${param} for UTCP variable syntax
const utcpPath = path.replace(/\{([^}]+)\}/g, '${$1}');

// Bad: States obvious
// Replace text
const utcpPath = path.replace(/\{([^}]+)\}/g, '${$1}');

Error Handling

// Good: Specific errors with context
if (!manual.utcp_version) {
  throw new Error('Missing required field: utcp_version');
}

// Bad: Generic errors
if (!manual.utcp_version) {
  throw new Error('Invalid manual');
}

Areas for Contribution

High Priority

  • Semantic search with embeddings
  • More protocol support (WebSocket, gRPC)
  • GraphQL to UTCP converter
  • Enhanced validation rules
  • Performance optimizations

Medium Priority

  • Web UI for manual builder
  • VS Code extension
  • More example manuals
  • Integration tests
  • Documentation improvements

Good First Issues

Look for issues labeled good-first-issue on GitHub. These are:

  • Well-documented
  • Relatively simple
  • Good for learning the codebase

Questions?

Recognition

Contributors will be:

  • Listed in CONTRIBUTORS.md
  • Mentioned in release notes
  • Acknowledged in README

Thank you for contributing! 🙏