Polovnjak MCP

A multi-provider MCP server for used-vehicle marketplaces. Agents get one unified tool surface — search, listing details, price statistics, price history, and per-user saved-search watches — backed by pluggable marketplace adapters. Included adapters: polovniautomobili.com (source id pa) and mojauto.rs (source id ma), both Serbia.

Users sign in with Google via the standard MCP OAuth 2.1 flow; watches are private per user. Every listing the hub observes (from any user's searches, stats sampling, or watch checks) is recorded into a shared Postgres "market memory" that powers price history and trend queries no single marketplace offers.

Architecture

• Adapters (src/adapters/) implement a common SourceAdapter interface: search, getListing, getMakesModels, plus capability flags. Each adapter translates the canonical filters into its provider's query and maps results back into a canonical listing model. Listings carry composite ids like pa:12345678 or ma:3554254. Make names are alias-resolved per source ("VW" and "Volkswagen" both work everywhere); filters a source cannot express are reported as per-source warnings in results.
• Tools (src/tools/) fan out across adapters and merge results, tagging everything with its source. Categories cover cars, motorcycles, vans, light/heavy trucks, buses, trailers, campers, machinery, tractors, boats, and bicycles.
• Recorder (src/recorder.ts) upserts every observed listing into listings and appends a price_observations row on first sighting or price change.
• Auth (src/auth/) is a self-hosted OAuth 2.1 authorization server (dynamic client registration, PKCE, refresh tokens) with Google OIDC as the identity layer. Tokens are stored hashed in Postgres.
• Storage is Postgres via Drizzle ORM; migrations run automatically at startup.

Quick start (Docker Compose)

1. Create a Google OAuth client at Google Cloud Console (type "Web application") with authorized redirect URI <PUBLIC_URL>/auth/google/callback (e.g. http://localhost:8321/auth/google/callback for local use).
2. Configure the environment:

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

3. Start everything (MCP server + Postgres + FlareSolverr):

docker compose up -d --build

4. Point your MCP client at http://localhost:8321/mcp. The client will discover the OAuth metadata, register itself, and open a browser window for Google sign-in. Everything after that is per-user.

For a quick local test without Google credentials, set AUTH_MODE=none — the server then skips auth and uses a single local dev user.

Tools

Tool	Purpose
list_sources	Registered marketplace sources with coverage and capability flags. Source ids are used in the sources param of other tools and in composite listing ids.
search_listings	One page of normalized listings per source, merged and source-tagged. Filters: category, make/models, price/year/mileage/power ranges, fuel, body, gearbox, region/city, condition flags. Listings include previousPrice when the source shows a discount; per-source warnings explain any filter a source could not apply natively.
get_listing	Full detail for one listing by composite id (pa:12345678, ma:3554254), URL, or bare id: specs, equipment, description, photos, seller contact.
get_makes_and_models	Per-source taxonomy: makes, models of a make, regions, accepted filter values, city-name resolution.
get_price_stats	Live market snapshot: min/p25/median/avg/p75/max + per-year breakdown, per source and combined, sampled from up to maxPages result pages per source.
get_price_history	Answered from the hub's own recorded observations: a single listing's price timeline (repricing detection) or a month-by-month trend for a segment (make/model/year). Coverage grows with usage.
create_watch / list_watches / delete_watch / check_watches	Per-user saved searches across one or more sources. check_watches returns only listings that appeared since the last check — ideal for a scheduled daily prompt.

Agent skill

The repo ships an agent skill at .cursor/skills/car-market-hub/SKILL.md that teaches LLM agents how to use this server effectively (tool workflows, gotchas), with per-client connection guides for OpenAI, Claude, LibreChat, and Cursor in clients.md. Cursor picks it up automatically; for other platforms, copy the skill directory into that platform's skills location (e.g. .claude/skills/) or paste its contents into the agent's instructions.

Watch workflow

1. create_watch with a name and filters (optionally restricted to specific sources) — current matches become the baseline.
2. Later (e.g. a scheduled prompt: "check my car watches"), check_watches returns only the listings that appeared since, per watch and per source.

Adding a new marketplace adapter

1. Create src/adapters/<name>/ and implement the SourceAdapter interface from src/adapters/types.ts: pick a short stable id (used in composite listing ids), translate canonical SearchQuery filters into your provider's query, and map raw results into the canonical ListingSummary / ListingDetail shapes from src/domain/listing.ts.
2. Register it in src/server.ts with registerAdapter(...).

Search fan-out, watches, recording, and price history pick the new source up automatically.

Environment variables

Variable	Default	Meaning
PORT	8080	HTTP listen port.
PUBLIC_URL	http://localhost:<PORT>	Public base URL; OAuth issuer and Google callback host.
DATABASE_URL	postgres://carhub:carhub@localhost:5432/carhub	Postgres connection string.
AUTH_MODE	oauth	oauth (Google-backed OAuth 2.1) or none (single local dev user, no auth).
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	—	Google OAuth credentials (required in oauth mode).
FLARESOLVERR_URL	—	Optional FlareSolverr instance for Cloudflare-challenge fallback.
CACHE_TTL_MS	600000	Upstream response cache TTL.
FETCH_CONCURRENCY	5	Max concurrent upstream requests per adapter.
REQUEST_TIMEOUT_MS	25000	Upstream request timeout.

Local development

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 changes: edit src/db/schema.ts, then npm run db:generate to produce a new migration under drizzle/ (applied automatically at startup).

Notes and limits

• polovniautomobili.com has no public API; the adapter reads the site's Next.js data endpoints using Chrome TLS impersonation (impit), with FlareSolverr as Cloudflare-challenge fallback. Use responsibly and respect the site's terms of service.
• Prices below 100 EUR are treated as "price on request" and excluded from stats and observations.
• Watch checks scan the first two result pages (~50 newest listings) per source.
• get_price_history reflects only listings observed through this hub — it is a growing sample, not the full market.
• The previous single-provider implementation is kept for reference in old/ (not part of the build).