Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
186 lines (124 loc) · 6.36 KB

CONTRIBUTING.md

File metadata and controls

186 lines (124 loc) · 6.36 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)
  • pnpm

Getting Started

  1. Clone the repository:

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

  2. Install dependencies:

    pnpm 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/esm/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:

    pnpm run inspect

  4. Commit your changes using conventional commits format.

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 pnpm scripts:

  • pnpm test: Run all tests

To run a specific test file or directory:

pnpm test path/to/test/file.test.ts
pnpm test path/to/directory

Accuracy Tests and colima

If you use colima to run Docker on Mac, you will need to apply additional configuration to ensure the accuracy tests run correctly.

Troubleshooting

Restart Server

  • Run pnpm 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:

pnpm run inspect

This is equivalent to:

npx @modelcontextprotocol/inspector -- node dist/esm/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

To release a new version of the MCP server, follow these steps:

  1. Ensure there is a Jira Release ticket in the MCP project for the new release and move it to In Progress.

  2. Verify that the Jira tickets you expect to be released are correctly mapped to the expected Release version. Add any additional required documentation to the release ticket.

  3. To create a new version, go to the GitHub repository Actions tab and run the "Prepare Release" workflow with 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)
    • Pre-release versions: To create a pre-release, enter the version suffixed by -prerelease.{n} where n is the pre-release number (e.g., 1.1.0-prerelease.1, 1.1.0-prerelease.2). Pre-releases are release candidates that provide early access to new features before they are promoted to stable.

    Note: Stable releases are published under the latest tag on NPM and are intended for production use. Pre-release versions are published under the prerelease tag and serve as release candidates for early access and feedback before being released as stable versions.

  4. This creates a pull request with the version change.

  5. Merge this pull request if all looks correct. This will trigger the "Publish" workflow which will publish it to NPM, Docker and the MCP Registry.

  6. Verify that the new version is published correctly by checking:

  7. Close the Jira ticket for the release.

  8. Go to the Releases section the and rename the vNext to the new version number and mark it as Released. Create a new vNext for the next release.

  9. Post an update in the #mongodb-mcp Slack channel.

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.