Polovnjak MCP

Un servidor MCP multi-proveedor para mercados de vehículos usados. Los agentes obtienen una superficie de herramientas unificada: búsqueda, detalles de anuncios, estadísticas de precios, historial de precios y alertas de búsqueda guardadas por usuario, respaldada por adaptadores de mercado conectables. Adaptadores incluidos: polovniautomobili.com (id de fuente pa) y mojauto.rs (id de fuente ma), ambos de Serbia.

Los usuarios inician sesión con Google mediante el flujo estándar MCP OAuth 2.1; las alertas son privadas por usuario. Cada anuncio que el hub observa (de las búsquedas de cualquier usuario, muestreo de estadísticas o comprobaciones de alertas) se registra en una "memoria de mercado" compartida en Postgres que alimenta consultas de historial de precios y tendencias que ningún mercado individual ofrece.

Arquitectura

• Adaptadores (src/adapters/) implementan una interfaz común SourceAdapter: search, getListing, getMakesModels, además de indicadores de capacidades. Cada adaptador traduce los filtros canónicos a la consulta de su proveedor y mapea los resultados de vuelta a un modelo de anuncio canónico. Los anuncios llevan ids compuestos como pa:12345678 o ma:3554254. Los nombres de marca se resuelven por alias por fuente ("VW" y "Volkswagen" funcionan en todas partes); los filtros que una fuente no puede expresar se informan como warnings por fuente en los resultados.

• Herramientas (src/tools/) se distribuyen entre los adaptadores y fusionan los resultados, etiquetando todo con su fuente. Las categorías cubren coches, motocicletas, furgonetas, camiones ligeros/pesados, autobuses, remolques, caravanas, maquinaria, tractores, barcos y bicicletas.

• Grabador (src/recorder.ts) inserta o actualiza cada anuncio observado en listings y añade una fila en price_observations en la primera aparición o cambio de precio.

• Autenticación (src/auth/) es un servidor de autorización OAuth 2.1 autoalojado (registro dinámico de clientes, PKCE, tokens de refresco) con Google OIDC como capa de identidad. Los tokens se almacenan con hash en Postgres.

• Almacenamiento es Postgres mediante Drizzle ORM; las migraciones se ejecutan automáticamente al inicio.

Related MCP server: Vehicle Database MCP Server

Inicio rápido (Docker Compose)

1. Crea un cliente OAuth de Google en Google Cloud Console (tipo "Aplicación web") con URI de redirección autorizada <PUBLIC_URL>/auth/google/callback (por ejemplo, http://localhost:8321/auth/google/callback para uso local).

2. Configura el entorno:

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

3. Inicia todo (servidor MCP + Postgres + FlareSolverr):

docker compose up -d --build

4. Apunta tu cliente MCP a http://localhost:8321/mcp. El cliente descubrirá los metadatos OAuth, se registrará y abrirá una ventana del navegador para iniciar sesión con Google. Todo lo demás es por usuario.

Para una prueba local rápida sin credenciales de Google, establece AUTH_MODE=none — el servidor omite la autenticación y usa un único usuario de desarrollo local.

Herramientas

Habilidad de agente

El repositorio incluye una habilidad de agente en .cursor/skills/car-market-hub/SKILL.md que enseña a los agentes LLM cómo usar este servidor de manera efectiva (flujos de trabajo de herramientas, trampas), con guías de conexión por cliente para OpenAI, Claude, LibreChat y Cursor en clients.md. Cursor la recoge automáticamente; para otras plataformas, copia el directorio de la habilidad en la ubicación de habilidades de esa plataforma (por ejemplo, .claude/skills/) o pega su contenido en las instrucciones del agente.

Flujo de alertas

1. create_watch con un nombre y filtros (opcionalmente restringido a sources específicas): las coincidencias actuales se convierten en la línea base.

2. Más tarde (por ejemplo, una consulta programada: "revisa mis alertas de coches"), check_watches devuelve solo los anuncios que aparecieron desde entonces, por alerta y por fuente.

Añadir un nuevo adaptador de mercado

1. Crea src/adapters/<name>/ e implementa la interfaz SourceAdapter de src/adapters/types.ts: elige un id corto y estable (usado en los ids compuestos de anuncios), traduce los filtros canónicos de SearchQuery a la consulta de tu proveedor y mapea los resultados brutos a las formas canónicas ListingSummary / ListingDetail de src/domain/listing.ts.

2. Regístralo en src/server.ts con registerAdapter(...).

La distribución de búsquedas, las alertas, el grabado y el historial de precios recogen la nueva fuente automáticamente.

Variables de entorno

Desarrollo local

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

Cambios de esquema: edita src/db/schema.ts y luego ejecuta npm run db:generate para generar una nueva migración en drizzle/ (se aplica automáticamente al inicio).

Notas y límites

• polovniautomobili.com no tiene API pública; el adaptador lee los endpoints de datos Next.js del sitio usando suplantación de TLS de Chrome (impit), con FlareSolverr como respaldo ante desafíos de Cloudflare. Úsalo de manera responsable y respeta los términos de servicio del sitio.

• Los precios por debajo de 100 EUR se tratan como "precio bajo petición" y se excluyen de estadísticas y observaciones.

• Las comprobaciones de alertas escanean las dos primeras páginas de resultados (~50 anuncios más recientes) por fuente.

• get_price_history refleja solo los anuncios observados a través de este hub: es una muestra creciente, no el mercado completo.

• La implementación anterior de un solo proveedor se mantiene como referencia en old/ (no forma parte de la compilación).