Qobrix CRM MCP Server

目次

• インストールガイド — Sharp Matrixイントラネット、pm2、Apache、Claude.ai + Dust.ttコネクタ

• ユーザーガイド — モードA → モードB → モードC → モードD（Claude.ai + Dust.tt）のステップバイステップ

• 機能概要

• 対象読者

• 標準的な不動産ワークフロー

• ツール一覧

• クイックスタート

• 設定

• 認証モード

• エンタープライズOAuth

• キャッシュ

• Cursor IDEのセットアップ

• その他のMCPホスト

• 検索式の構文

• 関連データの取得

• テスト

• アーキテクチャ

• LLMがどのように学習するか

• テクノロジー

• ライセンス

機能概要

このサーバーに接続されたAIアシスタントは、自然言語だけで、物件の閲覧、リードの評価、内見の追跡、オファーと契約の確認、フォローアップ活動の監査、CRMフィールドスキーマの発見を行うことができます。各ツールの説明は、LLMに対して、それがどの標準的な不動産ワークフローに属するか、どのRESOリソースにマッピングされるか、次にどのツールを連鎖させるかを教えます。

対象読者

• 不動産仲介会社と開発者 — Qobrixを利用しており、Claude.ai、Dust.tt、ChatGPT、Cursorに、ライブCRMデータに基づいた質問への回答をさせたい方（コピー＆ペーストしたエクスポートではなく）。

• エンジニア — 内部ツールにMCPを組み込む方：stdioトランスポート、型付きZod入力、書き込み面なし — プロンプトやエージェントで安全に実験できます。

• データ＆オペレーションチーム — ダッシュボードを運用する方：カスタムスクリプトなしでYoYスタイルのメトリクスに**qobrix_count** / **qobrix_top_values**を使用し、レスポンスキャッシュで繰り返しクエリのAPI負荷を削減します。

• エンタープライズIT — エージェントごとのアイデンティティに対応：このパッケージからモードA/Bを実行し、すべてのユーザーが自分自身として認証する必要がある場合は、モードCをSharpSirのEnterprise OAuth（SSO）製品と組み合わせてください — Enterprise OAuthを参照。

標準的な不動産ワークフロー

このサーバーは、RESOに準拠した6つのビジネスプロセスを中心に構成されています。LLMはこれらを組み込みの指示として受け取るため、事前のトレーニングなしでCRMを操作できます。

ステータスマッピング

ツール一覧

64ツール — CRMエンティティ、スキーマ探索、分析（qobrix_count、qobrix_top_values、qobrix_top_records、qobrix_aggregate）、柔軟なdealsショートカット（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_changers）、キャッシュヘルパー（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"。データセット全体のスキャンが必要な場合、またはサーバーソートで null 許容フィールド（例: 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

認証モード

このパッケージをクローンし、Mode A または B を実行して、実際の Qobrix データを Claude、Cursor、または任意の MCP クライアントで利用できるようにします — Apache 2.0。

Mode A と B はこのパッケージだけで完全にサポートされます。Mode C と D には SharpSir の別製品である Enterprise OAuth / SSO 製品が必要です — このリポジトリには含まれません。Mode D は Mode A/B/C を変更しません — Claude.ai や Dust.tt などのリモートホストに OAuth を自身で駆動させたい場合に選択してください。

エンタープライズ OAuth

エージェントを共有 API キーではなく、サインイン済みの Qobrix ユーザーとして動作させる必要がありますか? Mode C はそのために設計されています。これには SharpSir の Enterprise OAuth ソリューション が必要です: ホスト型認可サーバーバンドル（ログイン + 2FA + 同意、ユーザーごとの API キー発行、暗号化された認証情報ボールト、オーディエンスバインドトークン）で、この MCP サーバーと排他的に連携します。

Mode C の仕組み（MCP 自己認証 — ノースバウンドのクライアントは変更なし）:

1. セッションがない状態でツールが実行されると、MCP は認証 URL のいずれかを返します:

   • URL-mode elicitation (JSON-RPC -32042) — クライアントが elicitation.url をサポートしている場合 (Claude、Cursor など)

   • elicitation をサポートしていないクライアント (例: ragchat / LangChain) 向けのツール結果内の Markdown リンク [Sign In to Qobrix](/connect?e=…) — LLM はそのリンクを原文のまま伝える必要があります (一意 / 単回使用。古いリンクは再利用しないこと)

2. ユーザーはこのサーバー上の /connect を開きます (フィッシング防止の間接化) → 署名付き Cookie がセットされ、Enterprise OAuth ログインページへリダイレクトされます

3. ログイン + 2FA + 同意の後、AS は /oauth/callback へリダイレクトします。この MCP がコード交換 (PKCE) を行い、Qobrix の資格情報を introspection して、暗号化されたセッションボルトに保存します

4. 次のツール呼び出しは認証済みで実行されます。Qobrix が 401 / 403 を返した場合、ボルトはクリアされ、新しい /connect URL が返ります

5. エージェントは qobrix_sign_in、qobrix_whoami、qobrix_sign_out を呼び出すこともできます (AS の /disconnect による完全な取り消し + Qobrix API キーの削除)

