Skip to content

Latest commit

 

History

History
185 lines (123 loc) · 4.73 KB

CONTRIBUTING.md

File metadata and controls

185 lines (123 loc) · 4.73 KB

Contributing to MongoDB MCP Server

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

Project Overview

This project implements a Model Context Protocol (MCP) server for MongoDB and MongoDB Atlas, enabling AI assistants to interact with MongoDB Atlas resources through natural language.

Development Setup

Prerequisites

  • Node.js (v20 or later)
  • npm

Getting Started

  1. Clone the repository:

    git clone https://github.com/mongodb-labs/mongodb-mcp-server.git
cd mongodb-mcp-server

  2. Install dependencies:

    npm install

  3. Add the mcp server to your IDE of choice (see the README for detailed client integration instructions)

    {
  "mcpServers": {
    "MongoDB": {
      "command": "/path/to/mongodb-mcp-server/dist/index.js"
    }
  }
}

Code Contribution Workflow

  1. Create a new branch for your feature or bugfix:

    git checkout -b feature/your-feature-name

  2. Make your changes, following the code style of the project

  3. Run the inspector and double check your changes:

    npm run inspect

  4. Commit your changes with a descriptive commit message

Adding tests to the MCP Server

When adding new features or fixing bugs, please ensure that you also add tests to cover your changes. This helps maintain the quality and reliability of the codebase.

Running Tests

The tests can be found in the tests directory.

You can run tests using the following npm scripts:

  • npm test: Run all tests

To run a specific test file or directory:

npm test -- path/to/test/file.test.ts
npm test -- path/to/directory

Troubleshooting

Restart Server

  • Run npm run build to re-build the server if you made changes to the code
  • Press Cmd + Shift + P and type List MCP Servers
  • Select the MCP server you want to restart
  • Select the option to restart the server

View Logs

To see MCP logs, check https://code.visualstudio.com/docs/copilot/chat/mcp-servers.

  • Press Cmd + Shift + P and type List MCP Servers
  • Select the MCP server you want to see logs for
  • Select the option to view logs in the output panel

Debugging

For debugging, we use the MCP inspector tool. From the root of this repository, run:

npm run inspect

This is equivalent to:

npx @modelcontextprotocol/inspector -- node dist/index.js

Pull Request Guidelines

  1. Update documentation if necessary
  2. Ensure your PR includes only relevant changes
  3. Link any related issues in your PR description
  4. Keep PRs focused on a single topic

Code Standards

  • Use TypeScript for all new code
  • Follow the existing code style (indentation, naming conventions, etc.)
  • Comment your code when necessary, especially for complex logic
  • Use meaningful variable and function names

Reporting Issues

When reporting issues, please include:

  • A clear description of the problem
  • Steps to reproduce
  • Expected vs. actual behavior
  • Version information
  • Environment details

Adding New Tools

When adding new tools to the MCP server:

  1. Follow the existing pattern in server.ts
  2. Define clear parameter schemas using Zod
  3. Implement thorough error handling
  4. Add proper documentation for the tool
  5. Include examples of how to use the tool

Release Process

Our release process is automated using GitHub Actions workflows:

Version Bumping

  1. To create a new version, go to the GitHub repository Actions tab
  2. Select the "Version Bump" workflow
  3. Click "Run workflow" and choose one of the following options:
    • patch (e.g., 1.0.0 → 1.0.1) for backward-compatible bug fixes
    • minor (e.g., 1.0.0 → 1.1.0) for backward-compatible new features
    • major (e.g., 1.0.0 → 2.0.0) for breaking changes
    • A specific version number (e.g., 1.2.3)
  4. This creates a pull request with the version change
  5. Once approved and merged, the version is updated

Automatic Publishing

When a version bump is merged to the main branch:

  1. The "Publish" workflow automatically runs
  2. It checks if the version already exists as a git tag
  3. If the version is new, it:
    • Builds the package
    • Publishes to NPM
    • Creates a git tag for the version
    • Creates a GitHub release with auto-generated release notes

Code Quality

All pull requests automatically run through the "Code Health" workflow, which:

  • Verifies code style and formatting
  • Runs tests on multiple platforms (Ubuntu, macOS, Windows)

License

By contributing to this project, you agree that your contributions will be licensed under the project's license.

Questions?

If you have any questions or need help, please open an issue or reach out to the maintainers.