Qobrix CRM MCP Server

목차

• 설치 가이드 — Sharp Matrix 인트라넷, pm2, Apache, Claude.ai + Dust.tt 커넥터

• 사용자 가이드 — Mode A → Mode B → Mode C → Mode D (Claude.ai + Dust.tt) 단계별 안내

• 주요 기능

• 대상 사용자

• 표준 부동산 워크플로우

• 도구 한눈에 보기

• 빠른 시작

• 설정

• 인증 모드

• Enterprise OAuth

• 캐싱

• Cursor IDE 설정

• 기타 MCP 호스트

• 검색 표현식 구문

• 관련 데이터 가져오기

• 테스트

• 아키텍처

• LLM이 학습하는 방식

• 기술 스택

• 라이선스

주요 기능

이 서버에 연결된 AI 어시스턴트는 자연어만으로 매물 검색, 리드 검증, 방문·투어 추적, 오퍼·계약 검토, 후속 활동 감사, CRM 필드 스키마 탐색을 수행할 수 있습니다. 모든 도구 설명에는 해당 도구가 어떤 표준 부동산 워크플로우에 속하는지, 어떤 RESO 리소스에 매핑되는지, 그리고 다음에 연결할 수 있는 도구가 무엇인지가 LLM에 안내됩니다.

대상 사용자

• 중개업체 및 개발자 — Qobrix를 사용하면서 생동된 CRM 데이터(복사/붙여넣기된 내보내기 데이터가 아닌)를 바탕으로 질문에 답변해 주는 Claude.ai, Dust.tt, ChatGPT, Cursor를 원하는 곳.

• 엔지니어 — 내부 도구에 MCP를 연결하는 곳: stdio transport, 타입 지정된 Zod 입력, 워크서피스 없음 — 프롬프트와 에이전트 실험에 안전합니다.

• 데이터 및 운영 팀 — 대시보드를 운영하는 팀: 커스텀 스크립트 없이 YoY 스타일 지표를 위해 qobrix_count / qobrix_top_values 를 사용하고, 반복 쿼리의 API 부하를 줄이기 위해 응답 캐싱을 활용하세요.

• 엔터프라이즈 IT — 에이전트별 신원에 대비하는 곳: 이 패키지의 Mode A/B를 실행하고, 모든 사용자가 본인 인증을 해야 하는 경우에는 Mode C를 SharpSir의 Enterprise OAuth (SSO) 제품과 연결하세요. Enterprise OAuth 참조.

표준 부동산 워크플로우

이 서버는 RESO 규격에 맞는 여섯 가지 비즈니스 프로세스로 구성됩니다. LLM은 이 프로세스를 기본 내장된 안내로 받아 별도의 추가 학습 없이 CRM을 안내할 수 있습니다.

상태 매핑

도구 한눈에 보기

64개 도구 — CRM 엔티티, 스키마 탐색, 분석(qobrix_count, qobrix_top_values, qobrix_top_records, qobrix_aggregate), 유연한 거래 단축 명령(qobrix_deals), 리포팅(qobrix_timeseries, qobrix_funnel, qobrix_rep_scorecard, qobrix_stale_leads, qobrix_win_loss, qobrix_days_on_market), 고객 인텔리전스(qobrix_cohort), 감사 / 변경 이력(qobrix_get_changes, qobrix_search_changes, qobrix_field_change_history, qobrix_top_field_changes), 캐시 헬퍼(qobrix_cache_stats, qobrix_cache_clear), 그리고 세션 및 신원(qobrix_sign_in, qobrix_sign_out, qobrix_whoami):

모든 도구 설명에는 표준 워크플로 역할, RESO 등가물, 검증된 include[] 옵션, FK 해석 지침, 검색 표현식 예제가 포함됩니다.

분석 및 딜 사용 예제

서버 측 sort(OpenAPI sort[])는 대부분의 필드에서 작동합니다. 예: 매물의 sort: "-list_selling_price_amount". 전체 데이터셋 스캔이 필요하거나, 서버 정렬에서 nullable 필드(예: opportunities.budget)가 행을 반환하지 않는 경우 qobrix_top_records / **qobrix_aggregate**를 사용하세요. "완료된 거래"는 매물 플래그로 존재하지 않습니다. Contracts 테이블의 행입니다. 분석/딜 도구는 클라이언트 측 스크립팅의 필요성을 제거합니다:

// 1) Top 5 closed 2026 sales, sorted by final_selling_price_amount,
//    with property + agent + lawyers resolved to readable names.
{
  "tool": "qobrix_top_records",
  "args": {
    "resource": "contracts",
    "sort_by": "final_selling_price_amount",
    "search": "contract_type == \"cos\" and contract_status == \"agreed\" and date_of_contract >= \"2026-01-01\" and date_of_contract < \"2027-01-01\"",
    "top": 5
  }
}

