MongoDB MCP Server

Instructions

Implementation Reference

• src/tools/atlas/read/listClusters.ts:26-54 (handler)

  The execute method implements the core logic of the 'atlas-list-clusters' tool, listing clusters across all projects or filtered by a specific project ID using Atlas API calls.

  protected async execute({ projectId }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
      if (!projectId) {
          const data = await this.session.apiClient.listClusterDetails();
  
          return this.formatAllClustersTable(data);
      } else {
          const project = await this.session.apiClient.getGroup({
              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);
      }
  }

• src/tools/atlas/read/listClusters.ts:14-24 (schema)

  Schema definition for tool arguments (projectId optional) and tool metadata including name, description, operation type, and argsShape.

  export const ListClustersArgs = {
      projectId: AtlasArgs.projectId().describe("Atlas project ID to filter clusters").optional(),
  };
  
  export class ListClustersTool extends AtlasToolBase {
      public name = "atlas-list-clusters";
      protected description = "List MongoDB Atlas clusters";
      static operationType: OperationType = "read";
      protected argsShape = {
          ...ListClustersArgs,
      };

• src/tools/atlas/tools.ts:1-1 (registration)

  Re-export of ListClustersTool making it available for aggregation in higher-level tool collections.

  export { ListClustersTool } from "./read/listClusters.js";

• src/tools/atlas/read/listClusters.ts:56-79 (helper)

  Helper method to format and return a table of clusters from all projects.

  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) => ({
                  projectName: result.groupName,
                  projectId: result.groupId,
                  clusterName: cluster.name,
              }));
          })
          .flat();
      if (!formattedClusters.length) {
          throw new Error("No clusters found.");
      }
  
      return {
          content: formatUntrustedData(
              `Found ${formattedClusters.length} clusters across all projects`,
              JSON.stringify(formattedClusters)
          ),
      };
  }

• src/tools/atlas/read/listClusters.ts:81-102 (helper)

  Helper method to format and return a table of clusters (including flex clusters) for a specific project.

  private formatClustersTable(
      project: Group,
      clusters?: PaginatedClusterDescription20240805,
      flexClusters?: PaginatedFlexClusters20241113
  ): CallToolResult {
      // Check if both traditional clusters and flex clusters are absent
      if (!clusters?.results?.length && !flexClusters?.results?.length) {
          return {
              content: [{ type: "text", text: "No clusters found." }],
          };
      }
      const formattedClusters = clusters?.results?.map((cluster) => formatCluster(cluster)) || [];
      const formattedFlexClusters = flexClusters?.results?.map((cluster) => formatFlexCluster(cluster)) || [];
      const allClusters = [...formattedClusters, ...formattedFlexClusters];
  
      return {
          content: formatUntrustedData(
              `Found ${allClusters.length} clusters in project "${project.name}" (${project.id}):`,
              JSON.stringify(allClusters)
          ),
      };
  }