mcp-server

# Siftable MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes Siftable tools to IDE clients like Cursor, Claude Desktop, and VS Code.

## ExecuFunction 0.4.0.0 hosted compatibility

The npm package is `1.3.0`; the hosted and source projection profile is
`1.34.0`. Projection 1.34.0 standardizes bounded collection receipts, publishes
dataset aggregate semantics, and distinguishes OAuth connections that must
reconnect from sessions that can widen authorization in place. Projection
1.33.0 recognizes natural-language source-search intent
and returns the retired capability card with local recovery rather than routing
the request to curated code memories. Projection 1.32.0 added an explicit `no_matches` discovery outcome,
rejects generic-operation and weak-prefix-only capability matches, preserves
canonical compound-intent matches, and captures HTTP status classes in failure
receipts. Projection 1.31.0 added governed lead-discovery scope requirements.
Projection 1.29.0 added managed
work-lease sessions for hosted clients while keeping claim tokens server-side.
Projection 1.28.0 added four governed
lead-discovery tools and five app-equivalent person/organization enrichment tools.

Lead discovery is disabled by default. When enabled, it requires separately
granted `lead_discovery:read` or `lead_discovery:write` scopes; `mcp:*` does
not imply either scope. Hosted baseline catalogs therefore omit company search
until `request_capability` approval and a catalog refresh expose the hosted-capable
tool. A company search is bounded to one paid Crustdata
request, shows a maximum charge before dispatch, settles the actual provider
credits, and saves results only as review candidates. Canonical CRM records
are created through `lead_discovery_import_plan_create` followed by the
existing `crm_import_plan_approve` and `crm_import_plan_apply` review gates.

Person enrichment returns stored profile and fact proposals. Apply accepts
only proposal field names and fact IDs rehydrated from the completed run; it
does not accept free-form replacements and is not retry-safe. Organization
enrichment remains the app's paid preview-only flow and cannot apply canonical
CRM changes.

## 1.3.0 compatibility note

Version 1.3.0 publishes `sift.dataset.query.v2`, versioned aggregate receipts,
uniform work-item collection metadata, and the `reconnect_required` capability
state. Consumers that validate the previous dataset-query receipt should select
behavior by `schemaId`.

## 1.2.42 compatibility note

Version 1.2.42 closes the publication-readiness audit. Natural-language source
search discovery returns the canonical retired/local-only recovery card, while
curated code-memory discovery remains distinct. The hosted setup guide now gives
exact ChatGPT and Codex configuration steps.

## 1.2.41 compatibility note

Version 1.2.41 closes two hosted audit failures. Dataset routes reject malformed
dataset UUIDs at the HTTP boundary, and MCP receipts preserve the resulting 400
as `bad_request`. `find_capability` now requires a direct domain signal plus an
aligned operation; unrelated intent returns `queryOutcome: no_matches` with
empty capability lanes and rephrase guidance. Exact tool names, removed-tool
cards, and virtual orientation tools bypass semantic rejection.

## 1.2.40 compatibility note

Version 1.2.40 addresses the third round of live agent QA (the 2026-08-22
hosted audit).

- `claimability` is honest about lifecycle and lease state, not only
  dependencies: `state` is one of `ready`, `waiting`, `dependency_failed`,
  `leased`, `lease_expired`, `blocked`, `in_review`, `human_review_gate`, or
  `terminal`, with `claimable`, `reason`, and `nextAction` alongside
  `blockedBy`. Claimed, running, cancelled, and done work no longer advertise
  `ready`; `claimable` is the authoritative boolean (a `lease_expired` item
  and a legacy-converted `blocked` placeholder whose predecessors are
  satisfied are `claimable: true` because an explicit claim recovers them).
  Claiming a non-claimable item by ID returns a 409 that names the state
  (`lease_active`, `work_item_terminal`, …) instead of `not_found`. The CLI
  and TUI gate on `claimable` when the server provides it.
- `agent_work_list` and `work_item_list` hide done/failed/cancelled items by
  default (`includeTerminal: true` or an explicit `status` shows them), print
  their ordering rule, and document that higher `queueRank` sorts earlier,
  `0` is the default, and negative ranks are deferred (they sort after 0).
- `work_item_heartbeat` says that a heartbeat on claimed work starts it
  (claimed → running, same as `work_item_start`); `resultSummary` passed to
  start, heartbeat, or release is now persisted instead of silently dropped.