• 公開ダウンロードとしては利用できず、GitHub からクローンできるものではありません。

• 当チームが ご要望に応じてエンタープライズソリューションバンドルとして納品・設定します。

• サードパーティの OAuth サーバーはありません。Mode C はこの Enterprise OAuth ソリューションのみにハードワイヤードされています。

• セキュリティ: Mode C はユーザーごとの暗号化セッションボルト (チャット ID ヘッダーをキーとする) を使用し、/mcp をクライアント Bearer なしのままにします。QOBRIX_MCP_HOST=127.0.0.1 にバインドし、QOBRIX_MCP_IDENTITY_SECRET (信頼された MCP ホスト (例: ragchat) とのみ共有) を設定して、ID ヘッダーが偽造されないようにします。ボルトの暗号化は QOBRIX_MCP_STATE_SECRET (MCP 専用) に維持します。ブラウザ向けにリバースプロキシする場合は、/connect と /oauth/callback のみを公開し、/mcp と /health は公開しないでください。ローカルエージェント (ragchat) は http://127.0.0.1:<port>/mcp を呼び出します。ALLOWED_HOSTS にパブリックホスト名のみを指定している場合、サーバーがループバックにバインドしていれば、ループバック Host 値 (127.0.0.1 / localhost / ::1) が自動的に追加されます。接続 Cookie の Path は PUBLIC_URL のパス名に従います。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=… — 認可を開始 (Cookie を設定し、AS へ 302)

• GET /oauth/callback — PKCE コード交換 + ユーザーごとのセッションボルト書き込み

• GET /health — connected と session_vaults の数を含む

• 認証なしの /mcp は northbound クライアントにとって意図的なものです。必要に応じてツールが接続 URL を表示します。本番環境では /mcp を localhost に維持してください

Mode A → B → C のステップバイステップ、リバースプロキシのロックダウン、Host のメンドネス一覧の詳細は docs/USER_GUIDE.md を参照してください。

ragchat / Mode C の場合、リモート MCP URL (…/mcp) を通常の Streamable HTTP サーバーとして登録します (クライアント側の OAuth プロバイダーは不要)。MCP は /connect を介して認証を処理します。そのトポロジでは /mcp を localhost に維持してください。

Mode D — Claude.ai と Dust.tt のリモート MCP (共有リソース)

別の MCP プロセス (またはホスト) を QOBRIX_MCP_AUTH=oauth-claude で使用します。リモートホストは、同じ HTTPS /mcp URL に対して OAuth を自身で行います。

1. ユーザーは https://intranet.sharpsir.group/qobrix-crm/mcp を Claude または Dust に貼り付けます

2. Host が /mcp にアクセス → 401 と WWW-Authenticate: Bearer resource_metadata=… を受け取ります

3. Host が /.well-known/oauth-protected-resource を取得 → QOBRIX_OAUTH_ISSUER を検出します

4. Host は Enterprise OAuth AS に対して OAuth (DCR または Static) + PKCE を完了します

5. 以降の /mcp 呼び出しは Authorization: Bearer <access_token> を送信します。このサーバーは introspection し、その Qobrix ユーザーとしてツールを実行します

Claude と Dust は1 つの 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 の正確な finalize 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 のエグレス 160.104.0.0/21 を許可リストに追加し、さらに Dust のエグレスも許可します。Claude の許可リストは削除しないでください。Mode C のループバック / 「/mcp を公開しない」という手順は ragchat デプロイ向けに有効です。Mode C プロセスでは、そのトポロジを反転させないでください。

完全な手順は、INSTALL — Connect Claude · 参照。Dust の MCP サーバー追加。

キャッシング

すべての MCP ツールは読み取り専用の GET なので、レスポンスキャッシュが CRM 状態を壊すことはありません。サーバーは1 つのチョークポイント (QobrixClient.request()) を cache-aside (read-through) でラップするため、すべての list/get/search/schema 呼び出し — 関連度 max_scan の各ページを含む — がキャッシュされます。Boost スコアリングは取得後に行われるため、キャッシュキーは変更されません。異なる boost[] で再ランキングしても、同じ候補ページが再利用されます。

設計 — cache-aside と single-flight 合流:

• Tier 1 — インメモリ LRU (常時有効、依存性ゼロ): プロセスごと、TTL 付き、サイズ上限付き。

• Tier 2 — Redis (オプション、動的 import() による遅延ロード): 使用するには QOBRIX_REDIS_URL を設定します。Redis エラー発生時、サーバーはメモリのみにフォールバックします。

• Single-flight: 同じコールドキーに並列ツール呼び出しが衝突する場合 (よく出る qobrix_top_values で)、プロセス内の全呼び出し元が 1 つのアップストリームリクエストを共有します。

• エラーは決してキャッシュされません — 一時的な 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 (数時間) を推奨しています。リードパイプライン (分単位で変化) と物件情報 (時間単位で変化) とを混在するCRM の場合、300 秒が保守的な既定値です。即時更新が必要な場合は qobrix_clear_cache を使用しますとのような場合は、qobrix_cache_clear をお使いください。

