Elasticsearch MCP Server

Instructions

Implementation Reference

• index.ts:262-637 (handler)

  The main handler function for the 'search' tool. It performs an Elasticsearch search on the specified index using the provided query DSL, injects permission-based filters retrieved from Redis based on userId and index type, enables highlighting on text fields, processes aggregations, and formats the results with highlights and metadata.
  async ({ index, queryBody, userId }) => { console.error("[DEBUG] search tool called", index, userId, queryBody); try { const redisKey = `GLOBAL_SEARCH_INDEX_ID_MAPPING:${userId}`; const raw= await redis.get(redisKey); console.error("[DEBUG] Redis key fetched:", redisKey, "->", raw); const allowedIdsObj = JSON.parse(raw || "{}"); const allowedIds = [ ...allowedIdsObj.header_section_doc_ids, ...allowedIdsObj.line_item_section_doc_ids, ...allowedIdsObj.header_clause_doc_ids, ...allowedIdsObj.line_item_clause_doc_ids, ...allowedIdsObj.attachment_doc_ids, ...allowedIdsObj.meta_doc_ids, ]; let permissionFilter; if (index === "cdc_agreement_list") { // For this index, permission index is "permitted_agreement_for_meta" and keys are meta_doc_ids const allowedMetaDocIds = allowedIdsObj.meta_doc_ids; permissionFilter = { bool: { should: allowedMetaDocIds.map((id: string) => ({ terms: { "AGREEMENT_ID.keyword": { index: "permitted_agreement_for_meta", id: id, path: "agreement_ids" } } })) } }; } else if (index === "cms_documents") { // For this index, permission index is "permitted_agreement_for_attachment" and keys are attachment_doc_ids const allowedAttachmentDocIds = allowedIdsObj.attachment_doc_ids; permissionFilter = { bool: { should: allowedAttachmentDocIds.map((id: string) => ({ terms: { "AGREEMENT_ID.keyword": { index: "permitted_agreement_for_attachment", id: id, path: "agreement_ids" } } })) } }; } else if (index === "cdc_line_items") { const sectionDocIds = allowedIdsObj.line_item_section_doc_ids; // Array of doc IDs permissionFilter = { bool: { should: sectionDocIds.map((docId: string)=> ({ bool: { must: [ { terms: { "AGREEMENT_ID.keyword": { index: "permitted_line_item_section", id: docId, path: "sections.agreement_id" } } }, { terms: { "AGREEMENT_SECTION_ID.keyword": { index: "permitted_line_item_section", id: docId, path: "sections.section_id" } } } ] } })) } }; } else if (index === "cdc_field_data_agreements") { // For each doc_id in header_section_doc_ids, create a must of terms const sectionDocIds = allowedIdsObj.header_section_doc_ids; // array of doc IDs permissionFilter = { bool: { should: sectionDocIds.map((docId: string) => ({ bool: { must: [ { terms: { "AGREEMENT_ID.keyword": { index: "permitted_header_section", id: docId, path: "sections.agreement_id" } } }, { terms: { "SECTION_ID.keyword": { index: "permitted_header_section", id: docId, path: "sections.section_id" } } } ] } })) } }; } else if (index === "cdc_clauses_data") { const clauseDocIds = allowedIdsObj.header_clause_doc_ids; permissionFilter = { bool: { should: clauseDocIds.map((docId: string) => ({ terms: { "AGREEMENT_ID.keyword": { index: "permitted_agreement_for_clause", id: docId, path: "agreement_ids" } } })) } }; }else { // Default (old) logic for agreement permissions only permissionFilter = { terms: { "AGREEMENT_ID.keyword": allowedIds.length > 0 ? allowedIds : ["__none__"], }, }; } // If no query, make a bool with only your filter if (!queryBody.query) { queryBody.query = { bool: { must: [permissionFilter], } }; } // If the query is already a bool, inject your filter else if (queryBody.query.bool) { if (!queryBody.query.bool.must) { queryBody.query.bool.must = []; } queryBody.query.bool.must.push(permissionFilter); } // If the query is any other type (e.g. term, match), wrap in bool else { // Store the original query const originalQuery = queryBody.query; queryBody.query = { bool: { must: [originalQuery, permissionFilter] } }; } console.error("[DEBUG] Final queryBody to send to ES:", JSON.stringify(queryBody, null, 2)); // Get mappings to identify text fields for highlighting const mappingResponse = await esClient.indices.getMapping({ index, }); const indexMappings = mappingResponse[index]?.mappings || {}; const searchRequest = { index:index, body:queryBody, }; //queryBody.index = index; // Always do highlighting if (indexMappings.properties) { const textFields: Record<string, estypes.SearchHighlightField> = {}; for (const [fieldName, fieldData] of Object.entries( indexMappings.properties )) { if (fieldData.type === "text" || "dense_vector" in fieldData) { textFields[fieldName] = {}; } } searchRequest.body.highlight = { fields: textFields, pre_tags: ["<em>"], post_tags: ["</em>"], }; } // DEBUG: print the final searchRequest object console.error("[DEBUG] ES SearchRequest:", JSON.stringify(searchRequest, null, 2)); const result = await esClient.search(searchRequest); // DEBUG: print raw ES response // console.error("[DEBUG] ES Search Response:", JSON.stringify(result, null, 2)); // return { // content: [ // { // type: "text", // text: "[DEBUG] This is the final query that would be sent to ES:\n" + JSON.stringify(result, null, 2) // } // ] // }; // Extract the 'from' parameter from queryBody, defaulting to 0 if not provided const from = queryBody.from || 0; // ----- AGGREGATION UNIVERSAL HANDLER ----- function formatAggs( aggsObj: Record<string, unknown>, prefix = "" ): string[] { const lines: string[] = []; for (const [aggName, aggData] of Object.entries(aggsObj)) { if (aggData && typeof aggData === "object" && aggData !== null) { // Buckets: must cast and check if 'buckets' is an array const maybeBuckets = (aggData as Record<string, unknown>)["buckets"]; if (Array.isArray(maybeBuckets)) { lines.push(`${prefix}Aggregation "${aggName}" (buckets):`); if (maybeBuckets.length === 0) { lines.push(`${prefix} (no buckets)`); } for (const bucket of maybeBuckets) { if (bucket && typeof bucket === "object" && bucket !== null) { const key = (bucket as Record<string, unknown>)["key"]; const docCount = (bucket as Record<string, unknown>)["doc_count"]; lines.push( `${prefix} ${String(key)}: ${String(docCount)}` ); // Recursively print nested aggs in buckets for (const [k, v] of Object.entries(bucket)) { if ( v && typeof v === "object" && v !== null && (Array.isArray((v as Record<string, unknown>)["buckets"]) || (v as Record<string, unknown>)["value"] !== undefined) ) { lines.push( ...formatAggs({ [k]: v }, prefix + " ") ); } } } } } else if ( // Single metric: e.g., { value: 123 } Object.prototype.hasOwnProperty.call(aggData, "value") ) { lines.push( `${prefix}Aggregation "${aggName}": ${ (aggData as Record<string, unknown>)["value"] }` ); } else if ( // Multi-metric: e.g., { count, min, max, avg, sum } Object.keys(aggData).some((k) => ["values", "avg", "sum", "min", "max", "count"].includes(k) ) ) { lines.push( `${prefix}Aggregation "${aggName}": ${JSON.stringify( aggData )}` ); } else { // Recursively process other nested aggs (if any) for (const [k, v] of Object.entries(aggData)) { if ( v && typeof v === "object" && v !== null && (Array.isArray((v as Record<string, unknown>)["buckets"]) || (v as Record<string, unknown>)["value"] !== undefined) ) { lines.push(...formatAggs({ [k]: v }, prefix + " ")); } } } } } return lines; } let aggregationFragments: { type: "text"; text: string }[] = []; if (result.aggregations) { const aggLines = formatAggs(result.aggregations as Record<string, unknown>); if (aggLines.length > 0) { aggregationFragments.push({ type: "text" as const, text: aggLines.join("\n"), }); } } const contentFragments = result.hits.hits.map((hit) => { const highlightedFields = hit.highlight || {}; const sourceData = hit._source || {}; let content = ""; for (const [field, highlights] of Object.entries(highlightedFields)) { if (highlights && highlights.length > 0) { content += `${field} (highlighted): ${highlights.join( " ... " )}\n`; } } for (const [field, value] of Object.entries(sourceData)) { if (!(field in highlightedFields)) { content += `${field}: ${JSON.stringify(value)}\n`; } } return { type: "text" as const, text: content.trim(), }; }); const metadataFragment = { type: "text" as const, text: `Total results: ${ typeof result.hits.total === "number" ? result.hits.total : result.hits.total?.value || 0 }, showing ${result.hits.hits.length} from position ${from}`, }; return { content: [...aggregationFragments, metadataFragment, ...contentFragments], }; } catch (error) { console.error( `Search failed: ${ error instanceof Error ? error.message : String(error) }` ); return { content: [ { type: "text" as const, text: `Error: ${ error instanceof Error ? error.message : String(error) }`, }, ], }; } }
• index.ts:235-262 (schema)

  Input schema validation for the 'search' tool using Zod: requires 'index' (Elasticsearch index name), 'queryBody' (valid Elasticsearch query DSL object), and 'userId' (for permission filtering).
  index: z .string() .trim() .min(1, "Index name is required") .describe("Name of the Elasticsearch index to search"), queryBody: z .record(z.any()) .refine( (val) => { try { JSON.parse(JSON.stringify(val)); return true; } catch (e) { return false; } }, { message: "queryBody must be a valid Elasticsearch query DSL object", } ) .describe( "Complete Elasticsearch query DSL object that can include query, size, from, sort, etc." ), userId: z.string().min(1).describe("User ID for permission filtering"), }, async ({ index, queryBody, userId }) => {
• index.ts:231-638 (registration)

  Registration of the 'search' tool on the MCP server using server.tool(), with description 'Perform an Elasticsearch search with the provided query DSL. Highlights are always enabled.', input schema, and handler function.
  server.tool( "search", "Perform an Elasticsearch search with the provided query DSL. Highlights are always enabled.", { index: z .string() .trim() .min(1, "Index name is required") .describe("Name of the Elasticsearch index to search"), queryBody: z .record(z.any()) .refine( (val) => { try { JSON.parse(JSON.stringify(val)); return true; } catch (e) { return false; } }, { message: "queryBody must be a valid Elasticsearch query DSL object", } ) .describe( "Complete Elasticsearch query DSL object that can include query, size, from, sort, etc." ), userId: z.string().min(1).describe("User ID for permission filtering"), }, async ({ index, queryBody, userId }) => { console.error("[DEBUG] search tool called", index, userId, queryBody); try { const redisKey = `GLOBAL_SEARCH_INDEX_ID_MAPPING:${userId}`; const raw= await redis.get(redisKey); console.error("[DEBUG] Redis key fetched:", redisKey, "->", raw); const allowedIdsObj = JSON.parse(raw || "{}"); const allowedIds = [ ...allowedIdsObj.header_section_doc_ids, ...allowedIdsObj.line_item_section_doc_ids, ...allowedIdsObj.header_clause_doc_ids, ...allowedIdsObj.line_item_clause_doc_ids, ...allowedIdsObj.attachment_doc_ids, ...allowedIdsObj.meta_doc_ids, ]; let permissionFilter; if (index === "cdc_agreement_list") { // For this index, permission index is "permitted_agreement_for_meta" and keys are meta_doc_ids const allowedMetaDocIds = allowedIdsObj.meta_doc_ids; permissionFilter = { bool: { should: allowedMetaDocIds.map((id: string) => ({ terms: { "AGREEMENT_ID.keyword": { index: "permitted_agreement_for_meta", id: id, path: "agreement_ids" } } })) } }; } else if (index === "cms_documents") { // For this index, permission index is "permitted_agreement_for_attachment" and keys are attachment_doc_ids const allowedAttachmentDocIds = allowedIdsObj.attachment_doc_ids; permissionFilter = { bool: { should: allowedAttachmentDocIds.map((id: string) => ({ terms: { "AGREEMENT_ID.keyword": { index: "permitted_agreement_for_attachment", id: id, path: "agreement_ids" } } })) } }; } else if (index === "cdc_line_items") { const sectionDocIds = allowedIdsObj.line_item_section_doc_ids; // Array of doc IDs permissionFilter = { bool: { should: sectionDocIds.map((docId: string)=> ({ bool: { must: [ { terms: { "AGREEMENT_ID.keyword": { index: "permitted_line_item_section", id: docId, path: "sections.agreement_id" } } }, { terms: { "AGREEMENT_SECTION_ID.keyword": { index: "permitted_line_item_section", id: docId, path: "sections.section_id" } } } ] } })) } }; } else if (index === "cdc_field_data_agreements") { // For each doc_id in header_section_doc_ids, create a must of terms const sectionDocIds = allowedIdsObj.header_section_doc_ids; // array of doc IDs permissionFilter = { bool: { should: sectionDocIds.map((docId: string) => ({ bool: { must: [ { terms: { "AGREEMENT_ID.keyword": { index: "permitted_header_section", id: docId, path: "sections.agreement_id" } } }, { terms: { "SECTION_ID.keyword": { index: "permitted_header_section", id: docId, path: "sections.section_id" } } } ] } })) } }; } else if (index === "cdc_clauses_data") { const clauseDocIds = allowedIdsObj.header_clause_doc_ids; permissionFilter = { bool: { should: clauseDocIds.map((docId: string) => ({ terms: { "AGREEMENT_ID.keyword": { index: "permitted_agreement_for_clause", id: docId, path: "agreement_ids" } } })) } }; }else { // Default (old) logic for agreement permissions only permissionFilter = { terms: { "AGREEMENT_ID.keyword": allowedIds.length > 0 ? allowedIds : ["__none__"], }, }; } // If no query, make a bool with only your filter if (!queryBody.query) { queryBody.query = { bool: { must: [permissionFilter], } }; } // If the query is already a bool, inject your filter else if (queryBody.query.bool) { if (!queryBody.query.bool.must) { queryBody.query.bool.must = []; } queryBody.query.bool.must.push(permissionFilter); } // If the query is any other type (e.g. term, match), wrap in bool else { // Store the original query const originalQuery = queryBody.query; queryBody.query = { bool: { must: [originalQuery, permissionFilter] } }; } console.error("[DEBUG] Final queryBody to send to ES:", JSON.stringify(queryBody, null, 2)); // Get mappings to identify text fields for highlighting const mappingResponse = await esClient.indices.getMapping({ index, }); const indexMappings = mappingResponse[index]?.mappings || {}; const searchRequest = { index:index, body:queryBody, }; //queryBody.index = index; // Always do highlighting if (indexMappings.properties) { const textFields: Record<string, estypes.SearchHighlightField> = {}; for (const [fieldName, fieldData] of Object.entries( indexMappings.properties )) { if (fieldData.type === "text" || "dense_vector" in fieldData) { textFields[fieldName] = {}; } } searchRequest.body.highlight = { fields: textFields, pre_tags: ["<em>"], post_tags: ["</em>"], }; } // DEBUG: print the final searchRequest object console.error("[DEBUG] ES SearchRequest:", JSON.stringify(searchRequest, null, 2)); const result = await esClient.search(searchRequest); // DEBUG: print raw ES response // console.error("[DEBUG] ES Search Response:", JSON.stringify(result, null, 2)); // return { // content: [ // { // type: "text", // text: "[DEBUG] This is the final query that would be sent to ES:\n" + JSON.stringify(result, null, 2) // } // ] // }; // Extract the 'from' parameter from queryBody, defaulting to 0 if not provided const from = queryBody.from || 0; // ----- AGGREGATION UNIVERSAL HANDLER ----- function formatAggs( aggsObj: Record<string, unknown>, prefix = "" ): string[] { const lines: string[] = []; for (const [aggName, aggData] of Object.entries(aggsObj)) { if (aggData && typeof aggData === "object" && aggData !== null) { // Buckets: must cast and check if 'buckets' is an array const maybeBuckets = (aggData as Record<string, unknown>)["buckets"]; if (Array.isArray(maybeBuckets)) { lines.push(`${prefix}Aggregation "${aggName}" (buckets):`); if (maybeBuckets.length === 0) { lines.push(`${prefix} (no buckets)`); } for (const bucket of maybeBuckets) { if (bucket && typeof bucket === "object" && bucket !== null) { const key = (bucket as Record<string, unknown>)["key"]; const docCount = (bucket as Record<string, unknown>)["doc_count"]; lines.push( `${prefix} ${String(key)}: ${String(docCount)}` ); // Recursively print nested aggs in buckets for (const [k, v] of Object.entries(bucket)) { if ( v && typeof v === "object" && v !== null && (Array.isArray((v as Record<string, unknown>)["buckets"]) || (v as Record<string, unknown>)["value"] !== undefined) ) { lines.push( ...formatAggs({ [k]: v }, prefix + " ") ); } } } } } else if ( // Single metric: e.g., { value: 123 } Object.prototype.hasOwnProperty.call(aggData, "value") ) { lines.push( `${prefix}Aggregation "${aggName}": ${ (aggData as Record<string, unknown>)["value"] }` ); } else if ( // Multi-metric: e.g., { count, min, max, avg, sum } Object.keys(aggData).some((k) => ["values", "avg", "sum", "min", "max", "count"].includes(k) ) ) { lines.push( `${prefix}Aggregation "${aggName}": ${JSON.stringify( aggData )}` ); } else { // Recursively process other nested aggs (if any) for (const [k, v] of Object.entries(aggData)) { if ( v && typeof v === "object" && v !== null && (Array.isArray((v as Record<string, unknown>)["buckets"]) || (v as Record<string, unknown>)["value"] !== undefined) ) { lines.push(...formatAggs({ [k]: v }, prefix + " ")); } } } } } return lines; } let aggregationFragments: { type: "text"; text: string }[] = []; if (result.aggregations) { const aggLines = formatAggs(result.aggregations as Record<string, unknown>); if (aggLines.length > 0) { aggregationFragments.push({ type: "text" as const, text: aggLines.join("\n"), }); } } const contentFragments = result.hits.hits.map((hit) => { const highlightedFields = hit.highlight || {}; const sourceData = hit._source || {}; let content = ""; for (const [field, highlights] of Object.entries(highlightedFields)) { if (highlights && highlights.length > 0) { content += `${field} (highlighted): ${highlights.join( " ... " )}\n`; } } for (const [field, value] of Object.entries(sourceData)) { if (!(field in highlightedFields)) { content += `${field}: ${JSON.stringify(value)}\n`; } } return { type: "text" as const, text: content.trim(), }; }); const metadataFragment = { type: "text" as const, text: `Total results: ${ typeof result.hits.total === "number" ? result.hits.total : result.hits.total?.value || 0 }, showing ${result.hits.hits.length} from position ${from}`, }; return { content: [...aggregationFragments, metadataFragment, ...contentFragments], }; } catch (error) { console.error( `Search failed: ${ error instanceof Error ? error.message : String(error) }` ); return { content: [ { type: "text" as const, text: `Error: ${ error instanceof Error ? error.message : String(error) }`, }, ], }; } } );
• redisClient.ts:1-23 (helper)

  Helper module exporting a configured Redis client instance, used in the search handler to fetch user-specific permitted document IDs for permission filtering.
  import pkg from "ioredis"; const Redis = (pkg as any).default || pkg; const { REDIS_URL, REDIS_HOST, REDIS_PORT, REDIS_PASSWORD } = process.env; const redis = REDIS_URL ? new Redis(REDIS_URL) : new Redis({ host: REDIS_HOST || "localhost", port: REDIS_PORT ? Number(REDIS_PORT) : 6379, password: REDIS_PASSWORD || undefined, }); export default redis;