- `task_get` lists the executable work joined to the task (first ten, with a
  marker when more exist; "none yet" with the `work_item_create` hint when
  empty) when the connection can read work items; a missing scope keeps the
  capability hint and an upstream failure is reported as such (single
  attempt, no retry).
- `entity_graph` reports each record's own status where it has one (a
  completed task is `completed`, not `active`; notes/datasets active/archived;
  connected projects now carry their name and status instead of
  `[untitled entity]`/`active`) — migration V400 fixes the SQL function that
  labelled every non-note node `active` and never joined projects. Other node
  types keep their type-specific label in that slot (organization industry,
  person relationship, news published date).
- `note_search` ranks full-text matches (websearch syntax) ahead of semantic
  neighbours, then literal-substring fallbacks, instead of sorting raw scores on
  different scales; scores are comparable within a source, not across.
- `object_find` distinguishes an unknown object type key from a known type
  with zero records.
- Code-memory listings label a `confirmed` fact without chunk evidence as
  `not_recorded (confirmed; no source-chunk evidence recorded)` so the
  evidence gap is visible without downgrading human-admitted facts.

Projection 1.25.0 keeps hosted OAuth catalogs limited to tools callable with
the current token. `find_capability` still discovers tools that need scope
elevation, and those tools appear after authorization and a catalog refresh.
The server initialization guidance is also shorter so clients do not repeat a
large instruction block across tool descriptions.

## 1.2.39 compatibility note

Version 1.2.39 addresses the second round of live agent QA.

- `work_item_requeue` also returns a claimed/running item whose lease has
  expired to the queue, without the original claim token; active leases are
  still never requeued. `work_item_list` labels expired leases inline
  (`[claimed · lease expired <time>]`), and `work_item_get` prefixes its JSON
  with a `Lease: expired <time> — …` header saying the item is claimable
  as-is or requeueable, instead of showing plain `claimed`.
- `work_item_revision_history` / `work_item_verification_history` say so in a
  sentence when there is nothing recorded instead of printing `[]`.
- `object_find` names the object type it searched and points at
  `schema_introspect` / `people_search` / `organization_search` when nothing
  matches, instead of a bare "No objects found."
- `schema_introspect` summarises datasets (title, ID, rows, field count) by
  default; `includeDatasetFields: true` restores the per-field dump.
- `dataset_quality_check` counts blank strings as missing values and returns a
  versioned structured result. Frequently repeated values are observations;
  they are only quality violations when a field is declared unique.

Projection 1.22.0 records the `schema_introspect` input schema and the tool
description changes.

## 1.2.38 compatibility note

Version 1.2.38 makes the agent path to work authority direct instead of a
scavenger hunt (decision 2026-08-20, after live use from Grok and Claude).

- Hosted OAuth first connect (no `scope` parameter, or `scopes_supported`
  copied by the client) is issued `mcp:* work:read work:write` behind the
  consent screen. Vault and AI scopes remain step-up/CLI-only.
- Tools the connection could acquire through step-up are presented on
  `tools/list`; calling one before approval returns an in-band tool error
  carrying the same `elevation` link (or CLI/PAT guidance). The HTTP 403
  `insufficient_scope` challenge is now issued only for `request_capability`
  in `challenge` mode.
- Elevation links live for one hour (was ten minutes); after an approval the
  server publishes `tools/list_changed` so subscribed clients refresh, and the
  guidance tells the agent to refresh the tool list or restart the connector
  if the tools are still hidden.
- `find_capability`, `request_capability`, and `context_current` render a
  compact text summary (name, availability, next step) instead of the full
  JSON; the complete projections remain in `structuredContent`.
- `task_get` and the task tool descriptions no longer claim `work:read` is
  missing; they point at `work_item_list` with `taskId` and defer to
  `request_capability` only when the tool is not callable.
- "Stable handles" in generic list text now name the field each ID came from
  and group repeats, so a `projectId` shared by twenty rows reads as one
  project reference rather than twenty new records.

Projection 1.21.0 records the presented-tool and description changes.
Reconnect hosted MCP clients after upgrade to refresh the projection 1.21.0
schemas.

## 1.2.37 compatibility note

Version 1.2.37 makes scope step-up reachable from the agent's seat on hosted
OAuth connections instead of depending on the client re-running OAuth.

- `request_capability` (inspect) now returns `elevation` — a short-lived
  (ten-minute), owner-bound approval link for the connected OAuth token,
  replayable by the owner within its window — on Streamable HTTP whenever the
  missing scopes are elevatable (`work:read`