Decantr Mcp Server

@decantr/mcp-server

支持状态：core-supported
发布渠道：stable

Decantr 3.11.3 稳定版 MCP 集成，用于 Changed-UI Assurance、本地项目状态、具备权限感知能力的路由及非路由任务上下文、图谱与证据读取，以及修复提示词。

发布边界

发布的 npm 包版本为 3.11.3。其 8 个工具 ID、基于路由的 TaskCapsuleV1 路径、具备权限感知能力的目标发现、验证操作及兼容性封装均已稳定。现有的 decantr_verify 工具新增了 changes 操作，该操作会返回与裸 CLI verify 和显式 CI v3 相同的 change-assurance-report.v1。不会新增第 9 个工具。

• 观察项目状态 —— 检查共享发现元数据、项目自有的 Contract、已接受的本地规则、类型化图谱及采用情况实况
• 准备路由上下文 —— 通过当前图谱和生产路由权限，将关联路由解析为精简且按来源排序的任务胶囊
• 验证差异 —— 根据可用权限评估本地工作，并返回稳定的发现结果、健康状态和证据，不上传源代码
• 报告并修复 —— 提供类型化证据、限定范围的修复计划和修复提示词，任何编码 Agent 都可以使用

Decantr 不会调用 Agent、生成编辑内容、替代宿主项目的设计系统，也不会要求账号来使用其本地工作流。

快速设置

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "decantr": {
      "command": "npx",
      "args": ["@decantr/[email protected]"]
    }
  }
}

重启 Claude Desktop。Decantr 工具会自动显示。

Cursor

推荐设置：

npx @decantr/[email protected] connect cursor

在 monorepo 根目录中：

pnpm exec decantr connect cursor --project apps/web

该连接器会保留现有 MCP 服务，并写入项目规则，告知 Cursor Agent 在编辑路由前请求基于路由的 Decantr 任务上下文。若要手动设置，请在项目根目录中创建 .cursor/mcp.json：

{
  "mcpServers": {
    "decantr": {
      "command": "npx",
      "args": ["-y", "@decantr/[email protected]"]
    }
  }
}

重启 Cursor。工具可在 Agent 模式下使用。若手动配置 MCP，请添加与 decantr connect cursor 等效的项目规则。

Windsurf

将以下内容添加到 Windsurf MCP 配置文件（~/.windsurf/mcp.json）：

{
  "mcpServers": {
    "decantr": {
      "command": "npx",
      "args": ["@decantr/[email protected]"]
    }
  }
}

VS Code

在工作区中创建 .vscode/mcp.json（或添加到用户配置文件 mcp.json 中）：

{
  "servers": {
    "decantr": {
      "command": "npx",
      "args": ["-y", "@decantr/[email protected]"]
    }
  }
}

MCP 工具可在 VS Code Copilot Chat 的 Agent 模式下使用。

Zed

将以下内容添加到 Zed 的 settings.json：

{
  "context_servers": {
    "decantr": {
      "command": "npx",
      "args": ["-y", "@decantr/[email protected]"],
      "env": {}
    }
  }
}

Continue.dev

在工作区中创建 .continue/mcpServers/decantr.yaml：

name: Decantr MCP Server
version: 0.0.1
schema: v1
mcpServers:
  - name: Decantr
    type: stdio
    command: npx
    args:
      - "-y"
      - "@decantr/[email protected]"

MCP 工具仅可在 Continue.dev 的 Agent 模式下使用。

核心工具

该服务提供固定的 8 个 MCP 工具。传入 action 以选择路由行为：

工具	描述	示例输入
decantr_project	读取本地项目状态、共享发现摘要、采纳事实和工作区健康状况	{ "action": "state", "project_path": "apps/web" }
decantr_contract	读取并验证项目自有 Contract、检查偏差、创建兼容性骨架，或读取其胶囊	{ "action": "validate", "path": "./decantr.essence.json" }
decantr_context	读取脚手架、分区、页面、执行包上下文，或准备附带路由支持的任务胶囊	{ "action": "task", "project_path": "apps/web", "route": "/feed", "task": "improve loading behavior" }
decantr_graph	读取、查询和遍历本地图谱及源码证据，用于路由范围内的工作	{ "action": "query", "project_path": "apps/web", "file_path": "src/app/page.tsx", "include_impact": true }
decantr_registry	以旧名称提供兼容性访问，用于获取官方语料库词汇、基准元数据和执行包	{ "action": "resolve_pattern", "id": "data-table", "preset": "product" }
decantr_verify	返回 Changed-UI Assurance、评审、发现项、健康状态或 v2 证据包	{ "action": "changes", "project_path": "apps/web" }
decantr_repair	将类型化发现项转换为范围明确的修复计划、提示词和 v2 健康循环指南	{ "action": "health_loop", "project_path": "apps/web" }
decantr_contract_write	显式的工作区内写入接口，用于接受偏差或更新 Essence v4	{ "action": "update_essence", "operation": "add_feature", "payload": { "feature": "billing" } }

