mongo-aggregate

Instructions

Implementation Reference

• src/index.ts:241-261 (handler)

  Handler function that executes the MongoDB aggregation pipeline on the specified collection, formats the results, and returns them in the MCP response format.

  async ({ database: dbName, collection: collectionName, pipeline }) => {
    try {
      const db = await ensureConnection(dbName);
      const collection: Collection = db.collection(collectionName);
      
      const documents = await collection.aggregate(pipeline).toArray();
      
      const formattedOutput = formatJsonOutput(documents);
      
      return {
        content: [
          {
            type: "text",
            text: `Aggregation returned ${documents.length} document(s):\n\n${formattedOutput}`,
          },
        ],
      };
    } catch (error) {
      throw new Error(`Failed to execute aggregation: ${error instanceof Error ? error.message : 'Unknown error'}`);
    }
  }

• src/index.ts:236-240 (schema)

  Input schema using Zod for validating database name, collection name, and aggregation pipeline array.

  {
    database: z.string().describe("Database name"),
    collection: z.string().describe("Collection name"),
    pipeline: z.array(z.record(z.any())).describe("Aggregation pipeline as array of stage objects"),
  },

• src/index.ts:233-262 (registration)

  Registration of the 'mongo-aggregate' tool using server.tool(), including name, description, schema, and inline handler.

  server.tool(
    "mongo-aggregate",
    "Execute aggregation pipeline on a MongoDB collection",
    {
      database: z.string().describe("Database name"),
      collection: z.string().describe("Collection name"),
      pipeline: z.array(z.record(z.any())).describe("Aggregation pipeline as array of stage objects"),
    },
    async ({ database: dbName, collection: collectionName, pipeline }) => {
      try {
        const db = await ensureConnection(dbName);
        const collection: Collection = db.collection(collectionName);
        
        const documents = await collection.aggregate(pipeline).toArray();
        
        const formattedOutput = formatJsonOutput(documents);
        
        return {
          content: [
            {
              type: "text",
              text: `Aggregation returned ${documents.length} document(s):\n\n${formattedOutput}`,
            },
          ],
        };
      } catch (error) {
        throw new Error(`Failed to execute aggregation: ${error instanceof Error ? error.message : 'Unknown error'}`);
      }
    }
  );

• src/index.ts:88-100 (helper)

  Helper function to ensure MongoDB client connection and return the database instance, used by all tools including mongo-aggregate.

  async function ensureConnection(dbName: string): Promise<Db> {
    if (!mongoClient) {
      const uri = getMongoUri();
      mongoClient = new MongoClient(uri);
      await mongoClient.connect();
    }
    
    if (!databases.has(dbName)) {
      databases.set(dbName, mongoClient.db(dbName));
    }
    
    return databases.get(dbName)!;
  }

• src/index.ts:64-78 (helper)

  Helper function to format and truncate large JSON outputs for tool responses, called by the handler.

  function formatJsonOutput(data: unknown): string {
    const truncatedData = truncateForOutput(data);
    let outputText = JSON.stringify(truncatedData, null, 2);
    
    outputText = outputText.replace(
      /"\.\.\.(\d+) more items"/g,
      "...$1 more items"
    );
    outputText = outputText.replace(
      /"\.\.\.(\d+) more properties": "\.\.\.?"/g,
      "...$1 more properties"
    );
    
    return outputText;
  }