Siftable

Siftable MCP 服务

一个 Model Context Protocol 服务，可向 Cursor、Claude Desktop 和 VS Code 等 IDE 客户端提供 Siftable 工具。

ExecuFunction 0.4.0.0 托管兼容性

npm 包版本为 1.3.0；托管和源代码投影配置文件版本为 1.34.0。投影版本 1.34.0 统一了有界集合回执，公布了数据集聚合语义， 并区分了必须重新连接的 OAuth 连接和可在原位扩大授权范围的会话。投影版本 1.33.0 可识别自然语言源代码搜索意图， 并返回已弃用功能卡片及本地恢复方案，而不是将请求路由到精选代码记忆。投影版本 1.32.0 新增了明确的 no_matches 发现结果， 拒绝通用操作和仅匹配弱前缀的功能项，保留规范的复合意图匹配，并在失败 回执中记录 HTTP 状态类别。投影版本 1.31.0 新增了受管控的 潜在客户发现范围要求。投影版本 1.29.0 为托管客户端新增了受管工作租约 会话，同时将认领令牌保留在服务端。投影版本 1.28.0 新增了四个受管控的 潜在客户发现工具，以及五个与应用功能等效的人员／组织信息增强工具。

潜在客户发现默认处于禁用状态。启用后，必须单独授予 lead_discovery:read 或 lead_discovery:write 范围；mcp:* 不会 隐含授予上述任一范围。因此，托管基线目录会省略公司搜索，直到 request_capability 获得批准且目录刷新后，才会公开支持托管的 工具。一次公司搜索最多会发起一次付费 Crustdata 请求，派发前会显示最高费用，之后按实际服务商点数结算，并且只会将结果保存为待审核候选项。规范的 CRM 记录通过 lead_discovery_import_plan_create 创建，然后经过现有的 crm_import_plan_approve 和 crm_import_plan_apply 审核关卡。

人员信息增强会返回已存储的个人资料和事实提案。Apply 仅接受从已完成的运行中重新载入的提案字段名称和事实 ID； 不接受自由形式的替换内容，并且不可安全重试。组织信息增强仍是应用中付费的仅预览流程，无法应用规范的 CRM 更改。

1.3.0 兼容性说明

版本 1.3.0 发布了 sift.dataset.query.v2、有版本的聚合回执、 统一的工作项集合元数据，以及 reconnect_required 功能状态。 验证先前数据集查询回执的使用方应根据 schemaId 选择行为。

1.2.42 兼容性说明

版本 1.2.42 完成了发布就绪性审计。自然语言源代码搜索发现会返回规范的已弃用／仅限本地恢复卡片，而精选代码记忆发现仍保持独立。托管设置指南现在提供了准确的 ChatGPT 和 Codex 配置步骤。

1.2.41 兼容性说明

版本 1.2.41 解决了两项托管审计失败问题。数据集路由会在 HTTP 边界拒绝格式错误的数据集 UUID，MCP 回执会将由此产生的 400 保留为 bad_request。find_capability 现在要求直接的领域信号与匹配的操作；不相关的意图会返回 queryOutcome: no_matches，同时功能类别为空，并提供改述指导。精确工具名称、已移除工具卡片和虚拟引导工具不受语义拒绝规则影响。

1.2.40 兼容性说明

版本 1.2.40 解决了第三轮实时 Agent QA（2026-08-22 托管审计）中发现的问题。

• claimability 会如实反映生命周期和租约状态，而不只是依赖关系：state 的值为 ready、waiting、dependency_failed、leased、lease_expired、blocked、in_review、human_review_gate 或 terminal，并会同时提供 claimable、reason 和 nextAction，以及 blockedBy。已认领、正在运行、已取消和已完成的工作不再显示为 ready；claimable 是权威布尔值（lease_expired 项目和前置项已满足、由旧版转换而来的 blocked 占位项，因可通过显式认领恢复，所以 claimable: true）。按 ID 认领不可认领的项目时，会返回 409 并说明状态（lease_active、work_item_terminal 等），而不是 not_found。服务器提供 claimable 时，CLI 和 TUI 会据此控制认领操作。
• agent_work_list 和 work_item_list 默认隐藏已完成／失败／取消的项目（includeTerminal: true 或显式指定 status 时会显示），会输出排序规则，并说明较高的 queueRank 排在前面，默认值为 0，负值表示延后（排在 0 之后）。
• work_item_heartbeat 会说明：对已认领的工作发送心跳会将其启动（claimed → running，与 work_item_start 相同）；传给 start、heartbeat 或 release 的 resultSummary 现在会被持久化，不再被悄然丢弃。
• 当连接可以读取工作项时，task_get 会列出与任务关联的可执行工作（前十项，更多时会显示标记；如果为空，则显示“尚无”，并提示使用 work_item_create）；缺少权限范围时会保留功能提示，上游故障则会如实报告（仅尝试一次，不重试）。
• entity_graph 会报告每条记录自身的状态（如果有）（已完成的任务会显示为 completed，而不是 active；笔记／数据集会显示为 active／archived；关联的项目现在会显示其名称和状态，而不是 [untitled entity]／active）——迁移 V400 修复了 SQL 函数，该函数此前会将所有非笔记节点都标记为 active，且从不关联项目。其他节点类型会在该字段中保留各自类型的标签（组织的行业、人物的关系、新闻的发布日期）。
• note_search 会优先排列全文匹配（websearch 语法），其次是语义邻近结果，最后是字面子串回退结果，而不再直接对不同量纲的原始分数排序；分数只在同一来源内可比较，不能跨来源比较。
• object_find 会区分未知的对象类型键与已知类型但没有记录的情况。
• 代码记忆列表中，没有分块证据的 confirmed 事实会标记为 not_recorded (confirmed; no source-chunk evidence recorded)，以便明确显示证据缺口，同时不降低人工提交事实的可信度。