// 2) 2026 sales volume, plus an agent leaderboard in one extra call.
{
  "tool": "qobrix_aggregate",
  "args": {
    "resource": "contracts",
    "field": "final_selling_price_amount",
    "op": "sum",
    "search": "contract_type == \"cos\" and contract_status == \"agreed\" and date_of_contract >= \"2026-01-01\" and date_of_contract < \"2027-01-01\"",
    "group_by": "commission_to_2",
    "top": 10
  }
}

// 3) Flexible "deals" shortcut — same answer as (1) with one default-laden call,
//    plus a full-set summary block (by_status, by_type, totals, median).
{ "tool": "qobrix_deals", "args": { "year": 2026, "top": 5 } }

// 4) Best 2026 rental contracts by final rental price.
{ "tool": "qobrix_deals", "args": { "kind": "rental", "year": 2026, "top": 5 } }

// 5) Under-contract reservations + closed sales together (pipeline + actuals).
{
  "tool": "qobrix_deals",
  "args": { "contract_statuses": ["reserved", "agreed"], "year": 2026 }
}

// 6) "My deals this year": uses the CURRENT_USER special var.
{
  "tool": "qobrix_deals",
  "args": { "assigned_to": "CURRENT_USER", "year": 2026 }
}

// 7) Monthly 2026 closed-sale volume with prior-year YoY %.
{
  "tool": "qobrix_timeseries",
  "args": {
    "resource": "contracts",
    "bucket": "month",
    "metric": "sum",
    "field": "final_selling_price_amount",
    "year": 2026,
    "search": "contract_type == \"cos\" and contract_status == \"agreed\"",
    "compare_to_prior": true
  }
}

// 8) Full 2026 sales funnel (Leads → Qualified → Viewing → Offer → Reserved → Closed).
{ "tool": "qobrix_funnel", "args": { "year": 2026 } }

// 9) 2026 agent leaderboard by volume (omit `user` for leaderboard mode).
{ "tool": "qobrix_rep_scorecard", "args": { "year": 2026, "sort_by": "volume", "top": 10 } }

// 10) Silent leads — open opportunities with no activity in 30 days.
{ "tool": "qobrix_stale_leads", "args": { "since_days": 30 } }

// 11) Multi-dim pivot: 2026 closed-sale volume by city × property_type.
{
  "tool": "qobrix_aggregate",
  "args": {
    "resource": "contracts",
    "field": "final_selling_price_amount",
    "op": "sum",
    "search": "contract_type == \"cos\" and contract_status == \"agreed\" and date_of_contract >= \"2026-01-01\" and date_of_contract < \"2027-01-01\"",
    "group_by": ["property_id", "contract_type"],
    "top": 10
  }
}

// 12) Repeat buyers — contacts behind 2+ closed sales in 2026.
{ "tool": "qobrix_cohort", "args": { "kind": "buyers", "year": 2026, "min_count": 2 } }

// 13) Win-rate by lead source in 2026, with top loss reasons resolved.
{
  "tool": "qobrix_win_loss",
  "args": { "year": 2026, "group_by": "source", "include_top_losses": true }
}

// 14) 2026 days-on-market by property type, with longest/shortest outliers.
{
  "tool": "qobrix_days_on_market",
  "args": { "kind": "sold", "year": 2026, "group_by": "property_type", "include_outliers": true }
}

빠른 시작

git clone https://github.com/gca-ltd/qobrix-crm-mcp.git
cd qobrix-crm-mcp
npm install
npm run build

구성

프로젝트 루트에 .env 파일을 만드세요:

QOBRIX_API_URL=https://yourcrm.qobrix.com
QOBRIX_API_USER=your-api-user-uuid
QOBRIX_API_KEY=your-api-key
QOBRIX_LOCALE=en-US          # optional

인증 모드

이 패키지를 클론하고 모드 A 또는 B를 실행하여 실시간 Qobrix 데이터를 Claude, Cursor 또는 모든 MCP 클라이언트에 제공하세요 — Apache 2.0.

모드 A와 B는 이 패키지에서 완전히 지원됩니다. 모드 C와 D는 SharpSir의 별도 Enterprise OAuth / SSO 제품이 필요합니다 — 이 저장소의 일부로 배포되지 않습니다. 모드 D는 모드 A/B/C를 변경하지 않습니다 — Claude.ai 또는 Dust.tt와 같은 원격 호스트가 OAuth를 직접 처리하도록 하려면 선택하세요.

Enterprise OAuth

에이전트가 공유 API 키가 아닌 로그인된 Qobrix 사용자로 작동해야 하나요? 모드 C가 이를 위해 설계되었습니다. SharpSir의 Enterprise OAuth 솔루션이 필요합니다: 이 MCP 서버와만 페어링되는 호스팅 인증 서버 번들(로그인 + 2FA + 동의, 사용자별 API 키 발급, 암호화된 자격 증명 볼트, 대상 바인딩 토큰).

모드 C 작동 방식 (MCP 자체 인증 — 상위 클라이언트 변경 없음):

