Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
408 lines (298 loc) · 10.5 KB

CONTRIBUTING.md

File metadata and controls

408 lines (298 loc) · 10.5 KB

Contributing to MCP Memory Service

Thank you for your interest in contributing to MCP Memory Service! 🎉

This project provides semantic memory and persistent storage for AI assistants through the Model Context Protocol. We welcome contributions of all kinds - from bug fixes and features to documentation and testing.

Table of Contents

Code of Conduct

We are committed to providing a welcoming and inclusive environment for all contributors. Please:

  • Be respectful and considerate in all interactions
  • Welcome newcomers and help them get started
  • Focus on constructive criticism and collaborative problem-solving
  • Respect differing viewpoints and experiences
  • Avoid harassment, discrimination, or inappropriate behavior

Ways to Contribute

🐛 Bug Reports

Help us identify and fix issues by reporting bugs with detailed information.

✨ Feature Requests

Suggest new features or improvements to existing functionality.

📝 Documentation

Improve README, Wiki pages, code comments, or API documentation.

🧪 Testing

Write tests, improve test coverage, or help with manual testing.

💻 Code Contributions

Fix bugs, implement features, or improve performance.

🌍 Translations

Help make the project accessible to more users (future goal).

💬 Community Support

Answer questions in Issues, Discussions, or help other users.

Getting Started

Prerequisites

  • Python 3.10 or higher
  • Git
  • Platform-specific requirements:
    • macOS: Homebrew Python recommended for SQLite extension support
    • Windows: Visual Studio Build Tools for some dependencies
    • Linux: Build essentials package

Setting Up Your Development Environment

  1. Fork the repository on GitHub

  2. Clone your fork:

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

  3. Install dependencies:

    python install.py

    This will automatically detect your platform and install appropriate dependencies.

  4. Verify installation:

    python scripts/verify_environment.py

  5. Run the service:

    uv run memory server

  6. Test with MCP Inspector (optional):

    npx @modelcontextprotocol/inspector uv run memory server

Alternative: Docker Setup

For a containerized environment:

docker-compose up -d  # For MCP mode
docker-compose -f docker-compose.http.yml up -d  # For HTTP API mode

Development Process

1. Create a Feature Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

Use descriptive branch names:

  • feature/ for new features
  • fix/ for bug fixes
  • docs/ for documentation
  • test/ for test improvements
  • refactor/ for code refactoring

2. Make Your Changes

  • Write clean, readable code
  • Follow the coding standards (see below)
  • Add/update tests as needed
  • Update documentation if applicable
  • Keep commits focused and atomic

3. Test Your Changes

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_server.py

# Run with coverage
pytest --cov=mcp_memory_service tests/

4. Commit Your Changes

Use semantic commit messages:

git commit -m "feat: add memory export functionality"
git commit -m "fix: resolve timezone handling in memory search"
git commit -m "docs: update installation guide for Windows"
git commit -m "test: add coverage for storage backends"

Format: <type>: <description>

Types:

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

5. Push to Your Fork

git push origin your-branch-name

6. Create a Pull Request

Open a PR from your fork to the main repository with:

  • Clear title describing the change
  • Description of what and why
  • Reference to any related issues
  • Screenshots/examples if applicable

Coding Standards

Python Style Guide

  • Follow PEP 8 with these modifications:
    • Line length: 88 characters (Black formatter default)
    • Use double quotes for strings
  • Use type hints for all function signatures
  • Write descriptive variable and function names
  • Add docstrings to all public functions/classes (Google style)

Code Organization

# Import order
import standard_library
import third_party_libraries
from mcp_memory_service import local_modules

# Type hints
from typing import Optional, List, Dict, Any

# Async functions
async def process_memory(content: str) -> Dict[str, Any]:
    """Process and store memory content.

    Args:
        content: The memory content to process

    Returns:
        Dictionary containing memory metadata
    """
    # Implementation

Error Handling

  • Use specific exception types
  • Provide helpful error messages
  • Log errors appropriately
  • Never silently fail