Projection 1.25.0 会将托管 OAuth 目录限制为当前令牌可调用的工具。find_capability 仍会发现需要提升权限范围的工具；完成授权并刷新目录后，这些工具便会显示。服务器初始化指南也已缩短，避免客户端在工具描述中重复大量说明。

1.2.39 兼容性说明

版本 1.2.39 针对第二轮实时 Agent 质量检查进行了改进。

• work_item_requeue 也会将租约已过期的已认领／运行中工作项退回队列，且不再携带原始认领令牌；有效租约仍绝不会被重新排队。work_item_list 会内联标注已过期的租约（[claimed · lease expired <time>]），而 work_item_get 会在 JSON 前加上 Lease: expired <time> — … 标题，说明该工作项可以直接认领或重新排队，而不是仅显示 claimed。
• 如果没有记录，work_item_revision_history / work_item_verification_history 会用一句话说明，而不是输出 []。
• 如果没有匹配项，object_find 会指出搜索的对象类型，并提示使用 schema_introspect / people_search / organization_search，而不是只显示 “No objects found.”。
• schema_introspect 默认会汇总数据集（标题、ID、行数、字段数）；设置 includeDatasetFields: true 可恢复逐字段输出。
• dataset_quality_check 会将空字符串计为缺失值，并返回带版本号的结构化结果。频繁重复的值属于观测结果；只有在字段声明为唯一时，这些值才算质量违规。

Projection 1.22.0 记录了 schema_introspect 输入架构和工具描述的变更。

1.2.38 兼容性说明

版本 1.2.38 让 Agent 直接获得工作权限，不再需要四处寻找（根据 2026-08-20 的决策，在 Grok 和 Claude 的实际使用后发布）。

• Hosted OAuth 首次连接时（未提供 scope 参数，或客户端复制了 scopes_supported），会在同意页面后发放 mcp:* work:read work:write。Vault 和 AI 范围仍仅可通过提权／CLI 获取。
• 连接可通过提权获取的工具会显示在 tools/list 中；审批前调用此类工具会返回带内联链接的工具错误，其中包含相同的 elevation 链接（或 CLI／PAT 指引）。现在只有 request_capability 处于 challenge 模式时，才会发出 HTTP 403 insufficient_scope 挑战。
• 提权链接的有效期为一小时（原为十分钟）；审批通过后，服务端会发布 tools/list_changed，以便订阅的客户端刷新。如果工具仍不可见，指引会提示 Agent 刷新工具列表或重启连接器。
• find_capability、request_capability 和 context_current 会呈现精简的文本摘要（名称、可用性、后续步骤），而不是完整 JSON；完整投影仍保留在 structuredContent 中。
• task_get 和任务工具描述不再声称缺少 work:read；它们会提示使用带有 taskId 的 work_item_list，并且只有在工具不可调用时才改用 request_capability。
• 通用列表文本中的“Stable handles”现在会指出每个 ID 对应的字段，并将重复项分组，因此二十行共享的 projectId 会显示为一个项目引用，而不是二十条新记录。

Projection 1.21.0 记录了所呈现工具及描述的变更。 升级后请重新连接托管的 MCP 客户端，以刷新 Projection 1.21.0 架构。

1.2.37 兼容性说明

1.2.37 版本支持 Agent 直接发起托管 OAuth 连接的权限范围升级，无需依赖客户端重新运行 OAuth。

