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.
@@ -0,0 +1,10 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: github-actions
4
+ directory: /
5
+ schedule:
6
+ interval: monthly
7
+ - package-ecosystem: uv
8
+ directory: /
9
+ schedule:
10
+ interval: monthly
@@ -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,7 @@
1
+ __pycache__/
2
+ *.pyc
3
+ .venv/
4
+ dist/
5
+ .pytest_cache/
6
+ .ruff_cache/
7
+ .DS_Store
@@ -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.
@@ -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
+ [![CI](https://github.com/fxia0018/furima-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/fxia0018/furima-mcp/actions/workflows/ci.yml)
25
+ [![PyPI](https://img.shields.io/pypi/v/furima-mcp.svg)](https://pypi.org/project/furima-mcp/)
26
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](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
+ [![CI](https://github.com/fxia0018/furima-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/fxia0018/furima-mcp/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/furima-mcp.svg)](https://pypi.org/project/furima-mcp/)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](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,3 @@
1
+ from .server import main
2
+
3
+ main()
@@ -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}