Skip to content

Commit caf691a

Browse files
gagikgagik
committed
Merge branch 'main' of github.com:mongodb-js/mongodb-mcp-server into chore/MCP-242-validate-pre-filter-fields 
2 parents 92d5840 + f56f772 commit caf691a

38 files changed

+2433
-774
lines changed

‎.github/workflows/code-health-fork.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,9 @@ jobs:
3535
run: npm ci
3636
- name: Run tests
3737
run: npm test
38+
env:
39+
SKIP_ATLAS_TESTS: "true"
40+
SKIP_ATLAS_LOCAL_TESTS: "true"
3841
- name: Upload test results
3942
if: always() && matrix.os == 'ubuntu-latest'
4043
uses: actions/upload-artifact@v4

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,5 @@ tests/tmp
1313
coverage
1414
# Generated assets by accuracy runs
1515
.accuracy
16+
17+
.DS_Store

‎CONTRIBUTING.md‎

Lines changed: 21 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,10 @@ npm test -- path/to/test/file.test.ts
7676
npm test -- path/to/directory
7777
```
7878

79+
#### Accuracy Tests and colima
80+
81+
If you use [colima](https://github.com/abiosoft/colima) to run Docker on Mac, you will need to apply [additional configuration](https://node.testcontainers.org/supported-container-runtimes/#colima) to ensure the accuracy tests run correctly.
82+
7983
## Troubleshooting
8084

8185
### Restart Server
@@ -143,31 +147,28 @@ When adding new tools to the MCP server:
143147

144148
## Release Process
145149

146-
Our release process is automated using GitHub Actions workflows:
147-
148-
### Version Bumping
150+
To release a new version of the MCP server, follow these steps:
149151

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:
152+
1. Ensure there is a Jira _Release_ ticket in the [`MCP` project](https://jira.mongodb.org/projects/MCP) for the new release and move it to _In Progress_.
153+
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.
154+
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:
153155
- `patch` (e.g., 1.0.0 → 1.0.1) for backward-compatible bug fixes
154156
- `minor` (e.g., 1.0.0 → 1.1.0) for backward-compatible new features
155157
- `major` (e.g., 1.0.0 → 2.0.0) for breaking changes
156158
- 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
159+
- **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.
160+
161+
> **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.
162+
163+
4. This creates a pull request with the version change.
164+
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**.
165+
6. Verify that the new version is published correctly by checking:
166+
- NPM: https://www.npmjs.com/package/mongodb-mcp-server
167+
- Docker: https://hub.docker.com/r/mongodb/mongodb-mcp-server
168+
- MCP Registry: `curl "https://registry.modelcontextprotocol.io/v0.1/servers/io.github.mongodb-js%2Fmongodb-mcp-server/versions/latest"`
169+
7. Close the Jira ticket for the release.
170+
8. Go to the [Releases](https://jira.mongodb.org/projects/MCP?selectedItem=com.atlassian.jira.jira-projects-plugin%3Arelease-page&status=released-unreleased) section the and rename the `vNext` to the new version number and mark it as Released. Create a new `vNext` for the next release.
171+
9. Post an update in the `#mongodb-mcp` Slack channel.
171172

172173
### Code Quality
173174

‎README.md‎

Lines changed: 38 additions & 27 deletions
Large diffs are not rendered by default.