• 在 Streamable HTTP 上，request_capability（检查）现在会返回 elevation：这是一个短时有效（十分钟）、绑定所有者的批准链接，适用于已连接的 OAuth 令牌；所有者可在有效期内重复使用该链接。当缺失的权限范围可以升级（work:read、work:write），且服务端提供了 capabilityAcquisition.createElevationGrant 时，就会返回该链接。用户打开链接、重新验证身份，并在第一方授权页面上批准后，现有令牌会就地扩展；Agent 无需重新连接即可重试工具。在这种情况下，recommendedNextAction.type 为 open_elevation_url，且 reconnectRequired 为 false。对于无法升级的连接，仍会回退到重新连接指引。
• find_capability、context_current 和直接拒绝受限工具的响应现在会指向这一路径，而不是要求客户端重新连接。
• 托管 OAuth 现在接受明确请求的 work:write（须经用户同意）；在 1.2.37 中，客户端省略 scope 时的授权默认值为 mcp:* work:read，且 scopes_supported 仅公布这两个权限范围（两者都在 1.2.38 中扩展到完整的 work 权限范围）。

Projection 1.20.0 记录了 request_capability 的输出架构和描述变更。升级后请重新连接托管 MCP 客户端，以刷新 Projection 1.20.0 架构。

1.2.36 兼容性说明

1.2.36 版本为托管端点发布到 ChatGPT 插件目录做准备，同时不改变 stdio 工具接口。

• 托管配置中的 upload_document 不再公布 filePath：托管架构要求内联提供 content 和 filename；除非客户端在构造时启用了 allowLocalFiles，否则在 MCP 边界、executeTool 和 SiftClient 中都会拒绝 filePath 参数，并返回规范化的 bad_request 错误。只有本地 stdio 入口会设置该标志；托管客户端和远程客户端无法访问服务端文件系统。
• 托管工具现在会在 _meta 下附带仅供 OpenAI 使用的提示，其他 MCP 客户端按规范会忽略这些提示：securitySchemes 仅列出已连接的 OAuth 客户端实际可以请求的权限范围（基线为 mcp:*），以及根据各工具标题生成的工具调用状态字符串。
• 现在每个目录工具都会公布 outputSchema：原先缺少输出架构的 27 个只读查询工具现在声明了 sift.action_receipt 封装格式，并将结果设为 text/plain，与 tools/call 已返回的内容一致。
• Projection 和目录摘要现在根据传输格式的架构计算，因此托管版 find_capability 和 schemaDigest 描述的是客户端实际看到的工具接口。

Projection 1.19.0 记录了托管版 upload_document 架构和封装输出架构。升级后请重新连接托管 MCP 客户端，以刷新 Projection 1.19.0 架构。

1.2.35 兼容性说明

1.2.35 版本修复了在 1.2.32 审查中发现的剩余契约差异。

• schema_introspect 现在仅在部署级数据集开关和调用方的功能授权都允许访问数据集路由时，才会公开数据集。其数据集和对象类型查询现在会使用调用方的 RLS 身份运行。
• code_memory_delete 对所有曾经存在过的记忆都会返回 500。V351 为生命周期事件日志添加了 ON DELETE CASCADE 外键，并且添加了一个会无条件抛出异常的仅追加触发器，因此级联操作会中止所有删除。V389 允许引用级联继续执行，同时仍禁止直接编辑日志；修复了两个会将所有者列置为 NULL、从而违反 NOT NULL 约束的血缘外键；并在后继项被删除时，将孤立的前驱项恢复为 needs_review，同时记录审计事件。
• 人工审核操作不再能通过 MCP 调用。code_memory_confirm、code_memory_reject、code_memory_edit 和 code_memory_supersede 在托管和本地 Agent 传输方式上都会被隐藏并拒绝调用。Agent 可以存储候选项或将事实标记为 needs_review；由人工在 Siftable 界面中整理。
• project_get_context 在每个任务的 status 字段中报告了工作流的阶段，并将 phase 留为 null。现在，这两个字段都会返回真实的列值，适用于开放、受阻和逾期任务。

Projection 1.18.0 记录了人工整理的边界，并从呈现给 Agent 的界面中移除了四个工具。

此版本需要迁移 V389__code_memory_delete_cascade.sql。 应用此迁移之前，code_memory_delete 仍会失败。

1.2.34 兼容性说明

1.2.34 版本修复了一系列调用成功、但答案错误或不完整的问题。

• 写入带有 company 的人员信息时会无条件返回 500。组织 upsert 指定了一个在 V357 中变为部分索引的唯一索引，却没有提供其谓词，因此 Postgres 无法推断冲突目标。
• 传输过程中不再剥除创作内容。请求管道对每个字符串运行 striptags()，会删除过滤运算符中的 <，将 List<String> 变成 List，还会移除笔记标题中的标记——这一切都是静默发生的，并且影响每次 MCP 调用，因为内容允许列表只匹配顶层 body 键。现在会在渲染内容时转义 HTML。
• 对文本类型列进行范围比较（> >= < <=）并使用数值时，现在会通过重新指定类型的路径拒绝请求，而不是悄悄按文本比较，使得 '99' 的排序结果高于 '199'。对这类列排序时，现在会返回警告，而不是给出看似合理却错误且没有标记的顺序。
• dataset_query 现在会在其结构化结果中携带 warnings。
• task_get 现在会以结构化形式携带完整的任务说明——rationale、deliverable、verification、approachConstraints、acceptanceCriteria 和 scope。此前，优先使用结构化数据的客户端收到的任务没有完成定义。

