Skip to main content
Glama
goofish-price-mcp

goofish-price-mcp

by SkySabre
README.md
# goofish-price-mcp

把 [ai-goofish-monitor](https://github.com/Usagi-org/ai-goofish-monitor) 积累的闲鱼行情数据暴露成 MCP(Model Context Protocol)工具,让任意 AI Agent(Claude Desktop / Cursor / Cline / 本地 harness…)直接查询二手价格、历史趋势和蹲守结果。

Read-only MCP server that exposes Xianyu (Goofish) second-hand market prices collected by [ai-goofish-monitor](https://github.com/Usagi-org/ai-goofish-monitor) watch tasks.

## 它解决什么问题

ai-goofish-monitor 在浏览器里 7×24 蹲守关键词,把每次搜索页看到的挂牌价存进本地 SQLite。
本项目**只读这份数据库**(不碰网站、零风控风险、毫秒级响应),把它翻译成 Agent 友好的工具:

> 你:“DDR4 16G 现在什么行情?有没有低于 300 的单条?”
> Agent 调 `get_price_stats("DDR4")` + `latest_items("DDR4", max_price=300)` → 直接给出均价、趋势和具体商品链接。

## Tools

| Tool | 说明 |
|---|---|
| `get_price_stats(keyword, days=30)` | 行情统计:均价/中位/最低/最高、按天趋势、最便宜的 5 条商品(含链接)。关键词模糊匹配 |
| `latest_items(keyword?, max_price?, min_price?, recommended_only?, limit)` | 最近蹲到的在售商品明细(标题/价格/链接/卖家/发布时间) |
| `market_overview()` | 所有已监控关键词的行情速览 |
| `list_watch_tasks()` | 蹲守任务清单(关键词、价格区间、cron、判定模式、已入库数量) |

> 样本口径:`get_price_stats` 的数据 = 监控任务在其搜索条件(价格区间/个人闲置等筛选)下每次运行**实际看到的挂牌价**,会受任务筛选条件影响,不等于全网成交均价。

## Quick start

前置:本机已部署 ai-goofish-monitor 且至少跑过一个蹲守任务(产生 `data/app.sqlite3`)。

```bash
pip install -e .            # 或 uv pip install -e .
export GOOFISH_DB_PATH=/path/to/ai-goofish-monitor/data/app.sqlite3
goofish-price-mcp           # stdio MCP server,打印 DB 路径到 stderr 后等待连接
```

接入 MCP 客户端(以 Claude Desktop / 通用 `mcpServers` 配置为例):

```json
{
  "mcpServers": {
    "goofish-price": {
      "command": "/path/to/venv/bin/goofish-price-mcp",
      "env": { "GOOFISH_DB_PATH": "/path/to/ai-goofish-monitor/data/app.sqlite3" }
    }
  }
}
```

DB 路径解析顺序:`GOOFISH_DB_PATH` → `./data/app.sqlite3` → `/app/data/app.sqlite3` → `~/.ai-goofish/data/app.sqlite3`。

## Development

```bash
python tests/test_queries.py   # 内存库单元测试,无外部依赖
```

只读连接(`file:...?mode=ro`)与监控进程的 WAL 写入共存,不会阻塞爬虫。

## Roadmap (v0.2+)

- `refresh_price(keyword)`:按需现抓一屏实时价(复用登录态 + 进程锁排队)
- `add_watch_task(keyword, max_price)`:Agent 一句话建立新蹲守任务
- PyPI 发布(`uvx goofish-price-mcp`)

## License

MIT · 数据归属其来源(闲鱼页面公开展示信息),本项目仅供学习研究。

TDQS

B3.4/5.0

Scored across 4 tools

Disambiguation4/5

Each tool has a reasonably distinct target: per-keyword deep stats, per-item listing, cross-keyword snapshot, and task listing. The only soft overlap is between get_price_stats and market_overview, which both return aggregate prices (one deep per keyword, one shallow across all); descriptions clarify the split but an agent could still pick the wrong one for a quick check.

Naming Consistency3/5

All names are snake_case, but the conventions are mixed: get_price_stats and list_watch_tasks use verb_noun while latest_items and market_overview are bare noun phrases. It remains readable, but the set does not follow a single predictable pattern.

Tool Count4/5

Four tools is on the lean side but each covers a distinct query surface (stats, items, overview, tasks) with no filler. It is appropriately scoped for a read/query-oriented price monitoring server.

Completeness3/5

The read side is covered (stats, item lists, overview, task listing), but the monitoring lifecycle is incomplete: list_watch_tasks exists with no create_watch_task, update, or delete counterpart, so an agent cannot start or stop monitoring a keyword. No tool exposes per-item history or cross-keyword comparison either.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues