OpenSearch MCP Server

Instructions

Implementation Reference

• index.js:316-370 (handler)

  The execute handler function for the exploreFieldValues tool. Performs an OpenSearch aggregation (terms) on the specified field to retrieve top values, counts, and percentages.

    execute: async (args, { log }) => {
      log.info("Exploring field values", { 
        index: args.index,
        field: args.field,
        query: args.query 
      });
  
      return safeOpenSearchQuery(async () => {
        const response = await client.search({
          index: args.index,
          body: {
            size: 0,
            query: {
              query_string: {
                query: args.query
              }
            },
            aggs: {
              field_values: {
                terms: {
                  field: args.field,
                  size: args.maxValues
                }
              }
            },
            timeout: "25s"
          }
        });
  
        const buckets = response.body.aggregations?.field_values?.buckets || [];
        const total = response.body.hits.total?.value || 0;
        
        if (buckets.length === 0) {
          return `No values found for field "${args.field}" in index ${args.index}.\n\nPossible reasons:\n- The field does not exist\n- The field is not indexed for aggregations\n- No documents match your query\n- The field has no values`;
        }
  
        let resultText = `## Values for field "${args.field}" in ${args.index}\n\n`;
        resultText += `Found ${total} matching documents. Top ${buckets.length} values:\n\n`;
        
        // Calculate percentage of total for each value
        let totalCount = buckets.reduce((sum, bucket) => sum + bucket.doc_count, 0);
        
        // Format results as a table
        resultText += "| Value | Count | Percentage |\n";
        resultText += "|-------|-------|------------|\n";
        
        buckets.forEach(bucket => {
          const percentage = ((bucket.doc_count / totalCount) * 100).toFixed(2);
          resultText += `| ${bucket.key} | ${bucket.doc_count} | ${percentage}% |\n`;
        });
        
        return resultText;
      }, `Failed to explore values for field "${args.field}" in index ${args.index}.`);
    },
  });

• index.js:310-315 (schema)

  Zod schema defining input parameters for the exploreFieldValues tool: index, field, query, maxValues.

  parameters: z.object({
    index: z.string().describe("Index pattern to search"),
    field: z.string().describe("Field name to explore"),
    query: z.string().default("*").describe("Optional query to filter documents"),
    maxValues: z.number().default(20).describe("Maximum number of values to return"),
  }),

• index.js:307-307 (registration)

  Initial registration of the exploreFieldValues tool with name and description.

  server.addTool({

• index.js:62-86 (helper)

  Helper function used by exploreFieldValues (and other tools) to safely execute OpenSearch queries with error handling and user-friendly 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}`);
    }
  }