升级后请重新连接 MCP 客户端，以刷新 projection 1.18.0 架构。

1.2.33 兼容性说明

1.2.33 版本修复了托管 OAuth 令牌交换。授权服务器在查询已哈希的授权码时使用了 consumed_at IS NULL 过滤条件，但该表通过删除来消耗授权码，且没有此列。因此，Google 授权完成后，Cursor、Codex 或任何其他远程客户端的每次新连接都会失败，并返回 Internal Server Error。现有的已认证会话不受影响。工具契约和 projection 1.16.0 架构均未更改；除重试之前失败的登录外，无需重新连接。

1.2.32 兼容性说明

1.2.32 版新增了显式的、仅修改元数据的 repository_project_link mutation，使 Agent 能够持久化从 context_current.projectCandidates 中选定的项目。它还会将不受支持的客户端匹配项保留在次级发现通道中，并抑制得分为零的全文笔记命中结果。

升级后请重新连接 MCP 客户端，以刷新 projection 1.16.0 schemas。

托管远程客户端

推荐使用的托管端点是：

https://siftable.io/api/v1/mcp

Claude 远程连接器、Cursor、Codex、Devin、Kimi Code 和 Antigravity 均可通过 Streamable HTTP 连接。建议仅配置 URL 进行 OAuth：在第一方授权表单后端，省略 scope 的授权请求默认会获得 mcp:* work:read work:write；之后缺少的任何权限都可通过 request_capability 返回的一小时链接就地批准（仅限 Streamable HTTP；旧版 /sse 会话则需要重新连接）。配置 Authorization 标头会选择静态 PAT 模式；OAuth 挑战或权限提升链接都无法扩展该令牌的权限范围。

客户端配置键和回调行为各不相同（Cursor、Codex 和 Kimi 使用 url，Antigravity 使用 serverUrl，Claude 和 Devin 使用 UI 管理的连接）。有关基于各提供商信息整理的矩阵和验证流程，请参阅 docs/runbooks/hosted-mcp-client-compatibility.md。

对于需要已授权检出内容或无法使用托管端点的客户端，npm 包仍可用于本地 stdio 连接。

MCP Apps 视图

在实现 MCP Apps 扩展的宿主（Claude、ChatGPT、VS Code、Goose）中，某些工具可在沙盒视图中呈现。这些工具包含指向 ui://siftable/<view>.html 资源的 _meta.ui.resourceUri，该资源会由 resources/list 列出，并由 resources/read 以 MIME 类型 text/html;profile=mcp-app 提供。元数据仅用于呈现：它绝不会更改工具的 projection、权限范围、所呈现的目录或目录摘要；对于所有其他客户端，content 始终是完整的文本答案。

只有在 dist/ui/ 中存在 View bundle 时才会附加 UI 元数据。没有 bundle 的构建不会提供任何 UI 元数据。经过审核的工具到 View 白名单位于 src/ui/viewRegistry.ts；设计方案见 docs/design/mcp-ui-surfaces-plan.md。

这些 bundle 由 @siftable/mcp-apps 工作区（packages/exf-mcp-apps，每个 View 对应一个独立的 HTML 文件）构建，并由 scripts/copy-ui-bundles.mjs 在 npm run build 结束时复制到 dist/ui/。通过 Nx 构建时，apps 工作区会先行构建 （nx run @siftable/mcp-server:build）。不先构建 apps 而直接运行普通的 npm run build（目前托管 Docker 镜像就是如此），不会复制任何内容，因此保持未启用状态。verify:package、prepublishOnly 和 pack:mcpb 会先构建 apps，并在缺少 bundle 时失败，因此发布的 tarball 或 .mcpb 始终包含每个 View bundle（dist/ui/graph.html、data.html、review.html）。

目前可用的视图：

视图	资源	工具
图谱	ui://siftable/graph.html	entity_graph、object_links
数据	ui://siftable/data.html	dataset_query、dataset_aggregate、dataset_summarize、dataset_quality_check、dataset_facets、dataset_compare、dataset_rank、dataset_plot_result、dataset_timeseries、dataset_bucket、people_search、organization_search、task_list
审核	ui://siftable/review.html	lead_discovery_candidate_list、lead_discovery_run_get、crm_import_plan_get、crm_import_plan_create

重要工具的人工确认

