octodet-elasticsearch-mcp

Instructions

Implementation Reference

• src/index.ts:230-323 (handler)

  The main handler function for the 'search' MCP tool. It enhances the query body with script_fields if provided, performs the search using ElasticsearchService, processes the results including metadata, aggregations, highlights, script fields, and source data, and formats them into MCP-compliant text content fragments.
  async ({ index, queryBody, scriptFields }, extra) => { try { // Add script_fields to the query body if provided const enhancedQueryBody = { ...queryBody }; if (scriptFields && Object.keys(scriptFields).length > 0) { enhancedQueryBody.script_fields = scriptFields; } const result = await esService.search(index, enhancedQueryBody); // Extract the 'from' parameter from queryBody, defaulting to 0 if not provided const from = queryBody.from ?? 0; const contentFragments: TextContent[] = []; // Add metadata about the search results contentFragments.push({ type: "text", text: `Total results: ${ typeof result.hits.total === "number" ? result.hits.total : result.hits.total?.value ?? 0 }, showing ${result.hits.hits.length} from position ${from}`, }); // Add aggregation results if present if (result.aggregations) { contentFragments.push({ type: "text", text: `Aggregations: ${JSON.stringify( result.aggregations, null, 2 )}`, }); } // Process and add individual hit results result.hits.hits.forEach((hit: any) => { const highlightedFields = hit.highlight ?? {}; const sourceData = hit._source ?? {}; const scriptFieldsData = hit.fields ?? {}; let content = `Document ID: ${hit._id}\nScore: ${hit._score}\n\n`; // Add script fields results for (const [field, value] of Object.entries(scriptFieldsData)) { content += `${field} (script): ${JSON.stringify(value)}\n`; } // Add highlighted fields for (const [field, highlights] of Object.entries(highlightedFields)) { if (Array.isArray(highlights) && highlights.length > 0) { content += `${field} (highlighted): ${( highlights as string[] ).join(" ... ")}\n`; } } // Add source fields that weren't highlighted for (const [field, value] of Object.entries(sourceData)) { if (!(field in highlightedFields)) { content += `${field}: ${JSON.stringify(value)}\n`; } } contentFragments.push({ type: "text", text: content.trim(), }); }); const response: ResponseContent = { content: contentFragments, }; return response; } catch (error) { console.error( `Search failed: ${ error instanceof Error ? error.message : String(error) }` ); return { content: [ { type: "text", text: `Error: ${ error instanceof Error ? error.message : String(error) }`, }, ], }; } }
• src/index.ts:195-229 (schema)

  Zod schema defining the input parameters for the 'search' tool: required 'index' string, 'queryBody' as arbitrary record for Elasticsearch DSL, and optional 'scriptFields' for computed fields with script definitions.
  index: z .string() .trim() .min(1, "Index name is required") .describe("Name of the Elasticsearch index to search"), queryBody: z .record(z.any()) .describe( "Complete Elasticsearch query DSL object (can include query, size, from, sort, etc.)" ), scriptFields: z .record( z.object({ script: z.object({ source: z .string() .min(1, "Script source is required") .describe("Painless script source code"), params: z .record(z.any()) .optional() .describe("Optional parameters for the script"), lang: z .string() .optional() .default("painless") .describe("Script language (defaults to painless)"), }) }) ) .optional() .describe("Script fields to evaluate and include in the response"), },
• src/index.ts:191-324 (registration)

  Registration of the 'search' tool on the MCP server using server.tool(), including name, description, input schema, and handler function.
  server.tool( "search", "Perform an Elasticsearch search with the provided query DSL, highlighting, and script fields", { index: z .string() .trim() .min(1, "Index name is required") .describe("Name of the Elasticsearch index to search"), queryBody: z .record(z.any()) .describe( "Complete Elasticsearch query DSL object (can include query, size, from, sort, etc.)" ), scriptFields: z .record( z.object({ script: z.object({ source: z .string() .min(1, "Script source is required") .describe("Painless script source code"), params: z .record(z.any()) .optional() .describe("Optional parameters for the script"), lang: z .string() .optional() .default("painless") .describe("Script language (defaults to painless)"), }) }) ) .optional() .describe("Script fields to evaluate and include in the response"), }, async ({ index, queryBody, scriptFields }, extra) => { try { // Add script_fields to the query body if provided const enhancedQueryBody = { ...queryBody }; if (scriptFields && Object.keys(scriptFields).length > 0) { enhancedQueryBody.script_fields = scriptFields; } const result = await esService.search(index, enhancedQueryBody); // Extract the 'from' parameter from queryBody, defaulting to 0 if not provided const from = queryBody.from ?? 0; const contentFragments: TextContent[] = []; // Add metadata about the search results contentFragments.push({ type: "text", text: `Total results: ${ typeof result.hits.total === "number" ? result.hits.total : result.hits.total?.value ?? 0 }, showing ${result.hits.hits.length} from position ${from}`, }); // Add aggregation results if present if (result.aggregations) { contentFragments.push({ type: "text", text: `Aggregations: ${JSON.stringify( result.aggregations, null, 2 )}`, }); } // Process and add individual hit results result.hits.hits.forEach((hit: any) => { const highlightedFields = hit.highlight ?? {}; const sourceData = hit._source ?? {}; const scriptFieldsData = hit.fields ?? {}; let content = `Document ID: ${hit._id}\nScore: ${hit._score}\n\n`; // Add script fields results for (const [field, value] of Object.entries(scriptFieldsData)) { content += `${field} (script): ${JSON.stringify(value)}\n`; } // Add highlighted fields for (const [field, highlights] of Object.entries(highlightedFields)) { if (Array.isArray(highlights) && highlights.length > 0) { content += `${field} (highlighted): ${( highlights as string[] ).join(" ... ")}\n`; } } // Add source fields that weren't highlighted for (const [field, value] of Object.entries(sourceData)) { if (!(field in highlightedFields)) { content += `${field}: ${JSON.stringify(value)}\n`; } } contentFragments.push({ type: "text", text: content.trim(), }); }); const response: ResponseContent = { content: contentFragments, }; return response; } catch (error) { console.error( `Search 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:189-194 (helper)

  Supporting helper method in ElasticsearchService class that wraps the Elasticsearch client's search method, spreading the queryBody into the search parameters.
  async search(index: string, queryBody: any): Promise<any> { return await this.client.search({ index, ...queryBody, }); }