Tools

render_datachain

Render a datachain instance as an MCP App HTML document served via resources/read.

render_datachain

This tool produces an MCP App — an HTML document an MCP client can embed in an iframe. The tool response carries a short text summary plus _meta.ui.resourceUri; the client follows with resources/read on the same session to fetch the HTML.

Summary

Runs the same semantic validation as validate_datachain. On success, renders the instance through @dtpr/ui/html's renderDatachainDocument and stores the result in the session's MCP App slot. On semantic failure, returns a soft-failure envelope without rendering.

Input

Field	Type	Required	Default	Description
`version`	`string`	yes	—	Pinned schema version, e.g. `"ai@2026-04-16-beta"`.
`datachain`	`object`	yes	—	Datachain instance JSON.
`locale`	`string`	no	`"en"`	Locale used for rendered strings.

Output — success

{
  "structuredContent": {
    "ok": true,
    "data": {
      "resource_uri": "ui://dtpr/datachain/view.html",
      "section_count": 4,
      "element_count": 7,
      "warnings": []
    },
    "meta": { "content_hash": "sha256-…", "version": "ai@2026-04-16-beta" }
  },
  "content": [
    {
      "type": "text",
      "text": "Rendered DTPR datachain with 4 categories and 7 total elements. UI available at ui://dtpr/datachain/view.html.\n- Purpose (2 elements): …"
    }
  ],
  "_meta": {
    "ui": {
      "resourceUri": "ui://dtpr/datachain/view.html",
      "csp": { "resourceDomains": [], "connectDomains": [] }
    }
  }
}

_meta.ui.resourceUri is the MCP Apps pointer. Follow up with resources/read on the same mcp-session-id to fetch the HTML body.

Output — semantic failure (soft-failure)

{
  "ok": false,
  "errors": [
    {
      "code": "element_required",
      "message": "Category 'purpose' requires at least one element.",
      "path": "elements",
      "fix_hint": "Add an element with category_id='purpose'."
    }
  ],
  "meta": { "content_hash": "sha256-…", "version": "ai@2026-04-16-beta", "warnings": [] }
}

No HTML is written when validation fails — the previous session's document (if any) remains untouched.

Errors

Code	Meaning	Fix
`invalid_arguments`	`version` missing or `locale` invalid.	Fix the call.
`parse_error`	Datachain shape is malformed.	Follow `errors[].path`.
`unknown_version`	Version is not registered.	Call `list_schema_versions`.
Semantic validator codes	Instance is shape-valid but semantically wrong.	Follow `fix_hint`.

The two-call sequence

  ┌─ tools/call render_datachain ──┐         slot(session) ← HTML
  │   mcp-session-id: S            │────────►┌──────────┐
  │                                │         │ htmlSlots│
  │                                ◄─────────│  per S   │
  └────────────────────────────────┘         └──────────┘
                                                   ▲
  ┌─ resources/read ui://…────────┐                │
  │   mcp-session-id: S           │────────────────┘
  │                               ◄── text/html;profile=mcp-app
  └───────────────────────────────┘

The mcp-session-id header must match on both calls. See Resources for what resources/read returns when called before any render_datachain.

Example

SID=$(uuidgen)

# render
curl -s https://api.dtpr.io/mcp \
  -H 'content-type: application/json' \
  -H "mcp-session-id: $SID" \
  --data "{
    \"jsonrpc\":\"2.0\",\"id\":1,
    \"method\":\"tools/call\",
    \"params\":{
      \"name\":\"render_datachain\",
      \"arguments\":{
        \"version\":\"ai@2026-04-16-beta\",
        \"datachain\":{
          \"schema_version\":\"ai@2026-04-16-beta\",
          \"elements\":[{\"element_id\":\"purpose.example\",\"category_id\":\"purpose\"}]
        }
      }
    }
  }"

# fetch rendered HTML
curl -s https://api.dtpr.io/mcp \
  -H 'content-type: application/json' \
  -H "mcp-session-id: $SID" \
  --data '{
    "jsonrpc":"2.0","id":2,
    "method":"resources/read",
    "params":{"uri":"ui://dtpr/datachain/view.html"}
  }'

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "render_datachain",
    "arguments": {
      "version": "ai@2026-04-16-beta",
      "datachain": { "schema_version": "ai@2026-04-16-beta", "elements": [] },
      "locale": "en"
    }
  }
}