Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
489 lines (363 loc) · 10.1 KB

CONTRIBUTING.md

File metadata and controls

489 lines (363 loc) · 10.1 KB
Raw

Contributing to MCP Memory Keeper

Thank you for your interest in contributing to MCP Memory Keeper! This guide will help you get started with contributing to the project.

Table of Contents

Code of Conduct

By participating in this project, you agree to abide by our code of conduct:

  • Be respectful: Treat everyone with respect. No harassment, discrimination, or inappropriate behavior.
  • Be collaborative: Work together to solve problems and improve the project.
  • Be constructive: Provide helpful feedback and accept criticism gracefully.
  • Be inclusive: Welcome contributors of all backgrounds and experience levels.

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR-USERNAME/mcp-memory-keeper.git
cd mcp-memory-keeper
  3. Add upstream remote: 
    git remote add upstream https://github.com/mkreyman/mcp-memory-keeper.git

Development Setup

Prerequisites

  • Node.js 18+ and npm
  • Git
  • TypeScript knowledge
  • Familiarity with MCP (Model Context Protocol)

Installation

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run in development mode
npm run dev

Project Structure

mcp-memory-keeper/
├── src/
│   ├── index.ts           # Main MCP server
│   ├── utils/             # Utility modules
│   │   ├── database.ts    # Database operations
│   │   ├── validation.ts  # Input validation
│   │   ├── git.ts         # Git integration
│   │   ├── knowledge-graph.ts
│   │   ├── vector-store.ts
│   │   └── agents.ts
│   └── __tests__/         # Test files
├── dist/                  # Built files
├── docs/                  # Documentation
└── examples/              # Example usage

How to Contribute

Reporting Issues

  1. Search existing issues to avoid duplicates
  2. Create a new issue with:
    • Clear, descriptive title
    • Steps to reproduce (for bugs)
    • Expected vs actual behavior
    • System information (OS, Node version)
    • Error messages or logs

Issue Template:

## Description

Brief description of the issue

## Steps to Reproduce

1. Step one
2. Step two
3. ...

## Expected Behavior

What should happen

## Actual Behavior

What actually happens

## Environment

- OS: [e.g., macOS 14.0]
- Node: [e.g., 18.17.0]
- MCP Memory Keeper: [e.g., 0.8.0]

Suggesting Features

  1. Check existing issues and discussions
  2. Open a feature request with:
    • Use case description
    • Proposed solution
    • Alternative approaches
    • Implementation considerations

Contributing Code

1. Choose an Issue

  • Look for issues labeled good first issue or help wanted
  • Comment on the issue to claim it
  • Ask questions if requirements are unclear

2. Create a Branch

# Update your fork
git checkout main
git pull upstream main
git push origin main

# Create feature branch
git checkout -b feature/your-feature-name
# Or for bugs:
git checkout -b fix/issue-description

3. Make Changes

  • Write clean, documented code
  • Follow existing patterns
  • Add tests for new functionality
  • Update documentation as needed

4. Commit Guidelines

Follow conventional commits format:

# Format: <type>(<scope>): <subject>

# Examples:
git commit -m "feat(search): add semantic search capability"
git commit -m "fix(database): resolve connection pool leak"
git commit -m "docs(api): update context_save examples"
git commit -m "test(agents): add multi-agent coordination tests"
git commit -m "refactor(validation): simplify input validation logic"

Types:

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

Pull Request Process

1. Before Submitting

# Run all checks
npm run lint
npm run type-check
npm test
npm run build

# Ensure no conflicts
git pull upstream main
git rebase upstream/main