有七个工具会在运行前请求人工确认：四个批量删除工具会在其 apply 调用时请求确认（confirm: true，并提供 previewId；预览和试运行不会请求确认）、删除字段时的 dataset_schema_modify、crm_import_plan_approve，以及 lead_discovery_company_run，其提示词会说明以美元计的批准上限。该问题通过 MCP 2026-07-28 多轮往返的 InputRequiredResult 传递，其中包含一个带有单个 confirm 布尔值的表单征询；客户端显示该问题，然后使用 inputResponses 重试同一调用。在拥有反向通道（stdio 或有状态 HTTP）的 2025 年版本会话中，SDK 的旧版兼容层会通过 elicitation/create 请求发送相同的提示词。在无状态的 2025 HTTP 回退模式下，每个请求都无法获知客户端功能，因此不会请求确认。

未声明征询功能的客户端会像之前一样运行工具。每个受确认机制保护的回执，无论成功、失败还是被拒绝，都会在 humanGate 下记录确认结果：在工具已运行的回执中，记录 elicitation 和 accepted，或 unsupported_fallback 和 not_asked；在工具未运行的拒绝回执中（error.code: "declined_by_user"），记录 elicitation 和确切的拒绝原因：declined、cancelled 或 not_confirmed。此确认机制为诚实的宿主提供人在回路中的保障；OAuth 范围仍是授权边界。种子工具列表位于 src/registry/mcpToolContractSeed.ts，提示措辞位于 src/humanGate.ts。

1.2.31 兼容性说明

此版本确保任务集合总数在游标分页间保持稳定，通过事务范围内的 RLS 基于持久身份解析存储库上下文，并返回明确的项目候选项，而不再根据名称自动关联存储库。项目资源现在使用不透明游标分页并显示后端故障；图谱和人员结果也会提供可用的规范标签。升级后请重新连接 MCP 客户端，以刷新 projection 1.15.0 架构。

1.2.30 兼容性说明

此版本要求调用方为 Agent 创建、工作认领和生命周期转换、代码记忆写入、文档上传、Vault 条目创建，以及受治理的审批、执行授权和物化请求提供稳定的幂等键。使用相同键重试会重放原始权威响应；负载发生变化则会冲突。Vault 回执保留元数据或由运行器加密的密文，绝不保留明文。由于流式提供方输出不会持久化以供重放，ai_generate 仍明确不支持安全重试。升级后请重新连接 MCP 客户端，以刷新 projection 1.14.0 架构。

1.2.29 兼容性说明

此版本使托管功能检查具有终结性且可安全重连，新增任务状态和受治理审批的不变量，并在项目、任务、数据集、架构、人员、组织和日历结果中加入稳定 ID 和类型化详情。已退役的源索引／搜索名称会转到本地检出搜索，同时仍可使用精选的代码记忆。dataset_create、dataset_mutate、dataset_schema_modify 和 dataset_materialize_result 工具要求调用方提供稳定的 idempotencyKey。 使用相同的键和负载重试会重放原始结果；使用相同的键但更改负载则会被拒绝。现有 MCP 会话必须重新连接，以刷新缓存的工具架构，然后才能调用这些变更操作。省略 Idempotency-Key 标头时，直接 REST 调用方仍保持向后兼容。

隐私政策

服务器会将工具调用发送到配置的 Siftable API（SIFT_API_URL；默认值为 https://siftable.io），不会发送到其他任何地方。除启动服务器时所在的环境外，服务器不会在本地存储任何数据；个人访问令牌也只会发送到该 API。Siftable 的隐私政策涵盖数据收集、使用、存储、共享、保留和联系信息，详见 https://siftable.io/privacy.html。

分发制品

@siftable/mcp-server 从 monorepo 发布；公共源码镜像 https://github.com/execufunction-mcp/mcp-server 通过 scripts/mirror-mcp-server.sh 刷新，无法独立构建。

制品	命令	发布位置
npm 包	npm publish --workspace @siftable/mcp-server	面向 stdio 客户端的 npx @siftable/mcp-server
Claude Desktop 扩展	npm run pack:mcpb --workspace @siftable/mcp-server	build/siftable.mcpb；将其附加到 GitHub release，并通过桌面扩展表单提交
MCP Registry 条目	npm run publish:registry --workspace @siftable/mcp-server，需先运行 mcp-publisher login github	io.github.Tom-R-Main/mcp-server，该条目指向 npm 包

manifest.json 是桌面扩展清单；其 version 必须与 package.json 一致，且打包构建会对此进行断言。此扩展包包含自己的 生产环境 node_modules，因此无需 monorepo 即可运行。

快速开始

1. 创建个人访问令牌

