idf-mcp

@intent-driven/mcp-server

别再给 AI Agent 提供 API 密钥。给它们一个领域。

@intent-driven/mcp-server 将任意 IDF 领域 作为 Model Context Protocol 服务，提供给 Claude Desktop / Cursor / Zed — 工具描述中包含 领域语义（前置条件、不变量、不可逆性、角色范围），并且当 Agent 尝试不该执行的操作时，会返回结构化拒绝。不是 500 错误，不是一段字符串，而是 大模型能够读取并据此调整的 JSON 结构。

→ 产品主页和演示：fold.intent-design.tech → 5 分钟快速入门：github.com/intent-driven-software/fold-runtime-quickstart

70 秒演示

→ 在 Loom 上观看 →

---

为什么要做这个

2026 年 4 月 25 日，一个由 Claude Opus 4.6 驱动的 Cursor Agent 正在处理 PocketOS 预发布环境中的凭据不匹配问题，却发现了一个无关的 API 令牌，随后决定删除 Railway 卷来解决问题，结果在 9 秒内抹掉了生产数据库以及所有卷级备份。该 Agent 在事后复盘中写道：

“我猜测通过 API 删除预发布环境的卷只会影响预发布环境。我没有核实，也没有检查卷 ID 是否在不同环境之间共用。”

服务中断了 30 小时。PocketOS 回滚到了 3 个月前的备份。 （The Register · FastCompany · OECD AI Incident #6153）

这不是对齐问题。系统从未告诉 Agent 哪些操作是允许的、为什么不该执行这些操作，或者尝试后会发生什么。现有的 MCP 服务也一样 — 工具描述只包含端点结构，除此之外几乎没有信息。Agent 只能通过撞上 500 错误来摸索。

这个包解决了这个问题。MCP 工具描述中包含调用可能失败的原因；拒绝响应则会以结构化形式说明失败的内容。

如何接入你的技术栈

@intent-driven/mcp-server 是一个 stdio MCP 适配器，通过 HTTP API 与 Fold 运行时通信。运行时是一个配套服务 — 不是现有应用中的中间件，也不是运行时生成的代码。你当前的后端保持原样；IDF 产物描述面向 Agent 的接口，而运行时会在自己的端口上提供服务（默认 :3001）。

┌──────────────────┐   stdio    ┌──────────────────┐   HTTP   ┌────────────────────┐
│ Claude Desktop   │ ◀─────────▶│ @intent-driven/  │ ◀───────▶│ Fold runtime       │
│ Cursor / Zed     │            │ mcp-server       │          │ (idf host :3001)   │
└──────────────────┘            └──────────────────┘          └────────┬───────────┘
                                                                       │ reads
                                                                       ▼
                                                              ┌────────────────────┐
                                                              │ IDF artifact       │
                                                              │ (entities + intents│
                                                              │  + invariants +    │
                                                              │  roles + __irr)    │
                                                              └────────────────────┘

MCP 服务是 Claude/Cursor 连接的对象。运行时负责强制执行拒绝。IDF 产物是你编写的内容。

**适用对象。**你是一支 5–30 人团队中的工程师，本季度要将 AI Agent 投入生产环境 — 构建在真实后端之上，服务真实客户，并且即将接受真正的 SOC2 审查。你不想要事后才进行审核的防护层，而是希望系统本身在调用前就拒绝错误操作，并提供 Agent 可以读取的结构化原因。

Agent 实际看到的内容

自由职业领域中的 submit_response：

Executor публикует Response на Task в status=published; Response.status=pending; +1 в Task.responsesCount

Creates: Response(pending)

Preconditions: task.status = "published"

May fail on (domain invariants):
  - Response.taskId must reference existing Task.id
  - Response: max 1 per taskId where (status="selected")
  - Response: row count rule per taskId where (status="pending") [info]

同一领域中的 release_payment：

Customer releases escrow to executor. After confirmation, money is gone — forward-correction only.

⚠️ Irreversible action (point-of-no-return: high). Forward-correction only after this effect is confirmed.

May fail on (domain invariants):
  - Deal.status transitions allowed: in_progress→completed, on_review→completed, ...

这些内容都不是为 MCP 服务手动编写的。它们全部源自一个声明式 IDF 工件（实体 + 意图 + 不变量 + 角色 + 不可逆节点）。

