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

Author: himanshusinghs

MCP_SERVER_LIBRARY.md

@@ -2,6 +2,7 @@
   "entry": [
     "src/index.ts!",
     "src/lib.ts!",
+    "src/tools/index.ts!",
     "tests/**/*.ts",
     "scripts/**/*.ts",
     "eslint-rules/*.js"

knip.json

@@ -1,26 +1,29 @@
 export { Server, type ServerOptions } from "./server.js";
 export { Session, type SessionOptions } from "./common/session.js";
 export { type UserConfig, UserConfigSchema } from "./common/config/userConfig.js";
+export { createUserConfig as parseCliArgumentsAsUserConfig } from "./common/config/createUserConfig.js";
 export { LoggerBase, type LogPayload, type LoggerType, type LogLevel } from "./common/logger.js";
 export { StreamableHttpRunner } from "./transports/streamableHttp.js";
 export { StdioRunner } from "./transports/stdio.js";
 export { TransportRunnerBase, type TransportRunnerConfig } from "./transports/base.js";
 export {
     ConnectionManager,
     ConnectionStateConnected,
+    createMCPConnectionManager,
     type AnyConnectionState,
     type ConnectionState,
     type ConnectionStateDisconnected,
     type ConnectionStateErrored,
     type ConnectionManagerFactoryFn,
 } from "./common/connectionManager.js";
-export type {
-    ConnectionErrorHandler,
-    ConnectionErrorHandled,
-    ConnectionErrorUnhandled,
-    ConnectionErrorHandlerContext,
+export {
+    connectionErrorHandler,
+    type ConnectionErrorHandler,
+    type ConnectionErrorHandled,
+    type ConnectionErrorUnhandled,
+    type ConnectionErrorHandlerContext,
 } from "./common/connectionErrorHandler.js";
-export { ErrorCodes } from "./common/errors.js";
+export { ErrorCodes, MongoDBError } from "./common/errors.js";
 export { Telemetry } from "./telemetry/telemetry.js";
 export { Keychain, registerGlobalSecretToRedact } from "./common/keychain.js";
 export type { Secret } from "./common/keychain.js";

src/lib.ts

@@ -16,7 +16,7 @@ import {
     UnsubscribeRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import assert from "assert";
-import type { ToolBase, ToolCategory, ToolConstructorParams } from "./tools/tool.js";
+import type { ToolBase, ToolCategory, ToolClass } from "./tools/tool.js";
 import { validateConnectionString } from "./helpers/connectionOptions.js";
 import { packageInfo } from "./common/packageInfo.js";
 import { type ConnectionErrorHandler } from "./common/connectionErrorHandler.js";
@@ -35,10 +35,19 @@ export interface ServerOptions {
      * This will override any default tools. You can use both existing and custom tools by using the `mongodb-mcp-server/tools` export.
      *
      * ```ts
-     * import { AllTools, ToolBase } from "mongodb-mcp-server/tools";
+     * import { AllTools, ToolBase, type ToolCategory, type OperationType } from "mongodb-mcp-server/tools";
      * class CustomTool extends ToolBase {
-     *     name = "custom_tool";
-     *     // ...
+     *     override name = "custom_tool";
+     *     static category: ToolCategory = "mongodb";
+     *     static operationType: OperationType = "read";
+     *     protected description = "Custom tool description";
+     *     protected argsShape = {};
+     *     protected async execute() {
+     *         return { content: [{ type: "text", text: "Result" }] };
+     *     }
+     *     protected resolveTelemetryMetadata() {
+     *         return {};
+     *     }
      * }
      * const server = new Server({
      *     session: mySession,
@@ -51,7 +60,7 @@ export interface ServerOptions {
      * });
      * ```
      */
-    tools?: (new (params: ToolConstructorParams) => ToolBase)[];
+    tools?: ToolClass[];
 }
 
 export class Server {
@@ -60,7 +69,7 @@ export class Server {
     private readonly telemetry: Telemetry;
     public readonly userConfig: UserConfig;
     public readonly elicitation: Elicitation;
-    private readonly toolConstructors: (new (params: ToolConstructorParams) => ToolBase)[];
+    private readonly toolConstructors: ToolClass[];
     public readonly tools: ToolBase[] = [];
     public readonly connectionErrorHandler: ConnectionErrorHandler;
 
@@ -242,6 +251,8 @@ export class Server {
     private registerTools(): void {
         for (const toolConstructor of this.toolConstructors) {
             const tool = new toolConstructor({
+                category: toolConstructor.category,
+                operationType: toolConstructor.operationType,
                 session: this.session,
                 config: this.userConfig,
                 telemetry: this.telemetry,

src/server.ts

@@ -7,7 +7,7 @@ import { z } from "zod";
 import { ApiClientError } from "../../common/atlas/apiClientError.js";
 
 export abstract class AtlasToolBase extends ToolBase {
-    public category: ToolCategory = "atlas";
+    static category: ToolCategory = "atlas";
 
     protected verifyAllowed(): boolean {
         if (!this.config.apiClientId || !this.config.apiClientSecret) {

src/tools/atlas/atlasTool.ts

@@ -32,7 +32,7 @@ export const ConnectClusterArgs = {
 export class ConnectClusterTool extends AtlasToolBase {
     public name = "atlas-connect-cluster";
     protected description = "Connect to MongoDB Atlas cluster";
-    public operationType: OperationType = "connect";
+    static operationType: OperationType = "connect";
     protected argsShape = {
         ...ConnectClusterArgs,
     };

src/tools/atlas/connect/connectCluster.ts

@@ -19,7 +19,7 @@ export const CreateAccessListArgs = {
 export class CreateAccessListTool extends AtlasToolBase {
     public name = "atlas-create-access-list";
     protected description = "Allow Ip/CIDR ranges to access your MongoDB Atlas clusters.";
-    public operationType: OperationType = "create";
+    static operationType: OperationType = "create";
     protected argsShape = {
         ...CreateAccessListArgs,
     };

src/tools/atlas/create/createAccessList.ts

@@ -36,7 +36,7 @@ export const CreateDBUserArgs = {
 export class CreateDBUserTool extends AtlasToolBase {
     public name = "atlas-create-db-user";
     protected description = "Create an MongoDB Atlas database user";
-    public operationType: OperationType = "create";
+    static operationType: OperationType = "create";
     protected argsShape = {
         ...CreateDBUserArgs,
     };

src/tools/atlas/create/createDBUser.ts

@@ -8,7 +8,7 @@ import { AtlasArgs } from "../../args.js";
 export class CreateFreeClusterTool extends AtlasToolBase {
     public name = "atlas-create-free-cluster";
     protected description = "Create a free MongoDB Atlas cluster";
-    public operationType: OperationType = "create";
+    static operationType: OperationType = "create";
     protected argsShape = {
         projectId: AtlasArgs.projectId().describe("Atlas project ID to create the cluster in"),
         name: AtlasArgs.clusterName().describe("Name of the cluster"),

src/tools/atlas/create/createFreeCluster.ts

@@ -7,7 +7,7 @@ import { AtlasArgs } from "../../args.js";
 export class CreateProjectTool extends AtlasToolBase {
     public name = "atlas-create-project";
     protected description = "Create a MongoDB Atlas project";
-    public operationType: OperationType = "create";
+    static operationType: OperationType = "create";
     protected argsShape = {
         projectName: AtlasArgs.projectName().optional().describe("Name for the new project"),
         organizationId: AtlasArgs.organizationId().optional().describe("Organization ID for the new project"),