1. 前往 Siftable → Settings → Developer → Access Tokens
2. 点击“Create Token”
3. 为其命名（例如“Cursor MCP”）
4. 选择 mcp:* 以获取基础 MCP 访问权限，然后添加工作流所需的特定权限范围类别 （例如 projects:read、tasks:write 或 work:read）。mcp:* 并非通用授权。
5. 立即保存令牌——它只会显示一次！

2. 配置 MCP 客户端

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "siftable": {
      "command": "npx",
      "args": ["@siftable/mcp-server"],
      "env": {
        "SIFT_API_URL": "https://siftable.io",
        "SIFT_PAT": "sift_pat_your_token_here"
      }
    }
  }
}

Cursor

添加到 Cursor MCP 设置中：

{
  "siftable": {
    "command": "npx",
    "args": ["@siftable/mcp-server"],
    "env": {
      "SIFT_API_URL": "https://siftable.io",
      "SIFT_PAT": "sift_pat_your_token_here"
    }
  }
}

VS Code

在 MCP 扩展设置中配置。

3. 重启 IDE

配置完成后，重启 IDE 以加载 MCP 服务。

可用工具

定位与能力获取

每次新的客户端会话都从 context_current 开始。它会报告有效的工作区、项目、 仓库、传输方式、已提供/有效权限范围、缺失的可请求权限范围，以及建议的后续调用。托管 MCP 会返回一个 null 检出目录及原因，除非客户端明确提供根目录提示。

如果某个工具不可用或某项操作未获授权，请使用 find_capability 作为发现入口。以 inspect 模式调用 request_capability，可获取结构化恢复方案，而不会触发授权质询；仅当 客户端能够呈现 HTTP 403 响应中的符合标准的 OAuth 操作时，才使用 challenge 模式。

如果没有候选项符合发现置信度契约，find_capability 会返回 queryOutcome: no_matches、零计数和空通道。请同时用一个 Siftable 领域和操作重新表述查询，或检查 tools/list；不要将零结果响应视为授权依据。

task_* 用于管理人工规划。work_* 用于管理可执行的 Agent 工作。在后续调用中，优先使用集合和变更结果返回的稳定 ID。

工具	描述	是否修改数据
context_current	解析主体、所有者、项目、仓库、检出目录和有效能力上下文	否
find_capability	发现可调用、缺失、可请求和不受支持的能力	否
request_capability	检查恢复方案或请求 OAuth 授权质询	否

项目

工具	描述	是否修改数据
project_list	按状态筛选列出项目，支持有界游标分页、稳定 ID 和精简摘要	否
project_create	创建新项目	是
project_update	更新项目名称、摘要、状态和表情符号	是
project_archive	归档项目（破坏性操作）	是
project_get_context	获取完整的项目上下文（任务、笔记、信号）	否

任务

工具	描述	是否修改数据
task_list	按项目、状态、阶段、工作量和标题筛选并列出人工规划任务	否
task_get	获取单个人工规划任务的完整详情	否
task_create	创建人工规划任务，并设置优先级、阶段、工作量和验收标准	是
task_update	更新人工规划任务字段（标题、状态、优先级、阶段、工作量、范围）	是
task_delete	删除任务（不可逆操作）	是
task_bulk_delete	按 ID 或筛选条件预览或批量删除任务	是
task_complete	将任务标记为已完成	是

Agent

工具	描述	是否修改数据
agent_list	列出用户可见的 Agent 别名及其能力	否
agent_get	按 slug 或 ID 获取 Agent 别名	否
agent_create	创建 Agent 别名	是
agent_update	更新别名元数据、能力或权限	是
agent_disable	禁用别名，但保留历史记录	是
agent_work_list	列出分配给某个别名的可执行工作	否

工作项

工具	描述	是否修改数据
work_item_list	列出工作项及权威的依赖项可领取状态	否
work_item_get	获取工作详情、依赖项、满足情况和可领取状态	否
work_item_create	创建范围明确的工作，可选添加 UUID dependsOn 依赖边	是
work_item_dependencies_replace	原子替换工作项的 UUID 依赖项	是
work_item_claim	领取队列中可执行的工作并获取租约	是
work_dependency_policy_get	获取项目的默认依赖门控策略	否
work_dependency_policy_update	设置项目的默认依赖门控策略	是
work_item_start	将已领取的工作标记为运行中	是
work_item_heartbeat	延长租约	是
work_item_block	将工作标记为受阻	是
work_item_review	将工作标记为需要审核	是
work_item_complete	完成工作并附上摘要/工件	是
work_item_fail	将工作标记为失败	是
work_item_release	将工作释放回队列	是
work_item_cancel	取消工作	是

知识 / 笔记

工具	描述	是否修改数据
note_list	按类型、项目、归档状态和标题筛选并列出笔记	否
note_get	获取单条笔记的完整内容	否
note_search	在知识库中进行语义搜索	否
note_create	创建新笔记（Markdown）	是
note_update	更新笔记标题、内容或类型	是
note_delete	删除笔记（不可逆操作）	是
note_bulk_delete	按 ID 或筛选条件预览或批量删除笔记	是

