Polovnjak MCP

Ein Multi-Provider-MCP-Server für Gebrauchtfahrzeug-Marktplätze. Agents erhalten eine einheitliche Tool-Oberfläche – Suche, Listungsdetails, Preisstatistiken, Preishistorie und benutzerspezifische Watch-Abos für gespeicherte Suchen – unterstützt durch steckbare Marktplatz-Adapter. Enthaltene Adapter: polovniautomobili.com (Quell-ID pa) und mojauto.rs (Quell-ID ma), beide in Serbien.

Benutzer melden sich über den standardmäßigen MCP-OAuth-2.1-Flow mit Google an; Watches sind pro Benutzer privat. Jede Listung, die der Hub beobachtet (aus Suchen beliebiger Benutzer, Statistik-Stichproben oder Watch-Prüfungen), wird in einem gemeinsamen Postgres-„Marktgedächtnis“ gespeichert, das Preisverläufe und Trendabfragen ermöglicht, die kein einzelner Marktplatz bietet.

Architektur

• Adapter (src/adapters/) implementieren eine gemeinsame SourceAdapter-Schnittstelle: search, getListing, getMakesModels sowie Fähigkeitsflags. Jeder Adapter übersetzt die kanonischen Filter in die Abfrage seines Anbieters und bildet die Ergebnisse wieder auf ein kanonisches Listungsmodell ab. Listungen tragen zusammengesetzte IDs wie pa:12345678 oder ma:3554254. Markennamen werden pro Quelle über Aliase aufgelöst („VW“ und „Volkswagen“ funktionieren überall); Filter, die eine Quelle nicht ausdrücken kann, werden als quellenspezifische warnings in den Ergebnissen gemeldet.

• Tools (src/tools/) verteilen sich über die Adapter und führen Ergebnisse zusammen, wobei alles mit seiner Quelle gekennzeichnet wird. Die Kategorien umfassen Autos, Motorräder, Transporter, leichte/schwere Lkw, Busse, Anhänger, Wohnmobile, Maschinen, Traktoren, Boote und Fahrräder.

• Recorder (src/recorder.ts) fügt jede beobachtete Listung in listings ein (Upsert) und hängt bei der ersten Sichtung oder Preisänderung eine Zeile in price_observations an.

• Auth (src/auth/) ist ein selbst gehosteter OAuth-2.1-Autorisierungsserver (dynamische Client-Registrierung, PKCE, Refresh-Tokens) mit Google OIDC als Identitätsebene. Tokens werden gehasht in Postgres gespeichert.

• Speicherung erfolgt über Postgres mit Drizzle ORM; Migrationen werden beim Start automatisch ausgeführt.

Related MCP server: Vehicle Database MCP Server

Schnellstart (Docker Compose)

1. Erstellen Sie einen Google-OAuth-Client in der Google Cloud Console (Typ „Webanwendung“) mit autorisierter Weiterleitungs-URI <PUBLIC_URL>/auth/google/callback (z. B. http://localhost:8321/auth/google/callback für die lokale Nutzung).

2. Konfigurieren Sie die Umgebung:

cp .env.example .env
# set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET (and PUBLIC_URL for non-local deployments)

3. Starten Sie alles (MCP-Server + Postgres + FlareSolverr):

docker compose up -d --build

4. Richten Sie Ihren MCP-Client auf http://localhost:8321/mcp. Der Client erkennt die OAuth-Metadaten, registriert sich selbst und öffnet ein Browserfenster für die Google-Anmeldung. Alles danach ist benutzerspezifisch.

Für einen schnellen lokalen Test ohne Google-Anmeldedaten setzen Sie AUTH_MODE=none – der Server überspringt dann die Authentifizierung und verwendet einen einzelnen lokalen Entwicklungsbenutzer.

Tools

Agent-Fähigkeit

Das Repository enthält eine Agent-Fähigkeit unter .cursor/skills/car-market-hub/SKILL.md, die LLM-Agents den effektiven Umgang mit diesem Server beibringt (Tool-Workflows, Stolperfallen), mit client-spezifischen Verbindungsanleitungen für OpenAI, Claude, LibreChat und Cursor in clients.md. Cursor erkennt sie automatisch; für andere Plattformen kopieren Sie das Fähigkeitsverzeichnis in den Fähigkeitsort der jeweiligen Plattform (z. B. .claude/skills/) oder fügen Sie dessen Inhalt in die Anweisungen des Agents ein.

Watch-Workflow

1. create_watch mit einem Namen und Filtern (optional auf bestimmte sources beschränkt) – aktuelle Treffer werden zur Basislinie.

2. Später (z. B. ein geplanter Prompt: „check my car watches“) gibt check_watches nur die seitdem erschienenen Listungen zurück, pro Watch und pro Quelle.

Hinzufügen eines neuen Marktplatz-Adapters

1. Erstellen Sie src/adapters/<name>/ und implementieren Sie die SourceAdapter-Schnittstelle aus src/adapters/types.ts: Wählen Sie eine kurze stabile id (verwendet in zusammengesetzten Listungs-IDs), übersetzen Sie kanonische SearchQuery-Filter in die Abfrage Ihres Anbieters und bilden Sie rohe Ergebnisse auf die kanonischen ListingSummary- / ListingDetail-Formen aus src/domain/listing.ts ab.

2. Registrieren Sie es in src/server.ts mit registerAdapter(...).

Suchverteilung, Watches, Aufzeichnung und Preisverlauf übernehmen die neue Quelle automatisch.

Umgebungsvariablen

Lokale Entwicklung

npm install
docker compose up -d postgres        # or point DATABASE_URL at your own Postgres
AUTH_MODE=none npm run dev           # server on http://localhost:8080/mcp

Schemaänderungen: Bearbeiten Sie src/db/schema.ts und führen Sie dann npm run db:generate aus, um eine neue Migration unter drizzle/ zu erzeugen (wird beim Start automatisch angewendet).

Hinweise und Grenzen

• polovniautomobili.com hat keine öffentliche API; der Adapter liest die Next.js-Datenschnittstellen der Website mithilfe von Chrome-TLS-Imitation (impit), mit FlareSolverr als Cloudflare-Challenge-Fallback. Nutzen Sie es verantwortungsbewusst und respektieren Sie die Nutzungsbedingungen der Website.

• Preise unter 100 EUR werden als „Preis auf Anfrage“ behandelt und von Statistiken und Beobachtungen ausgeschlossen.

• Watch-Prüfungen durchsuchen die ersten beiden Ergebniseiten (~50 neueste Listungen) pro Quelle.

• get_price_history spiegelt nur Listungen wider, die über diesen Hub beobachtet wurden – es ist eine wachsende Stichprobe, nicht der gesamte Markt.

• Die vorherige Single-Provider-Implementierung ist zur Referenz in old/ aufbewahrt (nicht Teil des Builds).