mongodb-mcp-server 0.0.4

package/src/tools/tool.ts

@@ -0,0 +1,90 @@
+import { McpServer, ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z, ZodNever, ZodRawShape } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { Session } from "../session.js";
+import logger from "../logger.js";
+import { mongoLogId } from "mongodb-log-writer";
+import config from "../config.js";
+
+export type ToolArgs<Args extends ZodRawShape> = z.objectOutputType<Args, ZodNever>;
+
+export type OperationType = "metadata" | "read" | "create" | "delete" | "update" | "cluster";
+export type ToolCategory = "mongodb" | "atlas";
+
+export abstract class ToolBase {
+    protected abstract name: string;
+
+    protected abstract category: ToolCategory;
+
+    protected abstract operationType: OperationType;
+
+    protected abstract description: string;
+
+    protected abstract argsShape: ZodRawShape;
+
+    protected abstract execute(...args: Parameters<ToolCallback<typeof this.argsShape>>): Promise<CallToolResult>;
+
+    protected constructor(protected session: Session) {}
+
+    public register(server: McpServer): void {
+        if (!this.verifyAllowed()) {
+            return;
+        }
+
+        const callback: ToolCallback<typeof this.argsShape> = async (...args) => {
+            try {
+                // TODO: add telemetry here
+                logger.debug(
+                    mongoLogId(1_000_006),
+                    "tool",
+                    `Executing ${this.name} with args: ${JSON.stringify(args)}`
+                );
+
+                return await this.execute(...args);
+            } catch (error: unknown) {
+                logger.error(mongoLogId(1_000_000), "tool", `Error executing ${this.name}: ${error as string}`);
+
+                return await this.handleError(error);
+            }
+        };
+
+        server.tool(this.name, this.description, this.argsShape, callback);
+    }
+
+    // Checks if a tool is allowed to run based on the config
+    private verifyAllowed(): boolean {
+        let errorClarification: string | undefined;
+        if (config.disabledTools.includes(this.category)) {
+            errorClarification = `its category, \`${this.category}\`,`;
+        } else if (config.disabledTools.includes(this.operationType)) {
+            errorClarification = `its operation type, \`${this.operationType}\`,`;
+        } else if (config.disabledTools.includes(this.name)) {
+            errorClarification = `it`;
+        }
+
+        if (errorClarification) {
+            logger.debug(
+                mongoLogId(1_000_010),
+                "tool",
+                `Prevented registration of ${this.name} because ${errorClarification} is disabled in the config`
+            );
+
+            return false;
+        }
+
+        return true;
+    }
+
+    // This method is intended to be overridden by subclasses to handle errors
+    protected handleError(error: unknown): Promise<CallToolResult> | CallToolResult {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error running ${this.name}: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/src/types/mongodb-redact.d.ts

@@ -0,0 +1,4 @@
+declare module "mongodb-redact" {
+    function redact<T>(message: T): T;
+    export default redact;
+}

package/tests/integration/helpers.ts

@@ -0,0 +1,241 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "./inMemoryTransport.js";
+import { Server } from "../../src/server.js";
+import runner, { MongoCluster } from "mongodb-runner";
+import path from "path";
+import fs from "fs/promises";
+import { Session } from "../../src/session.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { MongoClient, ObjectId } from "mongodb";
+import { toIncludeAllMembers } from "jest-extended";
+import config from "../../src/config.js";
+
+interface ParameterInfo {
+    name: string;
+    type: string;
+    description: string;
+    required: boolean;
+}
+
+type ToolInfo = Awaited<ReturnType<Client["listTools"]>>["tools"][number];
+
+export interface IntegrationTest {
+    mcpClient: () => Client;
+    mcpServer: () => Server;
+    mongoClient: () => MongoClient;
+    connectionString: () => string;
+    connectMcpClient: () => Promise<void>;
+    randomDbName: () => string;
+}
+
+export function setupIntegrationTest(): IntegrationTest {
+    let mongoCluster: runner.MongoCluster | undefined;
+    let mongoClient: MongoClient | undefined;
+
+    let mcpClient: Client | undefined;
+    let mcpServer: Server | undefined;
+
+    let randomDbName: string;
+
+    beforeAll(async () => {
+        const clientTransport = new InMemoryTransport();
+        const serverTransport = new InMemoryTransport();
+
+        await serverTransport.start();
+        await clientTransport.start();
+
+        clientTransport.output.pipeTo(serverTransport.input);
+        serverTransport.output.pipeTo(clientTransport.input);
+
+        mcpClient = new Client(
+            {
+                name: "test-client",
+                version: "1.2.3",
+            },
+            {
+                capabilities: {},
+            }
+        );
+
+        mcpServer = new Server({
+            mcpServer: new McpServer({
+                name: "test-server",
+                version: "1.2.3",
+            }),
+            session: new Session(),
+        });
+        await mcpServer.connect(serverTransport);
+        await mcpClient.connect(clientTransport);
+    });
+
+    beforeEach(async () => {
+        randomDbName = new ObjectId().toString();
+    });
+
+    afterAll(async () => {
+        await mcpClient?.close();
+        mcpClient = undefined;
+
+        await mcpServer?.close();
+        mcpServer = undefined;
+    });
+
+    afterEach(async () => {
+        await mcpServer?.session.close();
+        config.connectionString = undefined;
+    });
+
+    beforeAll(async function () {
+        // Downloading Windows executables in CI takes a long time because
+        // they include debug symbols...
+        const tmpDir = path.join(__dirname, "..", "tmp");
+        await fs.mkdir(tmpDir, { recursive: true });
+
+        // On Windows, we may have a situation where mongod.exe is not fully released by the OS
+        // before we attempt to run it again, so we add a retry.
+        let dbsDir = path.join(tmpDir, "mongodb-runner", "dbs");
+        for (let i = 0; i < 10; i++) {
+            try {
+                mongoCluster = await MongoCluster.start({
+                    tmpDir: dbsDir,
+                    logDir: path.join(tmpDir, "mongodb-runner", "logs"),
+                    topology: "standalone",
+                });
+
+                return;
+            } catch (err) {
+                if (i < 5) {
+                    // Just wait a little bit and retry
+                    console.error(`Failed to start cluster in ${dbsDir}, attempt ${i}: ${err}`);
+                    await new Promise((resolve) => setTimeout(resolve, 1000));
+                } else {
+                    // If we still fail after 5 seconds, try another db dir
+                    console.error(
+                        `Failed to start cluster in ${dbsDir}, attempt ${i}: ${err}. Retrying with a new db dir.`
+                    );
+                    dbsDir = path.join(tmpDir, "mongodb-runner", `dbs${i - 5}`);
+                }
+            }
+        }
+
+        throw new Error("Failed to start cluster after 10 attempts");
+    }, 120_000);
+
+    afterAll(async function () {
+        await mongoCluster?.close();
+        mongoCluster = undefined;
+    });
+
+    const getMcpClient = () => {
+        if (!mcpClient) {
+            throw new Error("beforeEach() hook not ran yet");
+        }
+
+        return mcpClient;
+    };
+
+    const getMcpServer = () => {
+        if (!mcpServer) {
+            throw new Error("beforeEach() hook not ran yet");
+        }
+
+        return mcpServer;
+    };
+
+    const getConnectionString = () => {
+        if (!mongoCluster) {
+            throw new Error("beforeAll() hook not ran yet");
+        }
+
+        return mongoCluster.connectionString;
+    };
+
+    return {
+        mcpClient: getMcpClient,
+        mcpServer: getMcpServer,
+        mongoClient: () => {
+            if (!mongoClient) {
+                mongoClient = new MongoClient(getConnectionString());
+            }
+            return mongoClient;
+        },
+        connectionString: getConnectionString,
+        connectMcpClient: async () => {
+            await getMcpClient().callTool({
+                name: "connect",
+                arguments: { options: [{ connectionString: getConnectionString() }] },
+            });
+        },
+        randomDbName: () => randomDbName,
+    };
+}
+
+export function getResponseContent(content: unknown): string {
+    return getResponseElements(content)
+        .map((item) => item.text)
+        .join("\n");
+}
+
+export function getResponseElements(content: unknown): { type: string; text: string }[] {
+    expect(Array.isArray(content)).toBe(true);
+
+    const response = content as { type: string; text: string }[];
+    for (const item of response) {
+        expect(item).toHaveProperty("type");
+        expect(item).toHaveProperty("text");
+        expect(item.type).toBe("text");
+    }
+
+    return response;
+}
+
+export async function connect(client: Client, connectionString: string): Promise<void> {
+    await client.callTool({
+        name: "connect",
+        arguments: { connectionStringOrClusterName: connectionString },
+    });
+}
+
+export function getParameters(tool: ToolInfo): ParameterInfo[] {
+    expect(tool.inputSchema.type).toBe("object");
+    expect(tool.inputSchema.properties).toBeDefined();
+
+    return Object.entries(tool.inputSchema.properties!)
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([key, value]) => {
+            expect(value).toHaveProperty("type");
+            expect(value).toHaveProperty("description");
+
+            const typedValue = value as { type: string; description: string };
+            expect(typeof typedValue.type).toBe("string");
+            expect(typeof typedValue.description).toBe("string");
+            return {
+                name: key,
+                type: typedValue.type,
+                description: typedValue.description,
+                required: (tool.inputSchema.required as string[])?.includes(key) ?? false,
+            };
+        });
+}
+
+export const dbOperationParameters: ParameterInfo[] = [
+    { name: "database", type: "string", description: "Database name", required: true },
+    { name: "collection", type: "string", description: "Collection name", required: true },
+];
+
+export function validateParameters(tool: ToolInfo, parameters: ParameterInfo[]): void {
+    const toolParameters = getParameters(tool);
+    expect(toolParameters).toHaveLength(parameters.length);
+    expect(toolParameters).toIncludeAllMembers(parameters);
+}
+
+export function describeAtlas(name: number | string | Function | jest.FunctionLike, fn: jest.EmptyFunction) {
+    if (!process.env.MDB_MCP_API_CLIENT_ID?.length || !process.env.MDB_MCP_API_CLIENT_SECRET?.length) {
+        return describe.skip("atlas", () => {
+            describe(name, fn);
+        });
+    }
+    return describe("atlas", () => {
+        describe(name, fn);
+    });
+}

package/tests/integration/inMemoryTransport.ts

@@ -0,0 +1,58 @@
+import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+
+export class InMemoryTransport implements Transport {
+    private outputController: ReadableStreamDefaultController<JSONRPCMessage>;
+
+    private startPromise: Promise<unknown>;
+
+    public output: ReadableStream<JSONRPCMessage>;
+    public input: WritableStream<JSONRPCMessage>;
+
+    constructor() {
+        const [inputReady, inputResolve] = InMemoryTransport.getPromise();
+        const [outputReady, outputResolve] = InMemoryTransport.getPromise();
+
+        this.output = new ReadableStream<JSONRPCMessage>({
+            start: (controller) => {
+                this.outputController = controller;
+                outputResolve();
+            },
+        });
+
+        this.input = new WritableStream<JSONRPCMessage>({
+            write: (message) => this.onmessage?.(message),
+            start: () => {
+                inputResolve();
+            },
+        });
+
+        this.startPromise = Promise.all([inputReady, outputReady]);
+    }
+
+    async start(): Promise<void> {
+        await this.startPromise;
+    }
+
+    send(message: JSONRPCMessage): Promise<void> {
+        this.outputController.enqueue(message);
+        return Promise.resolve();
+    }
+
+    async close(): Promise<void> {
+        this.outputController.close();
+        this.onclose?.();
+    }
+    onclose?: (() => void) | undefined;
+    onerror?: ((error: Error) => void) | undefined;
+    onmessage?: ((message: JSONRPCMessage) => void) | undefined;
+    sessionId?: string | undefined;
+
+    private static getPromise(): [Promise<void>, resolve: () => void] {
+        let resolve: () => void;
+        const promise = new Promise<void>((res) => {
+            resolve = res;
+        });
+        return [promise, resolve!];
+    }
+}

package/tests/integration/server.test.ts

@@ -0,0 +1,35 @@
+import { setupIntegrationTest } from "./helpers";
+
+describe("Server integration test", () => {
+    const integration = setupIntegrationTest();
+
+    describe("list capabilities", () => {
+        it("should return positive number of tools", async () => {
+            const tools = await integration.mcpClient().listTools();
+            expect(tools).toBeDefined();
+            expect(tools.tools.length).toBeGreaterThan(0);
+        });
+
+        it("should return no resources", async () => {
+            await expect(() => integration.mcpClient().listResources()).rejects.toMatchObject({
+                message: "MCP error -32601: Method not found",
+            });
+        });
+
+        it("should return no prompts", async () => {
+            await expect(() => integration.mcpClient().listPrompts()).rejects.toMatchObject({
+                message: "MCP error -32601: Method not found",
+            });
+        });
+
+        it("should return capabilities", async () => {
+            const capabilities = integration.mcpClient().getServerCapabilities();
+            expect(capabilities).toBeDefined();
+            expect(capabilities?.completions).toBeUndefined();
+            expect(capabilities?.experimental).toBeUndefined();
+            expect(capabilities?.tools).toBeDefined();
+            expect(capabilities?.logging).toBeDefined();
+            expect(capabilities?.prompts).toBeUndefined();
+        });
+    });
+});

package/tests/integration/tools/atlas/accessLists.test.ts

@@ -0,0 +1,100 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { Session } from "../../../../src/session.js";
+import { describeAtlas, withProject } from "./atlasHelpers.js";
+
+function generateRandomIp() {
+    const randomIp: number[] = [192];
+    for (let i = 0; i < 3; i++) {
+        randomIp.push(Math.floor(Math.random() * 256));
+    }
+    return randomIp.join(".");
+}
+
+describeAtlas("ip access lists", (integration) => {
+    withProject(integration, ({ getProjectId }) => {
+        const ips = [generateRandomIp(), generateRandomIp()];
+        const cidrBlocks = [generateRandomIp() + "/16", generateRandomIp() + "/24"];
+        const values = [...ips, ...cidrBlocks];
+
+        beforeAll(async () => {
+            const session: Session = integration.mcpServer().session;
+            session.ensureAuthenticated();
+            const ipInfo = await session.apiClient.getIpInfo();
+            values.push(ipInfo.currentIpv4Address);
+        });
+
+        afterAll(async () => {
+            const session: Session = integration.mcpServer().session;
+            session.ensureAuthenticated();
+
+            const projectId = getProjectId();
+
+            for (const value of values) {
+                await session.apiClient.deleteProjectIpAccessList({
+                    params: {
+                        path: {
+                            groupId: projectId,
+                            entryValue: value,
+                        },
+                    },
+                });
+            }
+        });
+
+        describe("atlas-create-access-list", () => {
+            it("should have correct metadata", async () => {
+                const { tools } = await integration.mcpClient().listTools();
+                const createAccessList = tools.find((tool) => tool.name === "atlas-create-access-list")!;
+                expect(createAccessList).toBeDefined();
+                expect(createAccessList.inputSchema.type).toBe("object");
+                expect(createAccessList.inputSchema.properties).toBeDefined();
+                expect(createAccessList.inputSchema.properties).toHaveProperty("projectId");
+                expect(createAccessList.inputSchema.properties).toHaveProperty("ipAddresses");
+                expect(createAccessList.inputSchema.properties).toHaveProperty("cidrBlocks");
+                expect(createAccessList.inputSchema.properties).toHaveProperty("currentIpAddress");
+                expect(createAccessList.inputSchema.properties).toHaveProperty("comment");
+            });
+
+            it("should create an access list", async () => {
+                const projectId = getProjectId();
+
+                const response = (await integration.mcpClient().callTool({
+                    name: "atlas-create-access-list",
+                    arguments: {
+                        projectId,
+                        ipAddresses: ips,
+                        cidrBlocks: cidrBlocks,
+                        currentIpAddress: true,
+                    },
+                })) as CallToolResult;
+                expect(response.content).toBeArray();
+                expect(response.content).toHaveLength(1);
+                expect(response.content[0].text).toContain("IP/CIDR ranges added to access list");
+            });
+        });
+
+        describe("atlas-inspect-access-list", () => {
+            it("should have correct metadata", async () => {
+                const { tools } = await integration.mcpClient().listTools();
+                const inspectAccessList = tools.find((tool) => tool.name === "atlas-inspect-access-list")!;
+                expect(inspectAccessList).toBeDefined();
+                expect(inspectAccessList.inputSchema.type).toBe("object");
+                expect(inspectAccessList.inputSchema.properties).toBeDefined();
+                expect(inspectAccessList.inputSchema.properties).toHaveProperty("projectId");
+            });
+
+            it("returns access list data", async () => {
+                const projectId = getProjectId();
+
+                const response = (await integration
+                    .mcpClient()
+                    .callTool({ name: "atlas-inspect-access-list", arguments: { projectId } })) as CallToolResult;
+                expect(response.content).toBeArray();
+                expect(response.content).toHaveLength(1);
+                for (const value of values) {
+                    expect(response.content[0].text).toContain(value);
+                }
+            });
+        });
+    });
+});

package/tests/integration/tools/atlas/atlasHelpers.ts

@@ -0,0 +1,110 @@
+import { ObjectId } from "mongodb";
+import { Group } from "../../../../src/common/atlas/openapi.js";
+import { ApiClient } from "../../../../src/common/atlas/apiClient.js";
+import { setupIntegrationTest, IntegrationTest } from "../../helpers.js";
+import { Session } from "../../../../src/session.js";
+
+export type IntegrationTestFunction = (integration: IntegrationTest) => void;
+
+export function sleep(ms: number) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function describeAtlas(name: number | string | Function | jest.FunctionLike, fn: IntegrationTestFunction) {
+    const testDefinition = () => {
+        const integration = setupIntegrationTest();
+        describe(name, () => {
+            fn(integration);
+        });
+    };
+
+    if (!process.env.MDB_MCP_API_CLIENT_ID?.length || !process.env.MDB_MCP_API_CLIENT_SECRET?.length) {
+        return describe.skip("atlas", testDefinition);
+    }
+    return describe("atlas", testDefinition);
+}
+
+interface ProjectTestArgs {
+    getProjectId: () => string;
+}
+
+type ProjectTestFunction = (args: ProjectTestArgs) => void;
+
+export function withProject(integration: IntegrationTest, fn: ProjectTestFunction) {
+    return describe("project", () => {
+        let projectId: string = "";
+
+        beforeAll(async () => {
+            const session: Session = integration.mcpServer().session;
+            session.ensureAuthenticated();
+
+            const apiClient = session.apiClient;
+            const group = await createProject(apiClient);
+            projectId = group.id || "";
+        });
+
+        afterAll(async () => {
+            const session: Session = integration.mcpServer().session;
+            session.ensureAuthenticated();
+
+            const apiClient = session.apiClient;
+            await apiClient.deleteProject({
+                params: {
+                    path: {
+                        groupId: projectId,
+                    },
+                },
+            });
+        });
+
+        const args = {
+            getProjectId: () => projectId,
+        };
+
+        describe("with project", () => {
+            fn(args);
+        });
+    });
+}
+
+export function parseTable(text: string): Record<string, string>[] {
+    const data = text
+        .split("\n")
+        .filter((line) => line.trim() !== "")
+        .map((line) => line.split("|").map((cell) => cell.trim()));
+
+    const headers = data[0];
+    return data
+        .filter((_, index) => index >= 2)
+        .map((cells) => {
+            const row = {};
+            cells.forEach((cell, index) => {
+                row[headers[index]] = cell;
+            });
+            return row;
+        });
+}
+
+export const randomId = new ObjectId().toString();
+
+async function createProject(apiClient: ApiClient): Promise<Group> {
+    const projectName: string = `testProj-` + randomId;
+
+    const orgs = await apiClient.listOrganizations();
+    if (!orgs?.results?.length || !orgs.results[0].id) {
+        throw new Error("No orgs found");
+    }
+
+    const group = await apiClient.createProject({
+        body: {
+            name: projectName,
+            orgId: orgs.results[0].id,
+        } as Group,
+    });
+
+    if (!group?.id) {
+        throw new Error("Failed to create project");
+    }
+
+    return group;
+}