FrankenFish
by eone520
README.md
# 🧟 FrankenFish — the second-hand electronics shop assistant stitched from spare parts
> Kiroween 2026 · **Frankenstein** category · built with [Kiro](https://kiro.dev)
FrankenFish stitches together pieces that were never meant to meet:
| Body part | What it is | Role |
|---|---|---|
| 🦴 Skeleton | [goofish-cli](https://github.com/fancyboi999/goofish-cli) (Apache-2.0) MCP server | Talks to Xianyu (闲鱼), China's largest second-hand marketplace, **on the seller's own account** |
| 🧠 Brain | Any OpenAI-compatible LLM (domestic or overseas, user's own key) | Drafts buyer replies in Chinese |
| 🫀 Heart | FrankenFish MCP server (this repo) | Price radar, pricing rules for used phones/laptops, reply guard rails |
| ⚡ Lightning | Kiro specs, hooks and steering | How the creature was assembled |
**Who it is for:** one-person second-hand electronics shops on Xianyu. The owner does sourcing, listing, customer service and after-sales alone. FrankenFish answers three questions every day:
1. *What should I price this used iPhone 15 Pro 256G 95新 at?* → `suggest_price`
2. *What is the market doing for this model this week?* → `market_snapshot`
3. *How do I answer this buyer who is haggling / asking about battery health?* → `draft_reply` (never sends on its own)
---
## Quick start (demo mode — no Xianyu account needed)
```bash
pip install -e .
frankenfish demo # colourful walkthrough from bundled synthetic data
```
Expected output: market snapshot → price suggestion → three buyer reply drafts.
Runs in under one second.
### MCP server (Kiro / Claude Code / any MCP client)
```json
{ "mcpServers": { "frankenfish": { "command": "frankenfish", "args": ["mcp"] } } }
```
Three tools are available:
| Tool | Description |
|---|---|
| `market_snapshot(model)` | p25 / median / p75 of listing prices, outliers removed |
| `suggest_price(model, condition, battery_health?, full_box?, has_warranty?)` | list price (ends in 9) + floor price + basis explanation |
| `draft_reply(buyer_message, list_price, floor_price)` | classifies message, drafts Chinese reply, flags off-platform words, never auto-sends |
Every tool returns `{"ok": bool, "data": ..., "error": str|null, "source": str}`.
---
## Live mode (optional — seller's own account only)
1. Install [goofish-cli](https://github.com/fancyboi999/goofish-cli): `pip install goofish-cli`
2. Authenticate: `goofish auth login --qr`
3. Set the env var: `FRANKENFISH_SOURCE=goofish`
FrankenFish queries goofish-cli at most 3 times per minute and caches results for 1 hour.
If goofish-cli is missing or not logged in, it falls back to demo data automatically.
---
## LLM reply drafting (optional)
Set these env vars to enable LLM-drafted replies (falls back to rule-based drafts when unset):
```bash
FRANKENFISH_LLM_BASE_URL=https://api.openai.com/v1
FRANKENFISH_LLM_KEY=sk-...
FRANKENFISH_LLM_MODEL=gpt-4o-mini # any OpenAI-compatible model
```
The same guard rails apply to LLM output: off-platform words are flagged, bargain offers
below `floor_price` are clamped, and `auto_send` is always `False`.
---
## Pricing rules
| Input | Adjustment |
|---|---|
| Condition grade (全新/99新/95新/9新/8新/7新及以下) | ×1.10 to ×0.62 of market median |
| Battery health < 85% | −5% |
| Full original box included | +2% |
| Valid Apple/manufacturer warranty remaining | +3% |
| Outliers (< 40% or > 200% of raw median) | excluded before statistics |
| list_price | rounded to nearest ¥10, then −¥1 (ends in 9) |
| floor_price | min(list_price, p25 × factor) × 0.97, capped at list_price |
---
## Tests
```bash
pip install -e ".[dev]"
PYTHONPATH=src python -m pytest -q
```
24 tests including Hypothesis property tests for every pricing rule (R1–R3) and
reply guard rails (R4.1–R4.4).
---
## Responsible use
- Demo data in `src/frankenfish/data/` is **synthetic** (every row has `"synthetic": true`).
- Live mode reads a small number of on-demand searches on the seller's own account only.
- No bulk scraping, no storing other users' data beyond a 1-hour in-process cache.
- Replies are **never sent automatically** (`auto_send` is always `False`).
- See `docs/compliance.md` for full details.
## How Kiro was used
See `.kiro/` (specs, steering, hooks) and `docs/kiro-writeup.md`.
## License
MIT. Uses goofish-cli (Apache-2.0) as an optional external dependency — see `NOTICE`.
---
## 中文说明
FrankenFish(缝合鱼)是给闲鱼数码个体店主用的 AI 助手:行情雷达 + 智能定价 + 客服回复草稿,以 MCP 工具形式接入 Kiro、Claude Code 等。
默认演示模式用合成数据,不需要闲鱼账号;实盘模式只用卖家本人账号、按需少量查询(≤3次/分钟,缓存1小时),不批量爬取、不自动发消息。
可选 LLM 接入(OpenAI 兼容接口),未配置时降级为规则模板。每条定价建议都有 basis 字段解释每一步调整,议价回复永远不低于 floor_price。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues