diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml index 45fb0726..c424141c 100644 --- a/.github/workflows/publish.yaml +++ b/.github/workflows/publish.yaml @@ -2,8 +2,10 @@ name: Publish on: push: - tags: - - v* + branches: + - main +permissions: + contents: write jobs: publish: runs-on: ubuntu-latest @@ -11,19 +13,53 @@ jobs: steps: - uses: GitHubSecurityLab/actions-permissions/monitor@v1 - uses: actions/checkout@v4 + with: + fetch-depth: 0 - uses: actions/setup-node@v4 with: node-version-file: package.json registry-url: "https://registry.npmjs.org" cache: "npm" + - name: Get version + id: get-version + shell: bash + run: | + set +e + + VERSION=v$(jq -r '.version' < package.json) + echo "VERSION=${VERSION}" >> "$GITHUB_OUTPUT" + - name: Check if version already exists + id: check-version + shell: bash + run: | + set +e + + git rev-parse "${{ steps.get-version.outputs.VERSION }}" >/dev/null 2>&1 + if [[ $? -eq 0 ]]; then + echo "VERSION_EXISTS=true" >> "$GITHUB_OUTPUT" + else + echo "VERSION_EXISTS=false" >> "$GITHUB_OUTPUT" + fi - name: Build package + if: steps.check-version.outputs.VERSION_EXISTS == 'false' run: | npm ci npm run build - name: Publish to NPM + if: steps.check-version.outputs.VERSION_EXISTS == 'false' run: npm publish env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} - - name: Publish Github release + - name: Publish git tag + if: steps.check-version.outputs.VERSION_EXISTS == 'false' + run: | + git config --global user.name 'github-actions[bot]' + git config --global user.email '41898282+github-actions[bot]@users.noreply.github.com' + git tag ${{ steps.get-version.outputs.VERSION }} + git push origin --tags + - name: Publish git release + if: steps.check-version.outputs.VERSION_EXISTS == 'false' + env: + GH_TOKEN: ${{ github.token }} run: | - gh release create ${{ github.ref }} --title "${{ github.ref }}" --notes "Release ${{ github.ref }}" --generate-notes + gh release create ${{ github.env.VERSION }} --title "${{ github.env.VERSION }}" --generate-notes diff --git a/.github/workflows/version_bump.yaml b/.github/workflows/version_bump.yaml new file mode 100644 index 00000000..f0f4894e --- /dev/null +++ b/.github/workflows/version_bump.yaml @@ -0,0 +1,37 @@ +--- +name: Version Bump +on: + workflow_dispatch: + inputs: + version: + description: "Version to bump to" + required: true + default: "patch" +jobs: + bump-version: + runs-on: ubuntu-latest + steps: + - uses: GitHubSecurityLab/actions-permissions/monitor@v1 + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version-file: package.json + registry-url: "https://registry.npmjs.org" + cache: "npm" + - name: Build package + run: | + npm ci + - name: Bump version + run: | + npm version ${{ github.event.inputs.version }} --no-git-tag-version + - name: Create PR + uses: peter-evans/create-pull-request@v4 + with: + title: "Bump version to ${{ github.event.inputs.version }}" + body: "Bump version to ${{ github.event.inputs.version }}" + base: main + branch: ci/version-bump-${{ github.event.inputs.version }} + commit-message: "Bump version to ${{ github.event.inputs.version }}" + author: "github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>" + committer: "github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>" + labels: version-bump diff --git a/.npmrc b/.npmrc new file mode 100644 index 00000000..32fd3a78 --- /dev/null +++ b/.npmrc @@ -0,0 +1 @@ +git-tag-version=false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 42b7e068..9eb3620b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -141,6 +141,41 @@ When adding new tools to the MCP server: 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. diff --git a/README.md b/README.md index 3a2d93d4..b21a4759 100644 --- a/README.md +++ b/README.md @@ -10,38 +10,88 @@ A Model Context Protocol server for interacting with MongoDB Atlas. This project - [🚀 Getting Started](#getting-started) - [Prerequisites](#prerequisites) - [Installation](#installation) - - [Running the MCP Server](#running-the-mcp-server) + - [VSCode](#vscode) + - [Claude Desktop](#claude) - [🛠️ Supported Tools](#supported-tools) - [Tool List](#tool-list) +- [⚙️ Configuration](#configuration) + - [Configuration Options](#configuration-options) + - [Atlas API Access](#atlas-api-access) + - [Configuration Methods](#configuration-methods) - [👩‍💻 Client Integration](#client-integration) - [VSCode](#vscode) - [Claude](#claude) - [🤝 Contributing](#contributing) -## 🚀 Getting Started - -### Prerequisites +## Prerequisites - Node.js (v20 or later) - MongoDB Atlas account -### Installation +## Installation -```shell -# Clone the repository -git clone https://github.com/mongodb-labs/mongodb-mcp-server.git -cd mongodb-mcp-server +### VSCode + +Prerequisites: + +- Node.js v20.x + +Step 1: Add the mcp server to VSCode configuration + +- Press `Cmd + Shift + P` and type `MCP: Add MCP Server` and select it. +- Select command (Stdio). +- Input command `npx -y @mongodb-js/mongodb-mcp-server`. +- Choose between user / workspace +- Add arguments to the file + +Note: the file should look like: -# Install dependencies -npm install +``` +{ + "servers": { + "MongoDB": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@mongodb-js/mongodb-mcp-server" + ] + } + } +} ``` -### Running the MCP Server +Notes: You can configure the server with atlas access, make sure to follow configuration section for more details. -```shell -npm run build +Step 2: Try talking to github copilot + +- Can you connect to my mongodb instance? + +### Claude Desktop + +Step 1: Install claude and login + +Note: follow instructions at https://claude.ai/download + +Step 2: Launch Claude Settings -> Developer -> Edit Config + +Paste the mcp server configuration into the file + +```json +{ + "mcpServers": { + "MongoDB": { + "command": "npx", + "args": ["-y", "@mongodb-js/mongodb-mcp-server"] + } + } +} ``` +Step 3: Close and Relaunch Claude Desktop and click on the hammer icon, the MongoDB MCP server should be detected. + +You may experiment asking `Can you connect to my mongodb instance?`. + ## 🛠️ Supported Tools ### Tool List @@ -80,77 +130,6 @@ npm run build - `collection-storage-size` - Get the size of a collection in MB - `db-stats` - Return statistics about a MongoDB database -## 👩‍💻 Client Integration (Use the server!) - -### VSCode - -Prerequisites: - -- Node.js v20.x - -Step 1: Add the mcp server to VSCode configuration - -- Press `Cmd + Shift + P` and type `MCP: Add MCP Server` and select it. -- Select the first option for a local MCP server. -- Add the path to dist/index.js in the prompt - -Step 2: Verify the created mcp file - -It should look like this - -```json -{ - "servers": { - "mongodb-mcp-server": { - "type": "stdio", - "command": "npx", - "args": ["-y", "@mongodb-js/mongodb-mcp-server"] - } - } -} -``` - -Notes: You can configure the server with atlas access, make sure to follow configuration section for more details. - -Step 3: Open the copilot chat and check that the toolbox icon is visible and has the mcp server listed. - -Step 4: Try running a command - -- Can you list my clusters? - -### Claude - -Step 1: Install claude and login - -```shell -brew install claude -``` - -Step 2: Create a configuration file for your MCP server - -Open the file - -```shell -code ~/Library/Application\ Support/Claude/claude_desktop_config.json -``` - -Paste the mcp server configuration into the file - -```json -{ - "mcpServers": { - "Demo": { - "command": "npx", - "args": ["-y", "@mongodb-js/mongodb-mcp-server"] - } - } -} -``` - -Step 3: Launch Claude Desktop and click on the hammer icon, the Demo MCP server should be detected. Type in the chat "show me a demo of MCP" and allow the tool to get access. - -Note: If you make changes to your MCP server code, rebuild the project with `npm run build` and restart the server and Claude Desktop. - ## Configuration The MongoDB MCP Server can be configured using multiple methods, with the following precedence (highest to lowest): @@ -219,7 +198,7 @@ export MDB_MCP_LOG_PATH="/path/to/logs" Pass configuration options as command-line arguments when starting the server: ```shell -node dist/index.js --apiClientId="your-atlas-client-id" --apiClientSecret="your-atlas-client-secret" --connectionString="mongodb+srv://username:password@cluster.mongodb.net/myDatabase" --logPath=/path/to/logs +npx -y @mongodb-js/mongodb-mcp-server --apiClientId="your-atlas-client-id" --apiClientSecret="your-atlas-client-secret" --connectionString="mongodb+srv://username:password@cluster.mongodb.net/myDatabase" --logPath=/path/to/logs ``` ## 🤝 Contributing