‎deploy/azure/README.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Deploy MongoDB MCP Server on Azure Container Apps
2+
3+
## Overview
4+
5+
This directory contains an Azure Bicep template (`bicep/main.bicep`) and supporting parameter files for deploying the infrastructure required to run the MongoDB MCP (Model Context Protocol) server. Use this guide to prepare prerequisites, select the appropriate parameter file, and run the deployment end-to-end.
6+
7+
## Prerequisites
8+
9+
- Azure CLI (2.55.0 or later) installed and signed in (`az login`).
10+
- Azure subscription with permissions to deploy the required resources.
11+
- MongoDB MCP server container image available in dockerhub registry (mongodb/mongodb-mcp-server:latest).
12+
13+
## Parameter Files
14+
15+
Two sample parameter files are provided to help you tailor deployments:
16+
17+
- `bicep/params.json`: Baseline configuration that deploys the MongoDB MCP server with authentication disabled or using default settings. Use this when testing in development environments or when external authentication is not required.
18+
- `bicep/paramsWithAuthEnabled.json`: Extends the baseline deployment and enables Microsoft Entra ID (Azure AD) authentication using managed identity and client application IDs. Use this when you want the server protected with Azure AD authentication via managed identity.
19+
20+
> **Tip:** Update the image reference, secrets, networking, and any other environment-specific values in the chosen parameter file before deployment.
21+
22+
## Deploy the Bicep Template
23+
24+
1. **Set common variables (PowerShell example):**
25+
26+
```powershell
27+
$location = "eastus"
28+
$resourceGroup = "mongodb-mcp-demo-rg"
29+
$templateFile = "bicep/main.bicep"
30+
$parameterFile = "bicep/params.json" # or bicep/paramsWithAuthEnabled.json
31+
```
32+
33+
2. **Create the resource group (if it does not exist):**
34+
35+
```powershell
36+
az group create --name $resourceGroup --location $location
37+
```
38+
39+
3. **Validate the deployment (optional but recommended):**
40+
41+
```powershell
42+
az deployment group what-if \
43+
--resource-group $resourceGroup \
44+
--template-file $templateFile \
45+
--parameters @$parameterFile
46+
```
47+
48+
4. **Run the deployment:**
49+
50+
```powershell
51+
az deployment group create \
52+
--resource-group $resourceGroup \
53+
--template-file $templateFile \
54+
--parameters @$parameterFile
55+
```
56+
57+
5. **Monitor outputs:** Review the deployment outputs and logs for connection endpoints, credential references, or other values needed to complete integration.
58+
59+
## Post-Deployment Checklist
60+
61+
- After the Azure Container Apps deployment completes, access the MCP server by visiting the application’s public endpoint with /mcp appended. Example: https://[CONTAINER_APP_NAME].<region>.azurecontainerapps.io/mcp.
62+
63+
## Updating the Deployment
64+
65+
To apply changes:
66+
67+
1. Update the parameter file or `main.bicep` as needed.
68+
2. Re-run the `az deployment group create` command with the same resource group.
69+
3. Use `az deployment group what-if` to preview differences before applying them.
70+
71+
## Cleanup
72+
73+
Remove the deployed resources when no longer needed:
74+
75+
```powershell
76+
az group delete --name $resourceGroup --yes --no-wait
77+
```
78+
79+
> **Reminder:** Deleting the resource group removes all resources inside it. Ensure any persistent data or backups are retained elsewhere before running the cleanup command.

