explain_query

Instructions

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "collection": "<collection>",
      "filter": "<filter>"
    },
    "name": "explain_query"
  }
}

Implementation Reference

• src/index.ts:1241-1277 (handler)

  Handler for the 'explain_query' tool. Builds a MongoDB find query based on provided filter, projection, and sort, then executes .explain() to retrieve the query execution plan, and returns it as formatted JSON.

  case 'explain_query': {
    const { database, collection, filter, projection, sort } = request.params
      .arguments as {
      database?: string;
      collection: string;
      filter: object;
      projection?: object;
      sort?: Sort;
    };
    const dbName = database || this.defaultDatabase;
    if (!dbName) {
      throw new McpError(
        ErrorCode.InvalidRequest,
        'Database name is required when no default database is configured'
      );
    }
  
    const db = client.db(dbName);
    let query = db.collection(collection).find(filter);
  
    if (projection) {
      query = query.project(projection);
    }
    if (sort) {
      query = query.sort(sort);
    }
  
    const explanation = await query.explain();
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(explanation, null, 2),
        },
      ],
    };
  }

• src/index.ts:600-637 (registration)

  Registration of the 'explain_query' tool in the ListToolsRequestSchema handler. Includes the tool name, description, and input schema definition.

          {
            name: 'explain_query',
            description: `Get the execution plan for a query.
  
  Helps understand:
  - How MongoDB will execute the query
  - Which indexes will be used
  - Number of documents examined
  - Execution stages and timing
  
  Use this to optimize slow queries.`,
            inputSchema: {
              type: 'object',
              properties: {
                database: {
                  type: 'string',
                  description: 'Database name (optional if default database is configured)',
                },
                collection: {
                  type: 'string',
                  description: 'Collection name',
                },
                filter: {
                  type: 'object',
                  description: 'MongoDB query filter to explain',
                },
                projection: {
                  type: 'object',
                  description: 'MongoDB projection (optional)',
                },
                sort: {
                  type: 'object',
                  description: 'MongoDB sort specification (optional)',
                },
              },
              required: ['collection', 'filter'],
            },
          },

• src/index.ts:611-637 (schema)

  Input schema definition for the 'explain_query' tool, specifying parameters like database, collection, filter, projection, and sort.

    inputSchema: {
      type: 'object',
      properties: {
        database: {
          type: 'string',
          description: 'Database name (optional if default database is configured)',
        },
        collection: {
          type: 'string',
          description: 'Collection name',
        },
        filter: {
          type: 'object',
          description: 'MongoDB query filter to explain',
        },
        projection: {
          type: 'object',
          description: 'MongoDB projection (optional)',
        },
        sort: {
          type: 'object',
          description: 'MongoDB sort specification (optional)',
        },
      },
      required: ['collection', 'filter'],
    },
  },