/mongodb-mcp-v3-migration

name: mongodb-mcp-v3-migration
description: >
  Migrates external consumer code from the mongodb-mcp-server v1/v2 single-package API
  to the v3 scoped-package structure. In v3, mongodb-mcp-server is a binary-only package
  (npx / MCPB); library embedding uses @mongodb-js/mcp-cli, @mongodb-js/mcp-core,
  @mongodb-js/mcp-http-runners, @mongodb-js/mcp-tools-*, and the other @mongodb-js/mcp-*
  packages. Use when asked to migrate a project embedding or extending mongodb-mcp-server
  ("update my code to v3", "fix imports after the v3 release", "migrate my custom
  server/tools to the new packages"), or by external users following the v3 migration guide.

MongoDB MCP Server v1 → v3 migration

This skill migrates **consumer code**: projects that embed, customize, or extend `mongodb-mcp-server` as a library (custom CLIs, HTTP hosts, custom tools, selective tool registration, request-scoped configuration). It runs in the **consumer's repository**, not the mongodb-mcp-server repo.

**`MCP_SERVER_LIBRARY.md` now documents the v3 API surface** (the scoped `@mongodb-js/mcp-*` packages, `runMcpCli`, `CliServer`, `MCPHttpServer.createServerForRequest`, `ToolBase`/ `ToolClass`, …). Use it as the reference for the migration target; the before/after sections in this skill and its inventory script map v1/v2 consumer code onto that surface.

> **v3 is sessionless.** The v3 server has no `Session` / `CliSession` object and no > per-client session state anywhere. Each HTTP request (or stdio connection) gets a fresh > **request-scoped** `CliServer` built by `createServerFromConfig`; every heavy dependency > (connections, exports, API client, telemetry, metrics, keychain) is built once per > process inside `SharedServerServices` and shared. Tools/resources read services off > `this.server` (there is no `session`), and per-client identity travels on the tool > request (`ToolExecutionContext.request.clientInfo`) rather than on a session object.

The core rule

**`mongodb-mcp-server` is not a library in v3.**

• End users: `npx mongodb-mcp-server` or the MCPB binary only.
• **Do not** `npm install mongodb-mcp-server` and `import { … } from "mongodb-mcp-server"` in application code.
• **Do not** use the legacy `mongodb-mcp-server/tools` or `mongodb-mcp-server/web` entry points.

Embed via the scoped packages instead: **`@mongodb-js/mcp-cli`** (custom CLI), **`@mongodb-js/mcp-*`** for everything else.

Step 1 — Inventory consumer code

# repo root of the consumer project; resolves skill-relative scripts against this skill's dir
scripts/inventory-consumer-code.sh .

The script lists every file that imports `mongodb-mcp-server`, shows the matched import lines, and classifies each imported symbol to its v3 package. Anything reported as `unrecognized — manual review` is a symbol the table doesn't know: look it up in the v3 migration guide and the package's API report before deciding.

Then get the full picture of every usage site:

rg -n 'mongodb-mcp-server|from "mongodb-mcp-server"|require\("mongodb-mcp-server"' --glob '!node_modules' --glob '!dist' .

Step 2 — Classify the use case

Pick the row(s) that match what the consumer does; install those packages (v3):

| Use case | `npm install` | Primary v3 imports | | --------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | Custom CLI (most v1 embeds) | `@mongodb-js/mcp-cli` + needed tool packages | `runMcpCli`, `createRunnerFromConfig`, `create*FromConfig`, `Resources`, `CliServer` | | Host MCP over stdio | `@mongodb-js/mcp-core` | `StdioRunner`, `SessionStore`, `Keychain`, `Elicitation`, `NoopTelemetry`, `InMemoryTransport` | | Host MCP over HTTP | `@mongodb-js/mcp-http-runners` `@mongodb-js/mcp-core` | `StreamableHttpRunner`, `MCPHttpServer`, `MonitoringServer` | | Embed server (advanced) | cli + core + http-runners + metrics + logging + telemetry + tools | `CliServer`, `createSharedServicesFromConfig`, `createServerFromConfig`, `createRunnerFromConfig`, `startRunner` | | Config parsing / overrides | `@mongodb-js/mcp-cli` | `UserConfig`, `UserConfigSchema`, `parseUserConfig`, `applyConfigOverrides`, `configRegistry` | | Custom tools (any category) | `@mongodb-js/mcp-core` `@mongodb-js/mcp-types` | `ToolBase`, `ToolClass`, `OperationType`, `ToolCategory` | | MongoDB tools + connections | `@mongodb-js/mcp-tools-mongodb` | `FindTool`, `MongoDBToolBase`, `MCPConnectionManager`, `ErrorCodes`, `MongoDBError` | | Atlas Admin API tools | `@mongodb-js/mcp-tools-atlas` `@mongodb-js/mcp-atlas-api-client` | `AtlasTools`, `ApiClient`, `ClientCredentialsAuthProvider` | | Atlas Local tools | `@mongodb-js/mcp-tools-atlas-local` | `AtlasLocalTools`, `createAtlasLocalClient` | | Assistant / knowledge tools | `@mongodb-js/mcp-tools-assistant` | `AssistantTools` | | Telemetry | `@mongodb-js/mcp-atlas-telemetry` | `AtlasTelemetry`, `EventCache`, `TelemetryConfig`