try:
    result = await storage.store(memory)
except StorageError as e:
    logger.error(f"Failed to store memory: {e}")
    raise MemoryServiceError(f"Storage operation failed: {e}") from e

Testing Requirements

Writing Tests

  • Place tests in tests/ directory
  • Name test files with test_ prefix
  • Use descriptive test names
  • Include both positive and negative test cases
  • Mock external dependencies

Example test:

import pytest
from mcp_memory_service.storage import SqliteVecStorage

@pytest.mark.asyncio
async def test_store_memory_success():
    """Test successful memory storage."""
    storage = SqliteVecStorage(":memory:")
    result = await storage.store("test content", tags=["test"])
    assert result is not None
    assert "hash" in result

Test Coverage

  • Aim for >80% code coverage
  • Focus on critical paths and edge cases
  • Test error handling scenarios
  • Include integration tests where appropriate

Documentation

Code Documentation

  • Add docstrings to all public APIs
  • Include type hints
  • Provide usage examples in docstrings
  • Keep comments concise and relevant

Project Documentation

When adding features or making significant changes:

  1. Update README.md if needed
  2. Add/update Wiki pages for detailed guides
  3. Update CHANGELOG.md following Keep a Changelog format
  4. Update AGENTS.md or CLAUDE.md if development workflow changes

Advanced Workflow Automation:

API Documentation

  • Document new MCP tools in docs/api/tools.md
  • Include parameter descriptions and examples
  • Note any breaking changes

Submitting Changes

Pull Request Guidelines

  1. PR Title: Use semantic format (e.g., "feat: add batch memory operations")

  2. PR Description Template:

    ## Description
Brief description of changes

## Motivation
Why these changes are needed

## Changes
- List of specific changes
- Breaking changes (if any)

## Testing
- How you tested the changes
- Test coverage added

## Screenshots
(if applicable)

## Related Issues
Fixes #123

  3. PR Checklist:

    • Tests pass locally
    • Code follows style guidelines
    • Documentation updated
    • CHANGELOG.md updated
    • No sensitive data exposed

Review Process

  • PRs require at least one review
  • Address review feedback promptly
  • Keep discussions focused and constructive
  • Be patient - reviews may take a few days

Reporting Issues

Bug Reports

When reporting bugs, include:

  1. Environment:

    • OS and version
    • Python version
    • MCP Memory Service version
    • Installation method (pip, Docker, source)

  2. Steps to Reproduce:

    • Minimal code example
    • Exact commands run
    • Configuration used

  3. Expected vs Actual Behavior:

    • What you expected to happen
    • What actually happened
    • Error messages/stack traces

  4. Additional Context:

    • Screenshots if applicable
    • Relevant log output
    • Related issues

Feature Requests

For feature requests, describe:

  • The problem you're trying to solve
  • Your proposed solution
  • Alternative approaches considered
  • Potential impact on existing functionality

Community & Support

Getting Help

  • Documentation: Check the Wiki first
  • Issues: Search existing issues before creating new ones
  • Discussions: Use GitHub Discussions for questions
  • Response Time: Maintainers typically respond within 2-3 days

Communication Channels

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: General questions and community discussion
  • Pull Requests: Code contributions and reviews

For AI Agents

If you're an AI coding assistant, also check:

Recognition

We value all contributions! Contributors are:

  • Listed in release notes for their contributions
  • Mentioned in CHANGELOG.md entries
  • Credited in commit messages when providing fixes/solutions
  • Welcome to add themselves to a CONTRIBUTORS file (future)

Types of Recognition

  • 🐛 Bug reporters who provide detailed, reproducible issues
  • 💻 Code contributors who submit PRs
  • 📝 Documentation improvers
  • 🧪 Test writers and reviewers
  • 💬 Community helpers who support other users
  • 🎨 UI/UX improvers (for dashboard contributions)

Thank you for contributing to MCP Memory Service! Your efforts help make AI assistants more capable and useful for everyone. 🚀

If you have questions not covered here, please open a Discussion or check our Wiki.