对于附带的路由，在 task 操作中传入 route 或兼容的 page_id。精简模式会将由验证器管理的 TaskCapsuleV1 投射到现有响应字段中，并将内容控制在 12,000 个规范 UTF-8 字节 / 4,000 个预估 token 以内。SvelteKit 路由读取会优先读取 +page.svelte，并将同目录的页面数据模块作为辅助依据。缺失或过期的图谱证据会报告 blocked_missing_graph；Angular 生产路由依据不完整则会报告 DISCOVERY_NOT_PROVEN。这两种情况都不会通过猜测来选择实现来源。

只有当 pack-manifest.json 选定的本地脚手架、页面和分区路径确实指向所选项目 .decantr/context 目录下的文件时，这些路径才会作为任务读取目标被读取或输出。缺失、越界、目录和通过符号链接逃逸的引用都会被忽略；现有的 scaffold.md 和 section-<id>.md 叙述性上下文仍会作为本地回退方案。在 Greenfield style-bridge 采纳中，已接受的桥接会映射到宿主项目的令牌、类和样式运行时；它不会激活 @decantr/css。

decantr_project 状态包含由验证器构建的 AdoptionTruthV1。兼容性名称为 decantr_registry 的工具下，官方语料库操作使用 @decantr/content 实现；不存在第 9 个 decantr_content 工具。

decantr_verify 的 changes 操作不会写入任何内容，也不会执行采纳。它会解析当前 Git 更改，仅在能够证明时选择一个已更改的 UI 应用，并默认最多输出三个重要发现项。多应用存在歧义、Git 范围不可用以及依据无法确定时，都会返回 not_proven。在 3.11 中，JSX/TSX 的原语复用保证最为可靠；模板对等性仍有限。

3.10 权威性感知发现

decantr_context 任务输入接受 target：路由路径、精确的 surface ID、组件名称、kind:name 或 file:path。它会通过实时验证器发现解析每个目标，不会将已保存的分析、图谱猜测、测试、测试夹具、故事或生成的输出提升为生产路由权威信息。对于未知、存在歧义、推断得出、未解析或不可执行任务的目标，会返回错误，且不提供编辑读取集。

被静态解析的中间件/代理非成功策略隐藏的 Next 文件路由，是有效的发现界面，但不是可执行任务的 MCP 目标。如果该策略依赖路径且无法解析，任务准备会返回受阻的权威状态，而不会仅凭惯例选择路由。TanStack 生成的元数据可以佐证作者定义的路由公共路径，但仅属参考证据，绝不是实现目标。Astro 响应端点以及 TanStack/Angular 布局或回退项仍不可执行任务。SvelteKit 页面数据模块仍不可执行任务，只能为同目录的 +page.svelte 实现提供支持。Angular 任务读取包括静态解析的外部模板、组件样式和工作区次级入口源代码。按排名读取样式时，会保留生产 CSS 导入顺序，包括工作区软件包导出项。附带的路由兼容性响应会包含与 CLI 相同的验证器排名读取集，从变更源影响中排除生成的治理变更，并在超过任务胶囊预算前删减仅兼容性所需的细节。

权威的非路由目标和未采纳目标会返回独立的 ui-surface-task-context.v1 发现封套，其中包含有界读取范围和明确限制。独立组件或故事仍属于项目参考证据，不能证明运行时可达性。已采纳的路由继续使用兼容的 TaskCapsuleV1 合约。

产品边界

MCP 服务的核心是本地 Observe -> Prepare -> Verify -> Report 循环。以下界面仅在兼容性需要时保留：

• decantr_registry 是用于读取官方内容语料库的稳定 3.x 工具 ID。它不是公共注册表、市场或社区发布界面。
• @decantr/css 是可选的旧版适配器。它不会自动启用，也不会覆盖宿主项目的样式权威性。
• Studio 是 Decantr 证据的非核心只读使用方。使用此 MCP 服务不需要 Studio。
• 托管内容和智能元数据是可选的兼容性输入。本地项目权威性、本地验证和证据报告无需托管源代码分析或 Decantr 账户。

