Polyxd

Returns the instructions for writing a Polyxd UI document: the document shape, the rules for generated screens, bindings, actions, every component with its props, and the patterns. Call this once before writing your first document.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "specVersion": {
      "type": "string",
      "description": "The version of the Polyxd spec this server implements, e.g. \"0.3.0\". Documents set it as their \"specVersion\"."
    },
    "guide": {
      "type": "string",
      "description": "The instructions for writing a Polyxd UI document: how to use these tools, the document shape, the rules, bindings, actions, every component with its props, and the patterns. The same text as the result's text content."
    }
  },
  "required": [
    "specVersion",
    "guide"
  ],
  "additionalProperties": false
}

Checks a Polyxd UI document against the spec: the schema, ids and references, bindings against the data, actions, and the rules for generated screens. Returns every issue with its JSON Pointer, the component it is in, and a hint saying what to change. Call it after writing or changing a document, and fix every error before showing it.

{
  "type": "object",
  "properties": {
    "document": {
      "type": "object",
      "description": "A Polyxd UI document: {specVersion, surface, root, components, data?}. polyxd_guide explains the format.",
      "additionalProperties": true
    },
    "data": {
      "type": "object",
      "description": "The values the screen shows, bound by {\"path\": \"/pointer\"}. Replaces the document's own \"data\" when given.",
      "additionalProperties": true
    }
  },
  "required": [
    "document"
  ]
}

{
  "type": "object",
  "properties": {
    "valid": {
      "type": "boolean",
      "description": "True when the document has no errors and can be shown. Warnings do not make it invalid."
    },
    "errors": {
      "type": "integer",
      "minimum": 0,
      "description": "How many errors. Fix every one before showing the document."
    },
    "warnings": {
      "type": "integer",
      "minimum": 0,
      "description": "How many warnings. Advice; they do not stop the document being shown."
    },
    "issues": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One problem in the document.",
        "properties": {
          "severity": {
            "type": "string",
            "enum": [
              "error",
              "warning"
            ],
            "description": "\"error\" must be fixed before the document is shown; \"warning\" is advice."
          },
          "pointer": {
            "type": "string",
            "description": "JSON Pointer to the problem in the document, e.g. \"/components/2/label\"."
          },
          "component": {
            "type": "object",
            "description": "The component the pointer is inside, when it is inside one.",
            "properties": {
              "id": {
                "type": "string",
                "description": "The component's id."
              },
              "type": {
                "type": "string",
                "description": "The component's type (its \"component\" value), e.g. \"TextInput\"."
              }
            },
            "additionalProperties": false
          },
          "message": {
            "type": "string",
            "description": "What is wrong."
          },
          "hint": {
            "type": "string",
            "description": "What to change to fix it, when there is a known fix."
          }
        },
        "required": [
          "severity",
          "pointer",
          "message"
        ],
        "additionalProperties": false
      },
      "description": "Every error and warning, each at its JSON Pointer with a hint. Empty when the document is clean."
    }
  },
  "required": [
    "valid",
    "errors",
    "warnings",
    "issues"
  ],
  "additionalProperties": false
}

Runs the Polyxd verifier's document checks: the spec validator, the pattern the surface declares, readable and distinct labels, one primary action per view, at most six inputs per view, entity-first flows, confirmations, and, when you pass one, a Design Direction's rules and voice. Returns a compact report. Example directions by name: calm-finance, playful-personal.

{
  "type": "object",
  "properties": {
    "document": {
      "type": "object",
      "description": "A Polyxd UI document: {specVersion, surface, root, components, data?}. polyxd_guide explains the format.",
      "additionalProperties": true
    },
    "data": {
      "type": "object",
      "description": "The values the screen shows, bound by {\"path\": \"/pointer\"}. Replaces the document's own \"data\" when given.",
      "additionalProperties": true
    },
    "direction": {
      "description": "A Design Direction to hold the document to: the direction object, or the name of an example direction.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "additionalProperties": true
        }
      ]
    },
    "registry": {
      "type": "object",
      "description": "A capability registry ({capabilities: [...]}) to check the document's actions against. Leave out when there is none.",
      "additionalProperties": true
    }
  },
  "required": [
    "document"
  ]
}