トレードオフ / 既知の制限: single-flight 合流はプロセス内のみです。共有 Redis の背後で複数インスタンスを実行すると、ルードキーでスタンプコピーが発生する可能性が残ります。分散された SETNX ロックは将来課題ですが、シングルユーザーの MCP クライアントには不要です。

ベストプラクティスの対応:

Cursor IDE のセットアップ

このサーバーは **stdio (ローカルな node プラセス) で動作します。Cursor は プロジェクトまたはユーザーの mcp.json からサーバーを検出します: 開いたフォルダー内の .cursor/mcp.json、または 全ワークスペース用の ~/.cnode/mcp.json。

1. 前提条件

• Cursor が MCP を実行するマシン (ローカルまたはリモート SSH ホスト) 上の Node.js 20+。

• このリポジトリをクローンし、インストールしてビルドする ( Quick Start を参照)。

• MCP エントリを追加する前に、dist/index.js が存在する必要があります (npm run build)。

2. 認証情報

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+)

絶対パス を渡します。そうすれば、ワークスペースがこのリポジトリ自体であれ親フォルダーであめ差がある場合 SSH リモートパスが正しく解決される場合と同じように動作します 。

{
  "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. replace済み例: env をインラインで

--env-file を使用できない場合 (properties 大域)ににお勧めけします。シークレットは 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 の設定補間（例: ${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を再読み込み — コマンドパレット→ MCP再起動、またはCursorウィンドウをリロードします。

2. ログを確認 — 表示→ 出力→ ドロップダウンで**「MCP」/「MCPログ」**を選択し、パスやNodeのエラーを修正します。

3. ツールの承認 — デフォルトではCursorは各ツール呼び出しのたびに確認を求めます。信頼できるツールについては、Cursorの設定で自動実行を許可できます。

その他のMCPホスト

Claude.ai / Claude Desktop（モードD） — https://intranet.sharpsir.group/qobrix-crm/mcp にあるリモートカスタムコネクタ。 モードD と INSTALL — Connect Claude を参照してください。

Dust.tt（モードD） — Spaces → Tools → Add MCP Server で、同じURLを指定します。自動認証と個人アカウントを推奨します。INSTALL — Connect Dust を参照してください。

Claude Desktop / Cursor（モード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,
});

リード↔リスティングのマッチング（双方向）

• 需要→供給: リードの条件を取得→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,
});

ブースト演算子: == != < > <= >= 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、…）で更新してください。

関連データの取得

外部キーを解決する3つの戦略:

1. include[]パラメータ — 1回の呼び出しで関連をインライン展開

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

2. 個別の取得呼び出し — FKフィールドからUUIDを取得し、適切なツールを呼び出します

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

3. FKによる検索 — 検索式で関連レコードを検索

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

ツールの説明で検証済みとマークされた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 }) は通常、約300KBから約5〜10KBに縮小します。

出力上限

すべてのツール結果は、レンダリングされたJSONのQOBRIX_MCP_MAX_RESULT_CHARS文字（デフォルト30000、およそ7.5Kトークン）に制限されます。動作:

• ページネーションペイロード（{ data: [...], pagination: {...} }）: 収まるdata[]の最大プレフィックスに切り詰められ、_truncatedブロックにkept_rows、omitted_rows、original_chars、max_chars、および次回の呼び出しをスコープする方法をLLMに伝えるhintが添付されます。ネストされたexpand/mediaオブジェクトだけで上限を超える場合は、少なくとも1つの使用可能な行が返されるように、行はスカラーに圧縮されます（_truncated.compacted: true）。

• 過大サイズ（デフォルト: 元のサイズが上限の8倍超、QOBRIX_MCP_REFINE_MULTIPLIERで上書き可能）: status: "result_too_large" と_refine_required（アシスタントへの指示+推奨する絞り込み+小さなreturned_sample）を返し、LLMがユーザーにダンプではなく再定式化を依頼するようにします。

• 非ページネーションペイロード（単一のget、カスタム分析シェイプ）: JSONは上限でクリップされ、QOBRIX_MCP TRUNCATEDトレーラーが追加されます（過大サイズの場合は同じ絞り込みディレクティブ）。

boostをexpand=trueまたはmedia=trueと一緒に使用すると、max_scanは自動的に100に上限設定され、pagination.scan_capped_reasonは"expand/media"になる場合があります。

上限/絞り込みしきい値を上書き:

QOBRIX_MCP_MAX_RESULT_CHARS=60000
QOBRIX_MCP_REFINE_MULTIPLIER=8

上限または絞り込みガードに頻繁に達する場合は、fields[]（列のホワイトリスト）、より厳しいsearch式、より小さいlimitを使用するか、expand=false / media=false のままにしてください。

テスト

このプロジェクトには、63のdescribeスイート（統合、複数ステップシナリオ、RESOワークフロー、キャッシュ、関連性、出力上限、クライアントソート、OAuthモードスモーク）にわたる226の自動テストが含まれています:

# 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の学習方法

サーバーは3つのレベルで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 / ユーザーごとの ID）と連携します — これはリクエストに応じて提供される別の商用製品です — sharpsir.group ・ dev@sharpsir.group。