Idf Mcp

io.github.intent-driven-software由 GitHub 帳號 intent-driven-software 發布v1.0.2更新於 Oct 24, 2026

Turn an IDF domain into an MCP server with invariants and role scopes in every tool description.

已驗證STDIO僅桌面開發者工具安全與監控

概覽

AI 產生的概覽

本機 stdio MCP 轉接器,把 IDF 領域的意圖公開為工具,並在每個工具描述中帶上不變量、角色範圍與結構化拒絕資訊。

可以做什麼
把 IDF 領域中可由代理執行的每個意圖公開為 MCP 工具,輸入結構來自意圖參數,描述中包含前置條件、相關領域不變量與不可逆警告,高不可逆意圖還會標示破壞性提示。以資源形式讀取依角色可見範圍過濾的集合,並依檢視者裁剪。從宿主執行環境接收結構化 JSON 拒絕而非一般錯誤,方便助理調整後續動作。首次連線時可從本機本體路徑引導領域,或在宿主已載入時跳過引導。
適用情境
當你執行 Fold/IDF 宿主執行環境,希望 Claude Desktop、Cursor 或 Zed 在能看到領域規則與角色範圍的情況下呼叫某個領域的意圖,而不是使用只描述介面形狀的手寫 MCP 伺服器時適用。
執行需求
以 npm 套件形式透過 stdio 在本機執行。需要可存取的 IDF 宿主執行環境(IDF_SERVER,預設 指定的領域名稱,以及正確撰寫的領域(含代理角色、canExecute 意圖、visibleFields 與伺服器端效果建構器)。IDF_BOOTSTRAP 開啟時使用 IDF_ONTOLOGY_PATH;IDF_AUTH_TOKEN 為選用。
安裝前請注意
工具會執行真實的領域操作,包括釋放託管付款等不可逆操作;執行環境負責落實預先核准與角色範圍,但領域必須撰寫正確,否則工具可能為空或呼叫被拒。IDF_AUTH_TOKEN 是作為代理角色憑證轉送的密鑰。引導會讀取本機檔案系統路徑中的本體檔案。此版本僅支援電子郵件/密碼登入。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Idf Mcp,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

@intent-driven/mcp-server

[CI] [npm version] [npm downloads] [license: MIT]

Stop giving AI agents API keys. Give them a domain.

@intent-driven/mcp-server exposes any IDF domain to Claude Desktop / Cursor / Zed as a Model Context Protocol server — with domain semantics in tool descriptions (preconditions, invariants, irreversibility, role scopes) and structured rejections when the agent tries something it shouldn't. Not a 500. Not a string. A JSON shape the LLM can read and adapt to.

→ Landing & demo: fold.intent-design.tech → 5-min quickstart: github.com/intent-driven-software/fold-runtime-quickstart

70-second walkthrough

[Watch the demo on Loom]

→ Watch on Loom →


Why this exists

On April 25 2026 a Cursor agent powered by Claude Opus 4.6, working on a credential mismatch in PocketOS staging, found an unrelated API token, decided to delete a Railway volume to fix things, and wiped the production database and all volume-level backups in 9 seconds. The agent's own post-mortem:

"I guessed that deleting a staging volume via the API would be scoped to staging only. I didn't verify. I didn't check if the volume ID was shared across environments."

30-hour outage. PocketOS rolled back to a 3-month-old backup. (The Register · FastCompany · OECD AI Incident #6153)

This isn't an alignment problem. The system never told the agent what was allowed, why it shouldn't, or what would happen if it tried. Existing MCP servers don't either — tool descriptions carry endpoint shape and not much else. The agent learns by colliding with 500s.

This package fixes that. The MCP tool descriptions carry the why the call might fail; the rejection carries the what failed, structured.

How it plugs into your stack

@intent-driven/mcp-server is a stdio MCP adapter that talks to a Fold runtime over an HTTP API. The runtime is a sibling service — not middleware in your existing app, not codegen at runtime. Your current backend stays where it is; the IDF artifact describes the agent-facing surface, and the runtime serves it on its own port (default :3001).

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

The MCP server is what Claude/Cursor connects to. The runtime is what enforces the rejection. The IDF artifact is what you author.

Who this is for. You're the engineer at a 5–30-person team putting an AI agent into production this quarter — on top of a real backend, with real customers, real SOC2 review on the horizon. You don't want a guardrail layer that reviews after the fact. You want the system itself to refuse the wrong action — before the call, with a structured reason the agent can read.

What the agent actually sees

submit_response in the freelance domain:

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 in the same domain:

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, ...

None of this is hand-written for the MCP server. It's all derived from one declarative IDF artifact (entities + intents + invariants + roles

  • irreversibility points).

What a structured rejection looks like

Agent submits a $50,000 BTC long without preapproval. The runtime intercepts before any effect lands in storage:

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

The next move for any sane agent: stop, ask the human for a preapproval, retry. Not a 500. Not a string. A JSON shape the LLM can read and adapt to.


Quickstart

The fastest path is the fold-runtime-quickstart — two commands, Docker-bundled, no path configuration:

bash
git clone https://github.com/intent-driven-software/fold-runtime-quickstart && cd $_docker compose up                  # ~3 min first time, ~5 sec after
# in another terminalnpm installnpm 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

If you'd rather drive the host yourself (e.g. for development against your own ontologies), see the next section.

Drive the MCP server directly

You need a running IDF host on localhost:3001 (the quickstart's docker-compose gives you that, or run idf manually) and a bootstrapped domain.

CLI

bash
# 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

Flags / env vars:

FlagEnv varDefault
--domainIDF_DOMAINbooking
--serverIDF_SERVERhttp://localhost:3001
--ontology-pathIDF_ONTOLOGY_PATH./src/domains/<domain>
--agent-emailIDF_AGENT_EMAILmcp-agent@local
--no-bootstrapIDF_BOOTSTRAP=0bootstrap on (load FS ontology)

Claude Desktop

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

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 if the host already has the domain loaded (the quickstart container does this on docker compose up). Restart Claude Desktop fully (⌘Q + relaunch — closing the window isn't enough). All agent-callable intents appear in the Tools menu.


Schema mapping

IDF intent.canExecute              ─→  MCP toolintent.parameters                  ─→  JSON Schema inputSchemaintent.conditions                  ─→  description hint for LLMontology.invariants (relevant)     ─→  description block "May fail on"intent.irreversibility:high        ─→  annotations.destructiveHint + warningrole.visibleFields                 ─→  resource per collectionpreapproval guard                  ─→  automatic scope/limitscheckOwnership                     ─→  automatic access control

Tools

One tool per intent in ontology.roles.agent.canExecute.

  • name — intentId
  • title — intent.name
  • description — intent.description + Creates: … + preconditions + May fail on (domain invariants) block + irreversibility warning when irreversibility: "high"
  • inputSchema — JSON Schema from particles.parameters:
    • entityRef / id / text / textarea / select → string
    • number → number
    • boolean → boolean
    • datetime → string + format: "date-time"
    • email → string + format: "email"
  • annotations.destructiveHint — true when intent.irreversibility === "high" (§23 IDF: effect-level point of no return)

Resources

One resource per collection in role.visibleFields[entity]. URI scheme: idf://<domain>/<collection>.

resources/read returns the filtered world from /api/agent/:domain/world — already scoped per viewer (single-owner

  • m2m via role.scope).

What this gets you that hand-rolled MCP doesn't

The MCP community solves these by hand in every server:

  1. Scope / visibility. Decorators or middleware. → IDF declares role.visibleFields.
  2. Permissions. OAuth scopes, custom ACL. → IDF declares roles.agent.canExecute.
  3. Rate limits / spending caps. Bespoke per server. → IDF declares preapproval.requiredFor with maxAmount / dailySum.
  4. Destructive hints. Manual, often forgotten. → IDF: effect.context.__irr.point === "high" → destructiveHint: true automatic.
  5. Business rules as LLM hint. Usually not transmitted. → IDF: intent.conditions land in tool description as Preconditions:.
  6. Domain invariants in descriptions. Almost never. → IDF computes the relevant invariants per intent (alpha × entity match) and injects them as May fail on (domain invariants). Closes the #1 complaint about hand-rolled MCP servers: "the server doesn't carry domain semantics — the LLM knows what to call but not why it'll fail."

How long does authoring an IDF artifact take

Three reference points from the public IDF host runtime:

DomainShapeTime
invest14 entities · 61 intents · 5 invariants · ~600 linesa weekend, hand-written
gravitino253 entities (Apache catalog OpenAPI) · 120 intentsimported in <1h, enriched in 2 days
workflow9 entities · 47 intents · timer queue · cascade rulesa day

Where the speed comes from (all in @intent-driven/cli):

  • idf import postgres — reads your live schema, generates entity baseline with FKs and column types as fieldRole.
  • idf import openapi — reads your existing API spec, generates intents
    • parameter shapes + reference fields. This is how a 253-entity domain gets bootstrapped.
  • idf import prisma — same story for ORM-driven backends.
  • idf enrich — LLM pass to fill label, fieldRole, compositions, suggested roles.agent.preapproval predicates from your existing code comments.

The author-once-then-forget loop is the whole point. Once the artifact exists, you don't regenerate scaffolding on schema change — the runtime re-reads and serves four readers (UI, voice, agent, document) off the same file.


Domain prerequisites

The protocol is reliable, but it needs the IDF domain to be authored correctly. Without these, tools/list may return empty, tools/call may return domain_not_supported, resources may be empty:

  1. ontology.roles.agent must be declared. No agent role → no tools, no resources.
  2. role.agent.canExecute — list of safe intents. Avoid __irr:high without preapproval.
  3. role.agent.visibleFields — array of fields or "own" / "all" / "aggregated" markers.
  4. Server-side effect builder (server/schema/effectBuildersRegistry.cjs in idf) must include your domain. Without it tools/call returns domain_not_supported.
  5. Public catalogs without ownerField. When an entity has ownerField, the SDK filterWorldForRole filters out rows where row[ownerField] !== viewer.id. For public catalogs (e.g. Task with status: "published") use role.scope with a via-collection or a separate agent-roleable projection (roadmap).

Limitations (1.0)

  • tools and resources only. prompts / completion — roadmap.
  • Bootstrap reads ontology from local FS. SaaS variant (ontology from DB/API) — next.
  • Auth: email/password login. PAT / OAuth2 — next.
  • Sync only (POST /exec). Long-running via MCP tasks API — next.

Links

License

MIT

來源:README.md,提交 5794c16

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v1.0.2最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分