Polovnjak MCP

중고차 마켓플레이스를 위한 다중 공급자 MCP 서버입니다. 에이전트는 검색, 리스팅 상세, 가격 통계, 가격 이력, 사용자별 저장 검색 알림 등 하나의 통합된 도구 표면을 얻을 수 있으며, 플러그 가능한 마켓플레이스 어댑터로 구동됩니다. 포함된 어댑터: polovniautomobili.com (소스 id pa) 및 mojauto.rs (소스 id ma), 둘 다 세르비아입니다.

사용자는 표준 MCP OAuth 2.1 흐름을 통해 Google로 로그인하며, 알림은 사용자별로 비공개입니다. 허브가 관찰하는 모든 리스팅(모든 사용자의 검색, 통계 샘플링 또는 알림 확인에서)은 공유 Postgres "마켓 메모리"에 기록되며, 이는 어떤 단일 마켓플레이스도 제공하지 않는 가격 이력 및 추세 쿼리를 지원합니다.

아키텍처

• 어댑터 (src/adapters/)는 공통 SourceAdapter 인터페이스(search, getListing, getMakesModels 및 기능 플래그)를 구현합니다. 각 어댑터는 표준 필터를 해당 공급자의 쿼리로 변환하고 결과를 표준 리스팅 모델로 매핑합니다. 리스팅은 pa:12345678 또는 ma:3554254와 같은 복합 id를 갖습니다. 제조사 이름은 소스별로 별칭이 해석됩니다("VW"와 "Volkswagen"은 어디서나 모두 작동). 소스가 표현할 수 없는 필터는 결과에서 소스별 warnings로 보고됩니다.

• 도구 (src/tools/)는 어댑터에 걸쳐 팬아웃되어 결과를 병합하고 모든 것을 소스로 태그합니다. 카테고리는 자동차, 오토바이, 밴, 경/중트럭, 버스, 트레일러, 캠퍼, 기계, 트랙터, 보트 및 자전거를 포함합니다.

• 레코더 (src/recorder.ts)는 관찰된 모든 리스팅을 listings에 업서트하고, 첫 발견 또는 가격 변경 시 price_observations 행을 추가합니다.

• 인증 (src/auth/)은 Google OIDC를 ID 계층으로 사용하는 자체 호스팅 OAuth 2.1 인증 서버(동적 클라이언트 등록, PKCE, 리프레시 토큰)입니다. 토큰은 Postgres에 해시되어 저장됩니다.

• 스토리지는 Drizzle ORM을 통한 Postgres입니다. 마이그레이션은 시작 시 자동으로 실행됩니다.

Related MCP server: Vehicle Database MCP Server

빠른 시작 (Docker Compose)

1. Google Cloud Console에서 Google OAuth 클라이언트("웹 애플리케이션" 유형)를 만들고 승인된 리디렉션 URI를 <PUBLIC_URL>/auth/google/callback(예: 로컬 사용 시 http://localhost:8321/auth/google/callback)로 설정합니다.

2. 환경을 구성합니다:

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

3. 모든 것(MCP 서버 + Postgres + FlareSolverr)을 시작합니다:

docker compose up -d --build

4. MCP 클라이언트를 http://localhost:8321/mcp로 지정합니다. 클라이언트는 OAuth 메타데이터를 발견하고, 자체 등록한 다음 Google 로그인을 위해 브라우저 창을 엽니다. 그 이후의 모든 것은 사용자별로 이루어집니다.

Google 자격 증명 없이 빠른 로컬 테스트를 하려면 AUTH_MODE=none으로 설정하세요. 그러면 서버가 인증을 건너뛰고 단일 로컬 개발 사용자를 사용합니다.

도구

에이전트 스킬

이 저장소는 .cursor/skills/car-market-hub/SKILL.md에 에이전트 스킬을 제공하며, LLM 에이전트가 이 서버를 효과적으로 사용하는 방법(도구 워크플로, 함정)을 가르치고, clients.md에 OpenAI, Claude, LibreChat 및 Cursor용 클라이언트별 연결 가이드가 있습니다. Cursor는 자동으로 이를 인식합니다. 다른 플랫폼의 경우 스킬 디렉터리를 해당 플랫폼의 스킬 위치(예: .claude/skills/)에 복사하거나 내용을 에이전트 지침에 붙여넣으세요.

알림 워크플로

1. 이름과 필터로 create_watch를 호출합니다(선택적으로 특정 sources로 제한). 현재 일치 항목이 기준선이 됩니다.

2. 나중에(예: 예약된 프롬프트 "내 자동차 알림 확인") check_watches는 알림별 및 소스별로 그 이후에 나타난 리스팅만 반환합니다.

새 마켓플레이스 어댑터 추가

1. src/adapters/<name>/을 만들고 src/adapters/types.ts의 SourceAdapter 인터페이스를 구현합니다: 짧고 안정적인 id를 선택하고(복합 리스팅 id에 사용), 표준 SearchQuery 필터를 공급자의 쿼리로 변환하며, 원시 결과를 src/domain/listing.ts의 표준 ListingSummary / ListingDetail 형태로 매핑합니다.

2. src/server.ts에서 registerAdapter(...)로 등록합니다.

검색 팬아웃, 알림, 기록 및 가격 이력은 새 소스를 자동으로 인식합니다.

환경 변수

로컬 개발

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

스키마 변경: src/db/schema.ts를 편집한 다음 npm run db:generate를 실행하여 drizzle/ 아래에 새 마이그레이션을 생성합니다(시작 시 자동 적용).

참고 사항 및 제한

• polovniautomobili.com에는 공개 API가 없습니다. 어댑터는 Chrome TLS 위장(impit)을 사용하여 사이트의 Next.js 데이터 엔드포인트를 읽고, FlareSolverr을 Cloudflare 챌린지 폴백으로 사용합니다. 책임감 있게 사용하고 사이트의 서비스 약관을 준수하세요.

• 100 EUR 미만의 가격은 "가격 문의"로 처리되며 통계 및 관찰에서 제외됩니다.

• 알림 확인은 소스당 처음 두 결과 페이지(약 50개의 최신 리스팅)를 스캔합니다.

• get_price_history는 이 허브를 통해 관찰된 리스팅만 반영합니다. 이는 전체 시장이 아닌 증가하는 샘플입니다.

• 이전 단일 공급자 구현은 참조용으로 old/에 보관됩니다(빌드에 포함되지 않음).