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.

Related MCP server: Vehicle Database MCP Server

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

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

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).