Qobrix CRM MCP Server

Table of contents

• User Guide — Mode A → Mode B → Mode C step-by-step

• What it does

• Who it is for

• Canonical real-estate workflows

• Tools at a glance

• Quick start

• Configuration

• Auth modes

• Enterprise OAuth

• Caching

• Cursor IDE setup

• Other MCP hosts

• Search expression syntax

• Fetching related data

• Testing

• Architecture

• How the LLM learns

• Technology

• License

What It Does

An AI assistant connected to this server can browse properties, qualify leads, track showings, review offers and contracts, audit follow-up activity, and discover CRM field schemas — all through natural language. Every tool description teaches the LLM which canonical real-estate workflow it belongs to, which RESO resource it maps to, and which tools to chain next.

Who it is for

• Brokerages & developers using Qobrix who want ChatGPT, Claude, or Cursor to answer questions grounded in live CRM data (not copy-pasted exports).

• Engineers wiring MCP into internal tools: stdio transport, typed Zod inputs, and no write surface — safe to experiment with prompts and agents.

• Data & operations teams running dashboards: use qobrix_count / qobrix_top_values for YoY-style metrics without custom scripts, and response caching to cut API load on repeat queries.

• Enterprise IT ready for per-agent identity: run Modes A/B from this package, then pair Mode C with SharpSir’s Enterprise OAuth (SSO) product when every user must authenticate as themselves — see Enterprise OAuth.

Canonical RE Workflows

The server is organized around six RESO-aligned business processes. The LLM receives these as built-in instructions so it can navigate the CRM without prior training.

Status Mappings

Tools at a Glance

64 tools — CRM entities, schema discovery, analytics (qobrix_count, qobrix_top_values, qobrix_top_records, qobrix_aggregate), a flexible deals shortcut (qobrix_deals), reporting (qobrix_timeseries, qobrix_funnel, qobrix_rep_scorecard, qobrix_stale_leads, qobrix_win_loss, qobrix_days_on_market), customer intelligence (qobrix_cohort), audit / change history (qobrix_get_changes, qobrix_search_changes, qobrix_field_change_history, qobrix_top_field_changers), cache helpers (qobrix_cache_stats, qobrix_cache_clear), and session & identity (qobrix_sign_in, qobrix_sign_out, qobrix_whoami):

Every tool description includes its canonical workflow role, RESO equivalent, verified include[] options, FK resolution guidance, and search expression examples.

Analytics & Deals usage examples

Server-side sort (OpenAPI sort[]) works for most fields — e.g. sort: "-list_selling_price_amount" on properties. Use qobrix_top_records / qobrix_aggregate when you need a full-dataset scan, or when a nullable field (e.g. opportunities.budget) returns no rows under server sort. "Closed deals" don't live as a property flag — they're rows in the Contracts table. The analytics/deals tools remove the need for client-side scripting:

// 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 }
}

Quick Start

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

Configuration

Create a .env file in the project root:

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

Auth modes

Clone this package, run Mode A or B, and put live Qobrix data in front of Claude, Cursor, or any MCP client — Apache 2.0.

Modes A and B are fully supported out of this package. Mode C is for per-user authenticated CRM access (no northbound client OAuth wiring) and requires SharpSir’s separate Enterprise OAuth / SSO product — not distributed as part of this repo.

Enterprise OAuth

Need the agent to work as a signed-in Qobrix user — not a shared API key? Mode C is designed for that. It requires SharpSir’s Enterprise OAuth solution: a hosted Authorization Server bundle (login + 2FA + consent, per-user API-key minting, encrypted credential vault, audience-bound tokens) that pairs exclusively with this MCP server.

How Mode C works (MCP self-auth — northbound clients unchanged):

1. A tool runs with no session → the MCP returns an authorization URL:

   • URL-mode elicitation (JSON-RPC -32042) when the client supports elicitation.url (Claude, Cursor, etc.)

   • A Markdown [Sign In to Qobrix](/connect?e=…) link in the tool result for clients without elicitation (e.g. ragchat / LangChain) — the LLM must relay it verbatim (unique / single-use; never reuse an older link)