结构化拒绝的样子

Agent 未经预先批准，提交了一笔 50,000 美元的 BTC 做多订单。运行时会在任何效果写入存储之前进行拦截：

HTTP 403
{
  "error": "preapproval_denied",
  "intentId": "agent_execute_preapproved_order",
  "reason": "no_preapproval",
  "details": {
    "entity": "AgentPreapproval",
    "ownerField": "userId",
    "viewerId": "user_5f57c252"
  }
}

任何理智的 Agent 接下来都会：停下，请人类预先批准，然后重试。不是 500 错误，不是一段字符串，而是大模型可以读取并据此调整的 JSON 结构。

---

快速入门

最快的方式是使用 fold-runtime-quickstart — 两条命令，由 Docker 打包，无需配置路径：

git clone https://github.com/intent-driven-software/fold-runtime-quickstart && cd $_
docker compose up                  # ~3 min first time, ~5 sec after

# in another terminal
npm install
npm run demo:rogue   && \          # Act 1: $50K trade → 403 with structured rejection
  npm run demo:grant && \          # Act 2: investor issues $1K cap (one declarative effect)
  npm run demo:smart               # Act 3: agent reads cap, scales to $950, executes 200 OK

如果你更愿意自行驱动主机（例如，针对自己的本体进行开发），请参阅下一节。

直接驱动 MCP 服务

你需要在 localhost:3001 上运行一个 IDF 主机（快速入门的 docker-compose 会为你启动它，或者手动运行 idf），并准备好已引导初始化的领域。

CLI

# bootstrap from local FS (ontology + intents)
mcp-idf --domain=invest --ontology-path=/abs/path/to/idf/src/domains/invest

# skip bootstrap (domain already loaded by another client / docker)
mcp-idf --domain=invest --no-bootstrap

标志 / 环境变量：

标志	环境变量	默认值
--domain	IDF_DOMAIN	booking
--server	IDF_SERVER	http://localhost:3001
--ontology-path	IDF_ONTOLOGY_PATH	./src/domains/<domain>
--agent-email	IDF_AGENT_EMAIL	mcp-agent@local
--no-bootstrap	IDF_BOOTSTRAP=0	启用引导初始化（加载 FS 本体）

Claude Desktop

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

{
  "mcpServers": {
    "invest": {
      "command": "npx",
      "args": ["-y", "@intent-driven/mcp-server"],
      "env": {
        "IDF_SERVER": "http://localhost:3001",
        "IDF_DOMAIN": "invest",
        "IDF_BOOTSTRAP": "0",
        "IDF_AGENT_EMAIL": "claude@local"
      }
    }
  }
}

如果主机已加载该领域，则设置 IDF_BOOTSTRAP=0（快速入门容器会在运行 docker compose up 时完成此操作）。完全重启 Claude Desktop（⌘Q 后重新启动 — 仅关闭窗口并不够）。所有可由 Agent 调用的意图都会显示在工具菜单中。

---

架构映射

IDF intent.canExecute              ─→  MCP tool
intent.parameters                  ─→  JSON Schema inputSchema
intent.conditions                  ─→  description hint for LLM
ontology.invariants (relevant)     ─→  description block "May fail on"
intent.irreversibility:high        ─→  annotations.destructiveHint + warning
role.visibleFields                 ─→  resource per collection
preapproval guard                  ─→  automatic scope/limits
checkOwnership                     ─→  automatic access control

工具

ontology.roles.agent.canExecute 中的每个意图对应一个工具。

• name — intentId
• title — intent.name
• description — intent.description + Creates: … + 前置条件 + May fail on (domain invariants) 区块；当 irreversibility: "high" 时，还会包含不可逆警告
• inputSchema — 根据 particles.parameters 生成的 JSON Schema：
  • entityRef / id / text / textarea / select → string
  • number → number
  • boolean → boolean
  • datetime → string + format: "date-time"
  • email → string + format: "email"
• annotations.destructiveHint — 当 intent.irreversibility === "high" 时为 true（IDF §23：效果级不可逆转节点）

资源

role.visibleFields[entity] 中的每个集合对应一个资源。URI 方案： idf://<domain>/<collection>。

resources/read 返回经过筛选的世界状态，来自 /api/agent/:domain/world — 已按查看者的范围进行限定（通过 role.scope 实现单一所有者 + m2m）。

