집토리 사용 가이드

집토리 의 지도·필터·AI 챗봇 사용 방법과 MCP (Model Context Protocol) 서버 연결 방법을 한 페이지에 정리했습니다. 처음이신 분은 아래 사용 방법부터, AI 에이전트에서 직접 조회하고 싶다면 MCP 연결 안내로 이동하세요.

사이트 사용 방법

지도 기반 아파트 탐색 → 넛지 점수 확인 → 상세·비교 → 챗봇 질의까지 기본 흐름을 안내합니다.

  1. 지역·단지명 검색

    상단 🔍 검색창에 "강남구" 같은 지역이나 "래미안" 같은 단지명을 입력하고 Enter. 지역과 아파트 이름을 동시에 지원하며, 동명(同名) 지역이 여러 곳이면 후보 드롭다운에서 선택한다.

  2. 라이프스타일(넛지) 선택

    상단 칩에서 출퇴근·가성비·신혼부부·시니어·반려동물·자연친화·안전·교육·투자 중 관심 항목을 조합한다. 여러 개 동시 선택 가능하며, 선택한 조합에 맞춰 NUDGE 점수(0~100) 가 재계산된다.

  3. 결과 카드·지도에서 확인

    좌측 결과 카드와 지도 마커에서 NUDGE 점수 순으로 추천 단지를 확인. 마커 클릭 또는 카드 클릭으로 해당 단지로 초점이 이동한다.

  4. 🔽 필터로 조건 좁히기

    필터 버튼에서 준공연도·전용면적·가격대(매매·전세·월세) 범위를 설정. 활성 필터 개수는 버튼 옆에 숫자로 표시된다.

  5. ⚙ 가중치로 스코어링 커스터마이즈

    가중치 드로어에서 교통·교육·안전·편의·가격 등 항목별 중요도를 직접 조정하면 추천 점수가 실시간으로 재계산된다.

  6. 상세 보기·비교

    카드를 클릭하면 기본 정보·NUDGE 점수·학군 배정·시설 접근성·최근 거래이력을 한 화면에서 확인할 수 있고, 여러 단지를 선택하면 비교 모달에서 매트릭스로 대조할 수 있다.

  7. 💬 AI 챗봇으로 자연어 질의

    우하단 챗봇 버튼으로 "강남구에서 출퇴근 좋은 30평대 아파트 추천해줘" 같은 자연어 요청을 보낼 수 있다. OpenAI·Claude·Gemini 중 백엔드 설정된 모델이 응답한다.

  8. 실거래 대시보드 모드

    상단 탭에서 "실거래대시보드" 로 전환하면 시군구 월별 거래량·평균가 추이를 차트로 확인할 수 있다. 지도 모드와 독립된 뷰이다.

MCP 서버 연결 안내

집토리는 Model Context Protocol (MCP) 표준을 구현해 Claude Desktop·Cursor·Claude Code 같은 AI 에이전트가 아파트 데이터를 직접 조회할 수 있습니다.

엔드포인트
https://api.apt-recom.kr/mcp/
Transport
Streamable HTTP (MCP 2025-11-25 spec)
Auth
없음 (공개, stateless)
로컬 개발
http://localhost:8000/mcp/

제공 도구 (7종)

이름설명
search_apartments지역·단지명 키워드 + 라이프스타일 항목으로 NUDGE 스코어 순 추천
get_apartment_detail단일 아파트 전체 프로필 (기본정보·점수·시설·학군·최근 거래)
compare_apartments2~5개 단지 매트릭스 비교
get_similar_apartments위치/가격/라이프스타일/종합 기준 유사 단지 추천
get_market_trend시군구 월별 거래량·평균가 추이
get_school_info아파트의 초·중·고 학군 배정 정보
get_dashboard_info시군구 거래 동향 대시보드 요약

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

claude_desktop_config.json
{
  "mcpServers": {
    "apt-recom": {
      "url": "https://api.apt-recom.kr/mcp/"
    }
  }
}

저장 후 Claude Desktop 재시작. 대화 창 상단 도구 아이콘에서 apt-recom 도구 7개가 보이면 연결 완료.

Cursor

~/.cursor/mcp.json 또는 프로젝트 루트 .cursor/mcp.json

.cursor/mcp.json
{
  "mcpServers": {
    "apt-recom": {
      "url": "https://api.apt-recom.kr/mcp/"
    }
  }
}

Claude Code (CLI)

shell
claude mcp add --transport http apt-recom https://api.apt-recom.kr/mcp/

Python SDK (프로그래매틱 호출)

python
from mcp.client.streamable_http import streamablehttp_client
from mcp.client.session import ClientSession

async with streamablehttp_client("https://api.apt-recom.kr/mcp/") as (r, w, _):
    async with ClientSession(r, w) as session:
        await session.initialize()
        tools = await session.list_tools()
        result = await session.call_tool(
            "search_apartments",
            arguments={"keyword": "자양동", "nudges": ["commute", "education"], "top_n": 5},
        )

MCP Inspector 로 로컬 검증

백엔드를 로컬에서 기동한 뒤, 공식 MCP Inspector GUI 로 엔드포인트와 도구 응답을 확인할 수 있습니다.

shell
npx @modelcontextprotocol/inspector
# 접속 URL: http://localhost:8000/mcp/  (Transport: Streamable HTTP)

상세 사양은 프로젝트 저장소의 docs/mcp-server.md 를 참고하세요.

더 자세한 서비스 소개는 서비스 소개 페이지에서 확인할 수 있습니다.