Contributing

Thank you for your interest in contributing to the vCon MCP Server! This guide will help you get started.

Code of Conduct

Our Pledge

We pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity, experience level, nationality, personal appearance, race, religion, or sexual identity.

Our Standards

Positive behavior includes:

Using welcoming and inclusive language
Being respectful of differing viewpoints
Accepting constructive criticism gracefully
Focusing on what's best for the community
Showing empathy towards others

Unacceptable behavior includes:

Harassment, trolling, or derogatory comments
Publishing others' private information
Personal or political attacks
Other unprofessional conduct

Enforcement

Report violations to [project maintainers]. All complaints will be reviewed and investigated promptly and fairly.

Getting Started

Prerequisites

Before contributing, ensure you have:

Node.js 18+ installed
Git installed and configured
Supabase account for database testing
GitHub account
Read the Architecture documentation

Initial Setup

Fork the repository
```
# On GitHub, click "Fork" button
```

Clone your fork

git clone https://github.com/YOUR_USERNAME/vcon-mcp.git
cd vcon-mcp

Add upstream remote

git remote add upstream https://github.com/vcon-dev/vcon-mcp.git

Install dependencies
```
npm install
```

Set up environment

cp .env.example .env
# Edit .env with your Supabase credentials

Run tests
```
npm test
```
Build the project
```
npm run build
```

Development Environment

We recommend:

VS Code with these extensions:
- ESLint
- Prettier
- TypeScript and JavaScript Language Features
- GitLens
Database GUI: Supabase Dashboard or pgAdmin

Development Workflow

Creating a Feature Branch

# Update your main branch
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/issue-number-description

Branch Naming Convention:

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation changes
refactor/ - Code refactoring
test/ - Test additions/changes
chore/ - Maintenance tasks

Making Changes

Make your changes
- Follow Coding Standards
- Add tests for new functionality
- Update documentation

Test your changes

# Run all tests
npm test

# Run specific test
npm test -- search.test.ts

# Run with coverage
npm run test:coverage

Lint and format

# Check linting
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

Build and verify

npm run build
npm run dev  # Test locally

Committing Changes

We use Conventional Commits:

git add .
git commit -m "type(scope): description"

Commit Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting)
refactor: Code refactoring
test: Test additions/changes
chore: Maintenance tasks
perf: Performance improvements

Examples:

git commit -m "feat(search): add hybrid search capability"
git commit -m "fix(validation): correct analysis vendor requirement"
git commit -m "docs(api): update tools reference"
git commit -m "test(crud): add tests for delete operation"

Keeping Your Branch Updated

# Fetch upstream changes
git fetch upstream

# Rebase on upstream main
git rebase upstream/main

# Or merge if preferred
git merge upstream/main

# Force push if you rebased (after confirming with team)
git push origin feature/your-feature-name --force-with-lease

Pull Request Process

Before Submitting

Ensure your PR:

Creating a Pull Request

Push your branch

git push origin feature/your-feature-name

Open PR on GitHub
- Go to the repository
- Click "New Pull Request"
- Select your branch
- Fill in the PR template

PR Template

## Description
Brief description of changes

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

## Testing
- [ ] Existing tests pass
- [ ] New tests added
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings generated

## Related Issues
Closes #123

Review Process

Automated Checks
- CI/CD runs tests
- Linting checks
- Build verification
Code Review
- At least one maintainer approval required
- Address all comments
- Make requested changes
Final Checks
- All conversations resolved
- CI passes
- Up to date with main
Merge
- Maintainer will merge your PR
- Branch will be deleted

After Merge

Update your local repo

git checkout main
git pull upstream main

Delete feature branch

git branch -d feature/your-feature-name
git push origin --delete feature/your-feature-name

Coding Standards

See Code Style Guide for detailed standards.

Quick Reference

TypeScript:

// ✅ Good
export interface VCon {
  vcon: string;
  uuid: string;
  parties: Party[];
}

// ❌ Bad
export interface VCon {
  vcon: string;
  uuid: string;
  parties: any;  // Don't use 'any'
}

Function Documentation:

/**
 * Create a new vCon in the database.
 * 
 * @param vcon - The vCon object to create
 * @returns Promise resolving to UUID of created vCon
 * @throws {ValidationError} If vCon fails validation
 * @throws {DatabaseError} If database operation fails
 */
async function createVCon(vcon: VCon): Promise<string> {
  // Implementation
}

Error Handling:

// ✅ Good
try {
  const result = await queries.createVCon(vcon);
  return { success: true, uuid: result.uuid };
} catch (error) {
  logger.error('Failed to create vCon', { error, vcon });
  return {
    success: false,
    error: error instanceof Error ? error.message : 'Unknown error'
  };
}

Testing Requirements

Test Coverage