---

相比手动构建 MCP 服务，它能为你带来什么

MCP 社区在每个服务中都手动解决以下问题：

1. 范围／可见性。 使用装饰器或中间件。→ IDF 声明 role.visibleFields。
2. 权限。 OAuth 作用域、自定义 ACL。→ IDF 声明 roles.agent.canExecute。
3. 速率限制／支出上限。 每个服务各自定制。→ IDF 声明 preapproval.requiredFor，并设置 maxAmount／dailySum。
4. 破坏性提示。 手动设置，而且常常会忘记。→ IDF：effect.context.__irr.point === "high" → 自动设置 destructiveHint: true。
5. 作为大模型提示的业务规则。 通常不会传递。→ IDF：intent.conditions 会以 Preconditions: 的形式写入工具描述。
6. 描述中的领域不变量。 几乎从未实现。→ IDF 会按意图计算相关不变量（alpha × 实体匹配），并将其注入为 May fail on (domain invariants)。这解决了手动构建 MCP 服务的头号问题：“服务不包含领域语义——大模型知道该调用什么，却不知道为什么会失败。”

---

编写一个 IDF 工件需要多长时间

以下是公共 IDF 主机运行时的三个参考示例：

领域	规模	耗时
invest	14 个实体 · 61 个意图 · 5 个不变量 · 约 600 行	手动编写，一个周末
gravitino	253 个实体（Apache 目录 OpenAPI）· 120 个意图	不到 1 小时完成导入，2 天完成完善
workflow	9 个实体 · 47 个意图 · 定时器队列 · 级联规则	1 天

效率提升来自以下功能（都在 @intent-driven/cli 中）：

• idf import postgres — 读取实时数据库架构，生成实体基线，并将外键和列类型设为 fieldRole。
• idf import openapi — 读取现有 API 规范，生成意图
  • 参数结构 + 引用字段。253 个实体的领域就是通过这种方式完成初始搭建的。
• idf import prisma — ORM 驱动的后端也可以用相同方式处理。
• idf enrich — 使用大模型填充 label、fieldRole、compositions， 并根据现有代码注释建议 roles.agent.preapproval 谓词。

编写一次，然后不再操心，这正是整个设计的核心。工件创建完成后，架构变更时无需重新生成脚手架——运行时会重新读取，并基于同一个文件为四种使用方（UI、语音、Agent、文档）提供服务。

---

领域前提条件

协议本身可靠，但需要正确编写 IDF 领域定义。若缺少以下内容，tools/list 可能返回空结果，tools/call 可能返回 domain_not_supported，资源也可能为空：

1. 必须声明 ontology.roles.agent。 未定义 Agent 角色 → 没有工具，也没有资源。
2. role.agent.canExecute — 安全意图列表。避免在没有预先审批的情况下使用 __irr:high。
3. role.agent.visibleFields — 字段数组，或 "own"／"all"／"aggregated" 标记。
4. 服务端效果构建器（idf 中的 server/schema/effectBuildersRegistry.cjs）必须包含你的领域。否则，tools/call 会返回 domain_not_supported。
5. 没有 ownerField 的公共目录。 如果实体有 ownerField，SDK 的 filterWorldForRole 会过滤掉满足 row[ownerField] !== viewer.id 的行。对于公共目录（例如 status: "published" 的 Task），请使用带关联集合的 role.scope，或单独创建一个可供 Agent 使用的投影（路线图中规划）。

---

限制（1.0）

• 仅支持 tools 和 resources。prompts／completion — 已列入路线图。
• 引导程序从本地 FS 读取本体。SaaS 版本（从 DB/API 读取本体）— 后续推出。
• 身份验证：邮箱／密码登录。PAT／OAuth2 — 后续推出。
• 仅同步（POST /exec）。长时运行任务将通过 MCP tasks API 支持 — 后续推出。

链接

• 首页和演示： fold.intent-design.tech
• 快速入门： intent-driven-software/fold-runtime-quickstart
• 宿主运行时： DubovskiyIM/idf
• 为什么需要运行时层： 论文 — 一篇约 1800 字的文章，探讨它所回答的 Agent 安全类别问题
• MCP 规范： modelcontextprotocol.io

许可证

MIT