AI导哈

文档搜索管理系统

一个集成了Elasticsearch、Node.js CRUD API和MCP服务器的完整系统，提供无缝的文档管理和搜索功能。

  • by JacobZoarets
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 jacobzoarets/elasticsearch-mcp-server

使用说明

Elasticsearch MCP服务器

一个完整的系统，包含Elasticsearch、Node.js CRUD API和MCP服务器集成，可实现无缝文档管理和搜索功能。

建筑

  • 弹性搜索：使用示例数据在Docker中运行的搜索引擎
  • API服务器：具有RESTful CRUD操作的Node.js/TypeScript服务器
  • MCP服务器：用于与AI工具进行外部集成的模型上下文协议服务器

特性

弹性搜索

  • 带有相关性评分的全文搜索
  • 使用自定义映射进行文档索引
  • 持久数据存储
  • 健康监测

API服务器

  • 文档的RESTful CRUD操作
  • 输入验证和错误处理
  • 综合录井
  • 健康检查端点

MCP服务器

  • 5个用于文档操作的MCP工具：
    • create_document：创建新文档
    • get_document：按ID检索文档
    • update_document：更新现有文件
    • delete_document：删除文档
    • search_documents：带过滤器的全文搜索
  • 所有工具的JSON模式验证
  • 结构化错误响应

快速开始

自动设置（推荐）

Linux/macOS:

./scripts/start.sh

视窗:

scripts\start.bat

手动设置

  1. 设置环境:

    cp api/.env.example api/.env
cp mcp/.env.example mcp/.env

  2. 启动系统:

    docker-compose up -d

  3. 验证服务:

    • Elasticsearch：http://localhost:9200
    • API服务器：http://localhost:3000
    • API运行状况：http://localhost:3000/health

API终点

文件

  • POST /documents -创建文档
  • GET /documents/:id -按ID获取文档
  • PUT /documents/:id -更新文档
  • DELETE /documents/:id -删除文档
  • GET /documents/search -搜索文档

健康

  • GET /health -服务健康检查

API使用示例

# Create a document
curl -X POST http://localhost:3000/documents \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Document",
    "content": "Document content here",
    "tags": ["example", "test"],
    "metadata": {"author": "user"}
  }'

# Search documents
curl "http://localhost:3000/documents/search?query=document&limit=5"

MCP集成

与MCP检查器一起使用

  1. 设置MCP服务器:

    ./scripts/mcp-setup.sh  # Linux/macOS

  2. 安装MCP检查器:

    npm install -g @modelcontextprotocol/inspector

  3. 启动MCP服务器:

    cd mcp && npm start

  4. 连接检查器:

    mcp-inspector node mcp/dist/index.js

使用Claude代码

添加到MCP配置中：

{
  "mcpServers": {
    "elasticsearch": {
      "command": "node",
      "args": ["path/to/mcp/dist/index.js"],
      "env": {
        "API_URL": "http://localhost:3000"
      }
    }
  }
}

发展

API开发

cd api
npm install
npm run dev        # Development server
npm test          # Run tests
npm run build     # Build for production

MCP开发

cd mcp
npm install
npm run dev        # Development server
npm test          # Run tests
npm run build     # Build for production

测试

单元测试

# API tests
cd api && npm test

# MCP tests
cd mcp && npm test

集成测试

自动化测试:

./scripts/test.sh  # Linux/macOS

手动测试:

# Start test environment
docker-compose -f docker-compose.test.yml up -d

# Run integration tests
cd tests/integration
npm install
npm test

# Cleanup
docker-compose -f docker-compose.test.yml down

配置

环境变量

API服务器 (.env):

NODE_ENV=development
PORT=3000
ELASTICSEARCH_URL=http://localhost:9200
ELASTICSEARCH_INDEX=documents
LOG_LEVEL=info

MCP服务器 (.env):

NODE_ENV=development
API_URL=http://localhost:3000
MCP_PORT=3001
LOG_LEVEL=info

文档架构

interface Document {
  id?: string;
  title: string;
  content: string;
  tags: string[];
  created_at: Date;
  updated_at: Date;
  metadata?: Record<string, any>;
}

错误处理

该系统提供全面的错误处理：

  • 验证错误：带有详细字段级错误的输入验证
  • 未找到错误：对缺失文件的正确404响应
  • Elasticsearch错误：连接和查询错误处理
  • MCP错误：遵循MCP协议的结构化错误响应

监控

健康检查

  • API运行状况终结点： GET /health
  • Elasticsearch集群健康监控
  • Docker容器健康检查

日志记录

  • 结构化JSON日志记录
  • 请求/响应日志记录
  • 使用堆栈跟踪进行错误跟踪
  • 可配置的日志级别

生产部署

  1. 构建图像:

    docker-compose build

  2. 设置生产环境:

    export NODE_ENV=production

  3. 部署:

    docker-compose up -d

故障排除

常见问题

  1. Elasticsearch未启动:

    • 检查内存限制（至少需要512MB）
    • 验证Docker是否有足够的资源

  2. API连接错误:

    • 在启动API之前确保Elasticsearch是健康的
    • 检查容器之间的网络连接

  3. MCP工具不工作:

    • 验证API服务器运行正常
    • 检查MCP服务器日志中的连接错误

日志

# View all logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f elasticsearch
docker-compose logs -f api

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 通过测试进行更改
  4. 提交拉取请求

许可证

MIT许可证

相关 MCP