octodet-elasticsearch-mcp

Instructions

Implementation Reference

• src/index.ts:1044-1074 (handler)

  Handler function that executes the count_documents tool logic by calling esService.countDocuments, formatting the success response or error message.

  async ({ index, query }) => {
    try {
      const count = await esService.countDocuments(index, query);
      return {
        content: [
          {
            type: "text",
            text: `Count of documents in index '${index}'${
              query ? " matching the provided query" : ""
            }: ${count}`,
          },
        ],
      };
    } catch (error) {
      console.error(
        `Failed to count documents: ${
          error instanceof Error ? error.message : String(error)
        }`
      );
      return {
        content: [
          {
            type: "text",
            text: `Error: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
      };
    }
  }

• src/index.ts:1033-1043 (schema)

  Input schema using Zod for the count_documents tool: required 'index' string and optional 'query' object.

  {
    index: z
      .string()
      .trim()
      .min(1, "Index name is required")
      .describe("Name of the Elasticsearch index to count documents in"),
    query: z
      .record(z.any())
      .optional()
      .describe("Optional Elasticsearch query to filter documents to count"),
  },

• src/index.ts:1030-1075 (registration)

  Registration of the 'count_documents' tool on the MCP server using server.tool().

  server.tool(
    "count_documents",
    "Count documents in an index, optionally filtered by a query",
    {
      index: z
        .string()
        .trim()
        .min(1, "Index name is required")
        .describe("Name of the Elasticsearch index to count documents in"),
      query: z
        .record(z.any())
        .optional()
        .describe("Optional Elasticsearch query to filter documents to count"),
    },
    async ({ index, query }) => {
      try {
        const count = await esService.countDocuments(index, query);
        return {
          content: [
            {
              type: "text",
              text: `Count of documents in index '${index}'${
                query ? " matching the provided query" : ""
              }: ${count}`,
            },
          ],
        };
      } catch (error) {
        console.error(
          `Failed to count documents: ${
            error instanceof Error ? error.message : String(error)
          }`
        );
        return {
          content: [
            {
              type: "text",
              text: `Error: ${
                error instanceof Error ? error.message : String(error)
              }`,
            },
          ],
        };
      }
    }
  );

• src/utils/elasticsearchService.ts:294-301 (helper)

  Helper method in ElasticsearchService class that performs the actual document count using Elasticsearch client.count API.

  async countDocuments(index: string, query?: any): Promise<number> {
    const response = await this.client.count({
      index,
      ...(query ? { query } : {}),
    });
  
    return response.count;
  }