‎deploy/azure/bicep/main.bicep‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
@description('Name of the Container Apps Environment. Leave blank to create a new one.')
2+
param containerAppEnvName string = ''
3+
4+
@description('Location of resources')
5+
param location string = resourceGroup().location
6+
7+
@description('Name of the Container App')
8+
param containerAppName string = 'mongo-mcp-server-app'
9+
10+
@description('Docker image to deploy')
11+
param containerImage string = 'mongodb/mongodb-mcp-server:latest'
12+
13+
@description('Container CPU (vCPU) as string. Allowed: 0.25 - 2.0 in 0.25 increments')
14+
@allowed([
15+
'0.25'
16+
'0.5'
17+
'0.75'
18+
'1.0'
19+
'1.25'
20+
'1.5'
21+
'1.75'
22+
'2.0'
23+
])
24+
param containerCpu string = '1.0'
25+
26+
// Convert CPU string to number (Bicep lacks float type; json() parses to number)
27+
var containerCpuNumber = json(containerCpu)
28+
29+
@description('Container Memory (GB)')
30+
@allowed([
31+
'0.5Gi'
32+
'1Gi'
33+
'2Gi'
34+
'4Gi'
35+
])
36+
param containerMemory string = '2Gi'
37+
38+
@description('Container App Environment Variables')
39+
param appEnvironmentVars object = {
40+
MDB_MCP_READ_ONLY: 'true' // set to 'false' to enable write operations
41+
MDB_MCP_HTTP_PORT: '8080'
42+
MDB_MCP_HTTP_HOST: '::'
43+
MDB_MCP_TRANSPORT: 'http'
44+
MDB_MCP_LOGGERS: 'disk,mcp,stderr'
45+
MDB_MCP_LOG_PATH: '/tmp/mongodb-mcp'
46+
}
47+
48+
@description('Authentication mode toggle for the Container App. NOAUTH disables platform auth; MicrosoftMIBasedAuth enables Azure AD auth and enforces 401 for unauthenticated requests.')
49+
@allowed([
50+
'NOAUTH'
51+
'MicrosoftMIBasedAuth'
52+
])
53+
param authMode string = 'NOAUTH'
54+
55+
@description('Azure AD Application (client) ID used when authMode is MicrosoftMIBasedAuth. Leave blank for NOAUTH.')
56+
param authClientId string = ''
57+
58+
@description('Issuer URL (OpenID issuer) when authMode is MicrosoftMIBasedAuth. Example: https://login.microsoftonline.com/<tenant-id>/v2.0 or https://sts.windows.net/<tenant-id>/v2.0')
59+
param authIssuerUrl string = ''
60+
61+
@description('Azure AD Tenant ID (GUID) used when authMode is MicrosoftMIBasedAuth. Provided separately to avoid hard-coded cloud endpoints in template logic.')
62+
param authTenantId string = ''
63+
64+
@description('Optional array of allowed client application IDs. If empty, all applications are allowed (not recommended).')
65+
param authAllowedClientApps array = []
66+
67+
@secure()
68+
@description('MongoDB Connection String')
69+
param mdbConnectionString string
70+
71+
// Create Container App Environment if not provided
72+
resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-02-02-preview' = if (empty(containerAppEnvName)) {
73+
name: 'mcp-env-${uniqueString(resourceGroup().id)}'
74+
location: location
75+
properties: {}
76+
}
77+
78+
// Get the Container App Environment resource ID (either existing or newly created)
79+
var envResourceId = empty(containerAppEnvName)
80+
? containerAppEnv.id
81+
: resourceId('Microsoft.App/managedEnvironments', containerAppEnvName)
82+
83+
// Build environment variables array
84+
var envVarsArray = [
85+
for item in items(appEnvironmentVars): {
86+
name: item.key
87+
value: string(item.value)
88+
}
89+
]
90+
91+
// Additional environment variables injected when MicrosoftMIBasedAuth is enabled (merged after user-provided vars so user can override if desired)
92+
var authEnvVars = authMode == 'MicrosoftMIBasedAuth'
93+
? concat([
94+
{
95+
name: 'MDB_MCP_HTTP_AUTH_MODE'
96+
value: 'azure-managed-identity'
97+
}
98+
{
99+
// Tenant ID of the Azure AD tenant
100+
name: 'MDB_MCP_AZURE_MANAGED_IDENTITY_TENANT_ID'
101+
value: authTenantId
102+
}
103+
{
104+
// Client ID of the Azure AD App representing your container app
105+
name: 'MDB_MCP_AZURE_MANAGED_IDENTITY_CLIENT_ID'
106+
value: authClientId
107+
}
108+
], length(authAllowedClientApps) > 0 ? [
109+
{
110+
// Comma-separated list of allowed Client App IDs for access
111+
// (only listed Client Apps are allowed if client apps specified)
112+
name: 'MDB_MCP_AZURE_MANAGED_IDENTITY_ALLOWED_APP_IDS'
113+
value: join(authAllowedClientApps, ',')
114+
}
115+
] : [])
116+
: [
117+
{
118+
name: 'MDB_MCP_HTTP_AUTH_MODE'
119+
value: 'none'
120+
}
121+
]
122+
123+
// Deploy Container App
124+
resource containerApp 'Microsoft.App/containerApps@2024-02-02-preview' = {
125+
name: containerAppName
126+
location: location
127+
identity: {
128+
type: 'SystemAssigned'
129+
}
130+
properties: {
131+
managedEnvironmentId: envResourceId
132+
configuration: {
133+
ingress: {
134+
external: true
135+
targetPort: int(appEnvironmentVars.MDB_MCP_HTTP_PORT)
136+
transport: 'auto'
137+
}
138+
secrets: [
139+
{
140+
name: 'mdb-mcp-connection-string'
141+
value: mdbConnectionString
142+
}
143+
]
144+
}
145+
template: {
146+
containers: [
147+
{
148+
name: 'mcpserver'
149+
image: containerImage
150+
resources: {
151+
cpu: containerCpuNumber
152+
memory: containerMemory
153+
}
154+
env: concat(
155+
envVarsArray,
156+
authEnvVars,
157+
[
158+
{
159+
name: 'MDB_MCP_CONNECTION_STRING'
160+
secretRef: 'mdb-mcp-connection-string'
161+
}
162+
]
163+
)
164+
}
165+
]
166+
scale: {
167+
minReplicas: 1
168+
maxReplicas: 1
169+
rules: [] // disables autoscaling
170+
}
171+
}
172+
}
173+
}
174+
175+
// Container App Authentication (child resource) - only deployed when MicrosoftMIBasedAuth selected
176+
resource containerAppAuth 'Microsoft.App/containerApps/authConfigs@2024-10-02-preview' = if (authMode == 'MicrosoftMIBasedAuth') {
177+
name: 'current'
178+
parent: containerApp
179+
properties: {
180+
platform: {
181+
enabled: true
182+
// runtimeVersion optional
183+
}
184+
globalValidation: {
185+
unauthenticatedClientAction: 'Return401'
186+
redirectToProvider: 'azureActiveDirectory'
187+
}
188+
identityProviders: {
189+
azureActiveDirectory: {
190+
enabled: true
191+
registration: {
192+
clientId: authClientId
193+
openIdIssuer: authIssuerUrl
194+
}
195+
validation: {
196+
allowedAudiences: [
197+
authClientId
198+
]
199+
// defaultAuthorizationPolicy allows restriction to specific client applications
200+
defaultAuthorizationPolicy: length(authAllowedClientApps) > 0 ? {
201+
allowedApplications: authAllowedClientApps
202+
} : null
203+
jwtClaimChecks: length(authAllowedClientApps) > 0 ? {
204+
allowedClientApplications: authAllowedClientApps
205+
} : null
206+
}
207+
}
208+
}
209+
}
210+
}
211+
212+
output containerAppUrl string = containerApp.properties.configuration.ingress.fqdn