{
  "type": "object",
  "properties": {
    "errors": {
      "type": "integer",
      "minimum": 0,
      "description": "How many errors. Fix every one before showing the document."
    },
    "warnings": {
      "type": "integer",
      "minimum": 0,
      "description": "How many warnings. Advice; they do not stop the document being shown."
    },
    "findings": {
      "type": "array",
      "description": "Every check that failed. Empty when the document passes with no warnings.",
      "items": {
        "type": "object",
        "properties": {
          "severity": {
            "type": "string",
            "enum": [
              "error",
              "warning"
            ],
            "description": "\"error\" must be fixed before the document is shown; \"warning\" is advice."
          },
          "check": {
            "type": "string",
            "description": "The check that failed, e.g. \"spec\", \"data:missing-path\", \"pattern:<id>\", \"rule:<id>\", \"capability\" or \"load:inputs-per-view\"."
          },
          "message": {
            "type": "string",
            "description": "What failed; findings from the spec validator start with the JSON Pointer, as \"<pointer>: <message>\"."
          },
          "hint": {
            "type": "string",
            "description": "What to change to fix it, when there is a known fix."
          }
        },
        "required": [
          "severity",
          "check",
          "message"
        ],
        "additionalProperties": false
      }
    },
    "direction": {
      "type": "string",
      "description": "The name of the Design Direction the document was held to, when one was given and it has a name."
    },
    "rules": {
      "type": "integer",
      "minimum": 0,
      "description": "How many Design Direction rules were checked. 0 without a direction."
    }
  },
  "required": [
    "errors",
    "warnings",
    "findings",
    "rules"
  ],
  "additionalProperties": false
}

Validates a Polyxd UI document and shows it to the user as an interactive screen, drawn by the Polyxd renderer in the design-system pack you choose (default material3). Shows nothing if the document has errors; fix them first with polyxd_validate. When the user presses an action in the screen, you receive a chat message from the user naming the action and its context; that only tells you their choice, and nothing has been submitted or paid. Packs: material3, antd, bootstrap, carbon, chakra, fluent, govuk, mantine, polaris, primer, radix, shadcn, spectrum, brutalist, civic, editorial, finance, glass, health, mono, neon, pastel, sketch, terminal, wireframe.

{
  "type": "object",
  "properties": {
    "document": {
      "type": "object",
      "description": "A Polyxd UI document: {specVersion, surface, root, components, data?}. polyxd_guide explains the format.",
      "additionalProperties": true
    },
    "data": {
      "type": "object",
      "description": "The values the screen shows, bound by {\"path\": \"/pointer\"}. Replaces the document's own \"data\" when given.",
      "additionalProperties": true
    },
    "pack": {
      "type": "string",
      "description": "The design-system pack to draw the screen in, by id: material3, antd, bootstrap, carbon, chakra, fluent, govuk, mantine, polaris, primer, radix, shadcn, spectrum, brutalist, civic, editorial, finance, glass, health, mono, neon, pastel, sketch, terminal, wireframe. Names like \"Carbon\" or \"shadcn/ui\" work too. Pass it whenever the user names a design system. Default material3."
    },
    "mode": {
      "type": "string",
      "enum": [
        "light",
        "dark"
      ],
      "description": "Light or dark. Leave out to follow the host's theme."
    }
  },
  "required": [
    "document"
  ]
}

{
  "type": "object",
  "properties": {
    "shown": {
      "type": "boolean",
      "description": "Whether the screen was shown to the user. False when the document has errors."
    },
    "document": {
      "type": "object",
      "description": "The Polyxd UI document as shown, with the separately passed data merged in as its \"data\". The MCP App renders it.",
      "additionalProperties": true
    },
    "pack": {
      "type": "string",
      "enum": [
        "material3",
        "antd",
        "bootstrap",
        "carbon",
        "chakra",
        "fluent",
        "govuk",
        "mantine",
        "polaris",
        "primer",
        "radix",
        "shadcn",
        "spectrum",
        "brutalist",
        "civic",
        "editorial",
        "finance",
        "glass",
        "health",
        "mono",
        "neon",
        "pastel",
        "sketch",
        "terminal",
        "wireframe"
      ],
      "description": "The design-system pack the screen is drawn in."
    },
    "packName": {
      "type": "string",
      "description": "The pack's display name, e.g. \"Material 3\"."
    },
    "mode": {
      "type": "string",
      "enum": [
        "light",
        "dark"
      ],
      "description": "Light or dark, when one was asked for. Absent: the screen follows the host's theme."
    },
    "specVersion": {
      "type": "string",
      "description": "The version of the Polyxd spec this server implements, e.g. \"0.3.0\". Documents set it as their \"specVersion\"."
    },
    "issues": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One problem in the document.",
        "properties": {
          "severity": {
            "type": "string",
            "enum": [
              "error",
              "warning"
            ],
            "description": "\"error\" must be fixed before the document is shown; \"warning\" is advice."
          },
          "pointer": {
            "type": "string",
            "description": "JSON Pointer to the problem in the document, e.g. \"/components/2/label\"."
          },
          "component": {
            "type": "object",
            "description": "The component the pointer is inside, when it is inside one.",
            "properties": {
              "id": {
                "type": "string",
                "description": "The component's id."
              },
              "type": {
                "type": "string",
                "description": "The component's type (its \"component\" value), e.g. \"TextInput\"."
              }
            },
            "additionalProperties": false
          },
          "message": {
            "type": "string",
            "description": "What is wrong."
          },
          "hint": {
            "type": "string",
            "description": "What to change to fix it, when there is a known fix."
          }
        },
        "required": [
          "severity",
          "pointer",
          "message"
        ],
        "additionalProperties": false
      },
      "description": "When not shown: the document's errors and warnings, each at its JSON Pointer with a hint."
    }
  },
  "required": [
    "shown"
  ],
  "description": "shown is true with the document, pack and spec version when the screen was shown; false with the issues when it was not (that result is also an error).",
  "oneOf": [
    {
      "properties": {
        "shown": {
          "const": true
        }
      },
      "required": [
        "document",
        "pack",
        "packName",
        "specVersion"
      ]
    },
    {
      "properties": {
        "shown": {
          "const": false
        }
      },
      "required": [
        "issues"
      ]
    }
  ],
  "additionalProperties": false
}

