mongodb-mcp-server 0.0.4

package/src/tools/atlas/inspectAccessList.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { AtlasToolBase } from "./atlasTool.js";
+import { ToolArgs, OperationType } from "../tool.js";
+
+export class InspectAccessListTool extends AtlasToolBase {
+    protected name = "atlas-inspect-access-list";
+    protected description = "Inspect Ip/CIDR ranges with access to your MongoDB Atlas clusters.";
+    protected operationType: OperationType = "read";
+    protected argsShape = {
+        projectId: z.string().describe("Atlas project ID"),
+    };
+
+    protected async execute({ projectId }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        this.session.ensureAuthenticated();
+
+        const accessList = await this.session.apiClient.listProjectIpAccessLists({
+            params: {
+                path: {
+                    groupId: projectId,
+                },
+            },
+        });
+
+        if (!accessList?.results?.length) {
+            throw new Error("No access list entries found.");
+        }
+
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `IP ADDRESS | CIDR | COMMENT
+------|------|------
+${(accessList.results || [])
+    .map((entry) => {
+        return `${entry.ipAddress} | ${entry.cidrBlock} | ${entry.comment}`;
+    })
+    .join("\n")}`,
+                },
+            ],
+        };
+    }
+}

package/src/tools/atlas/inspectCluster.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { AtlasToolBase } from "./atlasTool.js";
+import { ToolArgs, OperationType } from "../tool.js";
+import { ClusterDescription20240805 } from "../../common/atlas/openapi.js";
+
+export class InspectClusterTool extends AtlasToolBase {
+    protected name = "atlas-inspect-cluster";
+    protected description = "Inspect MongoDB Atlas cluster";
+    protected operationType: OperationType = "read";
+    protected argsShape = {
+        projectId: z.string().describe("Atlas project ID"),
+        clusterName: z.string().describe("Atlas cluster name"),
+    };
+
+    protected async execute({ projectId, clusterName }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        this.session.ensureAuthenticated();
+
+        const cluster = await this.session.apiClient.getCluster({
+            params: {
+                path: {
+                    groupId: projectId,
+                    clusterName,
+                },
+            },
+        });
+
+        return this.formatOutput(cluster);
+    }
+
+    private formatOutput(cluster?: ClusterDescription20240805): CallToolResult {
+        if (!cluster) {
+            throw new Error("Cluster not found");
+        }
+
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Cluster Name | State | MongoDB Version | Connection String
+----------------|----------------|----------------|----------------|----------------
+${cluster.name} | ${cluster.stateName} | ${cluster.mongoDBVersion || "N/A"} | ${cluster.connectionStrings?.standard || "N/A"}`,
+                },
+            ],
+        };
+    }
+}

package/src/tools/atlas/listClusters.ts

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { AtlasToolBase } from "./atlasTool.js";
+import { ToolArgs, OperationType } from "../tool.js";
+import { PaginatedClusterDescription20240805, PaginatedOrgGroupView, Group } from "../../common/atlas/openapi.js";
+
+export class ListClustersTool extends AtlasToolBase {
+    protected name = "atlas-list-clusters";
+    protected description = "List MongoDB Atlas clusters";
+    protected operationType: OperationType = "read";
+    protected argsShape = {
+        projectId: z.string().describe("Atlas project ID to filter clusters").optional(),
+    };
+
+    protected async execute({ projectId }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        this.session.ensureAuthenticated();
+
+        if (!projectId) {
+            const data = await this.session.apiClient.listClustersForAllProjects();
+
+            return this.formatAllClustersTable(data);
+        } else {
+            const project = await this.session.apiClient.getProject({
+                params: {
+                    path: {
+                        groupId: projectId,
+                    },
+                },
+            });
+
+            if (!project?.id) {
+                throw new Error(`Project with ID "${projectId}" not found.`);
+            }
+
+            const data = await this.session.apiClient.listClusters({
+                params: {
+                    path: {
+                        groupId: project.id || "",
+                    },
+                },
+            });
+
+            return this.formatClustersTable(project, data);
+        }
+    }
+
+    private formatAllClustersTable(clusters?: PaginatedOrgGroupView): CallToolResult {
+        if (!clusters?.results?.length) {
+            throw new Error("No clusters found.");
+        }
+        const formattedClusters = clusters.results
+            .map((result) => {
+                return (result.clusters || []).map((cluster) => {
+                    return { ...result, ...cluster, clusters: undefined };
+                });
+            })
+            .flat();
+        if (!formattedClusters.length) {
+            throw new Error("No clusters found.");
+        }
+        const rows = formattedClusters
+            .map((cluster) => {
+                return `${cluster.groupName} (${cluster.groupId}) | ${cluster.name}`;
+            })
+            .join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Project | Cluster Name
+----------------|----------------
+${rows}`,
+                },
+            ],
+        };
+    }
+
+    private formatClustersTable(project: Group, clusters?: PaginatedClusterDescription20240805): CallToolResult {
+        if (!clusters?.results?.length) {
+            throw new Error("No clusters found.");
+        }
+        const rows = clusters.results
+            .map((cluster) => {
+                const connectionString = cluster.connectionStrings?.standard || "N/A";
+                const mongoDBVersion = cluster.mongoDBVersion || "N/A";
+                return `${cluster.name} | ${cluster.stateName} | ${mongoDBVersion} | ${connectionString}`;
+            })
+            .join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Here are your MongoDB Atlas clusters in project "${project.name}" (${project.id}):`,
+                },
+                {
+                    type: "text",
+                    text: `Cluster Name | State | MongoDB Version | Connection String
+----------------|----------------|----------------|----------------|----------------
+${rows}`,
+                },
+            ],
+        };
+    }
+}

package/src/tools/atlas/listDBUsers.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { AtlasToolBase } from "./atlasTool.js";
+import { ToolArgs, OperationType } from "../tool.js";
+import { DatabaseUserRole, UserScope } from "../../common/atlas/openapi.js";
+
+export class ListDBUsersTool extends AtlasToolBase {
+    protected name = "atlas-list-db-users";
+    protected description = "List MongoDB Atlas database users";
+    protected operationType: OperationType = "read";
+    protected argsShape = {
+        projectId: z.string().describe("Atlas project ID to filter DB users"),
+    };
+
+    protected async execute({ projectId }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        this.session.ensureAuthenticated();
+
+        const data = await this.session.apiClient.listDatabaseUsers({
+            params: {
+                path: {
+                    groupId: projectId,
+                },
+            },
+        });
+
+        if (!data?.results?.length) {
+            throw new Error("No database users found.");
+        }
+
+        const output =
+            `Username | Roles | Scopes
+----------------|----------------|----------------
+` +
+            data.results
+                .map((user) => {
+                    return `${user.username} | ${formatRoles(user.roles)} | ${formatScopes(user.scopes)}`;
+                })
+                .join("\n");
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    }
+}
+
+function formatRoles(roles?: DatabaseUserRole[]) {
+    if (!roles?.length) {
+        return "N/A";
+    }
+    return roles
+        .map(
+            (role) =>
+                `${role.roleName}${role.databaseName ? `@${role.databaseName}${role.collectionName ? `:${role.collectionName}` : ""}` : ""}`
+        )
+        .join(", ");
+}
+
+function formatScopes(scopes?: UserScope[]) {
+    if (!scopes?.length) {
+        return "All";
+    }
+    return scopes.map((scope) => `${scope.type}:${scope.name}`).join(", ");
+}

package/src/tools/atlas/listOrgs.ts

@@ -0,0 +1,34 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { AtlasToolBase } from "./atlasTool.js";
+import { OperationType } from "../tool.js";
+
+export class ListOrganizationsTool extends AtlasToolBase {
+    protected name = "atlas-list-orgs";
+    protected description = "List MongoDB Atlas organizations";
+    protected operationType: OperationType = "read";
+    protected argsShape = {};
+
+    protected async execute(): Promise<CallToolResult> {
+        this.session.ensureAuthenticated();
+
+        const data = await this.session.apiClient.listOrganizations();
+
+        if (!data?.results?.length) {
+            throw new Error("No projects found in your MongoDB Atlas account.");
+        }
+
+        // Format projects as a table
+        const output =
+            `Organization Name | Organization ID
+----------------| ----------------
+` +
+            data.results
+                .map((org) => {
+                    return `${org.name} | ${org.id}`;
+                })
+                .join("\n");
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    }
+}

package/src/tools/atlas/listProjects.ts

@@ -0,0 +1,46 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { AtlasToolBase } from "./atlasTool.js";
+import { OperationType } from "../tool.js";
+import { z } from "zod";
+import { ToolArgs } from "../tool.js";
+
+export class ListProjectsTool extends AtlasToolBase {
+    protected name = "atlas-list-projects";
+    protected description = "List MongoDB Atlas projects";
+    protected operationType: OperationType = "read";
+    protected argsShape = {
+        orgId: z.string().describe("Atlas organization ID to filter projects").optional(),
+    };
+
+    protected async execute({ orgId }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        this.session.ensureAuthenticated();
+
+        const data = orgId
+            ? await this.session.apiClient.listOrganizationProjects({
+                  params: {
+                      path: {
+                          orgId,
+                      },
+                  },
+              })
+            : await this.session.apiClient.listProjects();
+
+        if (!data?.results?.length) {
+            throw new Error("No projects found in your MongoDB Atlas account.");
+        }
+
+        // Format projects as a table
+        const rows = data.results
+            .map((project) => {
+                const createdAt = project.created ? new Date(project.created).toLocaleString() : "N/A";
+                return `${project.name} | ${project.id} | ${createdAt}`;
+            })
+            .join("\n");
+        const formattedProjects = `Project Name | Project ID | Created At
+----------------| ----------------| ----------------
+${rows}`;
+        return {
+            content: [{ type: "text", text: formattedProjects }],
+        };
+    }
+}

package/src/tools/atlas/tools.ts

@@ -0,0 +1,23 @@
+import { ListClustersTool } from "./listClusters.js";
+import { ListProjectsTool } from "./listProjects.js";
+import { InspectClusterTool } from "./inspectCluster.js";
+import { CreateFreeClusterTool } from "./createFreeCluster.js";
+import { CreateAccessListTool } from "./createAccessList.js";
+import { InspectAccessListTool } from "./inspectAccessList.js";
+import { ListDBUsersTool } from "./listDBUsers.js";
+import { CreateDBUserTool } from "./createDBUser.js";
+import { CreateProjectTool } from "./createProject.js";
+import { ListOrganizationsTool } from "./listOrgs.js";
+
+export const AtlasTools = [
+    ListClustersTool,
+    ListProjectsTool,
+    InspectClusterTool,
+    CreateFreeClusterTool,
+    CreateAccessListTool,
+    InspectAccessListTool,
+    ListDBUsersTool,
+    CreateDBUserTool,
+    CreateProjectTool,
+    ListOrganizationsTool,
+];

package/src/tools/mongodb/create/createCollection.ts

@@ -0,0 +1,26 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
+import { OperationType, ToolArgs } from "../../tool.js";
+
+export class CreateCollectionTool extends MongoDBToolBase {
+    protected name = "create-collection";
+    protected description =
+        "Creates a new collection in a database. If the database doesn't exist, it will be created automatically.";
+    protected argsShape = DbOperationArgs;
+
+    protected operationType: OperationType = "create";
+
+    protected async execute({ collection, database }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        const provider = await this.ensureConnected();
+        await provider.createCollection(database, collection);
+
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Collection "${collection}" created in database "${database}".`,
+                },
+            ],
+        };
+    }
+}