2. The user opens /connect on this server (anti-phishing indirection) → signed cookie + redirect to the Enterprise OAuth login page

3. After login + 2FA + consent, the AS redirects to /oauth/callback; this MCP exchanges the code (PKCE), introspects for Qobrix credentials, and stores them in an encrypted session vault

4. The next tool call runs authenticated. On Qobrix 401/403, the vault is cleared and a fresh /connect URL is returned

5. Agents can also call qobrix_sign_in, qobrix_whoami, and qobrix_sign_out (full revoke via AS /disconnect + Qobrix API-key delete)

• Not available as a public download and not something you can clone from GitHub.

• Delivered and configured by our team upon request as an enterprise solution bundle.

• No third-party OAuth servers — Mode C is hard-wired to this Enterprise OAuth solution only.

• Security: Mode C uses per-user encrypted session vaults (keyed by chat identity headers) and leaves /mcp without a client bearer. Bind QOBRIX_MCP_HOST=127.0.0.1 and set QOBRIX_MCP_IDENTITY_SECRET (shared only with the trusted MCP host like ragchat) so identity headers cannot be forged. Keep vault encryption on QOBRIX_MCP_STATE_SECRET (MCP-only). If you reverse-proxy for browsers, publish only /connect and /oauth/callback — deny public /mcp and /health. Local agents (ragchat) call http://127.0.0.1:<port>/mcp. When ALLOWED_HOSTS lists only the public hostname, loopback Host values (127.0.0.1 / localhost / ::1) are auto-added if the server binds to loopback. Connect cookie Path follows PUBLIC_URL pathname; Express trust proxy is 2 behind Cloudflare→Apache. Deliver /connect links only to the individual user — never into a shared/group thread.

Ready to upgrade? Contact SharpSir Group · dev@sharpsir.group and ask for the Qobrix CRM MCP Enterprise OAuth bundle.

Once delivered, you point this server at the issuer you receive:

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 endpoints (after the Enterprise OAuth solution is paired):

• GET /connect?e=… — start authorization (sets cookie, 302 to AS)

• GET /oauth/callback — PKCE code exchange + per-user session vault write

• GET /health — includes connected and session_vaults count

• Unauthenticated /mcp is intentional for northbound clients: tools surface the connect URL when needed — keep /mcp on localhost in production

See docs/USER_GUIDE.md for Mode A → B → C step-by-step, reverse-proxy lockdown, and Host allowlist details.

Register the remote MCP URL (…/mcp) in Claude / Cursor / ChatGPT / ragchat as a normal Streamable HTTP server (no client-side OAuth provider required). The MCP handles auth itself.

Caching

All MCP tools are read-only GETs, so a response cache cannot corrupt CRM state. The server wraps one chokepoint (QobrixClient.request()) with a read-through cache, so every list/get/search/schema call — including each page of a relevance max_scan — is cached. Boost scoring is post-fetch and does not change the cache key, so re-ranking with different boost[] reuses the same candidate pages.

Design — cache-aside with single-flight coalescing:

• Tier 1 — in-memory LRU (always on, zero deps): per-process, TTL'd, size-capped.

• Tier 2 — Redis (optional, lazy-loaded via dynamic import()): set QOBRIX_REDIS_URL to enable; the server falls back to memory-only on any Redis error.

• Single-flight: when the LLM fires parallel tool calls that hit the same cold cache key (common with qobrix_top_values), all in-process callers share one upstream fetch.

• Errors are never cached — a transient 5xx will not get stuck.

• TTL only, no stale-while-revalidate in v1.

Environment variables:

Cache tools (exposed to the LLM):

Recommended Redis server config (for a dedicated cache-only Redis, per Redis docs):

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

