es-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,182 @@
+# Elasticsearch MCP Server
+
+这是一个为 Elasticsearch 设计的 MCP (Model Context Protocol) 服务器，允许通过 Claude Code 直接管理和查询 Elasticsearch 集群。
+
+## 功能特性
+
+- ✅ 集群健康检查
+- ✅ 索引管理（创建、删除、查看）
+- ✅ 文档操作（增删改查）
+- ✅ 搜索和查询
+- ✅ 集群信息获取
+- ✅ 支持认证（用户名/密码 或 API Key）
+
+## 安装
+
+### 方式一：npm 全局安装（推荐）
+
+```bash
+npm install -g es-mcp-server
+```
+
+### 方式二：从本地安装
+
+```bash
+cd <path-to-es-mcp-server>
+npm install -g .
+```
+
+### 方式三：开发模式
+
+```bash
+cd <path-to-es-mcp-server>
+npm install
+npm start
+```
+
+## 配置
+
+### 环境变量（可选）
+
+```bash
+export ES_HOST="localhost:9200"
+export ES_USERNAME="your_username"  # 如果需要认证
+export ES_PASSWORD="your_password"  # 如果需要认证
+export ES_API_KEY="your_api_key"    # 如果使用 API Key 认证
+```
+
+## 使用方法
+
+### 集成到 Claude Code
+
+将以下配置添加到你的 Claude Code MCP 配置中：
+
+**使用 npm 全局安装的命令：**
+
+```json
+{
+  "mcpServers": {
+    "elasticsearch": {
+      "command": "es-mcp-server",
+      "env": {
+        "ES_HOST": "localhost:9200"
+      }
+    }
+  }
+}
+```
+
+**开发模式（从源码运行）：**
+
+```json
+{
+  "mcpServers": {
+    "elasticsearch": {
+      "command": "node",
+      "args": ["<path-to-es-mcp-server>/index.js"],
+      "env": {
+        "ES_HOST": "localhost:9200"
+      }
+    }
+  }
+}
+```
+
+## 可用工具
+
+| 工具名称 | 描述 | 参数 |
+|---------|------|------|
+| `es_health_check` | 检查集群健康状态 | 无 |
+| `es_list_indices` | 列出所有索引 | `pattern` (可选) - 索引模式 |
+| `es_create_index` | 创建新索引 | `index` (必需) - 索引名<br>`mappings` (可选) - 映射<br>`settings` (可选) - 设置 |
+| `es_delete_index` | 删除索引 | `index` (必需) - 索引名 |
+| `es_index_document` | 索引文档 | `index` (必需) - 索引名<br>`document` (必需) - 文档内容<br>`id` (可选) - 文档ID |
+| `es_get_document` | 获取文档 | `index` (必需) - 索引名<br>`id` (必需) - 文档ID |
+| `es_search` | 搜索文档 | `index` (必需) - 索引名<br>`query` (可选) - 查询DSL<br>`size` (可选) - 返回数量<br>`from` (可选) - 偏移量 |
+| `es_update_document` | 更新文档 | `index` (必需) - 索引名<br>`id` (必需) - 文档ID<br>`document` (必需) - 更新内容 |
+| `es_delete_document` | 删除文档 | `index` (必需) - 索引名<br>`id` (必需) - 文档ID |
+| `es_cluster_info` | 获取集群信息 | 无 |
+
+## 使用示例
+
+### 检查集群健康
+```javascript
+// 使用 MCP 工具
+await mcpCall("es_health_check", {});
+```
+
+### 创建索引
+```javascript
+await mcpCall("es_create_index", {
+  index: "products",
+  mappings: {
+    properties: {
+      name: { type: "text" },
+      price: { type: "float" },
+      category: { type: "keyword" }
+    }
+  }
+});
+```
+
+### 索引文档
+```javascript
+await mcpCall("es_index_document", {
+  index: "products",
+  document: {
+    name: "iPhone 15",
+    price: 999.99,
+    category: "Electronics"
+  }
+});
+```
+
+### 搜索文档
+```javascript
+await mcpCall("es_search", {
+  index: "products",
+  query: {
+    query: {
+      match: {
+        name: "iPhone"
+      }
+    }
+  },
+  size: 10
+});
+```
+
+## 认证配置
+
+### 用户名/密码认证
+```bash
+export ES_USERNAME="elastic"
+export ES_PASSWORD="your_password"
+```
+
+### API Key 认证
+```bash
+export ES_API_KEY="your_base64_encoded_api_key"
+```
+
+## 故障排除
+
+1. **连接失败**：确保 Elasticsearch 服务正在运行且可访问
+2. **认证错误**：检查用户名/密码或 API Key 是否正确
+3. **权限错误**：确保用户有足够的权限执行请求的操作
+
+## 开发
+
+### 开发模式运行
+```bash
+npm run dev
+```
+
+### 添加新工具
+1. 在 `index.js` 的 `ListToolsRequestSchema` 处理程序中添加工具定义
+2. 在 `CallToolRequestSchema` 处理程序中添加相应的 case
+3. 测试新功能
+
+## 许可证
+
+MIT License