2. PR Guidelines

  • Title: Use conventional commit format
  • Description:
    • Reference related issues (#123)
    • Describe what changed and why
    • Include screenshots for UI changes
    • List breaking changes
  • Size: Keep PRs focused and small
  • Tests: Include tests for new code

PR Template:

## Description

Brief description of changes

## Related Issues

Closes #123

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing

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

## Checklist

- [ ] Code follows project style
- [ ] Self-reviewed code
- [ ] Updated documentation
- [ ] No console.logs left

3. Review Process

  • Maintainers will review within 48-72 hours
  • Address feedback constructively
  • Push additional commits (don't force-push during review)
  • Once approved, maintainer will merge

Coding Standards

TypeScript Guidelines

// Use explicit types
function processContext(items: ContextItem[]): ProcessedResult {
  // Implementation
}

// Avoid any type
// Bad: let data: any = {};
// Good: let data: Record<string, unknown> = {};

// Use interfaces for objects
interface ContextItem {
  id: string;
  key: string;
  value: string;
  category?: ContextCategory;
  priority?: Priority;
}

// Use enums for constants
enum Priority {
  Critical = 'critical',
  High = 'high',
  Normal = 'normal',
  Low = 'low',
}

// Document complex functions
/**
 * Analyzes context items to extract entities and relationships
 * @param items - Array of context items to analyze
 * @param options - Analysis options
 * @returns Extracted entities and relationships
 */
function analyzeContext(items: ContextItem[], options?: AnalysisOptions): AnalysisResult {
  // Implementation
}

Error Handling

// Use specific error types
class ValidationError extends Error {
  constructor(
    message: string,
    public field?: string
  ) {
    super(message);
    this.name = 'ValidationError';
  }
}

// Handle errors gracefully
try {
  const result = await riskyOperation();
  return result;
} catch (error) {
  if (error instanceof ValidationError) {
    // Handle validation error
    throw new McpError(ErrorCode.INVALID_PARAMS, `Validation failed: ${error.message}`);
  }
  // Log unexpected errors
  console.error('Unexpected error:', error);
  throw new McpError(ErrorCode.INTERNAL_ERROR, 'An unexpected error occurred');
}

Code Style

  • Use 2 spaces for indentation
  • Use single quotes for strings
  • Add trailing commas in multiline objects/arrays
  • Maximum line length: 100 characters
  • Use async/await over promises
  • Prefer const over let

Testing Guidelines

Test Structure

describe('ContextStorage', () => {
  let storage: ContextStorage;

  beforeEach(() => {
    storage = new ContextStorage();
  });

  afterEach(() => {
    storage.close();
  });

  describe('save', () => {
    it('should save context with all fields', async () => {
      const item = {
        key: 'test_key',
        value: 'test value',
        category: 'task' as const,
        priority: 'high' as const,
      };

      const result = await storage.save(item);

      expect(result.id).toBeDefined();
      expect(result.key).toBe(item.key);
    });

    it('should throw on duplicate key', async () => {
      const item = { key: 'duplicate', value: 'value' };

      await storage.save(item);

      await expect(storage.save(item)).rejects.toThrow('Duplicate key');
    });
  });
});

Test Coverage

  • Aim for 90%+ coverage
  • Test edge cases and error conditions
  • Include integration tests
  • Test with real-world scenarios

Running Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test file
npm test -- storage.test.ts

# Run in watch mode
npm run test:watch

Documentation

Code Documentation

  • Document all public APIs
  • Include JSDoc comments for functions
  • Add inline comments for complex logic
  • Keep README.md up to date

Examples

When adding new features, include:

  1. API documentation in API.md
  2. Usage examples in EXAMPLES.md
  3. Common patterns in RECIPES.md
  4. Troubleshooting tips if applicable

Commit Messages

Good commit messages help maintain project history:

# Good examples
feat(search): implement semantic search with vector embeddings
fix(database): prevent connection leak in transaction handler
docs(api): add examples for context_delegate tool
test(integration): add session branching test cases

# Bad examples
fix: fixed stuff
update code
WIP

Community

Getting Help

  • Issues: For bugs and feature requests
  • Discussions: For questions and ideas
  • Discord: Join our Discord (if available)

Ways to Contribute

Not just code! You can help by:

  • Improving documentation
  • Creating tutorials or blog posts
  • Helping others in discussions
  • Testing pre-releases
  • Translating documentation
  • Sharing the project

Recognition

Contributors are recognized in:

  • GitHub contributors page
  • Release notes
  • Annual contributor spotlight

Release Process

  1. Version Bumping: Follow semantic versioning

    • MAJOR: Breaking changes
    • MINOR: New features
    • PATCH: Bug fixes

  2. Release Notes: Include

    • New features
    • Bug fixes
    • Breaking changes
    • Contributors

  3. Testing: All tests must pass

    • Unit tests
    • Integration tests
    • Manual smoke tests

Questions?

If you have questions about contributing:

  1. Check existing documentation
  2. Search closed issues
  3. Ask in discussions
  4. Contact maintainers

Thank you for contributing to MCP Memory Keeper! 🎉