TTL guidance — Redis docs recommend short TTLs for frequently-changing data (60–120s) and longer for stable data (hours). 300s is a conservative default for a CRM that mixes lead pipeline (changes minutely) with property listings (changes hourly). Use qobrix_cache_clear when you need an instant refresh.

Trade-off / known limit: Single-flight coalescing is in-process only. Multi-instance deployments behind one shared Redis can still see modest stampede on cold keys; a distributed SETNX lock is future work and not needed for single-user MCP clients.

Best-practices alignment:

Cursor IDE setup

This server uses stdio MCP (a local node process). Cursor discovers servers from project or user mcp.json: .cursor/mcp.json inside the folder you opened, or ~/.cursor/mcp.json for all workspaces.

1. Prerequisites

• Node.js 20+ on the machine where Cursor runs the MCP (local laptop or remote SSH host).

• Clone this repo, install, and build (see Quick Start).

• dist/index.js must exist (npm run build) before adding the MCP entry.

2. Credentials

1. Copy the template: cp .env.example .env

2. Edit .env and set at least QOBRIX_API_URL, QOBRIX_API_USER, and QOBRIX_API_KEY (see Configuration).

3. Keep .env out of git; it is listed in .gitignore.

3. Where to put the JSON

Merge your entry into the existing "mcpServers" object; do not replace the whole file if you already have other servers.

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

Pass absolute paths so it works the same whether the workspace root is this repo or a parent folder (and so SSH remote paths resolve correctly).

{
  "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"
    }
  }
}

Why this pattern:

• Credentials stay in .env, not in JSON.

• Node loads the file before your server starts, so process.env is populated even when the host’s envFile field is ignored or behaves inconsistently for stdio servers.

5. Alternative: inline env

Useful if you cannot use --env-file (older Node). Secrets live in mcp.json — restrict file permissions and do not commit them.

{
  "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"
      }
    }
  }
}

You can also use Cursor’s config interpolation (for example ${env:QOBRIX_API_KEY}) so values are injected from your OS environment instead of literals.

6. Optional: envFile in MCP JSON

Cursor supports an envFile property for stdio servers. Some setups do not pass those variables into the child process reliably; if tools fail with “Missing required environment variables”, switch to --env-file as in step 4.

7. After editing mcp.json or .env

1. Reload MCP — Command Palette → MCP restart, or reload the Cursor window.

2. Check logs — View → Output → pick “MCP” / “MCP Logs” in the dropdown; fix path or Node errors there.

3. Tool approval — By default Cursor asks before each tool call; you can allow auto-run for trusted tools in Cursor settings if you prefer.

Other MCP hosts

Claude Desktop — same stdio shape: command + args to node and either --env-file or env in the host’s MCP config file.

CI / headless — run node --env-file=.env dist/index.js with a stdio MCP client library; ensure .env is supplied via secrets, not committed.

Search Expression Syntax

Tools that accept a search parameter use Qobrix's Symfony Expression Language (OpenAPI SearchExpression). Call qobrix_search_dsl_help for the full grammar + property/project field cheatsheets (optionally with live schema field names).

Tip: Call qobrix_search_dsl_help({ resource: "Properties" }) before composing free-language demand into a query. Use qobrix_get_field_options for enum values and qobrix_get_schema for the full field list.

Relevant search on all resources (F1)

Every qobrix_search_* tool (properties, projects, contacts, agents, opportunities, viewings, tasks, offers, contracts) uses a two-tier design so free-language demand maps to high precision and high recall:

1. search — hard must-haves (server-side DSL filter → precision floor).

2. boost[] — soft weighted nice-to-haves scored in-process over a candidate pool (recall + ranking).

3. limit — how many ranked rows to return (default 10, max 100). Raise for more options; keep modest to avoid context overload.

4. max_scan — candidate pool when boosting (default 100, hard cap 500). Higher improves recall; each scanned page is response-cached.

With boost, each row includes _relevance (score) and _matched (which clauses hit); pagination.mode is "ranked". Without boost, a single cached list page is returned (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,
});