1. 세션이 연결되지 않은 상태로 도구를 실행하면 → MCP가 인증 URL을 반환합니다:

   • 클라이언트가 elicitation.url을 지원하는 경우(예: Claude, Cursor 등) URL-mode elicitation(JSON-RPC -32042)을 사용합니다.

   • elicitation을 지원하지 않는 클라이언트(예: ragchat / LangChain)의 경우 도구 결과에 Markdown [Sign In to Qobrix](/connect?e=…) 링크가 포함됩니다 — LLM은 이 링크를 그대로 전달해야 합니다(고유하며 반드시 일회용이고, 이전 링크는 재사용 하면 안 됩니다).

2. 사용자가 이 서버에서 **/connect**를 엽니다(피싱 방지 리다이렉션) → 서명된 쿠키와 함께 Enterprise OAuth 로그인 페이지로 리다이렉션됩니다.

3. 로그인 + 2FA + 동의 후, AS(Authorization Server)가 **/oauth/callback**으로 리다이렉션합니다. 이 MCP가 코드(PKCE) 교환, Qobrix 자격 증명 introspection, 이를 암호화된 세션 vault에 저장합니다.

4. 다음 도구 호출에서 인증된 상태로 실행됩니다. Qobrix가 401/403을 반환하면 vault를 지우고 새 /connect URL을 반환합니다.

5. 에이전트는 qobrix_sign_in, qobrix_whoami, **qobrix_sign_out**도 호출할 수 있습니다. (AS /disconnect 및 Qobrix API 키 삭제를 통한 완전한 취소 포함)

• 공개 다운로드로 제공되는 것이 아니며 GitHub에서 clone할 수 있는 것도 아닙니다>Pull남.

• 당사 팀이 엔터프라이즈 솔루션 번들 형태로 요청 시 배포하고 구성합니다.

• 제3자 OAuth 서버는 없습니다 — Mode C는 이 Enterprise OAuth 솔루션에만 전용으로 연결됩니다.

• 보안: Mode C는 사용자별 암호화 세션 vault(채팅 identity 헤더를 키로 사용)를 사용하며 /mcp에 bearer가 없는 상태로 둡니다. QOBRIX_MCP_HOST=127.0.0.1에 바인딩하고 QOBRIX_MCP_IDENTITY_SECRET(신뢰할 수 있는 MCP 호스트인 ragchat에만 공유)을 설정하여 identity 헤더가 위조되지 않도록 하세요. vault 암호화는 QOBRIX_MCP_STATE_SECRET(MCP 전용)에 유지하세요. 브라우저용로 리버스 프록시를 구성할 경우, /connect와 /oauth/callback만 공개하고 /mcp와 /health는 공개 차단하세요. 로컬 에이전트(ragchat)는 http://127.0.0.1:<port>/mcp를 호출합니다. ALLOWED_HOSTS가 호스트이름만 나열하면, 서버가 루프백에 바인딩된 경우 loopback Host 값(127.0.0.1 / localhost / ::1)이 자동 추가됩니다. Connect 쿠키 Path는 PUBLIC_URL의 pathname을 따르고, Express trust proxy는 Cloudflare→Apache 뒤에서 2입니다. /connect 링크는 항상 개인 사용자에게만 전달하고 공유/그룹 스레드에는 절대 넣지 마세요.

업그레이드할 준비가 되셨나요? SharpSir Group에 문의하거나 dev@sharpsir.group로 연락해 Qobrix CRM MCP Enterprise OAuth 번들을 요청하세요.

배포가 완료되면, 서버를 받은 issuer(제공된 발급자)에 지정합니다:

export QOBRIX_MCP_TRANSPORT=http
export QOBRIX_MCP_AUTH=oauth
export QOBRIX_MCP_HOST=127.0.0.1
export QOBRIX_MCP_PORT=3502
export QOBRIX_MCP_PUBLIC_URL=http://127.0.0.1:3502
export QOBRIX_MCP_RESOURCE_URL=http://127.0.0.1:3502/mcp
export QOBRIX_OAUTH_ISSUER=<issuer-from-enterprise-bundle>
export QOBRIX_OAUTH_INTROSPECTION_SECRET=<shared-secret-from-bundle>
export QOBRIX_MCP_STATE_SECRET=<16+-char-secret>
export QOBRIX_MCP_IDENTITY_SECRET=<16+-char-secret-shared-with-ragchat>
export QOBRIX_MCP_DATA_DIR=./data/mcp-oauth
export QOBRIX_MCP_ALLOWED_HOSTS=qobrix-mcp.example.com   # loopback Hosts auto-added when HOST is 127.0.0.1
npm start

Mode C 엔드포인트(Enterprise OAuth 솔루션 연동 후):

• GET /connect?e=… — 권한 부여 시작(쿠키 설정, AS로 302 리다이렉션)

• GET /oauth/callback — PKCE 코드 교환 및 사용자별 세션 vault 기록