package/src/tools/mongodb/create/createIndex.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
+import { ToolArgs, OperationType } from "../../tool.js";
+import { IndexDirection } from "mongodb";
+
+export class CreateIndexTool extends MongoDBToolBase {
+    protected name = "create-index";
+    protected description = "Create an index for a collection";
+    protected argsShape = {
+        ...DbOperationArgs,
+        keys: z.record(z.string(), z.custom<IndexDirection>()).describe("The index definition"),
+        name: z.string().optional().describe("The name of the index"),
+    };
+
+    protected operationType: OperationType = "create";
+
+    protected async execute({
+        database,
+        collection,
+        keys,
+        name,
+    }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        const provider = await this.ensureConnected();
+        const indexes = await provider.createIndexes(database, collection, [
+            {
+                key: keys,
+                name,
+            },
+        ]);
+
+        return {
+            content: [
+                {
+                    text: `Created the index "${indexes[0]}" on collection "${collection}" in database "${database}"`,
+                    type: "text",
+                },
+            ],
+        };
+    }
+}

package/src/tools/mongodb/create/insertMany.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
+import { ToolArgs, OperationType } from "../../tool.js";
+
+export class InsertManyTool extends MongoDBToolBase {
+    protected name = "insert-many";
+    protected description = "Insert an array of documents into a MongoDB collection";
+    protected argsShape = {
+        ...DbOperationArgs,
+        documents: z
+            .array(z.object({}).passthrough().describe("An individual MongoDB document"))
+            .describe(
+                "The array of documents to insert, matching the syntax of the document argument of db.collection.insertMany()"
+            ),
+    };
+    protected operationType: OperationType = "create";
+
+    protected async execute({
+        database,
+        collection,
+        documents,
+    }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        const provider = await this.ensureConnected();
+        const result = await provider.insertMany(database, collection, documents);
+
+        return {
+            content: [
+                {
+                    text: `Inserted \`${result.insertedCount}\` document(s) into collection "${collection}"`,
+                    type: "text",
+                },
+                {
+                    text: `Inserted IDs: ${Object.values(result.insertedIds).join(", ")}`,
+                    type: "text",
+                },
+            ],
+        };
+    }
+}

