OpenSearch MCP Server

Instructions

Implementation Reference

• index.js:244-304 (registration)

  Full registration of the 'getIndexMapping' tool using FastMCP server.addTool, including schema, description, and execute handler that queries OpenSearch for index mappings and formats them hierarchically.
  server.addTool({ name: "getIndexMapping", description: "Get the field mappings for an index", parameters: z.object({ index: z.string().describe("Index name to inspect"), }), execute: async (args, { log }) => { log.info("Getting index mapping", { index: args.index }); return safeOpenSearchQuery(async () => { const response = await client.indices.getMapping({ index: args.index, timeout: "20s" }); const mappings = response.body; if (!mappings) { return `No mappings found for index ${args.index}.`; } const indexName = Object.keys(mappings)[0]; const properties = mappings[indexName]?.mappings?.properties || {}; if (Object.keys(properties).length === 0) { return `No field mappings found for index ${args.index}.`; } let resultText = `## Field Mappings for ${args.index}\n\n`; function processProperties(props, prefix = '') { Object.entries(props).forEach(([field, details]) => { const fullPath = prefix ? `${prefix}.${field}` : field; if (details.type) { resultText += `- **${fullPath}**: ${details.type}`; if (details.fields) { resultText += ` (has multi-fields)`; } resultText += '\n'; } // Recursively process nested fields if (details.properties) { processProperties(details.properties, fullPath); } // Process multi-fields if (details.fields) { Object.entries(details.fields).forEach(([subField, subDetails]) => { resultText += ` - ${fullPath}.${subField}: ${subDetails.type}\n`; }); } }); } processProperties(properties); return resultText; }, `Failed to get mapping for index ${args.index}.`); }, });
• index.js:250-303 (handler)

  The handler function that executes the tool: logs the action, uses safeOpenSearchQuery to call client.indices.getMapping, extracts properties, recursively processes nested and multi-fields, formats as markdown list, and returns the result.
  execute: async (args, { log }) => { log.info("Getting index mapping", { index: args.index }); return safeOpenSearchQuery(async () => { const response = await client.indices.getMapping({ index: args.index, timeout: "20s" }); const mappings = response.body; if (!mappings) { return `No mappings found for index ${args.index}.`; } const indexName = Object.keys(mappings)[0]; const properties = mappings[indexName]?.mappings?.properties || {}; if (Object.keys(properties).length === 0) { return `No field mappings found for index ${args.index}.`; } let resultText = `## Field Mappings for ${args.index}\n\n`; function processProperties(props, prefix = '') { Object.entries(props).forEach(([field, details]) => { const fullPath = prefix ? `${prefix}.${field}` : field; if (details.type) { resultText += `- **${fullPath}**: ${details.type}`; if (details.fields) { resultText += ` (has multi-fields)`; } resultText += '\n'; } // Recursively process nested fields if (details.properties) { processProperties(details.properties, fullPath); } // Process multi-fields if (details.fields) { Object.entries(details.fields).forEach(([subField, subDetails]) => { resultText += ` - ${fullPath}.${subField}: ${subDetails.type}\n`; }); } }); } processProperties(properties); return resultText; }, `Failed to get mapping for index ${args.index}.`); },
• index.js:247-249 (schema)

  Zod input schema defining the required 'index' parameter as a string.
  parameters: z.object({ index: z.string().describe("Index name to inspect"), }),
• index.js:62-86 (helper)

  Helper function used by getIndexMapping to safely execute OpenSearch queries with error handling and user-friendly error messages.
  async function safeOpenSearchQuery(operation, fallbackMessage) { try { debugLog('Executing OpenSearch query'); const result = await operation(); debugLog('OpenSearch query completed successfully'); return result; } catch (error) { console.error(`OpenSearch error: ${error.message}`, error); debugLog('OpenSearch query failed:', error); // Check for common OpenSearch errors if (error.message.includes('timeout')) { throw new UserError(`OpenSearch request timed out. The query may be too complex or the cluster is under heavy load.`); } else if (error.message.includes('connect')) { throw new UserError(`Cannot connect to OpenSearch. Please check your connection settings in .env file.`); } else if (error.message.includes('no such index')) { throw new UserError(`The specified index doesn't exist in OpenSearch.`); } else if (error.message.includes('unauthorized')) { throw new UserError(`Authentication failed with OpenSearch. Please check your credentials in .env file.`); } // For any other errors throw new UserError(fallbackMessage || `OpenSearch operation failed: ${error.message}`); } }