联系人

工具	描述	是否修改数据
people_search	使用模糊匹配或精确/前缀筛选搜索联系人	否
person_create	创建联系人	是
person_update	更新联系人	是
person_delete	删除联系人（不可逆操作）	是
people_bulk_delete	按 ID 或筛选条件预览或批量删除联系人	是
person_enrichment_availability	检查身份信息是否就绪及应用当前价格，不会调度服务提供方	否
person_enrichment_run	执行付费且幂等的应用等效信息补充，并返回已存储的建议和计费凭据	是
person_enrichment_apply	应用已结算运行中的所选个人资料字段和事实；不支持安全重试	是

组织

工具	描述	是否会修改
organization_search	使用模糊匹配或精确匹配／前缀筛选搜索组织	否
organization_create	创建组织	是
organization_update	更新组织	是
organization_delete	删除组织（有破坏性）	是
organization_bulk_delete	按 ID 或筛选条件预览或批量删除组织	是
organization_enrichment_availability	检查提供商是否可用及当前应用价格，不会调用提供商	否
organization_enrichment_preview	运行付费且幂等的应用预览并保存证据，不会写入规范 CRM 数据	是

潜在客户发现

工具	描述	是否会修改
lead_discovery_company_search	运行一次范围受限的付费公司搜索，并暂存有来源支持的待审核候选项	是
lead_discovery_candidate_list	列出候选项及其 CRM 匹配／审核状态	否
lead_discovery_candidate_review	将一个候选项列入候选名单或拒绝，并记录原因	是
lead_discovery_import_plan_create	根据已列入候选名单的候选项创建持久化 CRM 导入计划；审批和应用仍分开进行	是

请参阅 无头 CRM 导入计划，了解 CLI 和 MCP 共用的 审批和应用流程。

日历

工具	描述	是否会修改
calendar_list_events	列出指定日期范围内的日历事件	否
calendar_create_event	创建新的日历事件	是
calendar_update_event	更新日历事件	是
calendar_delete_event	删除日历事件（有破坏性）	是

本地源代码上下文

工具	描述	是否会修改
git_blame_symbol	对本地文件范围运行 git blame	否

源代码检查和搜索通过 Git、rg、编辑器或 Agent 原生工具，在已获授权的检出目录中本地进行。Siftable 存储整理过的代码记忆；它不会为代码仓库源文件建立索引或进行语义搜索。

代码记忆

工具	描述	是否会修改
code_memory_store	存储整理过的代码事实	是
code_memory_search	搜索已存储的代码事实	否
code_memory_list	列出所有已存储的代码记忆	否
code_memory_delete	删除代码记忆（有破坏性）	是

保管库／密钥

工具	描述	是否会修改
vault_list	列出保管库条目（仅元数据）	否
vault_create	存储新的加密密钥	是
vault_update	更新保管库条目元数据	是
vault_search	按名称／描述搜索保管库条目	否
vault_audit	检查保管库审计跟踪	否
vault_materialization_request	请求批准一个确切的实体化目标位置	是
vault_materialization_status	检查实体化状态，不返回密钥字节	否
capability_list	列出受管控的保管库执行能力	否
capability_describe	描述受管控的保管库执行能力	否
capability_execute	执行受管控的能力，不暴露密钥字节	是

vault_read 已停用。MCP 绝不会返回明文密钥字节；请改用受管控的能力或明确批准的实体化操作。

实体图

工具	描述	是否会修改
entity_graph	遍历实体关系图	否
schema_introspect	探查完整数据模型和实体类型	否

文档上传

工具	描述	是否会修改
upload_document	将 PDF、Markdown 或文本文件上传到 Knowledge	是

数据集（功能标志：DATASETS_ENABLED=true）

工具	描述	是否会修改
dataset_list	列出数据集	否
dataset_create	创建数据集	是
dataset_query	按筛选条件和排序方式查询记录	否
dataset_mutate	创建、更新或删除记录（具有破坏性）	是
dataset_schema_modify	添加、更新或删除字段（具有破坏性）	是
dataset_summarize	汇总架构和示例行	否
dataset_facets	获取字段的值分布	否
dataset_quality_check	检查缺失值指标、无效值、唯一性问题和重复值情况	否
dataset_aggregate	获取分组指标（计数、平均值、总和等）	否
dataset_bucket	将数值或日期字段分桶为多个范围	否
dataset_rank	按排序方式或加权公式对记录排名	否
dataset_analyze	生成自然语言洞察	否
dataset_compare	比较不同细分群体的指标	否
dataset_export	将记录导出为 CSV	否
dataset_join_rows	使用按别名限定的字段进行自连接	否
dataset_compute_fields	计算派生列（滞后值、差值、滚动值）	否
dataset_timeseries	使用变换进行时间序列分析	否
dataset_materialize_result	将派生结果保存为新数据集	是
dataset_plot_result	验证派生结果中的图表载荷	否