package/src/tools/mongodb/delete/deleteMany.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
+import { ToolArgs, OperationType } from "../../tool.js";
+
+export class DeleteManyTool extends MongoDBToolBase {
+    protected name = "delete-many";
+    protected description = "Removes all documents that match the filter from a MongoDB collection";
+    protected argsShape = {
+        ...DbOperationArgs,
+        filter: z
+            .object({})
+            .passthrough()
+            .optional()
+            .describe(
+                "The query filter, specifying the deletion criteria. Matches the syntax of the filter argument of db.collection.deleteMany()"
+            ),
+    };
+    protected operationType: OperationType = "delete";
+
+    protected async execute({
+        database,
+        collection,
+        filter,
+    }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        const provider = await this.ensureConnected();
+        const result = await provider.deleteMany(database, collection, filter);
+
+        return {
+            content: [
+                {
+                    text: `Deleted \`${result.deletedCount}\` document(s) from collection "${collection}"`,
+                    type: "text",
+                },
+            ],
+        };
+    }
+}

package/src/tools/mongodb/delete/dropCollection.ts

@@ -0,0 +1,27 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
+import { ToolArgs, OperationType } from "../../tool.js";
+
+export class DropCollectionTool extends MongoDBToolBase {
+    protected name = "drop-collection";
+    protected description =
+        "Removes a collection or view from the database. The method also removes any indexes associated with the dropped collection.";
+    protected argsShape = {
+        ...DbOperationArgs,
+    };
+    protected operationType: OperationType = "delete";
+
+    protected async execute({ database, collection }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        const provider = await this.ensureConnected();
+        const result = await provider.dropCollection(database, collection);
+
+        return {
+            content: [
+                {
+                    text: `${result ? "Successfully dropped" : "Failed to drop"} collection "${collection}" from database "${database}"`,
+                    type: "text",
+                },
+            ],
+        };
+    }
+}

