arabam-mcp 0.1.0__tar.gz

arabam_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # required for PyPI trusted publishing (OIDC)
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

arabam_mcp-0.1.0/.github/workflows/registry.yml

@@ -0,0 +1,61 @@
+name: Publish to MCP Registry
+
+# Official MCP Registry (registry.modelcontextprotocol.io) via GitHub OIDC.
+# No secret, no interactive login: the runner's OIDC token proves ownership
+# of the io.github.mohammad-abbasi-sh/* namespace.
+# Refs: https://github.com/modelcontextprotocol/registry
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # required for OIDC -> MCP Registry
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Sync server.json version to tag
+        # Only sync when running on a version tag (v*). On workflow_dispatch
+        # (ref = refs/heads/main) keep the version committed in server.json.
+        run: |
+          VER=""
+          if [[ "$GITHUB_REF" == refs/tags/* ]]; then
+            TAG="${GITHUB_REF#refs/tags/}"
+            VER="${TAG#v}"
+          fi
+          if [ -n "$VER" ]; then
+            python3 - "$VER" << 'EOF'
+          import json, sys
+          ver = sys.argv[1]
+          d = json.load(open('server.json'))
+          d['version'] = ver
+          for pkg in d.get('packages', []):
+              pkg['version'] = ver
+          json.dump(d, open('server.json', 'w'), indent=2, ensure_ascii=False)
+          print('server.json version ->', ver)
+          EOF
+          else
+            echo "No version tag ($GITHUB_REF); keeping server.json version as-is"
+          fi
+
+      - name: Install mcp-publisher
+        run: |
+          curl -sL "https://github.com/modelcontextprotocol/registry/releases/download/v1.8.7/mcp-publisher_linux_amd64.tar.gz" -o /tmp/mcp-publisher.tar.gz
+          tar -xzf /tmp/mcp-publisher.tar.gz -C /tmp
+          sudo mv /tmp/mcp-publisher /usr/local/bin/mcp-publisher
+          mcp-publisher --version
+
+      - name: Validate server.json
+        run: mcp-publisher validate server.json
+
+      - name: Publish to MCP Registry (OIDC)
+        run: |
+          mcp-publisher login github-oidc
+          mcp-publisher publish server.json
+        # A registry outage must never break the release; re-run from Actions if needed.
+        continue-on-error: true

arabam_mcp-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+.pytest_cache/

arabam_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammad Abbasi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arabam_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.5
+Name: arabam-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for arabam.com used-car listings (search, details, price stats)
+Author: Mohammad Abbasi
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<2
+Description-Content-Type: text/markdown
+
+# arabam-mcp 🇹🇷
+
+mcp-name: io.github.mohammad-abbasi-sh/arabam-mcp
+
+Unofficial **read-only** MCP server for **arabam.com**, Türkiye's used-car marketplace (~176k listings) — live search, full listing details with the 19-field spec table, brand/model browser, and market price stats.
+
+> Built by Mohammad Abbasi as part of the "Turkey MCP factory" (Sepehr-style pipeline). Not affiliated with arabam.com.
+
+## For AI agents
+
+Add to your MCP client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "arabam": {
+      "command": "uvx",
+      "args": ["arabam-mcp"]
+    }
+  }
+}
+```
+
+Or run locally: `python -m arabam_mcp.server` (needs `mcp<2`, `httpx`).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `arabam_search` | Search listings — `brand` slug ("bmw"), `model` slug ("bmw-3-serisi"), `page` 1..50 |
+| `arabam_listing_detail` | Full detail of one listing (URL from search): price + 19-field spec table |
+| `arabam_list_brands` | All ~77 brands with listing counts and URL slugs |
+| `arabam_list_models` | Models of a brand (e.g. "bmw") with counts and slugs |
+| `arabam_price_stats` | Market stats: min/max/median/average TRY price over N pages |
+
+Example output (`arabam_search` / bmw 3-serisi):
+
+```json
+{"brand": "", "model": "bmw-3-serisi", "page": 1, "count": 20,
+ "listings": [{"id": "45288789", "title": "214 BİN KMDE SORUNSUZ A4 TDI",
+  "brand": "Audi", "year": 2019, "km": 214000, "price_try": 789900,
+  "url": "https://www.arabam.com/ilan/.../45288789"}]}
+```
+
+Example output (`arabam_listing_detail`):
+
+```json
+{"title": "Galeriden Honda Civic 1.4 S 1998 Model …", "price": 425000,
+ "price_currency": "TRY", "price_text": "425.000 TL",
+ "specs": {"Marka": "Honda", "Seri": "Civic", "Model": "1.4 S",
+  "Yıl": "1998", "Kilometre": "330.000 KM", "Vites tipi": "Düz",
+  "Yakıt tipi": "LPG & benzin", "Kimden": "Galeriden", …}}
+```
+
+Notes:
+- Data comes from arabam.com's public server-rendered pages (schema.org Vehicle/Car JSON-LD + spec table) — no key, no login, read-only.
+- Spec-table labels are Turkish (Marka, Seri, Model, Yıl, Kilometre, Vites tipi, Yakıt tipi, Kasa tipi, Renk, Motor hacmi, Motor gücü, Çekiş, Kimden…).
+- Requests are spaced ~0.8s apart to stay polite.
+- Environments behind an MITM proxy: set `SSL_CERT_FILE` to a CA bundle that trusts the proxy.
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install "mcp<2" httpx pytest
+.venv/bin/python -m pytest tests/ -q
+```
+
+- `tests/test_listings.py` — offline, parses real captured fixtures
+- `tests/test_live.py` — 5 cautious live requests against arabam.com (needs `SSL_CERT_FILE` behind the lab proxy)
+
+## License
+
+MIT

arabam_mcp-0.1.0/README-fa.md

@@ -0,0 +1,61 @@
+# arabam-mcp 🇹🇷
+
+سرور MCP غیررسمی و **فقط‌خواندنی** برای **arabam.com**، بازار خودروهای دست‌دوم ترکیه (حدود ۱۷۶ هزار آگهی) — جست‌وجوی زنده، جزئیات کامل هر آگهی با جدول ۱۹ فیلدی مشخصات، مرور برند/مدل و آمار قیمت بازار.
+
+> ساختهٔ محمد عباسی در قالب «کارخانهٔ Turkey MCP» (خط تولید به سبک سپهر). وابستگی به arabam.com ندارد.
+
+## برای ایجنت‌های هوش مصنوعی
+
+به پیکربندی کلاینت MCP خود (stdio) اضافه کنید:
+
+```json
+{
+  "mcpServers": {
+    "arabam": {
+      "command": "uvx",
+      "args": ["arabam-mcp"]
+    }
+  }
+}
+```
+
+یا به‌صورت محلی اجرا کنید: `python -m arabam_mcp.server` (نیازمند `mcp<2` و `httpx`).
+
+## ابزارها
+
+| ابزار | توضیح |
+|------|-------|
+| `arabam_search` | جست‌وجوی آگهی‌ها — `brand` مثل «bmw»، `model` مثل «bmw-3-serisi»، `page` از ۱ تا ۵۰ |
+| `arabam_listing_detail` | جزئیات کامل یک آگهی (آدرس از خروجی جست‌وجو): قیمت + جدول ۱۹ فیلدی مشخصات |
+| `arabam_list_brands` | همهٔ ~۷۷ برند با تعداد آگهی و نام کوتاه آدرس |
+| `arabam_list_models` | مدل‌های یک برند (مثلاً «bmw») با تعداد و نام کوتاه |
+| `arabam_price_stats` | آمار بازار: کمینه/بیشینه/میانه/میانگین قیمت (لیر) روی N صفحه |
+
+خروجی نمونه (`arabam_search` / ب‌ام‌و سری ۳):
+
+```json
+{"model": "bmw-3-serisi", "page": 1, "count": 20,
+ "listings": [{"id": "45288789", "title": "214 BİN KMDE SORUNSUZ A4 TDI",
+  "brand": "Audi", "year": 2019, "km": 214000, "price_try": 789900,
+  "url": "https://www.arabam.com/ilan/.../45288789"}]}
+```
+
+نکته‌ها:
+- داده‌ها از صفحات عمومی سمت‌سرور arabam.com می‌آیند (JSON-LD از نوع Vehicle/Car در schema.org + جدول مشخصات) — بدون کلید، بدون ورود، فقط خواندنی.
+- برچسب‌های جدول مشخصات ترکی‌اند (Marka، Seri، Model، Yıl، Kilometre، Vites tipi، Yakıt tipi، Kasa tipi، Renk، Motor hacmi، Motor gücü، Çekiş، Kimden…).
+- بین درخواست‌ها حدود ۰٫۸ ثانیه فاصله گذاشته می‌شود تا به سایت فشار نیاید.
+- پشت پروکسی MITM: متغیر `SSL_CERT_FILE` را به بستهٔ CA مورد اعتماد پروکسی بدهید.
+
+## توسعه
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install "mcp<2" httpx pytest
+.venv/bin/python -m pytest tests/ -q
+```
+
+- `tests/test_listings.py` — آفلاین، با نمونه‌های واقعی ذخیره‌شده
+- `tests/test_live.py` — ۵ درخواست محتاطانهٔ زنده به arabam.com
+
+## مجوز
+
+MIT

arabam_mcp-0.1.0/README-tr.md

@@ -0,0 +1,61 @@
+# arabam-mcp 🇹🇷
+
+Türkiye'nin ikinci el otomobil pazaryeri **arabam.com** için resmi olmayan, **salt okunur** MCP sunucusu — canlı ilan arama, 19 alanlık özellik tablosuyla tam ilan detayı, marka/model tarama ve piyasa fiyat istatistikleri.
+
+> Mohammad Abbasi tarafından "Turkey MCP factory" (Sepehr tarzı hat) kapsamında geliştirildi. arabam.com ile bağlantısı yoktur.
+
+## Yapay zekâ ajanları için
+
+MCP istemci yapılandırmanıza (stdio) ekleyin:
+
+```json
+{
+  "mcpServers": {
+    "arabam": {
+      "command": "uvx",
+      "args": ["arabam-mcp"]
+    }
+  }
+}
+```
+
+Veya yerelde çalıştırın: `python -m arabam_mcp.server` (`mcp<2`, `httpx` gerekir).
+
+## Araçlar
+
+| Araç | Açıklama |
+|------|----------|
+| `arabam_search` | İlan arama — `brand` ("bmw"), `model` ("bmw-3-serisi"), `page` 1..50 |
+| `arabam_listing_detail` | Tek ilanın tam detayı (arama sonucundaki URL): fiyat + 19 alanlık özellik tablosu |
+| `arabam_list_brands` | ~77 markanın tamamı, ilan sayıları ve URL kısaltmalarıyla |
+| `arabam_list_models` | Bir markanın modelleri (örn. "bmw"), sayılar ve kısaltmalarla |
+| `arabam_price_stats` | Piyasa istatistiği: N sayfadaki ilanların en düşük/en yüksek/ortanca/ortalama fiyatı (TL) |
+
+Örnek çıktı (`arabam_search` / bmw 3-serisi):
+
+```json
+{"model": "bmw-3-serisi", "page": 1, "count": 20,
+ "listings": [{"id": "45288789", "title": "214 BİN KMDE SORUNSUZ A4 TDI",
+  "brand": "Audi", "year": 2019, "km": 214000, "price_try": 789900,
+  "url": "https://www.arabam.com/ilan/.../45288789"}]}
+```
+
+Notlar:
+- Veriler arabam.com'un herkese açık sunucu taraflı sayfalarından gelir (schema.org Vehicle/Car JSON-LD + özellik tablosu) — anahtar yok, giriş yok, salt okunur.
+- Özellik tablosu etiketleri Türkçedir (Marka, Seri, Model, Yıl, Kilometre, Vites tipi, Yakıt tipi, Kasa tipi, Renk, Motor hacmi, Motor gücü, Çekiş, Kimden…).
+- İstekler arasında ~0,8 sn beklenir (nazik kullanım).
+- MITM proxy arkasındaki ortamlar: `SSL_CERT_FILE` ile proxy'ye güvenen bir CA paketi gösterin.
+
+## Geliştirme
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install "mcp<2" httpx pytest
+.venv/bin/python -m pytest tests/ -q
+```
+
+- `tests/test_listings.py` — çevrimdışı, gerçek yakalanmış örneklerle
+- `tests/test_live.py` — arabam.com'a karşı 5 temkinli canlı istek
+
+## Lisans
+
+MIT

arabam_mcp-0.1.0/README.md

@@ -0,0 +1,73 @@
+# arabam-mcp 🇹🇷
+
+mcp-name: io.github.mohammad-abbasi-sh/arabam-mcp
+
+Unofficial **read-only** MCP server for **arabam.com**, Türkiye's used-car marketplace (~176k listings) — live search, full listing details with the 19-field spec table, brand/model browser, and market price stats.
+
+> Built by Mohammad Abbasi as part of the "Turkey MCP factory" (Sepehr-style pipeline). Not affiliated with arabam.com.
+
+## For AI agents
+
+Add to your MCP client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "arabam": {
+      "command": "uvx",
+      "args": ["arabam-mcp"]
+    }
+  }
+}
+```
+
+Or run locally: `python -m arabam_mcp.server` (needs `mcp<2`, `httpx`).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `arabam_search` | Search listings — `brand` slug ("bmw"), `model` slug ("bmw-3-serisi"), `page` 1..50 |
+| `arabam_listing_detail` | Full detail of one listing (URL from search): price + 19-field spec table |
+| `arabam_list_brands` | All ~77 brands with listing counts and URL slugs |
+| `arabam_list_models` | Models of a brand (e.g. "bmw") with counts and slugs |
+| `arabam_price_stats` | Market stats: min/max/median/average TRY price over N pages |
+
+Example output (`arabam_search` / bmw 3-serisi):
+
+```json
+{"brand": "", "model": "bmw-3-serisi", "page": 1, "count": 20,
+ "listings": [{"id": "45288789", "title": "214 BİN KMDE SORUNSUZ A4 TDI",
+  "brand": "Audi", "year": 2019, "km": 214000, "price_try": 789900,
+  "url": "https://www.arabam.com/ilan/.../45288789"}]}
+```
+
+Example output (`arabam_listing_detail`):
+
+```json
+{"title": "Galeriden Honda Civic 1.4 S 1998 Model …", "price": 425000,
+ "price_currency": "TRY", "price_text": "425.000 TL",
+ "specs": {"Marka": "Honda", "Seri": "Civic", "Model": "1.4 S",
+  "Yıl": "1998", "Kilometre": "330.000 KM", "Vites tipi": "Düz",
+  "Yakıt tipi": "LPG & benzin", "Kimden": "Galeriden", …}}
+```
+
+Notes:
+- Data comes from arabam.com's public server-rendered pages (schema.org Vehicle/Car JSON-LD + spec table) — no key, no login, read-only.
+- Spec-table labels are Turkish (Marka, Seri, Model, Yıl, Kilometre, Vites tipi, Yakıt tipi, Kasa tipi, Renk, Motor hacmi, Motor gücü, Çekiş, Kimden…).
+- Requests are spaced ~0.8s apart to stay polite.
+- Environments behind an MITM proxy: set `SSL_CERT_FILE` to a CA bundle that trusts the proxy.
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install "mcp<2" httpx pytest
+.venv/bin/python -m pytest tests/ -q
+```
+
+- `tests/test_listings.py` — offline, parses real captured fixtures
+- `tests/test_live.py` — 5 cautious live requests against arabam.com (needs `SSL_CERT_FILE` behind the lab proxy)
+
+## License
+
+MIT

arabam_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "arabam-mcp"
+version = "0.1.0"
+description = "Unofficial read-only MCP server for arabam.com used-car listings (search, details, price stats)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "mcp<2",
+    "httpx>=0.27",
+]
+authors = [{ name = "Mohammad Abbasi" }]
+
+[project.scripts]
+arabam-mcp = "arabam_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/arabam_mcp"]

arabam_mcp-0.1.0/server.json

@@ -0,0 +1 @@
+{"$schema":"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json","description":"Unofficial read-only MCP server for arabam.com used-car listings: search, details, price stats.","name":"io.github.mohammad-abbasi-sh/arabam-mcp","packages":[{"identifier":"arabam-mcp","registryBaseUrl":"https://pypi.org","registryType":"pypi","transport":{"type":"stdio"},"version":"0.1.0"}],"repository":{"source":"github","url":"https://github.com/mohammad-abbasi-sh/arabam-mcp"},"title":"arabam.com Car Listings","version":"0.1.0","websiteUrl":"https://github.com/mohammad-abbasi-sh/arabam-mcp"}

arabam_mcp-0.1.0/src/arabam_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""arabam-mcp: unofficial read-only MCP server for arabam.com car listings."""
+
+__version__ = "0.1.0"

arabam_mcp-0.1.0/src/arabam_mcp/http.py

@@ -0,0 +1,117 @@
+"""HTTP layer for arabam_mcp — polite scraping of public SSR pages.
+
+arabam.com serves fully server-rendered pages with no bot wall: listing data
+comes from embedded JSON-LD (schema.org Vehicle/Car) and a facets JSON blob.
+We keep requests gentle (one at a time, ~0.8s apart) and read-only.
+"""
+from __future__ import annotations
+
+import os
+import re
+import time
+
+import httpx
+
+BASE = "https://www.arabam.com"
+UA = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/120.0 Safari/537.36"
+)
+TIMEOUT = 25.0
+MIN_INTERVAL = 0.8  # seconds between requests — be polite
+
+_last_fetch = 0.0
+
+
+class ArabamError(RuntimeError):
+    pass
+
+
+def _client() -> httpx.Client:
+    # NOTE: proxy URL is read from the environment but never logged.
+    # trust_env=False because httpx fails to parse bracketed IPv6 entries
+    # (e.g. [::1]) that some environments put in no_proxy.
+    proxy = os.environ.get("https_proxy") or os.environ.get("HTTPS_PROXY")
+    # Standard SSL_CERT_FILE convention lets MITM-proxied environments
+    # point at a CA bundle that trusts the proxy; default uses certifi,
+    # which is correct for normal users.
+    verify: object = True
+    cafile = os.environ.get("SSL_CERT_FILE")
+    if cafile:
+        import ssl
+
+        verify = ssl.create_default_context(cafile=cafile)
+    return httpx.Client(
+        headers={"User-Agent": UA, "Accept-Language": "tr-TR,tr;q=0.9"},
+        timeout=TIMEOUT,
+        proxy=proxy or None,
+        verify=verify,
+        trust_env=False,
+        follow_redirects=True,
+    )
+
+
+def search_url(brand: str | None, model: str | None, page: int) -> str:
+    slug_re = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+    path = "ikinci-el/otomobil"
+    if model:
+        m = model.strip().lower()
+        if not slug_re.fullmatch(m):
+            raise ArabamError(f"bad model slug: {model!r}")
+        path += f"/{m}"
+    elif brand:
+        b = brand.strip().lower()
+        if not slug_re.fullmatch(b):
+            raise ArabamError(f"bad brand slug: {brand!r}")
+        path += f"/{b}"
+    url = f"{BASE}/{path}"
+    if page and page > 1:
+        url += f"?page={int(page)}"
+    return url
+
+
+def fetch(url: str) -> str:
+    """GET a page; raises ArabamError on failure or bot-wall."""
+    global _last_fetch
+    wait = MIN_INTERVAL - (time.monotonic() - _last_fetch)
+    if wait > 0:
+        time.sleep(wait)
+    try:
+        with _client() as c:
+            r = c.get(url)
+    except httpx.HTTPError as e:
+        raise ArabamError(f"network error fetching {url}: {e}") from e
+    _last_fetch = time.monotonic()
+    if r.status_code != 200:
+        raise ArabamError(f"arabam.com returned HTTP {r.status_code} for {url}")
+    text = r.text
+    if 'name="description" content="px-captcha"' in text or "PerimeterX" in text:
+        raise ArabamError("arabam.com is showing a bot check for this request")
+    return text
+
+
+def fetch_search(brand: str | None = None, model: str | None = None,
+                 page: int = 1) -> str:
+    if page is not None and (int(page) < 1 or int(page) > 50):
+        raise ArabamError("page must be between 1 and 50")
+    return fetch(search_url(brand, model, int(page) if page else 1))
+
+
+def fetch_detail(url: str) -> str:
+    u = url.strip()
+    if u.startswith("/"):
+        u = BASE + u
+    if not re.fullmatch(r"https://www\.arabam\.com/ilan/[a-z0-9\-/]+", u):
+        raise ArabamError(
+            "detail URL must be an arabam.com /ilan/ listing URL "
+            "(get one from arabam_search first)"
+        )
+    return fetch(u)
+
+
+def fetch_brands_page() -> str:
+    return fetch(f"{BASE}/ikinci-el/otomobil")
+
+
+def fetch_brand_page(brand: str) -> str:
+    return fetch(search_url(brand, None, 1))