• GET /health — connected 및 session_vaults 개수 포함

• 인증되지 않은 /mcp는 northbound 클라이언트를 위해 의도적으로 열어 두는 것입니다. 필요 시 도구가 연결 URL을 표시하며, 운영 환경에서는 /mcp를 localhost에 유지하세요.

Mode A → B → C 순서, 리버스 프록시 잠금, 호스트 허용 목록에 대한 자세한 내용은 **docs/USER_GUIDE.md**를 참조하세요.

ragchat / Mode C의 경우 원격 MCP URL(…/mcp)을 일반 Streamable HTTP 서버로 등록하세요(클라이언트 측 OAuth provider가 필요 없음). MCP가 /connect를 통해 인증을 처리합니다. 이 구성에서는 /mcp를 로컬 레지스트리에 유지하세요.

Mode D — Claude.ai 및 Dust.tt 원격 MCP (공유 리소스)

QOBRIX_MCP_AUTH=oauth-claude 설정으로 별도의 MCP 프로세스(또는 호스트)를 사용하세요. 원격 호스트가 동일한 HTTPS /mcp URL에 대해 OAuth를 직접 수행합니다:

1. 사용자가 https://intranet.sharpsirgroup.net/qobrix-crm/mcp(실제 도메인)를 Claude 또는 Dust에 붙여넣습니다. (저장 URL을 그대로 사용해야 합니다 — 예: https://intranet.sharpsirgroup/qobrix-crm/mcp) 원본에는 https://intranet.sharpsirgroup/qobrix-crm/mcp라는 링크가 없었지만, 반복 문구가 아닌 일반 주소 규칙에 따라 다목적 도메인입니다. 그러나 인용문 원문이 실제 intranet.sharpsirgroup/qobrix-crm/mcp이므로 그것을 사용해야 합니다.

2. 호스트가 /mcp를 호출 → 401 + WWW-Authenticate: Bearer resource_metadata=… 수신

3. 호스트가 /.well-known/oauth-protected-resource을 fetch하여 QOBRIX_OAUTH_ISSUER를 검색

4. 호스트가 Enterprise OAuth AS에 대해 OAuth(DCR 또는 Static) + PKCE 완료

5. 이후 /mcp 호출에 Authorization: Bearer <access_token>이 전송되고, 이 서버는 introspection 후 해당 Qobrix 사용자로 도구 실행

Claude와 Dust는 하나의 Mode D 스택을 공유합니다(동일한 MCP 리소스 + 동일한 Authorization Server). 각 호스트는 자체 OAuth 클라이언트를 등록하고, 각 사용자는 자신의 신원으로 Qobrix에 로그인합니다.

export QOBRIX_MCP_TRANSPORT=http
export QOBRIX_MCP_AUTH=oauth-claude
export QOBRIX_MCP_HOST=127.0.0.1
export QOBRIX_MCP_PORT=3502
export QOBRIX_MCP_ALLOWED_HOSTS=intranet.sharpsir.group
export QOBRIX_MCP_PUBLIC_URL=https://intranet.sharpsir.group/qobrix-crm
export QOBRIX_MCP_RESOURCE_URL=https://intranet.sharpsir.group/qobrix-crm/mcp
export QOBRIX_OAUTH_ISSUER=https://intranet.sharpsir.group/qobrix-crm/mcp-oauth
export QOBRIX_OAUTH_INTROSPECTION_SECRET=<shared-secret-from-bundle>
npm start

AS에서 리다이렉션 허용 목록을 사용할 때는 Claude의 콜백을 유지하고 정확한 Dust 최종 URL을 추가하세요(Claude의 항목을 절대 대체하지 마세요):

export QOBRIX_OAUTH_REDIRECT_ALLOWLIST=https://claude.ai/api/mcp/auth_callback,http://127.0.0.1,http://localhost,cursor://,https://eu.dust.tt/oauth/mcp/finalize,https://eu.dust.tt/oauth/mcp_static/finalize,https://dust.tt/oauth/mcp/finalize,https://dust.tt/oauth/mcp_static/finalize,https://app.dust.tt/oauth/mcp/finalize,https://app.dust.tt/oauth/mcp_static/finalize

HTTPS /mcp + PRM(및 AS)을 공공 인터넷에 게시하세요. WAF를 사용하는 경우 Anthropic egress 160.23.104.0/21을 허용목록에 추가하고, 추가로 Dust egress도 허용하세요 — Claude의 허용 목록을 삭제하지 마세요. Mode C의 루프백 / deny public /mcp 가이드는 ragchat 배포에서 여전히 유효하며, Mode C 프로세스에 대해 이 구성을 변경하지 마세요.

전체 절차: INSTALL — Connect Claude · INSTALL — Connect Dust · Dust: Adding an MCP Server

Caching