‎deploy/azure/bicep/params.json‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
3+
"contentVersion": "1.0.0.0",
4+
"parameters": {
5+
"containerAppEnvName": { "value": "container-app-env" },
6+
"containerAppName": { "value": "mongo-mcp-server-app-without-auth" },
7+
"containerImage": { "value": "mongodb/mongodb-mcp-server:latest" },
8+
"containerCpu": { "value": "1.0" },
9+
"containerMemory": { "value": "2Gi" },
10+
"appEnvironmentVars": {
11+
"value": {
12+
"MDB_MCP_READ_ONLY": "false",
13+
"MDB_MCP_HTTP_PORT": "8080",
14+
"MDB_MCP_HTTP_HOST": "::",
15+
"MDB_MCP_TRANSPORT": "http",
16+
"MDB_MCP_LOGGERS": "disk,mcp,stderr",
17+
"MDB_MCP_LOG_PATH": "/tmp/mongodb-mcp",
18+
"MDB_MCP_DISABLED_TOOLS": "explain,export,atlas-create-access-list,atlas-create-db-user,drop-database,drop-collection,delete-many"
19+
}
20+
},
21+
"authMode": { "value": "NOAUTH" },
22+
"mdbConnectionString": { "value": "<MONGODB_CONNECTION_STRING>" }
23+
}
24+
}

0 commit comments

Comments
 (0)