Metadata-Version: 2.4
Name: ifc-es-mcp-server
Version: 0.1.3
Summary: Elasticsearch MCP Server for IFC logging system
Project-URL: Homepage, https://github.com/your-username/ifc-es-mcp-server
Project-URL: Repository, https://github.com/your-username/ifc-es-mcp-server
Project-URL: Issues, https://github.com/your-username/ifc-es-mcp-server/issues
Author-email: Your Name <your.email@example.com>
License-Expression: MIT
Keywords: elasticsearch,ifc,logging,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: System :: Logging
Requires-Python: >=3.10
Requires-Dist: elasticsearch<9.0.0,>=8.0.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# ifc-es-mcp-server

Elasticsearch MCP Server for IFC logging system.

## 功能特性

- 🔍 **索引管理** - 列出可用索引、查看字段映射
- 📊 **日志搜索** - 按时间范围、关键词、日志级别、服务名等条件搜索日志
- 📈 **聚合统计** - 对日志字段进行聚合分析（如错误码分布、级别分布等）
- 🔗 **链路追踪** - 通过 trace_id 追踪分布式调用的全链路日志

## 安装

### 从 PyPI 安装（推荐）

```bash
pip install ifc-es-mcp-server
```

### 从源码安装

```bash
git clone https://github.com/your-username/ifc-es-mcp-server.git
cd ifc-es-mcp-server
pip install -e .
```

## 配置

创建 `.env` 文件或设置以下环境变量：

```bash
# Elasticsearch 连接配置
ES_HOSTS=http://localhost:9200
ES_USERNAME=
ES_PASSWORD=
ES_VERIFY_CERTS=false
ES_REQUEST_TIMEOUT=30
ES_MAX_RETRIES=3

# 查询默认值
ES_DEFAULT_SIZE=20
ES_MAX_SIZE=50

# 字段配置（可选）
ES_LEVEL_FIELDS=level.keyword,level
ES_MESSAGE_FIELDS=log_message,logmsg
ES_TRACE_FIELDS=tid
ES_SERVICE_FIELDS=serviceName.keyword,serviceName
ES_SOURCE_FIELDS=logtime,hostIP,level,serviceName,tid,thread,class,line,log_message
```

## 使用方式

### 1. 命令行启动

```bash
# 使用 stdio 传输（适用于 Claude Desktop 等客户端）
ifc-es-mcp-server

# 或使用 SSE 传输
ifc-es-mcp-server --transport sse --port 8080
```

### 2. 在 Claude Desktop 中配置

在 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "elasticsearch": {
      "command": "ifc-es-mcp-server",
      "env": {
        "ES_HOSTS": "http://your-es-host:9200",
        "ES_USERNAME": "your-username",
        "ES_PASSWORD": "your-password"
      }
    }
  }
}
```

### 3. 在 Claude Code 中配置

```json
{
  "mcpServers": {
    "elasticsearch": {
      "command": "ifc-es-mcp-server",
      "env": {
        "ES_HOSTS": "http://your-es-host:9200",
        "ES_USERNAME": "your-username",
        "ES_PASSWORD": "your-password"
      }
    }
  }
}
```

## 工具说明

### list_indices

列出可用的 ES 索引。

**参数：**
- `pattern` (str): 索引名匹配模式，支持通配符，默认 `*`
- `limit` (int): 返回数量上限，默认 50，最大 200

### get_index_mapping

查看索引的字段映射，了解有哪些字段可用。

**参数：**
- `index` (str): 索引名（支持通配符）

### search_logs

在 ES 中按时间范围 + 关键词 + 日志级别查询日志。

**参数：**
- `index` (str): 索引名，支持通配符
- `query` (str, optional): 关键词，默认在 log_message 字段匹配
- `level` (str, optional): 日志级别过滤，如 ERROR/WARN/INFO
- `service_names` (List[str], optional): 按服务名过滤
- `time_from` (str): 起始时间，默认 `now-10m`
- `time_to` (str): 结束时间，默认 `now`
- `match_type` (str): 匹配方式，match/match_phrase/wildcard
- `size` (int): 返回条数，默认 20，硬上限 50
- `sort_order` (str): 排序方式，desc/asc

### aggregate_logs

对日志做字段聚合统计。

**参数：**
- `index` (str): 索引名，支持通配符
- `field` (str): 要聚合的字段名
- `time_field` (str): 时间字段名，默认 `@timestamp`
- `time_from` (str): 起始时间，默认 `now-1h`
- `time_to` (str): 结束时间，默认 `now`
- `query` (str, optional): 聚合前先过滤的关键词
- `level` (str, optional): 聚合前先按日志级别过滤
- `service_names` (List[str], optional): 聚合前先按服务名过滤
- `top_n` (int): 返回分组数，默认 10，上限 100

### get_trace_detail

通过 trace_id 追踪分布式调用的全链路日志。

**参数：**
- `trace_id` (str): 链路追踪 ID
- `index` (str): 索引名，支持通配符
- `trace_field` (str, optional): trace_id 字段名，不传则自动探测
- `service_field` (str, optional): 服务名字段名，不传则自动探测
- `time_field` (str): 时间字段名，默认 `@timestamp`
- `time_from` (str): 起始时间，默认 `now-24h`
- `time_to` (str): 结束时间，默认 `now`
- `size` (int): 返回 span 上限，默认 500

## 开发

### 环境准备（推荐使用 uv）

```bash
# 安装 uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 同步依赖（自动创建虚拟环境）
uv sync

# 激活虚拟环境
source .venv/bin/activate  # Linux/Mac
# 或 .venv\Scripts\activate  # Windows
```

### 运行测试

```bash
uv run pytest
```

### 代码格式化

```bash
uv run ruff format .
uv run ruff check .
```

### 构建包

```bash
uv build
```

## 发布到 PyPI

```bash
# 使用 uv 发布
uv publish

# 或使用 twine（如果需要更细粒度控制）
uv tool install twine
twine upload dist/*

# 上传到 TestPyPI（测试）
twine upload --repository testpypi dist/*
```

## 环境变量说明

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `ES_HOSTS` | `http://localhost:9200` | ES 集群地址，多个用逗号分隔 |
| `ES_USERNAME` | `""` | ES 用户名 |
| `ES_PASSWORD` | `""` | ES 密码 |
| `ES_VERIFY_CERTS` | `false` | 是否验证 SSL 证书 |
| `ES_REQUEST_TIMEOUT` | `30` | 请求超时时间（秒） |
| `ES_MAX_RETRIES` | `3` | 最大重试次数 |
| `ES_DEFAULT_SIZE` | `20` | 默认返回条数 |
| `ES_MAX_SIZE` | `50` | 最大返回条数 |
| `ES_LEVEL_FIELDS` | `level.keyword,level` | 日志级别字段候选列表 |
| `ES_MESSAGE_FIELDS` | `log_message,logmsg` | 消息字段候选列表 |
| `ES_TRACE_FIELDS` | `tid` | Trace ID 字段候选列表 |
| `ES_SERVICE_FIELDS` | `serviceName.keyword,serviceName` | 服务名字段候选列表 |
| `ES_SOURCE_FIELDS` | `logtime,hostIP,level,serviceName,tid,thread,class,line,log_message` | 默认返回字段列表 |

## License

MIT