모든 MCP 도구는 읽기 전용인 GET들이므로, 응답 캐시가 CRM 상태를 오염시킬 수 없습니다. 서버는 단일 병목 지점(QobrixClient.request())을 read-through 캐시로 감싸기 때문에 모든 list / get / search / schema 호출(각 relevance max_scan의 각 페이지 포함)이 캐시됩니다. 부스트 점수는 fetch 후 계산되므로 캐시 키를 변경하지 않으며, 다른 boost[] 값으로 재정렬해도 동일한 후보 페이지를 재사용합니다.

구현 — cache-aside 폴백에도 single-flight 병합:

• Tier 1 — in-memory LRU (기본 항상, 추가 의존성 없음): 프로세스별, TTL 적용, 크기 제한.

• Tier 2 — Redis (선택, 지연 동적 import()으로 실행): QOBRIX_REDIS_URL을 설정하면 활성화됩니다. Redis 오류가 발생하면 메모리 전용으로 대체됩니다.

• Single-flight: LLM이 동일한 cold cache 키로 병렬 도구 호출을 실행할 때(일반적으로 qobrix_top_values에서 발생) 모든 프로세스 내 호출자가 하나의 upstream fetch를 공유합니다.

• 오류는 절대 캐시하지 않습니다 — 일시 5xx 오류가 캐시에 남지 않습니다.

• TTL만 사용, v1에서는 stale-while-revalidate 사용 없음.

환경 변수:

캐시 도구(LLM에 노출되는 도구):

권장 Redis 서버 설정 (캐시 전용 Redis의 경우, Redis 문서 기준):

maxmemory 256mb
maxmemory-policy allkeys-lru
maxmemory-samples 10

TTL 가이드라인 — Redis 문서는 자주 변경되는 데이터에는 짧은 TTL(60–120초), 변동이 적은 데이터에는 더 긴 TTL(수시간)을 권장합니다. 300초는 분 단위로 변화는 리드 파이프라인과 시간 단위로 변화가 적은 부동산 목록이 혼합된 CRM에 적합한 디폴트입니다. 즉석 새로고침이 필요하면 qobrix_cache_clear를 사용하세요.

트레이드오프 / 알려진 한계: Single-flight coalescing은 단일 프로세스 내부입니다. Redis 하나를 공유하는 다중 인스턴스 배포에서는 여전히 cold key에 대한 일부 stampede를 확인할 수 있습니다. 분산 SETNX 락은 향후 과목이며 일반적인 단일 사용자 MCP 클라이언트에는 필요하지 않습니다.

모범 사례 적용:

Cursor IDE 설정

이 서버는 stdio MCP를 사용합니다(로컬 node 프로세스). Cursor는 프로젝트 또는 사용자 수준 mcp.json을 찾습니다: 열어둔 폴더 안 .cursor/mcp.json 또는 모든 워크스페이스에서 적용되는 ~/.cursor/mcp.json.

1. 전제 조건

• Node.js 20+ (Cursor가 MCP 실행하는 컴퓨터 - 로컬 노트북 또는 원격 SSH 호스트)

• 이 저장소를 클론하고, 설치 및 빌드(Quick Start 참조)

• MCP 엔트라 등록 전에 dist/index.js가 있어야 함(npm run build 실행)

2. Credentials

1. 템플릿 복사: cp .env.example .env

2. .env 를 편집해 최소 QOBRIX_API_URL, QOBRIX_API_USER, QOBRIX_API_KEY 설정 (Configuration 참고)

3. .env는 git에 노출하지 않기 — 이미 .gitignore 목록에 포함

3. JSON 위치

기존 "mcpServers" 객체에 항목을 병합하세요. 서버가 이미 포함된 경우 전체 파일을 교체하지 마세요.

4. 권장: node --env-file (Node 20+)

절대경로를 사용하시면, 워크스페이스 루트가 이 repo인지 상위 폴더인지 관계없고, SSH 리모트 경로도 올바르게 동작합니다.

D(this won't be changed) 등 대체.

{
  "mcpServers": {
    "qobrix-crm-mcp": {
      "command": "node",
      "args": [
        "--env-file=/absolute/path/to/qobrix-crm-mcp/.env",
        "/absolute/path/to/qobrix-crm-mcp/dist/index.js"
      ],
      "description": "Read-only Qobrix CRM MCP"
    }
  }
}

이 유형이 유용한 이유:

• 자격 증명이 JSON, ...의 .env에 남아 보안이 개선됩니다.

• Node는 서버 시작 전에 파일을 로드하므로, 호스트의 envFile 필드를 무시하거나 stdio 서버에서 동작이 일관되지 않아도 process.env가 미리 채워집니다.

5. 대안: 인라인 env

--env-file을 사용할 수 없을 때(구형 Node) 유용합니다. 시크릿이 mcp.json 내에 존재하므로 파일 권한을 제한하고 커밋하지 않습니다.

{
  "mcpServers": {
    "qobrix-crm-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/qobrix-crm-mcp/dist/index.js"],
      "env": {
        "QOBRIX_API_URL": "https://yourcrm.qobrix.com",
        "QOBRIX_API_USER": "your-api-user-uuid",
        "QOBRIX_API_KEY": "your-api-key",
        "QOBRIX_LOCALE": "en-US"
      }
    }
  }
}