All contributions must maintain test coverage:

Minimum: 80% overall coverage
New code: 90% coverage required
Critical paths: 100% coverage

Writing Tests

import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { VConQueries } from '../src/db/queries';
import { createTestVCon } from './fixtures';

describe('VConQueries', () => {
  let queries: VConQueries;
  
  beforeAll(async () => {
    // Setup
    queries = new VConQueries(supabase);
  });
  
  afterAll(async () => {
    // Cleanup
  });
  
  it('should create a vCon', async () => {
    const vcon = createTestVCon();
    const result = await queries.createVCon(vcon);
    
    expect(result.uuid).toBeDefined();
    expect(result.uuid).toMatch(/^[0-9a-f-]{36}$/);
  });
  
  it('should reject invalid vCon', async () => {
    const invalidVCon = { vcon: '0.3.0' }; // Missing required fields
    
    await expect(queries.createVCon(invalidVCon as any))
      .rejects
      .toThrow('Validation failed');
  });
});

Test Types

Unit Tests - Test individual functions
Integration Tests - Test component interactions
Compliance Tests - Test IETF spec compliance
E2E Tests - Test full workflows

Running Tests

# All tests
npm test

# Watch mode
npm test -- --watch

# Specific file
npm test -- crud.test.ts

# Coverage report
npm run test:coverage

# Compliance tests only
npm run test:compliance

Documentation

Documentation Requirements

All contributions must include:

Code Comments
- JSDoc for public APIs
- Inline comments for complex logic
- TODO/FIXME with issue numbers
API Documentation
- Update docs/api/ if changing tools/resources
- Include examples
- Document parameters and return values
User Documentation
- Update docs/guide/ if affecting user features
- Add examples and use cases
- Include troubleshooting tips
README Updates
- Update if changing setup process
- Keep examples current
- Update feature list

Documentation Style

See Documentation Standards for details.

Example:

/**
 * Search vCons using semantic similarity.
 * 
 * Uses AI embeddings to find conversations with similar meaning,
 * not just matching keywords.
 * 
 * @example
 * ```typescript
 * const results = await searchVConsSemantic(
 *   "frustrated customers",
 *   { threshold: 0.75, limit: 20 }
 * );
 * ```
 * 
 * @param query - Natural language search query
 * @param options - Search options
 * @param options.threshold - Minimum similarity (0-1), default 0.7
 * @param options.limit - Maximum results, default 20
 * @returns Promise resolving to search results
 * @throws {EmbeddingError} If embedding generation fails
 */
async function searchVConsSemantic(
  query: string,
  options?: SemanticSearchOptions
): Promise<SemanticResult[]> {
  // Implementation
}

Release Process

Versioning

We follow Semantic Versioning:

Major (X.0.0) - Breaking changes
Minor (0.X.0) - New features (backward compatible)
Patch (0.0.X) - Bug fixes

Release Checklist

For maintainers:

Update Version
```
npm version major|minor|patch
```
Update CHANGELOG
- Document all changes
- Group by type (Added, Changed, Fixed, Removed)
- Include issue/PR numbers
Create Release Branch
```
git checkout -b release/v1.2.0
```
Final Testing
- Run full test suite
- Test in production-like environment
- Verify documentation
Create Release PR
- Review all changes
- Get approval from maintainers

Merge and Tag

git checkout main
git merge release/v1.2.0
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags

Publish
```
npm publish
```
Create GitHub Release
- Copy CHANGELOG entry
- Attach built assets
- Publish release notes

Getting Help

Where to Ask

GitHub Issues - Bug reports, feature requests
GitHub Discussions - Questions, ideas, general discussion
Discord - Real-time chat with community
Email - Private matters to [maintainers email]

Issue Templates

Bug Report:

**Describe the bug**
Clear description of the bug

**To Reproduce**
Steps to reproduce

**Expected behavior**
What should happen

**Actual behavior**
What actually happens

**Environment**
- OS: [e.g., macOS 13.0]
- Node.js: [e.g., 18.12.0]
- vCon MCP Server: [e.g., 1.0.0]

Feature Request:

**Problem Statement**
What problem does this solve?

**Proposed Solution**
How would you solve it?

**Alternatives Considered**
Other approaches you considered

**Additional Context**
Any other relevant information

Recognition

Contributors are recognized in:

CONTRIBUTORS.md - All contributors listed
Release Notes - Major contributions highlighted
GitHub Profile - Contribution graph

We appreciate all contributions, big and small!

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Questions?

If you have questions about contributing:

Check existing documentation
Search existing issues/discussions
Ask in GitHub Discussions
Contact maintainers

Thank you for contributing to vCon MCP Server! 🎉

PreviousEmbeddings NextCode Style

Last updated 4 days ago

Table of Contents