Lists the design-system packs polyxd_show can draw a screen in: published design systems (Material 3, Carbon, GOV.UK and others) and original templates. The same document looks native in each.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "default": {
      "type": "string",
      "enum": [
        "material3",
        "antd",
        "bootstrap",
        "carbon",
        "chakra",
        "fluent",
        "govuk",
        "mantine",
        "polaris",
        "primer",
        "radix",
        "shadcn",
        "spectrum",
        "brutalist",
        "civic",
        "editorial",
        "finance",
        "glass",
        "health",
        "mono",
        "neon",
        "pastel",
        "sketch",
        "terminal",
        "wireframe"
      ],
      "description": "The pack polyxd_show uses when none is given."
    },
    "packs": {
      "type": "array",
      "description": "Every pack, for polyxd_show's \"pack\" argument.",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The pack's name: the value to pass as polyxd_show's \"pack\"."
          },
          "displayName": {
            "type": "string",
            "description": "The name to show people, e.g. \"IBM Carbon\"."
          },
          "template": {
            "type": "boolean",
            "description": "True for an original template to start from; false for a published design system."
          },
          "package": {
            "type": "string",
            "description": "The npm package with the pack's design tokens."
          },
          "description": {
            "type": "string",
            "description": "A one-line description of the pack."
          }
        },
        "required": [
          "name",
          "displayName",
          "template",
          "package",
          "description"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "default",
    "packs"
  ],
  "additionalProperties": false
}

Lists the semantic components a Polyxd document can use, with a one-line summary each. Pass "name" for one component's full definition: every prop and its type, which are required, when to use it and when not to, and how it renders.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "A component name, e.g. \"Choice\", for its full definition."
    }
  }
}

{
  "type": "object",
  "properties": {
    "component": {
      "type": "object",
      "description": "One component's full definition.",
      "properties": {
        "name": {
          "type": "string",
          "description": "The component's type name, the value of \"component\" in a document, e.g. \"Choice\"."
        },
        "category": {
          "type": "string",
          "description": "The component's kind: action, shell, structure, content, input, flow, layout, feedback."
        },
        "summary": {
          "type": "string",
          "description": "What the component is for, in one line."
        },
        "props": {
          "type": "object",
          "description": "Every prop, by name, as a JSON Schema. $refs point into the spec's common definitions (DynamicString, Binding, Options and so on).",
          "additionalProperties": true
        },
        "required": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The props a document must set."
        },
        "whenToUse": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "When to use this component."
        },
        "whenNotToUse": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "When not to, and what to use instead."
        },
        "shell": {
          "type": "boolean",
          "description": "True for shell components, which frame a product's screens: authored once per product, never generated."
        },
        "rendering": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "How renderers draw it."
        },
        "accessibility": {
          "type": "object",
          "description": "Its accessible role and requirements.",
          "additionalProperties": true
        },
        "agent": {
          "type": "string",
          "description": "How an agent operating the rendered screen should use it."
        }
      },
      "required": [
        "name",
        "category",
        "summary",
        "props",
        "required",
        "whenToUse",
        "whenNotToUse"
      ],
      "additionalProperties": true
    },
    "components": {
      "type": "array",
      "description": "Every component, in the spec's order.",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The component's type name. Pass it back as \"name\" for the full definition."
          },
          "category": {
            "type": "string",
            "description": "The component's kind: action, shell, structure, content, input, flow, layout, feedback."
          },
          "summary": {
            "type": "string",
            "description": "What the component is for, in one line."
          },
          "shell": {
            "type": "boolean",
            "description": "True for shell components: authored once per product, never generated. Use the others in generated screens."
          }
        },
        "required": [
          "name",
          "category",
          "summary",
          "shell"
        ],
        "additionalProperties": false
      }
    }
  },
  "description": "\"component\" when a name was given; \"components\" otherwise.",
  "oneOf": [
    {
      "required": [
        "component"
      ]
    },
    {
      "required": [
        "components"
      ]
    }
  ],
  "additionalProperties": false
}