AI 에이전트용 carsensor 가격대 MCP 서버

AI 에이전트, 챗봇, 또는 앱을 만들고 있고 "이 중고차의 제시 가격이 공정한가?"라는 질문에 — 추측이 아니라 실제 시장 데이터에 근거한 숫자로 — 답해야 한다면, 이 MCP 서버는 단 한 번의 도구 호출로 정확히 그 답을 제공합니다. resolvePriceRange(carModel, year)는 carsensor.net 자체의 공식 모델연식별 시세 통계에서 실시간으로 계산된 시장 가격대(min / max / median)를 반환합니다. 이는 carsensor가 자체 相場(시세) 페이지에 게시하는 것과 동일한 데이터를, 직접 읽고 해석해야 하는 페이지 대신 구조화된 즉시 사용 가능한 숫자로 변환한 것입니다.

제공 기능:

• 단일 도구 resolvePriceRange — 자동차 모델명과 연식만 입력하면 됩니다. 기본 데이터 소스에 대한 API 키 관리가 필요 없고, 직접 HTML을 파싱할 필요도 없습니다

• priceRangeYen: { min, max, median } 및 sampleSize(추정치의 기반이 된 실제 carsensor 매물 수)와 confidence(normal / low — 연식이 carsensor 자체 데이터로 완전히 검증되지 않을 때 숨기지 않고 정직하게 하향 조정됩니다. "알려진 제한 사항" 참조)

• Apify Standby 모드를 통한 상시 호스팅 — 직접 서버를 실행할 필요가 없습니다. 모든 MCP 클라이언트(Claude Desktop, Claude Code, 자체 에이전트)를 안정적인 HTTPS 엔드포인트에 직접 연결하거나, 자체 앱 코드에서 일반 Streamable HTTP MCP 서버로 호출할 수 있습니다

{
  "ok": true,
  "carModel": "プリウス",
  "year": 2018,
  "priceRangeYen": { "min": 750000, "max": 4772500, "median": 1573112 },
  "sampleSize": 412,
  "confidence": "normal",
  "disclaimer": "carsensor.net上の公開情報(相場ページの価格×年式集計)を基にした参考値です。個体差・装備差・実際の商談結果は反映されません。"
}

이벤트당 과금 — "가격" 섹션 참조. 전체 입출력 상세, 설정, 기술 설계는 이 페이지 아래쪽에 있습니다.

⚠️ 고지 사항 (꼭 읽어주세요)

• 이 Actor는 carsensor.net에 공개적으로 제공되는 정보를 자동으로 수집합니다. 이 데이터를 어떻게 수집하고 사용할지에 대한 책임은 사용자에게 있습니다.

• 사이트 소유자의 이용 약관, robots.txt 또는 접근 차단이 예고 없이 변경될 수 있으며, 이로 인해 이 Actor가 작동을 멈추거나 출력이 예기치 않게 변경될 수 있습니다.

• priceRangeYen은 carsensor가 자체적으로 게시한 가격×모델연식 집계 데이터에서 파생된 통계적 추정치이며, 개별 차량의 실제 가치를 보장하지 않습니다. 차량 상태, 트림/등급 차이, 주행 거리를 반영하지 않습니다("알려진 제한 사항" 참조). 이 데이터에 기반한 구매 또는 판매 결정을 내리기 전에 반드시 carsensor.net에서 특정 차량의 가격을 직접 확인하십시오.

누구를 위한 것인가?

• AI 에이전트 및 챗봇 — "이 차의 실제 가치는 얼마인가?"라는 질문에 모델의 (종종 오래되었거나 환각된) 중고차 가격 지식 대신 실제 시장 데이터로 근거를 제공해야 하는 경우

• 앱/도구 개발자 — 자체 carsensor.net 통합을 스크래핑하고 유지 관리하는 대신 바로 사용할 수 있는 가격대 조회 기능을 원하는 자동차 쇼핑, 가치 평가 또는 트레이드인 견적 기능을 구축하는 경우

• 단순 배치 스크래핑이 아닌 일반 MCP 도구 호출로 이 기능을 원하는 모든 사람 — 이 Actor는 동일한 기본 시장 데이터에 대해 전체 매물 목록을 평가하는 배치 지향 carsensor-resale-value-scout Actor의 단일 도구, 온디맨드 호출 대응 버전입니다

할 수 없는 것 (통합 전에 꼭 읽어주세요)

• 주행 거리는 아직 지원되는 입력이 아닙니다. 자동차 모델과 연식만 사용됩니다 — 가격대는 주행 거리 조정 추정치가 아닌 carsensor 자체의 모델연식 집계를 반영합니다. 향후 버전에서 추가될 수 있습니다.

