Skip to content

Commit cd6cb16

Browse files
CoolgiserzCoolgiserz
committed
chore
1 parent bd45429 commit cd6cb16

File tree

6 files changed

+239
-200
lines changed

6 files changed

+239
-200
lines changed

‎Dockerfile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ COPY pyproject.toml uv.lock /app
1616
ENV UV_PYPI_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
1717
# 安装 Python 依赖
1818
# 优先使用 uv（如有 uv.lock），否则用 pip 安装 requirements.txt
19-
RUN pip install -i https://mirrors.aliyun.com/pypi/simple uv && uv sync
19+
RUN uv sync
2020

2121
# 复制项目文件到容器
2222
COPY ./src/ /app

‎README.md‎

Lines changed: 184 additions & 183 deletions
Original file line numberDiff line numberDiff line change
@@ -1,183 +1,184 @@
1-
# Customized-Elasticsearch-MCP-Server
2-
3-
基于 Python `FastMCP` 和 `FastAPI` 的 自定义Elasticsearch MCP 服务Demo。
4-
5-
## 特性
6-
- 支持关键词搜索、二次过滤、按 ID 查询
7-
- 基于 FastMCP 提供 MCP 协议工具：`search_news`、`search_news_with_secondary_filter`、`read_single_news`
8-
- Prometheus 监控集成（`starlette_prometheus`）
9-
- Docker 与 Docker Compose 支持
10-
- 包含单元测试和集成测试
11-
![](images/mcp-server.png)
12-
13-
## 目录结构
14-
15-
```
16-
.
17-
├── src
18-
│ └── news_mcp_server
19-
│ ├── app.py # FastAPI 应用入口
20-
│ ├── mcp_server.py # FastMCP 服务定义
21-
│ ├── clients
22-
│ │ └── elastic_client.py # 异步 ES 客户端
23-
│ ├── services
24-
│ │ └── news_service.py # 业务逻辑封装
25-
│ ├── middlewares
26-
│ │ ├── auth.py # 简单 Token 鉴权
27-
│ │ ├── monitor.py # Prometheus 中间件
28-
│ │ └── session.py # Session 中间件
29-
│ ├── schemas
30-
│ │ └── news.py # Pydantic 数据模型
31-
│ └── config
32-
│ └── settings.py # 环境配置
33-
├── tests
34-
│ ├── unit # 单元测试
35-
│ └── integration # 集成测试
36-
├── Dockerfile # 容器构建配置
37-
├── docker-compose.yml # Docker Compose 配置
38-
├── Makefile # 常用命令集
39-
├── env.sample # 环境变量示例
40-
├── pyproject.toml # Python 项目配置
41-
└── README.md # 项目说明
42-
```
43-
44-
## 环境变量
45-
46-
复制 `env.sample` 为 `.env` 并配置：
47-
48-
```bash
49-
cp env.sample .env
50-
# 编辑 .env，至少需要以下变量：
51-
# ES_API_KEY Elasticsearch API Key（必填）
52-
# ES_HOST Elasticsearch 主机 URL（含端口）（必填）
53-
# ES_INDEX Elasticsearch 索引名称（必填）
54-
# API_KEY MCP 服务访问令牌（Bearer Token）（必填）
55-
```
56-
57-
58-
## 安装与运行
59-
60-
### 本地开发
61-
62-
1. 克隆项目并进入目录：
63-
```bash
64-
git clone https://github.com/Coolgiserz/customized-elasticsearch-mcp-server
65-
cd customized-elasticsearch-mcp-server
66-
```
67-
2. 创建并激活虚拟环境：
68-
```bash
69-
python3.12 -m venv .venv
70-
source .venv/bin/activate
71-
```
72-
3. 安装依赖：
73-
```bash
74-
pip install -U pip
75-
pip install uv[all]
76-
uv sync
77-
```
78-
4. 启动服务（热重载）：
79-
```bash
80-
make dev
81-
# 或者
82-
uv run uvicorn src.main:app --reload --host 0.0.0.0 --port 9009
83-
```
84-
5. 访问：
85-
- 健康检查: `GET http://localhost:9009/healthcheck`
86-
- Prometheus 指标: `GET http://localhost:9009/metrics`
87-
88-
### Docker & Docker Compose
89-
90-
- 构建镜像：
91-
```bash
92-
make build
93-
```
94-
- 使用 Docker Compose 一键启动：
95-
```bash
96-
make docker-build
97-
make docker-up
98-
```
99-
- 停止服务：
100-
```bash
101-
make docker-down
102-
```
103-
- 日志查看：
104-
```bash
105-
make docker-logs
106-
```
107-
- 默认映射端口：`28000 -> 8000`
108-
109-
## API 使用
110-
111-
### Healthcheck
112-
113-
```
114-
GET /healthcheck
115-
Response: {"status":"ok"}
116-
```
117-
118-
### Prometheus Metrics
119-
120-
```
121-
GET /metrics
122-
```
123-
124-
### MCP 工具调用示例
125-
126-
使用 Python FastMCP 客户端调用 `search_news`：
127-
128-
```python
129-
import asyncio
130-
from fastmcp import Client
131-
132-
async def main():
133-
# 将 URL 替换为实际部署地址
134-
async with Client("http://localhost:9009/mcp-server") as client:
135-
tools = await client.list_tools()
136-
print("可用工具：", tools)
137-
138-
result = await client.call_tool("search_news", {
139-
"query": "人工智能",
140-
"max_results": 5,
141-
"date_from": "2024-01-01",
142-
"date_to": "2024-12-31"
143-
})
144-
print(result)
145-
146-
asyncio.run(main())
147-
```
148-
149-
## 测试
150-
151-
- 单元测试：
152-
```bash
153-
make test
154-
```
155-
- 集成测试：
156-
```bash
157-
pytest -q -m "integration"
158-
```
159-
160-
## Makefile 常用命令
161-
162-
```bash
163-
make init # 初始化依赖
164-
env sync # 同步依赖（uv sync）
165-
make dev # 启动开发模式
166-
make lint # 代码检查
167-
make format # 代码格式化
168-
make test # 运行测试
169-
dmake build # 构建 Docker 镜像
170-
```
171-
172-
## TODO
173-
- 引入基于 JWT 或 OAuth2 的更安全鉴权机制
174-
- 支持多进程/多实例共享会话（如使用 Redis Session Store）
175-
- 优化 Elasticsearch 查询性能，添加缓存层（Redis）
176-
- 集成请求限流和熔断策略，以防止高频或恶意请求
177-
- 增加端到端集成测试覆盖，并配置 CI/CD 流水线
178-
- 支持 ES 聚合查询与热门关键词统计功能
179-
- 提供 Swagger UI 或 Postman 集合示例
180-
181-
## License
182-
183-
本项目采用 MIT 许可证，详见 LICENSE。
1+
# Customized-Elasticsearch-MCP-Server
2+
3+
基于 Python `FastMCP` 和 `FastAPI` 的 自定义Elasticsearch MCP 服务Demo。
4+
5+
## 特性
6+
- 支持关键词搜索、二次过滤、按 ID 查询
7+
- 基于 FastMCP 提供 MCP 协议工具：`search_news`、`search_news_with_secondary_filter`、`read_single_news`
8+
- Prometheus 监控集成（`starlette_prometheus`）
9+
- 基于 Redis 的服务端 Session 存储（`RedisSessionMiddleware`）
10+
- Docker 与 Docker Compose 支持
11+
- 包含单元测试和集成测试
12+
![](images/mcp-server.png)
13+
14+
## 目录结构
15+
16+
```
17+
.
18+
├── src
19+
│ └── news_mcp_server
20+
│ ├── app.py # FastAPI 应用入口
21+
│ ├── mcp_server.py # FastMCP 服务定义
22+
│ ├── clients
23+
│ │ └── elastic_client.py # 异步 ES 客户端
24+
│ ├── services
25+
│ │ └── news_service.py # 业务逻辑封装
26+
│ ├── middlewares
27+
│ │ ├── auth.py # 简单 Token 鉴权
28+
│ │ ├── monitor.py # Prometheus 中间件
29+
│ │ └── session.py # Session 中间件
30+
│ ├── schemas
31+
│ │ └── news.py # Pydantic 数据模型
32+
│ └── config
33+
│ └── settings.py # 环境配置
34+
├── tests
35+
│ ├── unit # 单元测试
36+
│ └── integration # 集成测试
37+
├── Dockerfile # 容器构建配置
38+
├── docker-compose.yml # Docker Compose 配置
39+
├── Makefile # 常用命令集
40+
├── env.sample # 环境变量示例
41+
├── pyproject.toml # Python 项目配置
42+
└── README.md # 项目说明
43+
```
44+
45+
## 环境变量
46+
47+
复制 `env.sample` 为 `.env` 并配置：
48+
49+
```bash
50+
cp env.sample .env
51+
# 编辑 .env，至少需要以下变量：
52+
# ES_API_KEY Elasticsearch API Key（必填）
53+
# ES_HOST Elasticsearch 主机 URL（含端口）（必填）
54+
# ES_INDEX Elasticsearch 索引名称（必填）
55+
# API_KEY MCP 服务访问令牌（Bearer Token）（必填）
56+
```
57+
58+
59+
## 安装与运行
60+
61+
### 本地开发
62+
63+
1. 克隆项目并进入目录：
64+
```bash
65+
git clone https://github.com/Coolgiserz/customized-elasticsearch-mcp-server
66+
cd customized-elasticsearch-mcp-server
67+
```
68+
2. 创建并激活虚拟环境：
69+
```bash
70+
python3.12 -m venv .venv
71+
source .venv/bin/activate
72+
```
73+
3. 安装依赖：
74+
```bash
75+
pip install -U pip
76+
pip install uv[all]
77+
uv sync
78+
```
79+
4. 启动服务（热重载）：
80+
```bash
81+
make dev
82+
# 或者
83+
uv run uvicorn src.main:app --reload --host 0.0.0.0 --port 9009
84+
```
85+
5. 访问：
86+
- 健康检查: `GET http://localhost:9009/healthcheck`
87+
- Prometheus 指标: `GET http://localhost:9009/metrics`
88+
89+
### Docker & Docker Compose
90+
91+
- 构建镜像：
92+
```bash
93+
make build
94+
```
95+
- 使用 Docker Compose 一键启动：
96+
```bash
97+
make docker-build
98+
make docker-up
99+
```
100+
- 停止服务：
101+
```bash
102+
make docker-down
103+
```
104+
- 日志查看：
105+
```bash
106+
make docker-logs
107+
```
108+
- 默认映射端口：`28000 -> 8000`
109+
110+
## API 使用
111+
112+
### Healthcheck
113+
114+
```
115+
GET /healthcheck
116+
Response: {"status":"ok"}
117+
```
118+
119+
### Prometheus Metrics
120+
121+
```
122+
GET /metrics
123+
```
124+
125+
### MCP 工具调用示例
126+
127+
使用 Python FastMCP 客户端调用 `search_news`：
128+
129+
```python
130+
import asyncio
131+
from fastmcp import Client
132+
133+
async def main():
134+
# 将 URL 替换为实际部署地址
135+
async with Client("http://localhost:9009/mcp-server") as client:
136+
tools = await client.list_tools()
137+
print("可用工具：", tools)
138+
139+
result = await client.call_tool("search_news", {
140+
"query": "人工智能",
141+
"max_results": 5,
142+
"date_from": "2024-01-01",
143+
"date_to": "2024-12-31"
144+
})
145+
print(result)
146+
147+
asyncio.run(main())
148+
```
149+
150+
## 测试
151+
152+
- 单元测试：
153+
```bash
154+
make test
155+
```
156+
- 集成测试：
157+
```bash
158+
pytest -q -m "integration"
159+
```
160+
161+
## Makefile 常用命令
162+
163+
```bash
164+
make init # 初始化依赖
165+
env sync # 同步依赖（uv sync）
166+
make dev # 启动开发模式
167+
make lint # 代码检查
168+
make format # 代码格式化
169+
make test # 运行测试
170+
dmake build # 构建 Docker 镜像
171+
```
172+
173+
## TODO
174+
- 引入基于 JWT 或 OAuth2 的更安全鉴权机制
175+
- 支持多进程/多实例共享会话（如使用 Redis Session Store）
176+
- 优化 Elasticsearch 查询性能，添加缓存层（Redis）
177+
- 集成请求限流和熔断策略，以防止高频或恶意请求
178+
- 增加端到端集成测试覆盖，并配置 CI/CD 流水线
179+
- 支持 ES 聚合查询与热门关键词统计功能
180+
- 提供 Swagger UI 或 Postman 集合示例
181+
182+
## License
183+
184+
本项目采用 MIT 许可证，详见 LICENSE。

0 commit comments

Comments
 (0)