Merge branch 'main' into api-error-check

Author: blva

README.md

@@ -67,7 +67,7 @@ You can pass your connection string via args, make sure to use a valid username
 
 #### Option 2: Atlas API credentials args
 
-Use your Atlas API Service Accounts credentials. More details in the [Atlas API Access](#atlas-api-access) section.
+Use your Atlas API Service Accounts credentials. Must follow all the steps in [Atlas API Access](#atlas-api-access) section.
 
 ```json
 {
@@ -87,9 +87,24 @@ Use your Atlas API Service Accounts credentials. More details in the [Atlas API
 }
 ```
 
-#### Other options
+### Option 3: Standalone Service using command arguments
 
-Alternatively you can use environment variables in the config file or set them and run the server via npx.
+Start Server using npx command:
+
+```shell
+ npx -y mongodb-mcp-server --apiClientId="your-atlas-service-accounts-client-id" --apiClientSecret="your-atlas-service-accounts-client-secret"
+```
+
+- For a complete list of arguments see [Configuration Options](#configuration-options)
+- To configure your Atlas Service Accounts credentials please refer to [Atlas API Access](#atlas-api-access)
+
+#### Option 4: Standalone Service using environment variables
+
+```shell
+ npx -y mongodb-mcp-server
+```
+
+You can use environment variables in the config file or set them and run the server via npx.
 
 - Connection String via environment variables in the MCP file [example](#connection-string-with-environment-variables)
 - Atlas API credentials via environment variables in the MCP file [example](#atlas-api-credentials-with-environment-variables)
@@ -229,7 +244,7 @@ To learn more about Service Accounts, check the [MongoDB Atlas documentation](ht
    - After creation, you'll be shown the Client ID and Client Secret
    - **Important:** Copy and save the Client Secret immediately as it won't be displayed again
 
-3. **Add Access List Entry (Optional but recommended):**
+3. **Add Access List Entry:**
 
    - Add your IP address to the API access list
 

scripts/filter.ts

@@ -25,9 +25,13 @@ function filterOpenapi(openapi: OpenAPIV3_1.Document): OpenAPIV3_1.Document {
         "createProject",
         "deleteProject",
         "listClusters",
+        "listFlexClusters",
         "getCluster",
+        "getFlexCluster",
         "createCluster",
+        "createFlexCluster",
         "deleteCluster",
+        "deleteFlexCluster",
         "listClustersForAllProjects",
         "createDatabaseUser",
         "deleteDatabaseUser",

src/common/atlas/apiClient.ts

@@ -275,6 +275,46 @@ export class ApiClient {
         }
     }
 
+    async listFlexClusters(options: FetchOptions<operations["listFlexClusters"]>) {
+        const { data, error, response } = await this.client.GET("/api/atlas/v2/groups/{groupId}/flexClusters", options);
+        if (error) {
+            throw ApiClientError.fromError(response, error);
+        }
+        return data;
+    }
+
+    async createFlexCluster(options: FetchOptions<operations["createFlexCluster"]>) {
+        const { data, error, response } = await this.client.POST(
+            "/api/atlas/v2/groups/{groupId}/flexClusters",
+            options
+        );
+        if (error) {
+            throw ApiClientError.fromError(response, error);
+        }
+        return data;
+    }
+
+    async deleteFlexCluster(options: FetchOptions<operations["deleteFlexCluster"]>) {
+        const { error, response } = await this.client.DELETE(
+            "/api/atlas/v2/groups/{groupId}/flexClusters/{name}",
+            options
+        );
+        if (error) {
+            throw ApiClientError.fromError(response, error);
+        }
+    }
+
+    async getFlexCluster(options: FetchOptions<operations["getFlexCluster"]>) {
+        const { data, error, response } = await this.client.GET(
+            "/api/atlas/v2/groups/{groupId}/flexClusters/{name}",
+            options
+        );
+        if (error) {
+            throw ApiClientError.fromError(response, error);
+        }
+        return data;
+    }
+
     async listOrganizations(options?: FetchOptions<operations["listOrganizations"]>) {
         const { data, error, response } = await this.client.GET("/api/atlas/v2/orgs", options);
         if (error) {

src/common/atlas/cluster.ts

@@ -0,0 +1,95 @@
+import { ClusterDescription20240805, FlexClusterDescription20241113 } from "./openapi.js";
+import { ApiClient } from "./apiClient.js";
+import logger, { LogId } from "../../logger.js";
+
+export interface Cluster {
+    name?: string;
+    instanceType: "FREE" | "DEDICATED" | "FLEX";
+    instanceSize?: string;
+    state?: "IDLE" | "CREATING" | "UPDATING" | "DELETING" | "REPAIRING";
+    mongoDBVersion?: string;
+    connectionString?: string;
+}
+
+export function formatFlexCluster(cluster: FlexClusterDescription20241113): Cluster {
+    return {
+        name: cluster.name,
+        instanceType: "FLEX",
+        instanceSize: undefined,
+        state: cluster.stateName,
+        mongoDBVersion: cluster.mongoDBVersion,
+        connectionString: cluster.connectionStrings?.standardSrv || cluster.connectionStrings?.standard,
+    };
+}
+
+export function formatCluster(cluster: ClusterDescription20240805): Cluster {
+    const regionConfigs = (cluster.replicationSpecs || [])
+        .map(
+            (replicationSpec) =>
+                (replicationSpec.regionConfigs || []) as {
+                    providerName: string;
+                    electableSpecs?: {
+                        instanceSize: string;
+                    };
+                    readOnlySpecs?: {
+                        instanceSize: string;
+                    };
+                    analyticsSpecs?: {
+                        instanceSize: string;
+                    };
+                }[]
+        )
+        .flat()
+        .map((regionConfig) => {
+            return {
+                providerName: regionConfig.providerName,
+                instanceSize:
+                    regionConfig.electableSpecs?.instanceSize ||
+                    regionConfig.readOnlySpecs?.instanceSize ||
+                    regionConfig.analyticsSpecs?.instanceSize,
+            };
+        });
+
+    const instanceSize = (regionConfigs.length <= 0 ? undefined : regionConfigs[0].instanceSize) || "UNKNOWN";
+
+    const clusterInstanceType = instanceSize == "M0" ? "FREE" : "DEDICATED";
+
+    return {
+        name: cluster.name,
+        instanceType: clusterInstanceType,
+        instanceSize: clusterInstanceType == "DEDICATED" ? instanceSize : undefined,
+        state: cluster.stateName,
+        mongoDBVersion: cluster.mongoDBVersion,
+        connectionString: cluster.connectionStrings?.standardSrv || cluster.connectionStrings?.standard,
+    };
+}
+
+export async function inspectCluster(apiClient: ApiClient, projectId: string, clusterName: string): Promise<Cluster> {
+    try {
+        const cluster = await apiClient.getCluster({
+            params: {
+                path: {
+                    groupId: projectId,
+                    clusterName,
+                },
+            },
+        });
+        return formatCluster(cluster);
+    } catch (error) {
+        try {
+            const cluster = await apiClient.getFlexCluster({
+                params: {
+                    path: {
+                        groupId: projectId,
+                        name: clusterName,
+                    },
+                },
+            });
+            return formatFlexCluster(cluster);
+        } catch (flexError) {
+            const err = flexError instanceof Error ? flexError : new Error(String(flexError));
+            logger.error(LogId.atlasInspectFailure, "inspect-cluster", `error inspecting cluster: ${err.message}`);
+            throw error;
+        }
+    }
+}