chore: add developer guide and code examples to extend MCP server via library exports MCP-299 #767

himanshusinghs · 2025-11-26T20:37:39Z

Proposed changes

This PR adds a guide targeting developers, explaining how to extend the MongoDB MCP server using the exports available from the library. Includes working code examples for the following use-cases:

Override Server Configuration
Per-Session Configuration
Adding Custom Tools
Selective Tool Registration

Most of the document was written by CoPilot, so it'd be nice to actually ready through it once. I have ensured correctness of the material particularly API reference and examples.

Please note of the following changes:

I have moved operationType as static property to the tool classes so that its easier for library consumers to address a few use-cases, also mentioned in the guidelines.
The library exports were also modified a bit to support the examples mentioned in the guide.
Includes a fix for InsertManyTool using unexpected Zod schema

Checklist

I have signed the MongoDB CLA

MCP_SERVER_LIBRARY.md

… library exports

This commit brings back static operationType property on ToolClass declarations and ensures that current tools abides by it. Additionally we are now exporting Tools as a record instead of list to allow selective picking.

Copilot

Pull request overview

This PR adds a comprehensive developer guide documenting how to extend and embed the MongoDB MCP server as a library. The changes also refactor the tool architecture to make operationType a static class property instead of an instance property, enabling better type safety and easier tool registration.

Key Changes:

Added detailed developer guide (MCP_SERVER_LIBRARY.md) with working code examples
Refactored operationType from instance property to static class property across all tools
Updated tool exports to use named exports instead of arrays for better tree-shaking and selective import
Enhanced TypeScript documentation for exported APIs

Reviewed changes

Copilot reviewed 53 out of 53 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`MCP_SERVER_LIBRARY.md`	New comprehensive developer guide with use cases and examples
`src/tools/tool.ts`	Made `operationType` static property; added extensive JSDoc documentation
`src/tools/index.ts`	Changed tool exports from arrays to named exports
`src/tools/mongodb/tools.ts`	Converted from array export to individual named exports
`src/tools/atlas/tools.ts`	Converted from array export to individual named exports
`src/tools/atlasLocal/tools.ts`	Converted from array export to individual named exports
`src/tools/mongodb/*/.ts`	Updated all MongoDB tools to use static `operationType`
`src/tools/atlas/*/.ts`	Updated all Atlas tools to use static `operationType`
`src/tools/atlasLocal/*/.ts`	Updated all Atlas Local tools to use static `operationType`
`src/transports/base.ts`	Added extensive JSDoc documentation for `TransportRunnerConfig`
`src/server.ts`	Updated to inject static `operationType` during tool construction
`src/lib.ts`	Added new exports for developer-facing APIs
`tests/*/.test.ts`	Updated tests to use static `operationType` and new export structure
`knip.json`	Ignored tool files due to knip limitation with named exports

src/tools/mongodb/create/insertMany.ts

src/tools/mongodb/connect/switchConnection.ts

coveralls · 2025-12-01T14:16:54Z

Pull Request Test Coverage Report for Build 19830106881

Details

125 of 129 (96.9%) changed or added relevant lines in 50 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage decreased (-0.04%) to 80.432%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/lib.ts	0	4	0.0%

Totals
Change from base Build 19766295633:	-0.04%
Covered Lines:	6640
Relevant Lines:	8178

💛 - Coveralls

himanshusinghs · 2025-12-01T14:18:18Z

src/tools/mongodb/create/insertMany.ts

+    protected argsShape = this.isFeatureEnabled("search")
+        ? {
+              ...commonArgs,
+              embeddingParameters: zSupportedEmbeddingParametersWithInput
+                  .optional()
+                  .describe(
+                      "The embedding model and its parameters to use to generate embeddings for fields with vector search indexes. Note to LLM: If unsure which embedding model to use, ask the user before providing one."
+                  ),
+          }
+        : commonArgs;


This fixes an unexpected ZodSchema because of earlier optional empty object getting injected when feature flag was not enabled. This was caught by one of the examples in the guide where a tool call was getting rejected right away.

himanshusinghs · 2025-12-01T14:20:58Z

src/tools/index.ts

+import * as AtlasTools from "./atlas/tools.js";
+import * as AtlasLocalTools from "./atlasLocal/tools.js";
+import * as MongoDbTools from "./mongodb/tools.js";

-const AllTools = [...MongoDbTools, ...AtlasTools, ...AtlasLocalTools];
+const AllTools = {
+    ...MongoDbTools,
+    ...AtlasTools,
+    ...AtlasLocalTools,
+} as const;


Please note that we're now exporting record like exports instead of array like exports. The changes allows nitpicking of individual tools.

I think we should export this as an array and also do:

export * from from "./mongodb/tools.js"; ...

This way the IDE can suggest these imports and no real nitpicking is required

But it is the same?

export * from "../mongodb/tools.js"