如需了解更广泛的产品界面和支持政策，请参阅 Decantr 根目录文档和软件包支持矩阵。

如需了解 Decantr 3 助手提示词迁移，请参阅 MCP 迁移指南：https://decantr.ai/reference/mcp-migration.md。

安全与权限

MCP 服务会读取 Decantr 文件，包括 .decantr/graph 类型化图谱产物、选定的项目文件、通过本地 Git 命令获取的用于确定变更范围的 Git 元数据，以及直接引用并用作组件权威来源的工作区软件包源代码。写入权限仅限于明确的 decantr_contract_write 工具及其 accept_drift 和 update_essence 操作。如果调用方明确请求该解决方式，accept_drift 可以将问题延后记录到 .decantr/drift-log.json。路径仅限于当前工作区根目录内。

内容语料库和软件包解析操作可能会调用已配置的 Decantr API。项目权威性、评审、审计和验证均为本地读取；源代码上传回退功能已停用。MCP 服务不会发送 Decantr 遥测数据。请参阅安全权限。

npm 软件包会捆绑其标准输入/输出传输所用的 MCP SDK 模块，但不会安装 SDK 中未使用的 HTTP 服务依赖树。捆绑代码的许可证保留在 THIRD_PARTY_NOTICES.md 中。

兼容性

对于文档所述的 MCP 工具接口，@decantr/mcp-server 在 Decantr 3 系列中保持稳定。

• Decantr 3 保留上述恰好八个工具；新增第九个内容工具或隐藏别名均与此发布系列不兼容
• 不得在没有主版本升级的情况下破坏现有文档所述的工具名称和封装格式
• 已确立的工具契约发生破坏性变更时，必须升级主版本并附带迁移说明

Decantr 3 工具接口

Decantr 3.4 将旧版 MCP 工具名称整合为上述八个基于操作的工具。3.x 系列保留该工具清单、服务身份、stdio 传输方式、现有操作名称和兼容封装格式。官方语料库兼容性仍通过 decantr_registry 提供，而不是新增第九个工具。例如，decantr_get_project_state 会变为 decantr_project，并使用 { "action": "state" }；decantr_get_graph_snapshot 会变为 decantr_graph，并使用 { "action": "snapshot" }；旧版写入工具则会变为 decantr_contract_write，并使用 { "action": "accept_drift" } 或 { "action": "update_essence" }。

npm tarball 包含 server.json，使 MCP 目录能够读取与仓库使用者相同的稳定身份和传输元数据。

工作原理

已发布的 3.11.3 会读取项目自身的证据：Git 变更、应用源代码和框架配置、直接引用的工作区组件、已接受的本地规则、存在时的 decantr.essence.json、图谱产物、基线以及验证结果。在 Brownfield 中，生产源代码仍是首要依据，而已接受的 Essence 是其下的项目规则。MCP 客户端可以在不进行任何采纳的情况下请求 Changed-UI Assurance，在编辑前请求范围明确的任务上下文，并在编辑后检查验证证据。Decantr 会报告证据和局限；代码变更仍由编码 Agent 负责。

工作流示例

提示词：“改善 /feed 上的加载和错误处理方式，不要替换现有的卡片组件或样式系统。”

具备 MCP 能力的编码 Agent 可以按以下顺序使用这些工具：

1. 使用 decantr_project 和 state，了解所选应用、可用依据、图谱就绪情况、采纳状态及限制。
2. 使用 decantr_context 和 task 及 route: "/feed"，在编辑前准备精简的图谱上下文。
3. 使用 decantr_graph 和 query 或 traverse，获取变更所需的、经排序的本地源代码和影响证据。
4. 编码 Agent 使用常规工具编辑项目；Decantr 不会生成或应用源代码变更。
5. 使用 decantr_verify 和 changes 优先验证当前 UI 差异；也可使用 audit_project、critique、evidence_bundle 或 health_loop 获取更深入的证据。
6. decantr_repair 会将任何带类型的发现转化为范围明确的计划或修复提示词，之后再次运行验证。

如果项目使用 Essence 契约，仍可使用 decantr_contract。如果任务需要官方语料库词汇或执行包，仍可使用 decantr_registry，但它不是本地必需工作流的一部分。

许可证

MIT