Cursor의 config interpolation(예: ${env:QOBRIX_API_KEY})을 사용할 수도 있습니다. 이렇게 하면 리터럴 값 대신 OS 환경 변수에서 값이 주입됩니다.

6. 선택 사항: MCP JSON의 envFile

Cursor는 stdio 서버에 대해 envFile 속성을 지원합니다. 일부 설정에서는 해당 변수가 하위 프로세스로 안정적으로 전달되지 않습니다. "Missing required environment variables" 오류로 도구가 실패하면 4단계의 --env-file 방식으로 전환하세요.

7. mcp.json 또는 .env 편집 후

1. MCP 다시 로드 — Command Palette → MCP restart, 또는 Cursor 창 다시 로드.

2. 로그 확인 — View → Output → 드롭다운에서 "MCP" / "MCP Logs" 선택; 경로 또는 Node 오류를 여기서 수정.

3. 도구 승인 — 기본적으로 Cursor는 각 도구 호출 전에 확인을 요청합니다. 원하면 Cursor 설정에서 신뢰할 수 있는 도구에 대해 자동 실행을 허용할 수 있습니다.

기타 MCP 호스트

Claude.ai / Claude Desktop (Mode D) — https://intranet.sharpsir.group/qobrix-crm/mcp의 원격 사용자 지정 커넥터. Mode D 및 INSTALL — Connect Claude 참조.

Dust.tt (Mode D) — Spaces → Tools → Add MCP Server에서 동일한 URL 사용. Automatic 인증 및 Personal 계정을 권장합니다. INSTALL — Connect Dust 참조.

Claude Desktop / Cursor (Mode A stdio) — 동일한 stdio 형태: command + args로 node를 지정하고 호스트의 MCP 구성 파일에서 --env-file 또는 env를 사용.

CI / 헤드리스 — stdio MCP 클라이언트 라이브러리와 함께 node --env-file=.env dist/index.js 실행; .env는 커밋하지 말고 시크릿으로 제공.

검색 표현식 구문

search 매개변수를 허용하는 도구는 Qobrix의 Symfony Expression Language(OpenAPI SearchExpression)를 사용합니다. 전체 문법 + 속성/프로젝트 필드 치트시트(선택적으로 라이브 스키마 필드 이름 포함)는 **qobrix_search_dsl_help**를 호출하세요.

팁: 자유 형식의 요구를 쿼리로 변환하기 전에 qobrix_search_dsl_help({ resource: "Properties" })를 호출하세요. 열거형 값에는 qobrix_get_field_options를, 전체 필드 목록에는 qobrix_get_schema를 사용하세요.

모든 리소스의 관련성 검색 (F1)

모든 qobrix_search_* 도구(속성, 프로젝트, 연락처, 에이전트, 기회, 방문, 작업, 제안, 계약)는 자유 형식의 요구를 높은 정밀도 및 높은 재현율로 매핑하는 2계층 설계를 사용합니다:

1. search — 필수 조건(서버 측 DSL 필터 → 정밀도 하한).

2. boost[] — 후보 풀에서 프로세스 내에서 점수가 매겨지는 소프트 가중치 선호 조건(재현율 + 순위).

3. limit — 반환할 순위가 매겨진 행 수(기본 10, 최대 100). 더 많은 옵션이 필요하면 늘리되, 컨텍스트 과부하를 피하기 위해 적당히 유지.

4. max_scan — 부스팅 시 후보 풀(기본 100, 하드 캡 500). 높을수록 재현율이 향상됨; 스캔된 각 페이지는 응답 캐시됩니다.

boost를 사용하면 각 행에 _relevance(점수)와 _matched(적중된 절)가 포함되며, pagination.mode는 "ranked"입니다. boost 없이 단일 캐시된 목록 페이지가 반환됩니다(mode: "fast").

qobrix_search_properties({
  search: 'status == "available" and sale_rent == "for_sale"',
  boost: [
    { field: "sea_view", op: "==", value: true, weight: 3 },
    { field: "bedrooms", op: ">=", value: 3, weight: 2 },
    { field: "list_selling_price_amount", op: "in", value: "200000..600000", weight: 2 },
  ],
  limit: 15,
  max_scan: 200,
});

리드 ↔ 매물 매칭 via 검색 (양방향)

• 수요 → 공급: 리드의 기준을 가져와 search+boost로 qobrix_search_properties / qobrix_search_projects 호출. 네이티브: qobrix_get_properties_by_lead / qobrix_get_lead_properties.

• 공급 → 수요: 매물에 대해 공개 리드 search + boost로 qobrix_search_opportunities 호출(프로젝트에도 작동). 속성 전용 네이티브: qobrix_get_leads_by_property.

