furima-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- furima_mcp-0.1.0/.github/dependabot.yml +10 -0
- furima_mcp-0.1.0/.github/workflows/ci.yml +22 -0
- furima_mcp-0.1.0/.github/workflows/release.yml +17 -0
- furima_mcp-0.1.0/.gitignore +7 -0
- furima_mcp-0.1.0/CHANGELOG.md +8 -0
- furima_mcp-0.1.0/LICENSE +21 -0
- furima_mcp-0.1.0/PKG-INFO +127 -0
- furima_mcp-0.1.0/README.ja.md +78 -0
- furima_mcp-0.1.0/README.md +106 -0
- furima_mcp-0.1.0/SECURITY.md +21 -0
- furima_mcp-0.1.0/pyproject.toml +50 -0
- furima_mcp-0.1.0/src/furima_mcp/__init__.py +1 -0
- furima_mcp-0.1.0/src/furima_mcp/__main__.py +3 -0
- furima_mcp-0.1.0/src/furima_mcp/core.py +137 -0
- furima_mcp-0.1.0/src/furima_mcp/http.py +135 -0
- furima_mcp-0.1.0/src/furima_mcp/models.py +45 -0
- furima_mcp-0.1.0/src/furima_mcp/server.py +212 -0
- furima_mcp-0.1.0/src/furima_mcp/sites/__init__.py +5 -0
- furima_mcp-0.1.0/src/furima_mcp/sites/mercari.py +201 -0
- furima_mcp-0.1.0/src/furima_mcp/sites/paypay.py +113 -0
- furima_mcp-0.1.0/src/furima_mcp/sites/rakuma.py +131 -0
- furima_mcp-0.1.0/src/furima_mcp/sites/yahoo.py +122 -0
- furima_mcp-0.1.0/tests/__init__.py +0 -0
- furima_mcp-0.1.0/tests/conftest.py +11 -0
- furima_mcp-0.1.0/tests/fixtures.py +212 -0
- furima_mcp-0.1.0/tests/test_core.py +66 -0
- furima_mcp-0.1.0/tests/test_http.py +94 -0
- furima_mcp-0.1.0/tests/test_server.py +89 -0
- furima_mcp-0.1.0/tests/test_sites.py +136 -0
- furima_mcp-0.1.0/uv.lock +1342 -0
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
test:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
strategy:
|
|
12
|
+
matrix:
|
|
13
|
+
python: ["3.10", "3.11", "3.12", "3.13"]
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v4
|
|
16
|
+
- uses: astral-sh/setup-uv@v6
|
|
17
|
+
with:
|
|
18
|
+
python-version: ${{ matrix.python }}
|
|
19
|
+
- run: uv sync
|
|
20
|
+
- run: uv run ruff check .
|
|
21
|
+
- run: uv run ruff format --check .
|
|
22
|
+
- run: uv run pytest
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
name: Release
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
tags: ["v*"]
|
|
6
|
+
|
|
7
|
+
jobs:
|
|
8
|
+
pypi:
|
|
9
|
+
runs-on: ubuntu-latest
|
|
10
|
+
environment: pypi
|
|
11
|
+
permissions:
|
|
12
|
+
id-token: write # PyPI trusted publishing, no API token stored
|
|
13
|
+
steps:
|
|
14
|
+
- uses: actions/checkout@v4
|
|
15
|
+
- uses: astral-sh/setup-uv@v6
|
|
16
|
+
- run: uv build
|
|
17
|
+
- run: uv publish
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0 (2026-11-19)
|
|
4
|
+
|
|
5
|
+
- Tools: `search_listings`, `sold_price_stats`, `check_price`, `get_listing`.
|
|
6
|
+
- Sites: Mercari, Yahoo! Auctions, Yahoo! Flea Market, Rakuma.
|
|
7
|
+
- Per-site request spacing, retry with backoff on `429`/`503`, and a 5-minute result cache.
|
|
8
|
+
- `get_listing` only accepts listing URLs on the supported hosts and requests each site's canonical URL.
|
furima_mcp-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 fxia0018
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: furima-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: MCP server for Japanese second-hand marketplaces: search Mercari, Yahoo! Auctions, Yahoo! Flea Market and Rakuma, and check what things actually sell for.
|
|
5
|
+
Project-URL: Homepage, https://github.com/fxia0018/furima-mcp
|
|
6
|
+
Project-URL: Issues, https://github.com/fxia0018/furima-mcp/issues
|
|
7
|
+
Author: fxia0018
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: agent,japan,llm,mcp,mercari,price,rakuma,yahoo-auctions
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Natural Language :: Japanese
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Topic :: Internet :: WWW/HTTP
|
|
16
|
+
Requires-Python: >=3.10
|
|
17
|
+
Requires-Dist: cryptography>=42
|
|
18
|
+
Requires-Dist: httpx>=0.27
|
|
19
|
+
Requires-Dist: mcp<3,>=2.0
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
|
|
22
|
+
# furima-mcp
|
|
23
|
+
|
|
24
|
+
[](https://github.com/fxia0018/furima-mcp/actions/workflows/ci.yml)
|
|
25
|
+
[](https://pypi.org/project/furima-mcp/)
|
|
26
|
+
[](LICENSE)
|
|
27
|
+
|
|
28
|
+
English | [日本語](README.ja.md)
|
|
29
|
+
|
|
30
|
+
<!-- mcp-name: io.github.fxia0018/furima-mcp -->
|
|
31
|
+
|
|
32
|
+
An MCP server for Japanese second-hand marketplaces. It lets Claude, Cursor or any MCP client search **Mercari**, **Yahoo! Auctions**, **Yahoo! Flea Market** (PayPay Flea Market) and **Rakuma** at once, and check what an item actually sells for.
|
|
33
|
+
|
|
34
|
+
> **You:** Is ¥30,000 a good price for a Switch OLED?
|
|
35
|
+
>
|
|
36
|
+
> **Claude:** *(calls `check_price`)* Not really. Across 214 recent sales on Mercari, Yahoo! Auctions and Rakuma the median was ¥25,000 and the middle half sold for ¥22,000–28,000. ¥30,000 is dearer than 82% of them.
|
|
37
|
+
|
|
38
|
+
- No browser, no login, no API key. Plain HTTP; a search across all four sites takes a few seconds.
|
|
39
|
+
- Prices come from **sold** listings, not asking prices: Yahoo! Auctions final bids, Mercari and Rakuma sold items.
|
|
40
|
+
- One site failing doesn't fail the call. Its error is reported next to the other sites' results.
|
|
41
|
+
- Polite by default: requests to each site are spaced at least 1 s apart, `429`/`503` responses are retried with backoff, and repeated searches are served from a 5-minute cache.
|
|
42
|
+
|
|
43
|
+
## Tools
|
|
44
|
+
|
|
45
|
+
| Tool | What it does |
|
|
46
|
+
| --- | --- |
|
|
47
|
+
| `search_listings` | Search items for sale now. Filter by site and price, sort by relevance, newest or price across all sites. |
|
|
48
|
+
| `sold_price_stats` | Min / p25 / median / p75 / max of recent sold prices, overall and per site, with example sales. |
|
|
49
|
+
| `check_price` | Where a price falls among recent sales (percentile) and a one-line verdict. |
|
|
50
|
+
| `get_listing` | Full details of one listing URL: description, condition, images, seller rating, auction end time. |
|
|
51
|
+
|
|
52
|
+
Every tool takes `exclude` (drop titles containing these words, e.g. `["ジャンク", "箱のみ"]`). The price tools also take `match_all_words` (on by default) because the sites' own search is fuzzy: on Mercari, `PS5 CFI-2000` also returns PS5 games, which would drag the median down to a game's price.
|
|
53
|
+
|
|
54
|
+
## Install
|
|
55
|
+
|
|
56
|
+
Needs [uv](https://docs.astral.sh/uv/).
|
|
57
|
+
|
|
58
|
+
**Claude Code**
|
|
59
|
+
|
|
60
|
+
```sh
|
|
61
|
+
claude mcp add furima -- uvx furima-mcp
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
**Claude Desktop, Cursor and others** — add to the client's MCP config (`claude_desktop_config.json`, `.cursor/mcp.json`, ...):
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"mcpServers": {
|
|
69
|
+
"furima": {
|
|
70
|
+
"command": "uvx",
|
|
71
|
+
"args": ["furima-mcp"]
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Things to ask
|
|
78
|
+
|
|
79
|
+
- 「ドラクエ3 SFC 箱説付き」の相場を調べて
|
|
80
|
+
- Find a Pokémon card "ピカチュウ 25th プロモ" under ¥5,000, cheapest first, no PSA-graded ones
|
|
81
|
+
- Compare what a used Sony α7 III body sells for on Yahoo! Auctions vs Mercari
|
|
82
|
+
- Is this a good deal? https://jp.mercari.com/item/m12345678901
|
|
83
|
+
|
|
84
|
+
Search in Japanese for best results. Product names and model numbers (`CFI-2000`, `ILCE-7M3`) match far better than English descriptions.
|
|
85
|
+
|
|
86
|
+
## Notes
|
|
87
|
+
|
|
88
|
+
- **Sold history** comes from Yahoo! Auctions' closed auctions and Rakuma's sold items (most recent first) and Mercari's sold items (best match first). Yahoo! Flea Market has no public sold history, so it only appears in `search_listings`.
|
|
89
|
+
- **Auction prices** (`is_auction: true`) are current bids and may still rise until `ends_at`.
|
|
90
|
+
- **Mercari's `sold_at`** is the item's last update time, which is normally the sale.
|
|
91
|
+
- **Mercari Shops** products show up in search but `get_listing` doesn't support them yet.
|
|
92
|
+
|
|
93
|
+
## Configuration
|
|
94
|
+
|
|
95
|
+
Environment variables, all optional:
|
|
96
|
+
|
|
97
|
+
| Variable | Default | Meaning |
|
|
98
|
+
| --- | --- | --- |
|
|
99
|
+
| `FURIMA_MIN_INTERVAL` | `1.0` | Minimum seconds between two requests to the same site. Raising it is fine; lowering it is not recommended. |
|
|
100
|
+
| `FURIMA_CACHE_TTL` | `300` | Seconds a site's search result is reused for an identical query. `0` disables the cache. |
|
|
101
|
+
|
|
102
|
+
## Responsible use
|
|
103
|
+
|
|
104
|
+
This tool reads the same public pages a person sees in a browser, one search at a time, on behalf of the person asking. It is meant for personal shopping and price research.
|
|
105
|
+
|
|
106
|
+
Please don't use it for bulk scraping, for building a database of other people's listings, or for automated buying or reselling. It carries no account, cookie or personal data, and adding any is out of scope. If a site's operator asks for something to change, open an issue and it will be handled.
|
|
107
|
+
|
|
108
|
+
## Disclaimer
|
|
109
|
+
|
|
110
|
+
furima-mcp is an independent, unofficial project. It is not affiliated with, endorsed by or sponsored by Mercari, Inc., LY Corporation, Rakuten Group, Inc. or any marketplace it reads. All product names, trademarks and listing content belong to their respective owners.
|
|
111
|
+
|
|
112
|
+
The sites can change or restrict access at any time, and results may be incomplete, delayed or wrong. Prices and verdicts are informational, not financial or purchasing advice; check the listing itself before you buy. You are responsible for complying with each site's terms of service and the laws that apply to you. The software is provided as is, without warranty of any kind; see [LICENSE](LICENSE).
|
|
113
|
+
|
|
114
|
+
## Development
|
|
115
|
+
|
|
116
|
+
```sh
|
|
117
|
+
git clone https://github.com/fxia0018/furima-mcp && cd furima-mcp
|
|
118
|
+
uv sync
|
|
119
|
+
uv run pytest # offline tests against hand-written page fixtures
|
|
120
|
+
uv run pytest -m live # one smoke test against the real sites
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Each site is one module in `src/furima_mcp/sites/` with a `search(client, query)` and an `item(client, url)`. Adding a site means adding a module there and registering it in `sites/__init__.py`.
|
|
124
|
+
|
|
125
|
+
## License
|
|
126
|
+
|
|
127
|
+
MIT
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# furima-mcp
|
|
2
|
+
|
|
3
|
+
[English](README.md) | 日本語
|
|
4
|
+
|
|
5
|
+
メルカリ・ヤフオク・Yahoo!フリマ(旧 PayPayフリマ)・ラクマをまとめて検索し、実際の落札・売却価格から相場を調べられる MCP サーバーです。Claude や Cursor など、MCP に対応した AI クライアントから使えます。
|
|
6
|
+
|
|
7
|
+
> **あなた:** Switch 有機ELモデル、3万円は安い?
|
|
8
|
+
>
|
|
9
|
+
> **Claude:** *(`check_price` を実行)* やや高めです。メルカリ・ヤフオク・ラクマの直近の売却 214 件では中央値が 25,000 円、真ん中の半分が 22,000〜28,000 円でした。30,000 円はそのうち 82% より高い価格です。
|
|
10
|
+
|
|
11
|
+
- ブラウザ・ログイン・API キーは不要。4 サイトの検索が数秒で終わります。
|
|
12
|
+
- 相場は出品価格ではなく **売れた価格**(ヤフオクの落札価格、メルカリ・ラクマの売り切れ商品)から計算します。
|
|
13
|
+
- 1 サイトが落ちても他のサイトの結果は返ります。エラーはサイトごとに表示されます。
|
|
14
|
+
- 同じサイトへのリクエストは 1 秒以上の間隔をあけ、`429`/`503` は待ってから再試行し、同じ検索は 5 分間キャッシュします。
|
|
15
|
+
|
|
16
|
+
## ツール
|
|
17
|
+
|
|
18
|
+
| ツール | 内容 |
|
|
19
|
+
| --- | --- |
|
|
20
|
+
| `search_listings` | 出品中の商品を検索。サイト・価格で絞り込み、関連度・新着・価格順(全サイト横断)で並べ替え。 |
|
|
21
|
+
| `sold_price_stats` | 直近の売却価格の最安値・25%・中央値・75%・最高値。全体とサイト別、実例付き。 |
|
|
22
|
+
| `check_price` | ある価格が直近の売却価格の中でどの位置か(パーセンタイル)と一言の判定。 |
|
|
23
|
+
| `get_listing` | 商品 URL の詳細:説明文・状態・画像・出品者の評価・オークション終了時刻。 |
|
|
24
|
+
|
|
25
|
+
すべてのツールで `exclude`(例: `["ジャンク", "箱のみ"]`)を指定でき、タイトルにその語を含む商品を除外します。相場系のツールは `match_all_words`(初期値オン)で、検索語をすべて含むタイトルだけを使います。メルカリで `PS5 CFI-2000` を検索すると PS5 のソフトも混ざり、中央値がソフトの値段まで下がってしまうためです。
|
|
26
|
+
|
|
27
|
+
## インストール
|
|
28
|
+
|
|
29
|
+
[uv](https://docs.astral.sh/uv/) が必要です。
|
|
30
|
+
|
|
31
|
+
**Claude Code**
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
claude mcp add furima -- uvx furima-mcp
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
**Claude Desktop・Cursor など**(`claude_desktop_config.json`、`.cursor/mcp.json` など)
|
|
38
|
+
|
|
39
|
+
```json
|
|
40
|
+
{
|
|
41
|
+
"mcpServers": {
|
|
42
|
+
"furima": {
|
|
43
|
+
"command": "uvx",
|
|
44
|
+
"args": ["furima-mcp"]
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## 使い方の例
|
|
51
|
+
|
|
52
|
+
- 「ドラクエ3 SFC 箱説付き」の相場を調べて
|
|
53
|
+
- 「ピカチュウ 25th プロモ」を 5,000 円以下で安い順に。PSA 鑑定品は除いて
|
|
54
|
+
- α7 III ボディの中古相場をヤフオクとメルカリで比べて
|
|
55
|
+
- この商品はお得? https://jp.mercari.com/item/m12345678901
|
|
56
|
+
|
|
57
|
+
商品名や型番(`CFI-2000`、`ILCE-7M3` など)で検索すると精度が上がります。
|
|
58
|
+
|
|
59
|
+
## 設定
|
|
60
|
+
|
|
61
|
+
| 環境変数 | 初期値 | 意味 |
|
|
62
|
+
| --- | --- | --- |
|
|
63
|
+
| `FURIMA_MIN_INTERVAL` | `1.0` | 同じサイトへのリクエスト間隔(秒)。下げることは推奨しません。 |
|
|
64
|
+
| `FURIMA_CACHE_TTL` | `300` | 同じ検索結果を再利用する秒数。`0` でキャッシュ無効。 |
|
|
65
|
+
|
|
66
|
+
## 利用上の注意
|
|
67
|
+
|
|
68
|
+
ブラウザで誰でも見られる公開ページを、依頼した人の代わりに 1 回ずつ読むツールです。個人の買い物や相場調べを想定しています。大量の自動収集、他人の出品データのデータベース化、自動購入・転売目的には使わないでください。
|
|
69
|
+
|
|
70
|
+
## 免責事項
|
|
71
|
+
|
|
72
|
+
本プロジェクトは非公式の個人プロジェクトであり、株式会社メルカリ、LINEヤフー株式会社、楽天グループ株式会社、その他の各サービスとは一切関係がなく、承認・後援も受けていません。商品名・商標・出品内容はそれぞれの権利者に帰属します。
|
|
73
|
+
|
|
74
|
+
各サイトの仕様変更などにより、結果が不完全・遅延・誤っている場合があります。価格や判定は参考情報であり、購入の助言ではありません。購入前に必ず商品ページをご確認ください。各サイトの利用規約および適用される法令の遵守は利用者の責任です。本ソフトウェアは現状のまま提供され、いかなる保証もありません([LICENSE](LICENSE) 参照)。
|
|
75
|
+
|
|
76
|
+
## ライセンス
|
|
77
|
+
|
|
78
|
+
MIT
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
# furima-mcp
|
|
2
|
+
|
|
3
|
+
[](https://github.com/fxia0018/furima-mcp/actions/workflows/ci.yml)
|
|
4
|
+
[](https://pypi.org/project/furima-mcp/)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
|
|
7
|
+
English | [日本語](README.ja.md)
|
|
8
|
+
|
|
9
|
+
<!-- mcp-name: io.github.fxia0018/furima-mcp -->
|
|
10
|
+
|
|
11
|
+
An MCP server for Japanese second-hand marketplaces. It lets Claude, Cursor or any MCP client search **Mercari**, **Yahoo! Auctions**, **Yahoo! Flea Market** (PayPay Flea Market) and **Rakuma** at once, and check what an item actually sells for.
|
|
12
|
+
|
|
13
|
+
> **You:** Is ¥30,000 a good price for a Switch OLED?
|
|
14
|
+
>
|
|
15
|
+
> **Claude:** *(calls `check_price`)* Not really. Across 214 recent sales on Mercari, Yahoo! Auctions and Rakuma the median was ¥25,000 and the middle half sold for ¥22,000–28,000. ¥30,000 is dearer than 82% of them.
|
|
16
|
+
|
|
17
|
+
- No browser, no login, no API key. Plain HTTP; a search across all four sites takes a few seconds.
|
|
18
|
+
- Prices come from **sold** listings, not asking prices: Yahoo! Auctions final bids, Mercari and Rakuma sold items.
|
|
19
|
+
- One site failing doesn't fail the call. Its error is reported next to the other sites' results.
|
|
20
|
+
- Polite by default: requests to each site are spaced at least 1 s apart, `429`/`503` responses are retried with backoff, and repeated searches are served from a 5-minute cache.
|
|
21
|
+
|
|
22
|
+
## Tools
|
|
23
|
+
|
|
24
|
+
| Tool | What it does |
|
|
25
|
+
| --- | --- |
|
|
26
|
+
| `search_listings` | Search items for sale now. Filter by site and price, sort by relevance, newest or price across all sites. |
|
|
27
|
+
| `sold_price_stats` | Min / p25 / median / p75 / max of recent sold prices, overall and per site, with example sales. |
|
|
28
|
+
| `check_price` | Where a price falls among recent sales (percentile) and a one-line verdict. |
|
|
29
|
+
| `get_listing` | Full details of one listing URL: description, condition, images, seller rating, auction end time. |
|
|
30
|
+
|
|
31
|
+
Every tool takes `exclude` (drop titles containing these words, e.g. `["ジャンク", "箱のみ"]`). The price tools also take `match_all_words` (on by default) because the sites' own search is fuzzy: on Mercari, `PS5 CFI-2000` also returns PS5 games, which would drag the median down to a game's price.
|
|
32
|
+
|
|
33
|
+
## Install
|
|
34
|
+
|
|
35
|
+
Needs [uv](https://docs.astral.sh/uv/).
|
|
36
|
+
|
|
37
|
+
**Claude Code**
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
claude mcp add furima -- uvx furima-mcp
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
**Claude Desktop, Cursor and others** — add to the client's MCP config (`claude_desktop_config.json`, `.cursor/mcp.json`, ...):
|
|
44
|
+
|
|
45
|
+
```json
|
|
46
|
+
{
|
|
47
|
+
"mcpServers": {
|
|
48
|
+
"furima": {
|
|
49
|
+
"command": "uvx",
|
|
50
|
+
"args": ["furima-mcp"]
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Things to ask
|
|
57
|
+
|
|
58
|
+
- 「ドラクエ3 SFC 箱説付き」の相場を調べて
|
|
59
|
+
- Find a Pokémon card "ピカチュウ 25th プロモ" under ¥5,000, cheapest first, no PSA-graded ones
|
|
60
|
+
- Compare what a used Sony α7 III body sells for on Yahoo! Auctions vs Mercari
|
|
61
|
+
- Is this a good deal? https://jp.mercari.com/item/m12345678901
|
|
62
|
+
|
|
63
|
+
Search in Japanese for best results. Product names and model numbers (`CFI-2000`, `ILCE-7M3`) match far better than English descriptions.
|
|
64
|
+
|
|
65
|
+
## Notes
|
|
66
|
+
|
|
67
|
+
- **Sold history** comes from Yahoo! Auctions' closed auctions and Rakuma's sold items (most recent first) and Mercari's sold items (best match first). Yahoo! Flea Market has no public sold history, so it only appears in `search_listings`.
|
|
68
|
+
- **Auction prices** (`is_auction: true`) are current bids and may still rise until `ends_at`.
|
|
69
|
+
- **Mercari's `sold_at`** is the item's last update time, which is normally the sale.
|
|
70
|
+
- **Mercari Shops** products show up in search but `get_listing` doesn't support them yet.
|
|
71
|
+
|
|
72
|
+
## Configuration
|
|
73
|
+
|
|
74
|
+
Environment variables, all optional:
|
|
75
|
+
|
|
76
|
+
| Variable | Default | Meaning |
|
|
77
|
+
| --- | --- | --- |
|
|
78
|
+
| `FURIMA_MIN_INTERVAL` | `1.0` | Minimum seconds between two requests to the same site. Raising it is fine; lowering it is not recommended. |
|
|
79
|
+
| `FURIMA_CACHE_TTL` | `300` | Seconds a site's search result is reused for an identical query. `0` disables the cache. |
|
|
80
|
+
|
|
81
|
+
## Responsible use
|
|
82
|
+
|
|
83
|
+
This tool reads the same public pages a person sees in a browser, one search at a time, on behalf of the person asking. It is meant for personal shopping and price research.
|
|
84
|
+
|
|
85
|
+
Please don't use it for bulk scraping, for building a database of other people's listings, or for automated buying or reselling. It carries no account, cookie or personal data, and adding any is out of scope. If a site's operator asks for something to change, open an issue and it will be handled.
|
|
86
|
+
|
|
87
|
+
## Disclaimer
|
|
88
|
+
|
|
89
|
+
furima-mcp is an independent, unofficial project. It is not affiliated with, endorsed by or sponsored by Mercari, Inc., LY Corporation, Rakuten Group, Inc. or any marketplace it reads. All product names, trademarks and listing content belong to their respective owners.
|
|
90
|
+
|
|
91
|
+
The sites can change or restrict access at any time, and results may be incomplete, delayed or wrong. Prices and verdicts are informational, not financial or purchasing advice; check the listing itself before you buy. You are responsible for complying with each site's terms of service and the laws that apply to you. The software is provided as is, without warranty of any kind; see [LICENSE](LICENSE).
|
|
92
|
+
|
|
93
|
+
## Development
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
git clone https://github.com/fxia0018/furima-mcp && cd furima-mcp
|
|
97
|
+
uv sync
|
|
98
|
+
uv run pytest # offline tests against hand-written page fixtures
|
|
99
|
+
uv run pytest -m live # one smoke test against the real sites
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Each site is one module in `src/furima_mcp/sites/` with a `search(client, query)` and an `item(client, url)`. Adding a site means adding a module there and registering it in `sites/__init__.py`.
|
|
103
|
+
|
|
104
|
+
## License
|
|
105
|
+
|
|
106
|
+
MIT
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Security policy
|
|
2
|
+
|
|
3
|
+
## Reporting a vulnerability
|
|
4
|
+
|
|
5
|
+
Please report security issues privately through GitHub: **Security → Report a vulnerability** on this repository. Don't open a public issue for them.
|
|
6
|
+
|
|
7
|
+
Include what you found, how to reproduce it, and what an attacker could do with it. You should get a first reply within a week.
|
|
8
|
+
|
|
9
|
+
## Scope
|
|
10
|
+
|
|
11
|
+
furima-mcp runs locally as a subprocess of an MCP client. It makes outbound HTTPS requests to the four supported marketplaces only and stores nothing on disk. Things worth reporting include:
|
|
12
|
+
|
|
13
|
+
- a tool argument that makes the server request a host other than the supported marketplaces
|
|
14
|
+
- a tool argument that reads or writes local files, or runs code
|
|
15
|
+
- a way for page content returned by a site to break out of the JSON result
|
|
16
|
+
|
|
17
|
+
Listing text (titles, descriptions) is third-party content and is returned as data. MCP clients should treat it as untrusted, like any web page.
|
|
18
|
+
|
|
19
|
+
## Supported versions
|
|
20
|
+
|
|
21
|
+
Only the latest release gets fixes.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "furima-mcp"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "MCP server for Japanese second-hand marketplaces: search Mercari, Yahoo! Auctions, Yahoo! Flea Market and Rakuma, and check what things actually sell for."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
requires-python = ">=3.10"
|
|
8
|
+
authors = [{ name = "fxia0018" }]
|
|
9
|
+
keywords = ["mcp", "mercari", "yahoo-auctions", "rakuma", "japan", "price", "llm", "agent"]
|
|
10
|
+
classifiers = [
|
|
11
|
+
"Development Status :: 4 - Beta",
|
|
12
|
+
"Intended Audience :: Developers",
|
|
13
|
+
"Natural Language :: Japanese",
|
|
14
|
+
"Programming Language :: Python :: 3",
|
|
15
|
+
"Topic :: Internet :: WWW/HTTP",
|
|
16
|
+
]
|
|
17
|
+
dependencies = [
|
|
18
|
+
"mcp>=2.0,<3",
|
|
19
|
+
"httpx>=0.27",
|
|
20
|
+
"cryptography>=42",
|
|
21
|
+
]
|
|
22
|
+
|
|
23
|
+
[project.urls]
|
|
24
|
+
Homepage = "https://github.com/fxia0018/furima-mcp"
|
|
25
|
+
Issues = "https://github.com/fxia0018/furima-mcp/issues"
|
|
26
|
+
|
|
27
|
+
[project.scripts]
|
|
28
|
+
furima-mcp = "furima_mcp.server:main"
|
|
29
|
+
|
|
30
|
+
[dependency-groups]
|
|
31
|
+
dev = ["pytest>=8", "pytest-asyncio>=0.24", "respx>=0.21", "ruff>=0.6"]
|
|
32
|
+
|
|
33
|
+
[build-system]
|
|
34
|
+
requires = ["hatchling"]
|
|
35
|
+
build-backend = "hatchling.build"
|
|
36
|
+
|
|
37
|
+
[tool.pytest.ini_options]
|
|
38
|
+
asyncio_mode = "auto"
|
|
39
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
40
|
+
markers = ["live: hits the real sites (run with -m live)"]
|
|
41
|
+
addopts = "-m 'not live'"
|
|
42
|
+
|
|
43
|
+
[tool.ruff]
|
|
44
|
+
line-length = 110
|
|
45
|
+
target-version = "py310"
|
|
46
|
+
|
|
47
|
+
[tool.ruff.lint]
|
|
48
|
+
select = ["E", "F", "I", "B", "UP", "SIM", "RUF"]
|
|
49
|
+
ignore = ["E501", "E741", "RUF001", "RUF002", "RUF003"]
|
|
50
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.1.0"
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
"""Fan a query out to the sites and summarize the results."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
import os
|
|
7
|
+
import re
|
|
8
|
+
import statistics
|
|
9
|
+
import time
|
|
10
|
+
import unicodedata
|
|
11
|
+
from dataclasses import astuple
|
|
12
|
+
from itertools import chain, zip_longest
|
|
13
|
+
|
|
14
|
+
import httpx
|
|
15
|
+
|
|
16
|
+
from .models import Listing, Query, SiteResult
|
|
17
|
+
from .sites import SITES, SOLD_SITES
|
|
18
|
+
|
|
19
|
+
SITE_TIMEOUT = 60.0
|
|
20
|
+
# Agents often repeat a search while refining a question; serve those from memory.
|
|
21
|
+
CACHE_TTL = float(os.environ.get("FURIMA_CACHE_TTL", "300"))
|
|
22
|
+
CACHE_MAX = 256
|
|
23
|
+
_cache: dict[tuple, tuple[float, SiteResult]] = {}
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def pick_sites(sites: list[str] | None, sold: bool) -> list[str]:
|
|
27
|
+
allowed = SOLD_SITES if sold else tuple(SITES)
|
|
28
|
+
if not sites:
|
|
29
|
+
return list(allowed)
|
|
30
|
+
unknown = [s for s in sites if s not in SITES]
|
|
31
|
+
if unknown:
|
|
32
|
+
raise ValueError(f"unknown site(s): {', '.join(unknown)}; choose from {', '.join(SITES)}")
|
|
33
|
+
return [s for s in sites if s in allowed]
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
async def _one(client: httpx.AsyncClient, site: str, q: Query) -> SiteResult:
|
|
37
|
+
key = (site, *astuple(q))
|
|
38
|
+
hit = _cache.get(key)
|
|
39
|
+
if hit and time.monotonic() - hit[0] < CACHE_TTL:
|
|
40
|
+
return hit[1]
|
|
41
|
+
try:
|
|
42
|
+
result = await asyncio.wait_for(SITES[site].search(client, q), SITE_TIMEOUT)
|
|
43
|
+
except asyncio.TimeoutError:
|
|
44
|
+
return SiteResult(site=site, error="timed out")
|
|
45
|
+
except httpx.HTTPStatusError as e:
|
|
46
|
+
return SiteResult(site=site, error=f"HTTP {e.response.status_code}")
|
|
47
|
+
except Exception as e: # one broken site must not sink the others
|
|
48
|
+
return SiteResult(site=site, error=f"{type(e).__name__}: {e}")
|
|
49
|
+
if len(_cache) >= CACHE_MAX: # drop the oldest entry; failures are never cached
|
|
50
|
+
_cache.pop(min(_cache, key=lambda k: _cache[k][0]))
|
|
51
|
+
_cache[key] = (time.monotonic(), result)
|
|
52
|
+
return result
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
async def search_sites(client: httpx.AsyncClient, sites: list[str], q: Query) -> list[SiteResult]:
|
|
56
|
+
return list(await asyncio.gather(*(_one(client, s, q) for s in sites)))
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
_PUNCT = re.compile(r"[\s\-_・/・.,、。]+")
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def normalize(text: str) -> str:
|
|
63
|
+
"""Fold width, case and separators: "CFI-2000" and "cfi2000" compare equal."""
|
|
64
|
+
return _PUNCT.sub("", unicodedata.normalize("NFKC", text).casefold())
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def has_all_words(title: str, keyword: str) -> bool:
|
|
68
|
+
norm = normalize(title)
|
|
69
|
+
return all(normalize(w) in norm for w in unicodedata.normalize("NFKC", keyword).split())
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def keep(listing: Listing, exclude: list[str] | None, q: Query, match_all: bool = False) -> bool:
|
|
73
|
+
if listing.price is None or listing.sold != q.sold:
|
|
74
|
+
return False
|
|
75
|
+
# Sites treat price bounds loosely (Yahoo compares the buy-now price, not the bid).
|
|
76
|
+
if q.min_price and listing.price < q.min_price:
|
|
77
|
+
return False
|
|
78
|
+
if q.max_price and listing.price > q.max_price:
|
|
79
|
+
return False
|
|
80
|
+
if match_all and not has_all_words(listing.title, q.keyword):
|
|
81
|
+
return False
|
|
82
|
+
title = normalize(listing.title)
|
|
83
|
+
return not any(normalize(w) in title for w in exclude or [] if normalize(w))
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def merge(
|
|
87
|
+
results: list[SiteResult], q: Query, exclude: list[str] | None, match_all: bool = False
|
|
88
|
+
) -> list[Listing]:
|
|
89
|
+
"""Filter each site's listings, then combine them in the order `q.sort` asks for."""
|
|
90
|
+
per_site = [[l for l in r.listings if keep(l, exclude, q, match_all)] for r in results]
|
|
91
|
+
if q.sort == "price_asc":
|
|
92
|
+
return sorted(chain(*per_site), key=lambda l: l.price)
|
|
93
|
+
if q.sort == "price_desc":
|
|
94
|
+
return sorted(chain(*per_site), key=lambda l: -l.price)
|
|
95
|
+
# Relevance and newest are each site's own ranking; interleave so no site is buried.
|
|
96
|
+
return [l for row in zip_longest(*per_site) for l in row if l is not None]
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def price_stats(prices: list[int]) -> dict:
|
|
100
|
+
if not prices:
|
|
101
|
+
return {"count": 0}
|
|
102
|
+
prices = sorted(prices)
|
|
103
|
+
out = {"count": len(prices), "min": prices[0], "max": prices[-1]}
|
|
104
|
+
if len(prices) >= 2:
|
|
105
|
+
q1, med, q3 = statistics.quantiles(prices, n=4, method="inclusive")
|
|
106
|
+
out.update(p25=round(q1), median=round(med), p75=round(q3))
|
|
107
|
+
else:
|
|
108
|
+
out.update(p25=prices[0], median=prices[0], p75=prices[0])
|
|
109
|
+
out["mean"] = round(statistics.fmean(prices))
|
|
110
|
+
return out
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def percentile_of(price: int, prices: list[int]) -> float | None:
|
|
114
|
+
"""Share of prices strictly below `price`, plus half of the ties, in percent."""
|
|
115
|
+
if not prices:
|
|
116
|
+
return None
|
|
117
|
+
below = sum(p < price for p in prices)
|
|
118
|
+
ties = sum(p == price for p in prices)
|
|
119
|
+
return round(100 * (below + ties / 2) / len(prices), 1)
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def verdict(pct: float | None, count: int) -> str:
|
|
123
|
+
if pct is None or count < 5:
|
|
124
|
+
return "not enough sold data to judge"
|
|
125
|
+
if pct <= 10:
|
|
126
|
+
return "very cheap: below 90% of recent sales; check condition and authenticity"
|
|
127
|
+
if pct <= 25:
|
|
128
|
+
return "cheap: in the bottom quarter of recent sales"
|
|
129
|
+
if pct < 75:
|
|
130
|
+
return "typical: within the middle half of recent sales"
|
|
131
|
+
if pct < 90:
|
|
132
|
+
return "expensive: in the top quarter of recent sales"
|
|
133
|
+
return "very expensive: above 90% of recent sales"
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def errors_of(results: list[SiteResult]) -> dict:
|
|
137
|
+
return {r.site: r.error for r in results if r.error}
|