Opensearch MCP (Hpower2)

OpenSearch MCP服务器

使用FastMCP构建的模型上下文协议（MCP）服务器，用于通过事务ID（TID）从OpenSearch日志中检索错误堆栈跟踪。

特性

• 堆栈跟踪检索错误：按事务ID（TID）获取完整的错误堆栈跟踪
• 基于Docker的设置：使用Docker Compose轻松进行本地开发
• 环境变量配置：通过环境变量进行灵活的连接设置

先决条件

• Python 3.10或更高版本
• Docker和Docker Compose（用于在容器中运行MCP服务器）
• 一个可访问的OpenSearch实例（您自己提供）
• pip或uv用于包装管理

安装

1. 克隆存储库：

git clone 
cd opensearch-mcp

1. 安装依赖项：

pip install -r requirements.txt

或使用紫外线：

uv pip install -r requirements.txt

1. 设置环境变量（可选）：

cp .env.example .env
# Edit .env with your OpenSearch connection settings

快速开始

先决条件：您需要自己的OpenSearch实例正在运行并可访问。在中配置连接详细信息 .env 文件。

选项1：使用Docker Compose（推荐）

1. 复制环境文件并配置OpenSearch连接：

cp .env.example .env
# Edit .env and set OPENSEARCH_HOST and OPENSEARCH_PORT to your OpenSearch instance

1. 启动MCP服务器：

docker-compose up

这将开始：

• 端口48081上的MCP服务器（HTTP端点： http://localhost:48081/mcp)

MCP服务器将使用以下配置连接到您的OpenSearch实例 .env.

要在分离模式下运行：

docker-compose up -d

选项2：直接用Python运行MCP服务器

1. 设置环境变量：

cp .env.example .env
# Edit .env and configure OPENSEARCH_HOST and OPENSEARCH_PORT to your OpenSearch instance

1. 运行MCP服务器：

python server.py

服务器将于启动 http://localhost:48081/mcp.

选项3：使用Docker运行MCP服务器（独立）

1. 构建Docker镜像：

docker build -t opensearch-mcp .

1. 使用您的OpenSearch连接详细信息运行容器：

docker run --rm -p 48081:48081 \
  -e OPENSEARCH_HOST=your-opensearch-host \
  -e OPENSEARCH_PORT=9200 \
  opensearch-mcp

或者使用env文件：

docker run --rm -p 48081:48081 --env-file .env opensearch-mcp

MCP服务器将在 http://localhost:48081/mcp.

备注:

• 替换 your-opensearch-host 使用您的实际OpenSearch主机名或IP
• 使用 host.docker.internal （macOS/Windows）或您的主机IP（Linux）（如果主机上运行OpenSearch）
• 对于远程实例，请使用实际的主机名或IP地址

配置

MCP服务器从环境变量中读取连接设置：

使用Docker Compose时，这些变量会自动从容器环境中可用。

MCP工具

stack_trace_tid

按事务ID（TID）检索完整的错误堆栈跟踪。

参数：

• tid （字符串，必填）：要搜索的交易ID
• index_pattern （字符串，可选）：要搜索的索引模式（默认值： servicelogs-*)
• repo_name （字符串，可选）：按存储库/应用程序名称筛选（映射到 application_name 现场）

例子：

{
    "tid": "e1020584c0a74074a930c4e90e953912.139.17702793574644017",
    "repo_name": "xxx"
}

退货： 每行有一个日志条目的格式化文本。每一行都遵循以下格式：

timestamp - level - message - application_name - project

如果单独 stack_trace 字段存在于日志文档中，格式为：

timestamp - level - message - stack_trace - application_name - project

注： 日志条目按时间顺序排序 @timestamp 按升序排列。消息和堆栈跟踪中的新行被规范化为 | （管道字符）用于单行格式。

输出示例：

2026-02-05T08:15:57.566Z - INFO - channel GOPAY got phone A0:1ec614bbcb328b7c66436a318d7b77e0 from token - xxx - xxx
2026-02-05T08:15:57.570Z - INFO - register user for A0:44b351780fec875b97ad01d9bb946f3e , system : SYSTEM_TYPE_ATOME, channel: GOPAY - user-service-provider - pintar-user
2026-02-05T08:15:58.263Z - ERROR - POST http://:8080/user/info -d [{"module":"RESIDENTIAL_INFO","module":"RESIDENTIAL_INFO",...}] ***RESPONSE*** 400 {"timestamp":1770279358262,"status":400,"error":"Bad Request","path":"/user/info"} - xxx - xxx
2026-02-05T08:15:58.264Z - ERROR - [Gopay Linking] Failed to save user info for userId : [400 ] during [POST] to [http://:8080/user/info] [PintarUserInfoFeignClient#saveUserInfo(List)]: [{"timestamp":1770279358262,"status":400,"error":"Bad Request","path":"/user/info"}] - feign.FeignException$BadRequest: [400 ] during [POST] to [http://:8080/user/info] [PintarUserInfoFeignClient#saveUserInfo(List)]: [{"timestamp":1770279358262,"status":400,"error":"Bad Request","path":"/user/info"}] | at feign.FeignException.clientErrorStatus(FeignException.java:243) | at feign.FeignException.errorStatus(FeignException.java:223) | at feign.FeignException.errorStatus(FeignException.java:213) | ... - xxx - xxx
2026-02-05T08:15:58.267Z - INFO - [GopayServiceImpl] linking account failed for userId: , error: INVALID_KYC - xxx - xxx

注： 日志条目按时间戳升序排序。堆栈跟踪（如果存在）作为消息字段的一部分包含在内，堆栈帧之间用 | （管道字符）。

与MCP客户端一起使用

MCP服务器使用 流式Http 港口运输 48081。这支持基于HTTP的通信，而不是stdio，使其更容易部署和扩展。

启动服务器

重要：启动MCP服务器之前，请确保您的OpenSearch实例正在运行且可访问。

选项1：使用Docker Compose（推荐）

1. 在中配置您的OpenSearch连接 .env:

cp .env.example .env
# Edit .env with your OpenSearch host and port

1. 启动MCP服务器：

docker-compose up

MCP服务器将在 http://localhost:48081/mcp.

选项2：本地运行

1. 设置环境变量：

cp .env.example .env
# Edit .env with your OpenSearch host and port

1. 运行MCP服务器：

python server.py

服务器将于启动 http://localhost:48081/mcp.

选项3：使用Docker Run

塑造形象：

docker build -t opensearch-mcp .

使用OpenSearch连接运行容器：

docker run --rm -p 48081:48081 \
  -e OPENSEARCH_HOST=your-opensearch-host \
  -e OPENSEARCH_PORT=9200 \
  opensearch-mcp

或者使用env文件：

docker run --rm -p 48081:48081 --env-file .env opensearch-mcp

配置MCP客户端

光标IDE

添加到光标MCP设置(mcp.json):

{
    "mcpServers": {
        "opensearch": {
            "url": "http://localhost:48081/mcp"
        }
    }
}

克劳德桌面版

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
    "mcpServers": {
        "opensearch": {
            "url": "http://localhost:48081/mcp"
        }
    }
}

远程访问

如果MCP服务器在远程计算机上运行，请使用远程URL：

{
    "mcpServers": {
        "opensearch": {
            "url": "http://your-server-ip:48081/mcp"
        }
    }
}

配置

MCP服务器端口和主机可以通过环境变量进行配置：

• MCP_PORT：HTTP服务器的端口（默认值：48081）
• MCP_HOST：要绑定的主机（默认值：0.0.0.0）

例子：

MCP_PORT=8080 MCP_HOST=127.0.0.1 python server.py

Docker网络说明

• 本地开发：使用 http://localhost:48081/mcp
• vpn访问：docker-compose.yml使用 network_mode: host 允许容器通过主机的网络访问VPN资源
• Docker Compose：使用主机网络模式时，容器共享主机的网络堆栈，包括VPN连接
• 远程访问：确保端口48081可从MCP客户端访问

备注：与 network_mode: host，容器直接使用主机的网络，因此：

• 可以从容器访问VPN资源
• 不需要端口映射（端口可以在主机上直接访问）
• 容器可以访问需要VPN连接的资源

发展

项目结构

opensearch-mcp/
├── src/
│   └── opensearch_mcp/
│       ├── __init__.py
│       ├── server.py              # FastMCP server with tool definitions
│       └── opensearch_client.py    # OpenSearch client wrapper
├── docker-compose.yml              # Docker Compose setup (OpenSearch + MCP server)
├── Dockerfile                      # MCP server Docker image
├── .dockerignore                   # Docker ignore file
├── .env.example                    # Example environment variables
├── mcp.json.example                # Example MCP client configuration
├── requirements.txt                # Python dependencies
├── pyproject.toml                  # Python project configuration
└── README.md                       # This file

运行测试

# Ensure your OpenSearch instance is running and accessible

# Start MCP server with Docker Compose
docker-compose up

# Or run MCP server locally
python server.py

Docker编写服务

这 docker-compose.yml 仅包括MCP服务器服务：

1. opensearch mcp：MCP服务器（使用 .env 配置文件）

MCP服务器服务：

• 从本地Dockerfile构建
• 从加载环境变量 .env 文件
• 使用以下配置连接到您的OpenSearch实例 .env
• 暴露端口48081上的HTTP端点 /mcp 路径
• 使用流式Http传输进行MCP通信

备注：您需要提供自己的OpenSearch实例。在中配置连接详细信息 .env 文件。

日志数据格式

MCP服务器需要具有以下结构的日志文档：

{
    "@timestamp": "2024-01-01T10:00:00Z",
    "level": "ERROR",
    "msg": "Error occurred...",
    "application_name": "xxx",
    "project": "xxx",
    "stack_trace": "feign.FeignException$BadRequest: [...] | at ...",
    "TID": "e1020584c0a74074a930c4e90e953912.139.17702793574644017"
}

关键字段：

• @timestamp：日志时间戳（ISO 8601格式）
• level：日志级别（信息、警告、错误等）
• msg：日志消息内容
• application_name：应用程序/服务名称（用于通过筛选 repo_name 参数）
• project：项目/存储库名称
• stack_trace：堆栈跟踪内容（可选，格式为管道分隔线）
• TID：交易ID字段（使用所有字段中的短语匹配进行搜索）

故障排除

连接错误

如果您看到连接错误：

1. 确保您的OpenSearch实例正在运行且可访问
2. 检查OpenSearch运行状况： curl http://your-opensearch-host:9200/_cluster/health
3. 验证中的环境变量 .env 设置正确（OPENSEARCH_HOST和OPENSEARCH_PORT）
4. 如果在Docker中运行，请确保容器可以访问您的OpenSearch实例（网络配置）

未找到结果

• 检查您的索引模式是否与现有索引匹配（默认值： servicelogs-*)
• 验证日志文档中是否存在TID（使用所有字段中的短语匹配进行搜索）
• 如果使用 repo_name 过滤器，验证 application_name 字段存在并与筛选值匹配
• 确保TID格式与日志中存储的格式匹配

SSL/TLS问题

如果使用SSL：

• 集 OPENSEARCH_USE_SSL=true
• 配置 OPENSEARCH_VERIFY_CERTS 适当地
• 如果需要，提供CA证书

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交拉取请求。