本体（功能标志：DATASET_ONTOLOGY_ENABLED=true）

工具	描述	是否会修改
object_find	按类型和属性筛选条件查找对象	否
object_links	遍历对象的图链接	否
object_action_run	对对象执行声明式操作（具有破坏性）	是

使用示例

1. 获取项目上下文并创建任务

用户提示词：“获取我的 auth 项目上下文，并创建一个修复令牌刷新错误的任务”

调用的工具：

1. project_list — 列出项目以查找 auth 项目
2. project_get_context — 获取项目的任务、备注和信号
3. task_create — 创建人工规划任务，并设置标题、描述和项目关联

**结果：**AI 会读取现有项目上下文（未完成的任务、近期备注）以避免重复，然后创建范围明确且关联到正确项目的任务。

要运行 Agent，请使用 work_item_create 创建关联的可执行工作项，并将 taskId 设置为父级人工任务。任务工具应跟踪规划状态；工作项工具应跟踪执行、租约、制品、验证和审核状态。

依赖关系以权威 UUID 引用为准。将 dependsOn 作为 { workItemId, requiredGate? } 数组传入，其中 requiredGate 为 done 或 commands_passed。如果省略门槛，则根据项目的工作依赖策略确定。列表和获取结果会显示解析后的 dependencies 投影以及派生的 claimability（ready、waiting 或 dependency_failed）。使用 work_item_dependencies_replace 替换完整的依赖边集合；传入空数组可移除所有依赖项。在验证器退役迁移期间，历史上的 verified 门槛会被规范化为 commands_passed。

由租约持有者调用的生命周期操作（start、heartbeat、block、review 和 fail）需要提供 work_item_claim 返回的 claimOwner 和 claimToken；release 需要提供有效令牌。complete 支持为租约持有者完成操作提供凭据，但凭据为可选项，以便人工无需租约即可解决 needs_review。cancel 同样无需令牌。获取和列表输出中不会包含认领令牌，客户端不应记录或持久化这些令牌。

2. 知识搜索和笔记创建

用户提示词：“搜索我们的部署流程，并创建一篇总结步骤的笔记”

调用的工具：

1. note_search — 在知识库中搜索“deployment process”
2. code_memory_search — 搜索已存储的代码事实，查找与部署相关的记忆
3. note_create — 创建一篇以 Markdown 总结部署步骤的新笔记

**结果：**AI 将现有笔记和代码记忆中的信息综合成一篇参考笔记，并关联到相关项目。

资源

该服务还会将项目上下文包作为 MCP 资源公开：

• exf://projects/{id}/context - 项目的完整上下文包

环境变量

变量	必填	说明
SIFT_API_URL	是	Siftable API URL
SIFT_PAT	是	个人访问令牌

现有 MCP 配置仍支持旧版 EXF_API_URL 和 EXF_PAT。

开发

# Install dependencies
npm install

# Run in development mode
npm run dev

# Test with MCP Inspector
npm run inspect

# Build for production
npm run build

安全

• PAT 以 SHA-256 哈希形式存储，不会存储明文
• 可随时从 Siftable Settings 撤销令牌
• 仅使用满足用例所需的最小权限范围
• 切勿将令牌提交到版本控制系统

权限范围

权限范围	说明
mcp:*	核心项目、任务、日历、知识和人员操作
projects:read	读取项目数据
projects:write	创建/更新项目
tasks:read	读取任务
tasks:write	创建/更新/完成任务
knowledge:read	搜索/读取笔记
knowledge:write	创建笔记
calendar:read	查看日历/空闲时段
calendar:write	创建日历事件
people:read	搜索/查看联系人
people:write	创建/更新联系人
work:read	读取可执行工作队列
work:write	修改可执行工作队列
lead_discovery:read	读取潜在客户发现运行记录和候选项
lead_discovery:write	发起付费搜索并审核/导入候选项
vault:metadata:read	读取 Vault 元数据和物化状态
vault:manage	创建/更新 Vault 元数据并请求物化
vault:audit:read	读取 Vault 审计记录

故障排除

“SIFT_API_URL environment variable is required”

请确保已在 MCP 客户端配置中设置 env 部分。

“Invalid token”

1. 检查令牌是否以 sift_pat_ 或旧版 exf_pat_ 开头
2. 确认令牌尚未被撤销
3. 检查令牌是否已过期

未显示工具

1. 更改配置后重启 IDE
2. 检查 IDE 日志中的 MCP 错误
3. 尝试运行 npm run inspect，直接测试该服务

许可证

MIT