package/bin/cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Import and run the main server
+import(join(__dirname, '../index.js'));

package/index.js

@@ -0,0 +1,435 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { Client } from "@elastic/elasticsearch";
+
+// Elasticsearch client
+let esClient;
+
+// MCP Server
+const server = new Server(
+  {
+    name: "elasticsearch-mcp",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// Initialize Elasticsearch client
+function initESClient() {
+  const esHost = process.env.ES_HOST || "localhost:9200";
+  const esUsername = process.env.ES_USERNAME;
+  const esPassword = process.env.ES_PASSWORD;
+  const esApiKey = process.env.ES_API_KEY;
+
+  const clientConfig = {
+    node: `http://${esHost}`,
+    requestTimeout: 30000,
+    sniffOnStart: true,
+  };
+
+  if (esApiKey) {
+    clientConfig.auth = {
+      apiKey: esApiKey,
+    };
+  } else if (esUsername && esPassword) {
+    clientConfig.auth = {
+      username: esUsername,
+      password: esPassword,
+    };
+  }
+
+  esClient = new Client(clientConfig);
+}
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "es_health_check",
+        description: "Check Elasticsearch cluster health",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      {
+        name: "es_list_indices",
+        description: "List all indices in the cluster",
+        inputSchema: {
+          type: "object",
+          properties: {
+            pattern: {
+              type: "string",
+              description: "Index pattern (default: '*')",
+            },
+          },
+        },
+      },
+      {
+        name: "es_create_index",
+        description: "Create a new index",
+        inputSchema: {
+          type: "object",
+          properties: {
+            index: {
+              type: "string",
+              description: "Index name",
+            },
+            mappings: {
+              type: "object",
+              description: "Index mappings (optional)",
+            },
+            settings: {
+              type: "object",
+              description: "Index settings (optional)",
+            },
+          },
+          required: ["index"],
+        },
+      },
+      {
+        name: "es_delete_index",
+        description: "Delete an index",
+        inputSchema: {
+          type: "object",
+          properties: {
+            index: {
+              type: "string",
+              description: "Index name",
+            },
+          },
+          required: ["index"],
+        },
+      },
+      {
+        name: "es_index_document",
+        description: "Index a document",
+        inputSchema: {
+          type: "object",
+          properties: {
+            index: {
+              type: "string",
+              description: "Index name",
+            },
+            id: {
+              type: "string",
+              description: "Document ID (optional, will be auto-generated if not provided)",
+            },
+            document: {
+              type: "object",
+              description: "Document content",
+            },
+          },
+          required: ["index", "document"],
+        },
+      },
+      {
+        name: "es_get_document",
+        description: "Get a document by ID",
+        inputSchema: {
+          type: "object",
+          properties: {
+            index: {
+              type: "string",
+              description: "Index name",
+            },
+            id: {
+              type: "string",
+              description: "Document ID",
+            },
+          },
+          required: ["index", "id"],
+        },
+      },
+      {
+        name: "es_search",
+        description: "Search documents",
+        inputSchema: {
+          type: "object",
+          properties: {
+            index: {
+              type: "string",
+              description: "Index name or pattern",
+            },
+            query: {
+              type: "object",
+              description: "Search query DSL",
+            },
+            size: {
+              type: "number",
+              description: "Number of results to return (default: 10)",
+            },
+            from: {
+              type: "number",
+              description: "Starting offset (default: 0)",
+            },
+          },
+          required: ["index"],
+        },
+      },
+      {
+        name: "es_update_document",
+        description: "Update a document",
+        inputSchema: {
+          type: "object",
+          properties: {
+            index: {
+              type: "string",
+              description: "Index name",
+            },
+            id: {
+              type: "string",
+              description: "Document ID",
+            },
+            document: {
+              type: "object",
+              description: "Partial document to update",
+            },
+          },
+          required: ["index", "id", "document"],
+        },
+      },
+      {
+        name: "es_delete_document",
+        description: "Delete a document",
+        inputSchema: {
+          type: "object",
+          properties: {
+            index: {
+              type: "string",
+              description: "Index name",
+            },
+            id: {
+              type: "string",
+              description: "Document ID",
+            },
+          },
+          required: ["index", "id"],
+        },
+      },
+      {
+        name: "es_cluster_info",
+        description: "Get cluster information",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+    ],
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    if (!esClient) {
+      initESClient();
+    }
+
+    switch (name) {
+      case "es_health_check":
+        const health = await esClient.cluster.health();
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(health, null, 2),
+            },
+          ],
+        };
+
+      case "es_list_indices":
+        const indices = await esClient.cat.indices({
+          format: "json",
+          index: args.pattern || "*",
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(indices, null, 2),
+            },
+          ],
+        };
+
+      case "es_create_index":
+        const createParams = {
+          index: args.index,
+        };
+        if (args.mappings) {
+          createParams.mappings = args.mappings;
+        }
+        if (args.settings) {
+          createParams.settings = args.settings;
+        }
+        const createResult = await esClient.indices.create(createParams);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(createResult, null, 2),
+            },
+          ],
+        };
+
+      case "es_delete_index":
+        const deleteResult = await esClient.indices.delete({
+          index: args.index,
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(deleteResult, null, 2),
+            },
+          ],
+        };
+
+      case "es_index_document":
+        const indexParams = {
+          index: args.index,
+          body: args.document,
+        };
+        if (args.id) {
+          indexParams.id = args.id;
+        }
+        const indexResult = await esClient.index(indexParams);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(indexResult, null, 2),
+            },
+          ],
+        };
+
+      case "es_get_document":
+        const doc = await esClient.get({
+          index: args.index,
+          id: args.id,
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(doc, null, 2),
+            },
+          ],
+        };
+
+      case "es_search":
+        const searchParams = {
+          index: args.index,
+          body: args.query || { query: { match_all: {} } },
+        };
+        if (args.size) {
+          searchParams.size = args.size;
+        }
+        if (args.from) {
+          searchParams.from = args.from;
+        }
+        const searchResult = await esClient.search(searchParams);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(searchResult, null, 2),
+            },
+          ],
+        };
+
+      case "es_update_document":
+        const updateResult = await esClient.update({
+          index: args.index,
+          id: args.id,
+          body: { doc: args.document },
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(updateResult, null, 2),
+            },
+          ],
+        };
+
+      case "es_delete_document":
+        const deleteDocResult = await esClient.delete({
+          index: args.index,
+          id: args.id,
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(deleteDocResult, null, 2),
+            },
+          ],
+        };
+
+      case "es_cluster_info":
+        const info = await esClient.info();
+        const nodes = await esClient.nodes.stats();
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  cluster_info: info,
+                  nodes_stats: nodes,
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              error: error.message,
+              details: error.meta?.body || error.stack,
+            },
+            null,
+            2
+          ),
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// Start the server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Elasticsearch MCP Server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Server error:", error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "es-mcp-server",
+  "version": "1.0.0",
+  "description": "Elasticsearch MCP Server for Claude Code",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "es-mcp-server": "bin/cli.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "dev": "node --watch index.js"
+  },
+  "keywords": [
+    "mcp",
+    "elasticsearch",
+    "claude-code"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.6.0",
+    "@elastic/elasticsearch": "^8.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0"
+  },
+  "files": [
+    "index.js",
+    "bin/"
+  ]
+}