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); }