package/src/tools/mongodb/delete/dropDatabase.ts

@@ -0,0 +1,26 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
+import { ToolArgs, OperationType } from "../../tool.js";
+
+export class DropDatabaseTool extends MongoDBToolBase {
+    protected name = "drop-database";
+    protected description = "Removes the specified database, deleting the associated data files";
+    protected argsShape = {
+        database: DbOperationArgs.database,
+    };
+    protected operationType: OperationType = "delete";
+
+    protected async execute({ database }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        const provider = await this.ensureConnected();
+        const result = await provider.dropDatabase(database);
+
+        return {
+            content: [
+                {
+                    text: `${result.ok ? "Successfully dropped" : "Failed to drop"} database "${database}"`,
+                    type: "text",
+                },
+            ],
+        };
+    }
+}

package/src/tools/mongodb/metadata/collectionSchema.ts

@@ -0,0 +1,41 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
+import { ToolArgs, OperationType } from "../../tool.js";
+import { parseSchema, SchemaField } from "mongodb-schema";
+
+export class CollectionSchemaTool extends MongoDBToolBase {
+    protected name = "collection-schema";
+    protected description = "Describe the schema for a collection";
+    protected argsShape = DbOperationArgs;
+
+    protected operationType: OperationType = "metadata";
+
+    protected async execute({ database, collection }: ToolArgs<typeof DbOperationArgs>): Promise<CallToolResult> {
+        const provider = await this.ensureConnected();
+        const documents = await provider.find(database, collection, {}, { limit: 5 }).toArray();
+        const schema = await parseSchema(documents);
+
+        return {
+            content: [
+                {
+                    text: `Found ${schema.fields.length} fields in the schema for \`${database}.${collection}\``,
+                    type: "text",
+                },
+                {
+                    text: this.formatFieldOutput(schema.fields),
+                    type: "text",
+                },
+            ],
+        };
+    }
+
+    private formatFieldOutput(fields: SchemaField[]): string {
+        let result = "| Field | Type | Confidence |\n";
+        result += "|-------|------|-------------|\n";
+        for (const field of fields) {
+            const fieldType = Array.isArray(field.type) ? field.type.join(", ") : field.type;
+            result += `| ${field.name} | \`${fieldType}\` | ${(field.probability * 100).toFixed(0)}% |\n`;
+        }
+        return result;
+    }
+}

package/src/tools/mongodb/metadata/collectionStorageSize.ts

@@ -0,0 +1,30 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
+import { ToolArgs, OperationType } from "../../tool.js";
+
+export class CollectionStorageSizeTool extends MongoDBToolBase {
+    protected name = "collection-storage-size";
+    protected description = "Gets the size of the collection in MB";
+    protected argsShape = DbOperationArgs;
+
+    protected operationType: OperationType = "metadata";
+
+    protected async execute({ database, collection }: ToolArgs<typeof DbOperationArgs>): Promise<CallToolResult> {
+        const provider = await this.ensureConnected();
+        const [{ value }] = (await provider
+            .aggregate(database, collection, [
+                { $collStats: { storageStats: {} } },
+                { $group: { _id: null, value: { $sum: "$storageStats.storageSize" } } },
+            ])
+            .toArray()) as [{ value: number }];
+
+        return {
+            content: [
+                {
+                    text: `The size of \`${database}.${collection}\` is \`${(value / 1024 / 1024).toFixed(2)} MB\``,
+                    type: "text",
+                },
+            ],
+        };
+    }
+}