octodet-elasticsearch-mcp

Instructions

Implementation Reference

• src/index.ts:696-766 (handler)

  The handler function that executes the delete_by_query tool logic. It constructs the parameters including index, query body, conflicts, max_docs, and refresh options, calls esService.deleteByQuery(params), formats the response summary including deleted count, failures, and time taken, and returns formatted text content.

  async ({ index, query, conflicts, maxDocs, refresh }) => {
    try {
      const params: Record<string, any> = {
        index,
        body: {
          query,
        },
        refresh: refresh !== false, // true by default unless explicitly set to false
      };
  
      if (conflicts) params.conflicts = conflicts;
      if (maxDocs) params.max_docs = maxDocs;
  
      const response = await esService.deleteByQuery(params);
  
      // Format the response for better readability
      let resultText = `Delete by query completed successfully in index '${index}':\n`;
      resultText += `- Total documents processed: ${response.total}\n`;
      resultText += `- Documents deleted: ${response.deleted}\n`;
      resultText += `- Deletion failures: ${
        response.failures?.length || 0
      }\n`;
      resultText += `- Time taken: ${response.took}ms`;
  
      // Add version conflicts if any occurred
      if (response.version_conflicts && response.version_conflicts > 0) {
        resultText += `\n- Version conflicts: ${response.version_conflicts}`;
      }
  
      // Add detailed failure information
      if (response.failures && response.failures.length > 0) {
        resultText += "\n\nFailures:";
        response.failures.slice(0, 5).forEach((failure: any, idx: number) => {
          resultText += `\n${idx + 1}. ID: ${
            failure.id || "unknown"
          }, Reason: ${failure.cause?.reason || "Unknown"}`;
        });
  
        if (response.failures.length > 5) {
          resultText += `\n...and ${
            response.failures.length - 5
          } more failures.`;
        }
      }
  
      return {
        content: [
          {
            type: "text",
            text: resultText,
          },
        ],
      };
    } catch (error) {
      console.error(
        `Delete by query failed: ${
          error instanceof Error ? error.message : String(error)
        }`
      );
      return {
        content: [
          {
            type: "text",
            text: `Error: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
      };
    }
  }

• src/index.ts:667-695 (schema)

  Zod schema defining input parameters for the delete_by_query tool: index (required string), query (required object), conflicts (optional enum), maxDocs (optional positive int), refresh (optional boolean, default true).

  {
    index: z
      .string()
      .trim()
      .min(1, "Index name is required")
      .describe("Name of the Elasticsearch index to delete documents from"),
    query: z
      .record(z.any())
      .describe("Elasticsearch query to select documents for deletion"),
    conflicts: z
      .enum(["abort", "proceed"])
      .optional()
      .describe(
        "What to do when version conflicts occur during the deletion"
      ),
    maxDocs: z
      .number()
      .int()
      .positive()
      .optional()
      .describe("Limit the number of documents to delete"),
    refresh: z
      .boolean()
      .optional()
      .default(true)
      .describe(
        "Should the index be refreshed after the deletion (defaults to true)"
      ),
  },

• src/index.ts:664-766 (registration)

  Registration of the delete_by_query tool using server.tool, including name, description, input schema, and handler function.

  server.tool(
    "delete_by_query",
    "Delete documents in an Elasticsearch index based on a query",
    {
      index: z
        .string()
        .trim()
        .min(1, "Index name is required")
        .describe("Name of the Elasticsearch index to delete documents from"),
      query: z
        .record(z.any())
        .describe("Elasticsearch query to select documents for deletion"),
      conflicts: z
        .enum(["abort", "proceed"])
        .optional()
        .describe(
          "What to do when version conflicts occur during the deletion"
        ),
      maxDocs: z
        .number()
        .int()
        .positive()
        .optional()
        .describe("Limit the number of documents to delete"),
      refresh: z
        .boolean()
        .optional()
        .default(true)
        .describe(
          "Should the index be refreshed after the deletion (defaults to true)"
        ),
    },
    async ({ index, query, conflicts, maxDocs, refresh }) => {
      try {
        const params: Record<string, any> = {
          index,
          body: {
            query,
          },
          refresh: refresh !== false, // true by default unless explicitly set to false
        };
  
        if (conflicts) params.conflicts = conflicts;
        if (maxDocs) params.max_docs = maxDocs;
  
        const response = await esService.deleteByQuery(params);
  
        // Format the response for better readability
        let resultText = `Delete by query completed successfully in index '${index}':\n`;
        resultText += `- Total documents processed: ${response.total}\n`;
        resultText += `- Documents deleted: ${response.deleted}\n`;
        resultText += `- Deletion failures: ${
          response.failures?.length || 0
        }\n`;
        resultText += `- Time taken: ${response.took}ms`;
  
        // Add version conflicts if any occurred
        if (response.version_conflicts && response.version_conflicts > 0) {
          resultText += `\n- Version conflicts: ${response.version_conflicts}`;
        }
  
        // Add detailed failure information
        if (response.failures && response.failures.length > 0) {
          resultText += "\n\nFailures:";
          response.failures.slice(0, 5).forEach((failure: any, idx: number) => {
            resultText += `\n${idx + 1}. ID: ${
              failure.id || "unknown"
            }, Reason: ${failure.cause?.reason || "Unknown"}`;
          });
  
          if (response.failures.length > 5) {
            resultText += `\n...and ${
              response.failures.length - 5
            } more failures.`;
          }
        }
  
        return {
          content: [
            {
              type: "text",
              text: resultText,
            },
          ],
        };
      } catch (error) {
        console.error(
          `Delete by query failed: ${
            error instanceof Error ? error.message : String(error)
          }`
        );
        return {
          content: [
            {
              type: "text",
              text: `Error: ${
                error instanceof Error ? error.message : String(error)
              }`,
            },
          ],
        };
      }
    }

• src/utils/elasticsearchService.ts:223-225 (helper)

  Helper method in ElasticsearchService that proxies the deleteByQuery call to the underlying Elasticsearch client.

  async deleteByQuery(params: any): Promise<any> {
    return await this.client.deleteByQuery(params);
  }