// Who wants a Limassol 3-bed ~€400k listing?
qobrix_search_opportunities({
  search: 'status in ["new","open"] and buy_rent == "buy"',
  boost: [
    { field: "area_of_interest", op: "contains", value: "Limassol", weight: 3 },
    { field: "bedrooms_from", op: "<=", value: 3, weight: 2 },
    { field: "list_selling_price_to", op: ">=", value: 400000, weight: 2 },
  ],
  limit: 15,
  max_scan: 200,
});

Boost 연산자: == != < > <= >= in contains starts_with ends_with. 범위는 op: "in"과 value: "min..max"를 사용하세요.

검색(및 기타 모든 목록/가져오기)은 전역 캐시 TTL(QOBRIX_CACHE_TTL, 기본 300초)을 공유합니다. CRM 편집 후 qobrix_cache_clear({ prefix: "v1:request:properties" })(또는 opportunities, projects, …)로 새로 고치세요.

관련 데이터 가져오기

외래 키를 해결하는 세 가지 전략:

1. include[] 매개변수 — 한 번의 호출로 연관 관계를 인라인으로 확장

qobrix_get_property({ id: "...", include: ["Agents", "PropertyViewings"] })

2. 별도 get 호출 — FK 필드에서 UUID를 가져와 적절한 도구 호출

// property.agent → UUID
qobrix_get_agent({ id: "<agent-uuid>" })

3. FK로 검색 — 검색 표현식으로 관련 레코드 찾기

qobrix_search_properties({ search: 'agent == "<agent-uuid>"' })

도구 설명에서 Verified로 표시된 include[] 값만 작동이 보장됩니다. 연관 관계에 include[]를 사용할 수 없으면 FK 검색을 사용하세요.

페이로드 기본값

호출하는 LLM의 컨텍스트 창에 맞게 도구 출력을 짧게 유지하기 위해 목록 / 검색 / 가져오기 도구는 기본적으로 컴팩트 페이로드를 사용합니다:

호출자가 실제로 더 무거운 페이로드가 필요할 때만 호출별로 재정의하세요:

// Cheap browse — recommended for most reporting / pipeline calls
qobrix_list_properties({ limit: 10 });

// Heavy detail — only when the LLM truly needs nested FKs + media URLs
qobrix_list_properties({ limit: 5, expand: true, media: true });

// Prefer surgical include[] over full expand=true:
qobrix_get_property({ id: "...", include: ["AgentAgents", "ProjectProjects"] });

이 변경으로 qobrix_list_properties({ limit: 10 })가 일반적으로 ~300 KB에서 ~5–10 KB로 줄어듭니다.

출력 상한

모든 도구 결과는 렌더링된 JSON의 QOBRIX_MCP_MAX_RESULT_CHARS 문자로 제한됩니다(기본 30 000, 약 7.5 K 토큰). 동작:

• 페이지 매김 페이로드 ({ data: [...], pagination: {...} }): 맞는 data[]의 가장 큰 접두사로 잘리고, _truncated 블록이 kept_rows, omitted_rows, original_chars, max_chars, 그리고 다음 호출 범위를 LLM에 알려주는 hint와 함께 첨부됩니다. 중첩된 expand/media 객체만으로 상한을 초과하면 행이 스칼라로 압축되어(_truncated.compacted: true) 최소한 하나의 사용 가능한 행이 반환됩니다.

• 과도하게 큰 경우 (기본: 원본 크기 > 8 × 상한, QOBRIX_MCP_REFINE_MULTIPLIER로 재정의): status: "result_too_large"와 _refine_required(어시스턴트 지침 + 제안된 축소 + 작은 returned_sample)를 반환하여 LLM이 사용자에게 덤프가 아닌 재구성을 요청하도록 합니다.

• 페이지 매김 없는 페이로드 (단일 get, 사용자 지정 분석 형태): JSON이 상한에서 잘리고 QOBRIX_MCP TRUNCATED 트레일러가 추가됩니다(또는 과도하게 큰 경우 동일한 refine 지시문).

boost를 expand=true 또는 media=true와 함께 사용하면 max_scan이 자동으로 100으로 제한되고 pagination.scan_capped_reason이 "expand/media"일 수 있습니다.

상한 / refine 임계값 재정의:

QOBRIX_MCP_MAX_RESULT_CHARS=60000
QOBRIX_MCP_REFINE_MULTIPLIER=8

상한 또는 refine 가드에 자주 도달하면 fields[](화이트리스트 열), 더 좁은 search 표현식, 더 작은 limit을 사용하거나 expand=false / media=false를 유지하세요.

테스트

이 프로젝트에는 63개의 describe 스위트에 걸친 226개의 자동화 테스트가 포함되어 있습니다(통합, 다단계 시나리오, RESO 워크플로, 캐시, 관련성, 출력 상한, 클라이언트 정렬, OAuth 모드 스모크):

# Integration tests — individual tool mechanics
npm test

