内容
# kupi-scraper-mcp
Railway-ready 服务器，暴露来自本地CSV文件的产品和销售数据。
运行时目标：Python `3.14.4`。
## 功能特点
- 快速MCP服务器，支持三种传输方式：`streamable-http`，`sse`，和 `stdio`。
- 基于CSV的MCP工具：
- `获取分类`
- `获取所有产品`
- `按分类获取产品`
- `获取销售数据`
- `按零售商获取销售数据`
- HTTP传输的可选API密钥认证。
- 公共健康检查端点 `/healthz`。
- 针对Railway部署优化的Dockerfile。
## 数据源
- 产品分类文件：`produkty/*.csv`
- 销售文件：`slevy_all.csv`
- CSV解析：UTF-8 (`utf-8-sig`)，`;`分隔符。
## 工具合约
所有工具响应都使用此信封：
```json
{
"tool": "工具名称",
"dummy": false,
"timestamp": "ISO-8601 UTC",
"input": {},
"data": {}
}
```
### 工具详情
- `获取分类()`
- 返回分类名称（CSV文件名）和每个分类的产品数量。
- `获取所有产品()`
- 返回来自所有分类文件的去重产品。
- 产品字段：`名称`，`制造商`，`来源分类`，`分类`（可为空）。
- `按分类获取产品(分类: list[str])`
- 返回按选定文件分类筛选的去重产品。
- 为未知分类引发验证错误，并包含允许的值。
- `获取销售数据(查询: str | None = None)`
- 当查询为空时，返回 `slevy_all.csv` 中的所有销售记录。
- 提供查询时，按产品名称部分匹配（不区分大小写和变音符号不敏感）进行筛选。
- 销售字段：`名称`，`商店`，`价格`，`数量`，`有效期`。
- `按零售商获取销售数据(查询: str | None = None)`
- 当查询为空时，返回 `slevy_all.csv` 中的所有销售记录。
- 提供查询时，按零售商/商店部分匹配（不区分大小写和变音符号不敏感）进行筛选。
- 销售字段：`名称`，`商店`，`价格`，`数量`，`有效期`。
## 项目布局
```text
src/kupi_scraper_mcp/
__init__.py
__main__.py
server.py
tests/
test_tools.py
test_transport.py
test_cli.py
produkty/
*.csv
slevy_all.csv
Dockerfile
pyproject.toml
```
## 本地使用
以可编辑模式安装：
```bash
pip install -e .
```
运行 streamable HTTP：
```bash
kupi-scraper-mcp streamable-http
```
运行 SSE：
```bash
kupi-scraper-mcp sse
```
运行_stdio：
```bash
kupi-scraper-mcp stdio
```
## 环境变量
- `PORT`: 主要绑定端口（Railway友好，默认为 `8000`）
- `FASTMCP_PORT`: 当 `PORT` 未设置时的备用绑定端口
- `FASTMCP_HOST`: 绑定主机（默认为 `0.0.0.0`）
- `KUPI_MCP_API_KEY`: 用于保护HTTP MCP端点的可选API密钥
- `KUPI_MCP_API_KEY_HEADER`: API密钥头名称（默认为 `x-api-key`）
- `KUPI_MCP_DATA_DIR`: 包含 `produkty/` 和 `slevy_all.csv` 的基准目录
- `KUPI_MCP_PRODUCTS_DIR`: 分类CSV目录的覆盖路径（默认为 `<data_dir>/produkty`）
- `KUPI_MCP_SALES_FILE`: 销售CSV文件的覆盖路径（默认为 `<data_dir>/slevy_all.csv`）
## 端点
Streamable HTTP模式：
- MCP端点：`/mcp`
- 零售商销售端点：`/sales/by-retailer?query=Tesco`
- 健康端点：`/healthz`
SSE模式：
- SSE端点：`/sse`
- 零售商销售端点：`/sales/by-retailer?query=Tesco`
- 健康端点：`/healthz`
`/healthz` 端点即使启用API密钥认证也是公开的。
## Railway部署（Dockerfile优先）
此仓库包含一个带有默认启动命令的`Dockerfile`：
```text
kupi-scraper-mcp streamable-http
```
Railway应自动设置 `PORT`。您可以选择设置：
- `KUPI_MCP_API_KEY`
- `KUPI_MCP_API_KEY_HEADER`
- `KUPI_MCP_DATA_DIR` （或 `KUPI_MCP_PRODUCTS_DIR` + `KUPI_MCP_SALES_FILE`）
用于SSE的备用Railway启动命令：
```text
kupi-scraper-mcp sse
```
## LibreChat MCP配置示例
无认证的Streamable HTTP：
```yaml
mcpServers:
kupi-scraper:
type: streamable-http
url: https://your-railway-domain/mcp
```
启用API密钥的Streamable HTTP：
```yaml
mcpServers:
kupi-scraper:
type: streamable-http
url: https://your-railway-domain/mcp
headers:
x-api-key: "${KUPI_MCP_API_KEY}"
```
启用API密钥的SSE：
```yaml
mcpServers:
kupi-scraper:
type: sse
url: https://your-railway-domain/sse
headers:
x-api-key: "${KUPI_MCP_API_KEY}"
```
## 测试
运行测试：
```bash
pytest -q
```
