Skip to content

Commit 71bb316

Browse files
fmenezesfmenezes
authored
ci: improve release process (#68)
1 parent bbe20a5 commit 71bb316

File tree

5 files changed

+178
-90
lines changed

5 files changed

+178
-90
lines changed

‎.github/workflows/publish.yaml

+40-4
Original file line numberDiff line numberDiff line change
@@ -2,28 +2,64 @@
22
name: Publish
33
on:
44
push:
5-
tags:
6-
- v*
5+
branches:
6+
- main
7+
permissions:
8+
contents: write
79
jobs:
810
publish:
911
runs-on: ubuntu-latest
1012
environment: Production
1113
steps:
1214
- uses: GitHubSecurityLab/actions-permissions/monitor@v1
1315
- uses: actions/checkout@v4
16+
with:
17+
fetch-depth: 0
1418
- uses: actions/setup-node@v4
1519
with:
1620
node-version-file: package.json
1721
registry-url: "https://registry.npmjs.org"
1822
cache: "npm"
23+
- name: Get version
24+
id: get-version
25+
shell: bash
26+
run: |
27+
set +e
28+
29+
VERSION=v$(jq -r '.version' < package.json)
30+
echo "VERSION=${VERSION}" >> "$GITHUB_OUTPUT"
31+
- name: Check if version already exists
32+
id: check-version
33+
shell: bash
34+
run: |
35+
set +e
36+
37+
git rev-parse "${{ steps.get-version.outputs.VERSION }}" >/dev/null 2>&1
38+
if [[ $? -eq 0 ]]; then
39+
echo "VERSION_EXISTS=true" >> "$GITHUB_OUTPUT"
40+
else
41+
echo "VERSION_EXISTS=false" >> "$GITHUB_OUTPUT"
42+
fi
1943
- name: Build package
44+
if: steps.check-version.outputs.VERSION_EXISTS == 'false'
2045
run: |
2146
npm ci
2247
npm run build
2348
- name: Publish to NPM
49+
if: steps.check-version.outputs.VERSION_EXISTS == 'false'
2450
run: npm publish
2551
env:
2652
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
27-
- name: Publish Github release
53+
- name: Publish git tag
54+
if: steps.check-version.outputs.VERSION_EXISTS == 'false'
55+
run: |
56+
git config --global user.name 'github-actions[bot]'
57+
git config --global user.email '41898282+github-actions[bot]@users.noreply.github.com'
58+
git tag ${{ steps.get-version.outputs.VERSION }}
59+
git push origin --tags
60+
- name: Publish git release
61+
if: steps.check-version.outputs.VERSION_EXISTS == 'false'
62+
env:
63+
GH_TOKEN: ${{ github.token }}
2864
run: |
29-
gh release create ${{ github.ref }} --title "${{ github.ref }}" --notes "Release ${{ github.ref }}" --generate-notes
65+
gh release create ${{ github.env.VERSION }} --title "${{ github.env.VERSION }}" --generate-notes

‎.github/workflows/version_bump.yaml

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
name: Version Bump
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
version:
7+
description: "Version to bump to"
8+
required: true
9+
default: "patch"
10+
jobs:
11+
bump-version:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: GitHubSecurityLab/actions-permissions/monitor@v1
15+
- uses: actions/checkout@v4
16+
- uses: actions/setup-node@v4
17+
with:
18+
node-version-file: package.json
19+
registry-url: "https://registry.npmjs.org"
20+
cache: "npm"
21+
- name: Build package
22+
run: |
23+
npm ci
24+
- name: Bump version
25+
run: |
26+
npm version ${{ github.event.inputs.version }} --no-git-tag-version
27+
- name: Create PR
28+
uses: peter-evans/create-pull-request@v4
29+
with:
30+
title: "Bump version to ${{ github.event.inputs.version }}"
31+
body: "Bump version to ${{ github.event.inputs.version }}"
32+
base: main
33+
branch: ci/version-bump-${{ github.event.inputs.version }}
34+
commit-message: "Bump version to ${{ github.event.inputs.version }}"
35+
author: "github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>"
36+
committer: "github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>"
37+
labels: version-bump

‎.npmrc

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
git-tag-version=false

‎CONTRIBUTING.md

+35
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,41 @@ When adding new tools to the MCP server:
141141
4. Add proper documentation for the tool
142142
5. Include examples of how to use the tool
143143

144+
## Release Process
145+
146+
Our release process is automated using GitHub Actions workflows:
147+
148+
### Version Bumping
149+
150+
1. To create a new version, go to the GitHub repository Actions tab
151+
2. Select the "Version Bump" workflow
152+
3. Click "Run workflow" and choose one of the following options:
153+
- `patch` (e.g., 1.0.0 → 1.0.1) for backward-compatible bug fixes
154+
- `minor` (e.g., 1.0.0 → 1.1.0) for backward-compatible new features
155+
- `major` (e.g., 1.0.0 → 2.0.0) for breaking changes
156+
- A specific version number (e.g., `1.2.3`)
157+
4. This creates a pull request with the version change
158+
5. Once approved and merged, the version is updated
159+
160+
### Automatic Publishing
161+
162+
When a version bump is merged to the main branch:
163+
164+
1. The "Publish" workflow automatically runs
165+
2. It checks if the version already exists as a git tag
166+
3. If the version is new, it:
167+
- Builds the package
168+
- Publishes to NPM
169+
- Creates a git tag for the version
170+
- Creates a GitHub release with auto-generated release notes
171+
172+
### Code Quality
173+
174+
All pull requests automatically run through the "Code Health" workflow, which:
175+
176+
- Verifies code style and formatting
177+
- Runs tests on multiple platforms (Ubuntu, macOS, Windows)
178+
144179
## License
145180

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

‎README.md

+65-86
Original file line numberDiff line numberDiff line change
@@ -10,38 +10,88 @@ A Model Context Protocol server for interacting with MongoDB Atlas. This project
1010
- [🚀 Getting Started](#getting-started)
1111
- [Prerequisites](#prerequisites)
1212
- [Installation](#installation)
13-
- [Running the MCP Server](#running-the-mcp-server)
13+
- [VSCode](#vscode)
14+
- [Claude Desktop](#claude)
1415
- [🛠️ Supported Tools](#supported-tools)
1516
- [Tool List](#tool-list)
17+
- [⚙️ Configuration](#configuration)
18+
- [Configuration Options](#configuration-options)
19+
- [Atlas API Access](#atlas-api-access)
20+
- [Configuration Methods](#configuration-methods)
1621
- [👩‍💻 Client Integration](#client-integration)
1722
- [VSCode](#vscode)
1823
- [Claude](#claude)
1924
- [🤝 Contributing](#contributing)
2025

21-
## 🚀 Getting Started
22-
23-
### Prerequisites
26+
## Prerequisites
2427

2528
- Node.js (v20 or later)
2629
- MongoDB Atlas account
2730

28-
### Installation
31+
## Installation
2932

30-
```shell
31-
# Clone the repository
32-
git clone https://github.com/mongodb-labs/mongodb-mcp-server.git
33-
cd mongodb-mcp-server
33+
### VSCode
34+
35+
Prerequisites:
36+
37+
- Node.js v20.x
38+
39+
Step 1: Add the mcp server to VSCode configuration
40+
41+
- Press `Cmd + Shift + P` and type `MCP: Add MCP Server` and select it.
42+
- Select command (Stdio).
43+
- Input command `npx -y @mongodb-js/mongodb-mcp-server`.
44+
- Choose between user / workspace
45+
- Add arguments to the file
46+
47+
Note: the file should look like:
3448

35-
# Install dependencies
36-
npm install
49+
```
50+
{
51+
"servers": {
52+
"MongoDB": {
53+
"type": "stdio",
54+
"command": "npx",
55+
"args": [
56+
"-y",
57+
"@mongodb-js/mongodb-mcp-server"
58+
]
59+
}
60+
}
61+
}
3762
```
3863

39-
### Running the MCP Server
64+
Notes: You can configure the server with atlas access, make sure to follow configuration section for more details.
4065

41-
```shell
42-
npm run build
66+
Step 2: Try talking to github copilot
67+
68+
- Can you connect to my mongodb instance?
69+
70+
### Claude Desktop
71+
72+
Step 1: Install claude and login
73+
74+
Note: follow instructions at https://claude.ai/download
75+
76+
Step 2: Launch Claude Settings -> Developer -> Edit Config
77+
78+
Paste the mcp server configuration into the file
79+
80+
```json
81+
{
82+
"mcpServers": {
83+
"MongoDB": {
84+
"command": "npx",
85+
"args": ["-y", "@mongodb-js/mongodb-mcp-server"]
86+
}
87+
}
88+
}
4389
```
4490

91+
Step 3: Close and Relaunch Claude Desktop and click on the hammer icon, the MongoDB MCP server should be detected.
92+
93+
You may experiment asking `Can you connect to my mongodb instance?`.
94+
4595
## 🛠️ Supported Tools
4696

4797
### Tool List
@@ -80,77 +130,6 @@ npm run build
80130
- `collection-storage-size` - Get the size of a collection in MB
81131
- `db-stats` - Return statistics about a MongoDB database
82132

83-
## 👩‍💻 Client Integration (Use the server!)
84-
85-
### VSCode
86-
87-
Prerequisites:
88-
89-
- Node.js v20.x
90-
91-
Step 1: Add the mcp server to VSCode configuration
92-
93-
- Press `Cmd + Shift + P` and type `MCP: Add MCP Server` and select it.
94-
- Select the first option for a local MCP server.
95-
- Add the path to dist/index.js in the prompt
96-
97-
Step 2: Verify the created mcp file
98-
99-
It should look like this
100-
101-
```json
102-
{
103-
"servers": {
104-
"mongodb-mcp-server": {
105-
"type": "stdio",
106-
"command": "npx",
107-
"args": ["-y", "@mongodb-js/mongodb-mcp-server"]
108-
}
109-
}
110-
}
111-
```
112-
113-
Notes: You can configure the server with atlas access, make sure to follow configuration section for more details.
114-
115-
Step 3: Open the copilot chat and check that the toolbox icon is visible and has the mcp server listed.
116-
117-
Step 4: Try running a command
118-
119-
- Can you list my clusters?
120-
121-
### Claude
122-
123-
Step 1: Install claude and login
124-
125-
```shell
126-
brew install claude
127-
```
128-
129-
Step 2: Create a configuration file for your MCP server
130-
131-
Open the file
132-
133-
```shell
134-
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
135-
```
136-
137-
Paste the mcp server configuration into the file
138-
139-
```json
140-
{
141-
"mcpServers": {
142-
"Demo": {
143-
"command": "npx",
144-
"args": ["-y", "@mongodb-js/mongodb-mcp-server"]
145-
}
146-
}
147-
}
148-
```
149-
150-
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.
151-
152-
Note: If you make changes to your MCP server code, rebuild the project with `npm run build` and restart the server and Claude Desktop.
153-
154133
## Configuration
155134

156135
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"
219198
Pass configuration options as command-line arguments when starting the server:
220199

221200
```shell
222-
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
201+
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
223202
```
224203

225204
## 🤝 Contributing

0 commit comments

Comments
 (0)