# Scenario tests — multi-step tool chains (19 real-world scenarios)
npm run test:scenarios

# Workflow tests — canonical RE business processes (8 RESO-aligned suites)
npm run test:workflows

# Cache tests — read-through, single-flight, LRU eviction, search-page keys (no API needed)
npm run test:cache

# Relevance tests — boost scoring, DSL help, search cache keys (no API needed)
npm run test:relevance

# Format tests — output cap + truncation behaviour (no API needed)
npm run test:format

# OAuth modes smoke — Mode B header rejection + Mode C /connect elicitation path
npm run test:oauth-modes

# Run everything
npm run test:all

아키텍처

src/
├── index.ts          # MCP server entry point + RESO workflow instructions
├── http.ts           # Streamable HTTP transport (Modes B / C)
├── modes.ts          # Auth mode resolution (env / headers / oauth / oauth-claude)
├── client.ts         # QobrixClient — HTTP + read-through response cache
├── auth-context.ts   # AsyncLocalStorage per-request credentials
├── oauth-client.ts   # Mode C self-service OAuth client + session vault
├── oauth-rs.ts       # Companion AS metadata + introspection helpers
├── request-context.ts# ALS for McpServer (elicitation capability detection)
├── cache.ts          # LRU memory tier, optional Redis, single-flight coalescing
├── relevance.ts      # Boost scoring + cached candidate pager for search
├── search-dsl.ts     # Full SearchExpression DSL reference + field cheatsheets
├── types.ts          # TypeScript interfaces
├── schemas.ts        # Zod schemas with rich LLM-facing descriptions
└── tools/
    ├── index.ts      # Tool registration hub + formatResult / errorResult
    ├── properties.ts # Listing Lifecycle + relevance search
    ├── contacts.ts   # Lead-Contact Lifecycle tools
    ├── agents.ts     # RESO Member tools
    ├── opportunities.ts # Sales Pipeline tools
    ├── viewings.ts   # Showing Lifecycle tools
    ├── tasks.ts      # Follow-up & Pipeline Management tools
    ├── media.ts      # Media Lifecycle tools
    ├── projects.ts   # Project/Development + relevance search
    ├── offers.ts     # Transaction Lifecycle tools
    ├── contracts.ts  # Transaction close tools
    ├── activities.ts # Activity Tracking (calls, meetings, emails)
    ├── analytics.ts  # qobrix_count, qobrix_top_values, qobrix_top_records, qobrix_aggregate
    ├── deals.ts      # qobrix_deals (flexible Contracts shortcut)
    ├── reports.ts    # qobrix_timeseries (bucketed metric + YoY), qobrix_days_on_market
    ├── pipeline.ts   # qobrix_funnel, qobrix_stale_leads, qobrix_win_loss
    ├── productivity.ts # qobrix_rep_scorecard
    ├── customers.ts  # qobrix_cohort (repeat buyers/sellers/leads)
    ├── cache.ts      # qobrix_cache_stats, qobrix_cache_clear
    ├── audit.ts      # change log / field history / top changers
    └── meta.ts       # Schema discovery + qobrix_search_dsl_help
test-suite/
├── integration.test.mjs  # Live API smoke tests
├── scenarios.test.mjs    # Multi-step CRM scenarios
├── workflows.test.mjs    # RESO workflow coverage
├── cache.test.mjs        # Cache unit tests (incl. search-page keys)
├── relevance.test.mjs    # Boost scoring + DSL help unit tests
├── format.test.mjs       # Output-cap / truncation tests
└── oauth-modes.test.mjs  # Mode B/C auth smoke tests

LLM이 학습하는 방식

서버는 세 가지 수준에서 LLM을 교육합니다:

1. 서버 지침 — MCP initialize 응답의 최상위 instructions 필드는 전체 데이터 모델, 도구 레시피가 포함된 6가지 표준 워크플로, 검색 구문, FK 해결 전략, 알려진 특이 사항을 제공합니다.

2. 도구 설명 — 각 도구 설명에는 표준 워크플로 역할, RESO 등가물, 검증된 include[] 옵션, FK 필드 매핑, 응답 형태, 검색 예시가 포함됩니다. 관련성 검색 도구는 2계층 search + boost 레시피를 문서화합니다; qobrix_search_dsl_help는 필요 시 전체 DSL을 제공합니다.

3. 매개변수 설명 — Zod 스키마는 구체적인 예시, 유효한 열거형 값, 교차 도구 참조와 함께 매개변수별 도움말을 제공합니다.

기술

라이선스

Apache License 2.0 — Copyright 2025–2026 SharpSir Group

모드 A와 B는 이 오픈소스 패키지에 포함되어 있습니다. 모드 C는 SharpSir의 Enterprise OAuth 인증 서버(SSO / 사용자별 신원)와 연동됩니다 — 요청 시 제공되는 별도의 상용 제품입니다 — sharpsir.group · dev@sharpsir.group.