Lead ↔ listing matching via search (2-way)

• Demand → supply: take a lead's criteria → qobrix_search_properties / qobrix_search_projects with search+boost. Native: qobrix_get_properties_by_lead / qobrix_get_lead_properties.

• Supply → demand: qobrix_search_opportunities with open-lead search + boost against the listing (works for projects too). Native for properties only: 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 operators: == != < > <= >= in contains starts_with ends_with. For ranges use op: "in" with value: "min..max".

Search (and every other list/get) shares the global cache TTL (QOBRIX_CACHE_TTL, default 300s). After CRM edits, refresh with qobrix_cache_clear({ prefix: "v1:request:properties" }) (or opportunities, projects, …).

Fetching Related Data

Three strategies to resolve foreign keys:

1. include[] parameter — expand associations inline in one call

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

2. Separate get call — take the UUID from an FK field and call the appropriate tool

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

3. Search by FK — find related records via search expression

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

Only include[] values marked Verified in tool descriptions are guaranteed to work. When include[] is unavailable for an association, use search-by-FK.

Payload defaults

To keep tool outputs short enough for the calling LLM's context window, list / search / get tools default to compact payloads:

Override per call only when the caller actually needs the heavier payload:

// 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"] });

This change typically shrinks qobrix_list_properties({ limit: 10 }) from ~300 KB to ~5–10 KB.

Output cap

Every tool result is capped at QOBRIX_MCP_MAX_RESULT_CHARS characters of rendered JSON (default 30 000, roughly 7.5 K tokens). Behaviour:

• Paginated payloads ({ data: [...], pagination: {...} }): truncated to the largest prefix of data[] that fits, and a _truncated block is attached with kept_rows, omitted_rows, original_chars, max_chars, and a hint telling the LLM how to scope the next call. If nested expand/media objects alone blow the cap, rows are compacted to scalars (_truncated.compacted: true) so at least one usable row is returned.

• Grossly oversized (default: original size > 8 × the cap, override QOBRIX_MCP_REFINE_MULTIPLIER): returns status: "result_too_large" with _refine_required (assistant instruction + suggested narrowing + small returned_sample) so the LLM asks the user to reformulate — not dump.

• Non-paginated payloads (single get, custom analytic shapes): the JSON is clipped at the cap and a QOBRIX_MCP TRUNCATED trailer is appended (or the same refine directive when grossly oversized).

When boost is used with expand=true or media=true, max_scan is auto-capped at 100 and pagination.scan_capped_reason may be "expand/media".

Override the cap / refine threshold:

QOBRIX_MCP_MAX_RESULT_CHARS=60000
QOBRIX_MCP_REFINE_MULTIPLIER=8

If you regularly hit the cap or refine guard, use fields[] (whitelist columns), a tighter search expression, a smaller limit, or keep expand=false / media=false.

Testing

The project includes 226 automated tests across 63 describe suites (integration, multi-step scenarios, RESO workflows, cache, relevance, output-cap, client-sort, and OAuth mode smoke):

# 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

Architecture

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)
├── 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

How the LLM Learns

The server teaches the LLM at three levels:

1. Server instructions — top-level instructions field in the MCP initialize response provides the full data model, six canonical workflows with tool recipes, search syntax, FK resolution strategies, and known quirks.

2. Tool descriptions — each tool description includes its canonical workflow role, RESO equivalent, verified include[] options, FK field mappings, response shape, and search examples. Relevance search tools document the two-tier search + boost recipe; qobrix_search_dsl_help exposes the full DSL on demand.

3. Parameter descriptions — Zod schemas provide per-parameter help with concrete examples, valid enum values, and cross-tool references.

Technology

License

Apache License 2.0 — Copyright 2025–2026 SharpSir Group

Modes A and B are included in this open-source package. Mode C pairs with SharpSir’s Enterprise OAuth Authorization Server (SSO / per-user identity) — a separate commercial product delivered upon request — sharpsir.group · dev@sharpsir.group.