needs to be imported as:
import { ConnectTool } from "mongodb-mcp-server/tools"

and currently you would do the same either by:

import { AllTools } from "mongodb-mcp-server/tools" AllTools.ConnectTool

or

import { MongoDbTools } from "mongodb-mcp-server/tools" MongoDbTools.ConnectTool

Actually with the current change, we do get per category division already which we would miss if we do:
export * from "../mongodb/tools.js"

unless we do
export * as MongoDbTools from "../mongodb/tools.js"

which then essentially is the same.

Based on our discussion, I have updated the export to have individual exports alongside the list of all the tools for convenience.

knip.json

MCP_SERVER_LIBRARY.md

gagik

It's nice, I think we should just export all classes and not rely on expanding the object

knip.json

MCP_SERVER_LIBRARY.md

himanshusinghs requested a review from a team as a code owner November 26, 2025 20:37

gagik reviewed Nov 27, 2025

View reviewed changes

MCP_SERVER_LIBRARY.md Outdated Show resolved Hide resolved

MCP_SERVER_LIBRARY.md Outdated Show resolved Hide resolved

himanshusinghs force-pushed the chore/disallow-overriding-of-internal-tools branch 3 times, most recently from b232a56 to 9cc5526 Compare November 27, 2025 16:11

himanshusinghs force-pushed the chore/MCP-299-mcp-lib-code-examples branch 2 times, most recently from 5d00ab6 to 64cb9bf Compare November 27, 2025 17:05

gagik approved these changes Nov 28, 2025

View reviewed changes

himanshusinghs mentioned this pull request Nov 28, 2025

chore: disallow overriding of internal tool implementations #766

Closed

1 task

himanshusinghs added 2 commits November 28, 2025 18:04

chore: add developer guide and code examples to extend MCP server via…

9a6f1df

… library exports

chore: bring back static operationType

79fe868

This commit brings back static operationType property on ToolClass declarations and ensures that current tools abides by it. Additionally we are now exporting Tools as a record instead of list to allow selective picking.

himanshusinghs force-pushed the chore/MCP-299-mcp-lib-code-examples branch from 3c82e49 to 79fe868 Compare December 1, 2025 13:43

himanshusinghs changed the base branch from chore/disallow-overriding-of-internal-tools to main December 1, 2025 13:43

chore: further refine the examples

c5bffeb

Copilot AI review requested due to automatic review settings December 1, 2025 14:10

Copilot AI reviewed Dec 1, 2025

View reviewed changes

src/tools/mongodb/create/insertMany.ts Show resolved Hide resolved

src/tools/mongodb/connect/switchConnection.ts Show resolved Hide resolved

himanshusinghs mentioned this pull request Dec 1, 2025

chore: export UserConfigSchema for consumers #771

Merged

himanshusinghs commented Dec 1, 2025

View reviewed changes

knip.json Outdated Show resolved Hide resolved

himanshusinghs requested a review from gagik December 1, 2025 14:24

gagik reviewed Dec 1, 2025

View reviewed changes

MCP_SERVER_LIBRARY.md Outdated Show resolved Hide resolved

gagik reviewed Dec 1, 2025

View reviewed changes

knip.json Outdated Show resolved Hide resolved

gagik reviewed Dec 1, 2025

View reviewed changes

MCP_SERVER_LIBRARY.md Outdated Show resolved Hide resolved

himanshusinghs added 4 commits December 1, 2025 16:18

chore: fix knip config

2ea82d5

chore: move category to static property

e00143b

chore: add test for export reliance

18f8da3

chore: add test for export reliance

c786c6b

Merge branch 'main' into chore/MCP-299-mcp-lib-code-examples

164b79f

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

chore: add developer guide and code examples to extend MCP server via library exports MCP-299 #767

chore: add developer guide and code examples to extend MCP server via library exports MCP-299 #767

himanshusinghs commented Nov 26, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

coveralls commented Dec 1, 2025 •

edited

Loading

Uh oh!

himanshusinghs Dec 1, 2025

Uh oh!

himanshusinghs Dec 1, 2025

Uh oh!

gagik Dec 1, 2025

Uh oh!

himanshusinghs Dec 1, 2025

Uh oh!

himanshusinghs Dec 1, 2025

Uh oh!

Uh oh!

Uh oh!

gagik left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

chore: add developer guide and code examples to extend MCP server via library exports MCP-299 #767

Are you sure you want to change the base?

chore: add developer guide and code examples to extend MCP server via library exports MCP-299 #767

Conversation

himanshusinghs commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Checklist

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

coveralls commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 19830106881

Details

💛 - Coveralls

Uh oh!

himanshusinghs Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

himanshusinghs Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

gagik Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

himanshusinghs Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

himanshusinghs Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

gagik left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

himanshusinghs commented Nov 26, 2025 •

edited

Loading

coveralls commented Dec 1, 2025 •

edited

Loading

gagik left a comment •

edited

Loading