• 익숙하지 않은 모델의 경우 모델명 해석이 가끔 실패하거나 첫 사용 시 느릴 수 있습니다 — 이유는 "알려진 제한 사항"을 참조하고, 첫 호출 후 캐싱이 이를 어떻게 완화하는지도 확인하세요.

• 이것은 감정이 아닌 통계적 추정치입니다. 위의 고지 사항을 참조하세요.

입력 / 출력

입력 (MCP 도구 호출 인자):

출력 (성공):

출력 (모델을 찾을 수 없음 / 해당 연식 데이터 없음): { "ok": false, "reason": "no_code_resolved" | "no_matching_data", "message": "..." } — 과금되지 않음 ("가격" 참조).

사용 예시

Claude Desktop / 모든 MCP 클라이언트 설정:

{
  "mcpServers": {
    "carsensor-price-range": {
      "url": "https://woolen-snake--carsensor-price-range-mcp.apify.actor/mcp",
      "headers": { "Authorization": "Bearer YOUR_APIFY_TOKEN" }
    }
  }
}

자체 앱에서 직접 호출 (Node.js, @modelcontextprotocol/sdk):

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(
  new URL('https://woolen-snake--carsensor-price-range-mcp.apify.actor/mcp'),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.APIFY_TOKEN}` } } },
);
const client = new Client({ name: 'my-app', version: '1.0.0' });
await client.connect(transport);

const result = await client.callTool({
  name: 'resolvePriceRange',
  arguments: { carModel: 'プリウス', year: 2018 },
});
console.log(JSON.parse(result.content[0].text));

가격

호출이 캐시된 데이터를 사용했는지 또는 carsensor.net에 새 요청을 했는지와 관계없이 균일 가격 — 전체 근거는 아래 "가격이 책정된 방식"을 참조하세요. 캐시 계층별 가격 책정이 의도적으로 거부된 이유도 포함됩니다.

가격이 책정된 방식

$0.03은 이 Actor 계열의 기본 분류 계층($0.015, 예: carsensor-resale-value-scout Actor의 listing-extracted)과 더 무거운 파생 신호 계층($0.045–$0.065, 예: value-score-computed) 사이에 위치합니다. 이는 가격대가 원시 데이터 조회가 아닌 계산된 시장 신호임을 반영하면서도, 이 도구의 기본 인프라 비용(호출당 $0.001 미만, 대부분의 호출은 캐시에서 처리)이 어느 쪽이든 큰 여유를 남기기 때문입니다.

캐시 적중과 미적중이 동일하게 과금되는 이유: 전달되는 가치 — priceRangeYen, sampleSize, confidence — 는 어느 쪽이든 동일합니다. 캐싱은 순전히 내부 성능/비용 최적화일 뿐, 사용자가 받는 것에는 차이가 없습니다. 다르게 과금하면 캐시 TTL을 줄이는 왜곡된 인센티브(미적중 증가 = 수익 증가)가 생기며, 이는 carsensor.net에 대한 부하를 최소화하려는 이 도구의 설계 목표와 정면으로 배치됩니다.

데이터 소스 및 계산

해석된 모델에 대한 carsensor.net 자체의 공개 게시 相場(시세) 페이지(/usedcar/souba/{makerCode}_S{modelCode}/)를 사용하며, 특히 "가격 × 모델연식" 교차표(가격 버킷, 연식 버킷, 셀별 매물 수)를 사용합니다 — 이는 제3자 추정치가 아닌 carsensor가 자체 실시간 재고에서 직접 계산한 공식 집계 데이터입니다.

• median은 각 일치하는 연식 버킷의 가격 버킷 중간값의 개수 가중 평균입니다

• min / max는 일치하는 셀의 실제 가격 버킷 경계에서 가져옵니다 (개방형 버킷, 예: "¥4,150,000 이상"은 ±15% 경험적 휴리스틱으로 근사 — 통계적으로 파생된 것이 아닌 경험적 조정입니다)

• 이는 등급 수준의 집계 데이터(예: 모든 Toyota Prius 트림 결합)이며 개별 매물 가격이 아닙니다 — 트림/등급 차이, 장비, 상태를 반영하지 않습니다

캐싱 (2계층)

두 계층 모두 캐시 적중 시 해당 호출에 대해 carsensor.net에 대한 HTTP 요청이 0회입니다. Apify 호스팅 버전에서 이 캐시는 단일 Standby 실행/컨테이너 인스턴스로 범위가 제한됩니다 — 동시 세션이 독립적인 캐시를 가진 다른 컨테이너 인스턴스에 배치될 수 있으므로, 호스팅 버전의 실제 적중률은 단일 장기 실행 로컬 프로세스보다 낮을 수 있습니다. 향후 버전에서 이것이 실제로 문제가 되는 경우 Apify의 Key-Value Store(실행 간 공유)로 이동할 수 있습니다.

접근 간격 및 로깅

carsensor.net에 대한 요청은 부하 감소 조치로 최소 1000ms 간격(기본 1500ms)으로 조절됩니다 — carsensor-resale-value-scout Actor에서 사용하는 것과 동일한 하한입니다. 모든 호출은 로깅됩니다(모델, 연식, 계층별 캐시 적중/미적중, 실제로 수행된 HTTP 요청, 응답 시간, 결과) — 호출자에게 노출되지 않으며 이 Actor를 책임감 있게 운영하는 데만 사용됩니다.

FAQ

confidence가 때때로 "low"인 이유는 무엇인가요? carsensor의 연식 축에는 자체 데이터에 개방형 하한 버킷(예: "2012년 이하")이 있습니다. 해당 경계 이하의 모든 연식은 모델이 실제로 그 연식에 존재했는지 여부와 관계없이 일치합니다 — 이 데이터만으로는 타당성을 완전히 검증할 방법이 없으므로, 확실하다고 보고하는 대신 confidence를 정직하게 하향 조정합니다. 해당 응답의 note 필드에서 구체적인 이유를 확인하세요.

특정 모델에 대한 첫 호출은 몇 초 걸리는데 반복 호출은 훨씬 빠른 이유는 무엇인가요? 익숙하지 않은 모델의 첫 호출은 어떤 모델인지 해석하기 위해 carsensor.net에 최대 3회의 실제 요청(검색 → 상세 페이지 → 시세 페이지)이 필요합니다. 해석되면 모델→코드 매핑은 사실상 영구적으로 캐시되고, 가격 데이터 자체는 12시간 동안 캐시됩니다 — 따라서 같은 모델에 대한 반복 호출은 거의 즉시 처리됩니다.

주행 거리를 다루나요? 아직 아닙니다 — "할 수 없는 것"을 참조하세요.

carsensor-resale-value-scout과 어떻게 다른가요? 그 Actor는 배치 스크래퍼입니다: 검색어를 주면 동일한 시장 데이터에 대해 각각 평가된 실시간 매물 목록을 반환합니다. 이 Actor는 단일 호출, 온디맨드 대응 버전으로, 스크래핑하고 처리할 목록이 아닌 특정 모델/연식에 대한 하나의 숫자를 원하는 AI 에이전트와 앱을 위해 만들어졌습니다.

알려진 제한 사항

• 모델명 확인에는 직접 조회가 없습니다 — carsensor 자체 프리워드 검색을 거쳐 일치하는 매물 페이지를 읽어 모델을 식별합니다. 실제로 인식되지 않는 모델(오타, 존재하지 않는 모델)의 경우, carsensor 검색 결과 페이지에는 여전히 관련 없는 자동차가 포함된 "좋아할 만한 다른 차량" 위젯이 표시됩니다. 이 Actor는 해당 위젯을 명시적으로 감지하고 제외하므로 실제 일치 항목으로 오인되지 않습니다 — 실시간 테스트로 확인됨.

• confidence는 조회된 연식이 해당 모델에 타당한지 완전히 검증할 수 없습니다 — FAQ 참조.

• 이것은 등급별 집계 값이지 개별 매물 가격이 아닙니다 — "데이터 출처 및 계산" 참조.

• 파일 기반 캐시는 호스팅(Apify Standby) 버전에서 컨테이너별로 유지됩니다 — "캐싱" 참조.

• 이 도구의 기본 스크래핑 로직은 일부러 복제된 것이지, carsensor-resale-value-scout의 코드베이스에서 import된 것이 아닙니다. 독립적으로 배포되는 두 Actor를 분리된 상태로 유지하기 위해서입니다. carsensor.net 마크업 변경이 둘 중 하나에 영향을 주면 다른 쪽에도 그에 맞는 수정이 필요할 수 있습니다.

• Smithery에 등록되지 않음: Apify Standby의 인증 응답이 OAuth 디스커버리 규격을 준수하지 않아, Smithery의 자동 연결 검사가 이 서버 자체의 구성 기반 인증에 도달하기도 전에 중단됩니다. 현재로선 우회 방법이 계획되어 있지 않습니다.

향후 확장 가능 항목(이 버전에서는 미구현)

• 주행거리를 세 번째 입력으로 사용, carsensor의 가격×주행거리 매트릭스 활용(가져올 수 있음을 확인했지만 아직 연결되지 않음)

• 캐시를 Apify의 Key-Value Store로 옮겨 Standby 컨테이너 인스턴스 간에 공유

• Apify Store 이외의 추가 MCP 디렉터리에 등록