@xano/xanoscript-language-server 12.16.6 → 12.18.0

package/onHover/PolicyMessageProvider.js

@@ -0,0 +1,142 @@
+import { CommentToken } from "../lexer/comment.js";
+import {
+  ColonToken,
+  EqualToken,
+  LCurly,
+  LSquare,
+  RCurly,
+  RSquare,
+} from "../lexer/control.js";
+import { SingleQuotedStringLiteral, StringLiteral } from "../lexer/literal.js";
+import { PolicyToken } from "../lexer/policy.js";
+import { Identifier, NewlineToken } from "../lexer/tokens.js";
+import { getPolicyCatalogue } from "../parser/policy/catalogue.js";
+import { checkMarkdown, paramMarkdown } from "../parser/policy/policyDocs.js";
+import { isA, own, policyStringValue } from "../parser/policy/policyLiteral.js";
+import { HoverMessageProvider } from "./HoverMessageProvider.js";
+
+const isString = (token) => isA(token, StringLiteral) || isA(token, SingleQuotedStringLiteral);
+
+const unquote = policyStringValue;
+
+/** The key a value at `k` belongs to: the word before the `=` or `:` just before it. */
+function keyBefore(tokens, k) {
+  const sep = tokens[k - 1];
+  if ((isA(sep, EqualToken) || isA(sep, ColonToken)) && isA(tokens[k - 2], Identifier)) {
+    return tokens[k - 2].image;
+  }
+  return null;
+}
+
+/** The first word on the line holding token `k`. */
+function lineHead(tokens, k) {
+  if (tokens[k - 1]?.image === "rule" && tokens[k - 2]?.image !== "policy") return "rule";
+  let j = k;
+  while (j > 0 && !isA(tokens[j - 1], NewlineToken)) j--;
+  return isA(tokens[j], Identifier) ? tokens[j].image : null;
+}
+
+/**
+ * The blocks open at `index`, outermost first, each with the check its rule names (read from the
+ * whole rule, so a `check` written after `params` still counts).
+ */
+function framesAt(tokens, index) {
+  const stack = [];
+  let at = null;
+  for (let k = 0; k < tokens.length; k++) {
+    if (k === index) at = [...stack];
+    const token = tokens[k];
+    if (isA(token, LCurly) || isA(token, LSquare)) {
+      stack.push({
+        owner: keyBefore(tokens, k) ?? (isA(token, LCurly) ? lineHead(tokens, k) : null),
+        check: null,
+      });
+    } else if (isA(token, RCurly) || isA(token, RSquare)) {
+      stack.pop();
+      // Past the block that holds `index`: nothing later can change what it names.
+      if (at && stack.length < 2) break;
+    } else if (isString(token) && keyBefore(tokens, k) === "check" && stack.length) {
+      stack[stack.length - 1].check = unquote(token.image).trim();
+    }
+  }
+  return at ?? [];
+}
+
+/** Markdown for a policy or rule field, from the catalogue's `document`. */
+function fieldMarkdown(name, spec) {
+  const lines = [`**${name}** (${spec.type ?? "string"}${spec.required ? ", required" : ""})`];
+  if (spec.description) lines.push("", spec.description);
+  if (spec.values?.length) lines.push("", `One of: ${spec.values.map((v) => "`" + v + "`").join(", ")}.`);
+  if (spec.default !== undefined) lines.push("", `Default: \`${spec.default}\``);
+  return lines.join("\n");
+}
+
+/**
+ * Hover inside a `policy` document: a policy or rule field shows what it is for; a rule's check id
+ * shows what the check does and its params; a param (or an object param's field) shows its type,
+ * values, default and description. All of it is rendered from the check catalogue the host loaded.
+ */
+export class PolicyMessageProvider extends HoverMessageProvider {
+  /**
+   * @returns {{kind: "field", name: string, spec: Object} | {kind: "check", check: Object}
+   *   | {kind: "param", check: Object, path: string, spec: Object} | null}
+   */
+  resolve(index, tokens) {
+    const head = tokens.find((t) => !isA(t, NewlineToken) && !isA(t, CommentToken));
+    if (!isA(head, PolicyToken)) return null;
+    const catalogue = getPolicyCatalogue();
+    if (!catalogue.source) return null;
+
+    const token = tokens[index];
+    const frames = framesAt(tokens, index);
+    const [policy, rule, params, nested] = frames;
+    if (policy?.owner !== "policy") return null;
+
+    // A field name: `name =` in the policy or in a rule.
+    if (isA(token, Identifier) && isA(tokens[index + 1], EqualToken)) {
+      const fields =
+        frames.length === 1
+          ? catalogue.document?.fields
+          : frames.length === 2 && rule?.owner === "rule"
+            ? catalogue.document?.rule
+            : null;
+      const spec = own(fields, token.image);
+      return spec ? { kind: "field", name: token.image, spec } : null;
+    }
+    if (rule?.owner !== "rule") return null;
+
+    if (frames.length === 2 && isString(token) && keyBefore(tokens, index) === "check") {
+      const check = catalogue.checks.get(unquote(token.image).trim());
+      return check ? { kind: "check", check } : null;
+    }
+
+    const check = catalogue.checks.get(rule.check ?? "");
+    if (!check || params?.owner !== "params" || !isA(token, Identifier) || !isA(tokens[index + 1], ColonToken)) {
+      return null;
+    }
+    if (frames.length === 3) {
+      const spec = own(check.params, token.image);
+      return spec ? { kind: "param", check, path: token.image, spec } : null;
+    }
+    if (frames.length === 4) {
+      const spec = own(own(check.params, nested.owner)?.properties, token.image);
+      return spec
+        ? { kind: "param", check, path: `${nested.owner}.${token.image}`, spec }
+        : null;
+    }
+    return null;
+  }
+
+  isMatch(index, tokens) {
+    return this.resolve(index, tokens) !== null;
+  }
+
+  render(index, tokens) {
+    const found = this.resolve(index, tokens);
+    if (!found) return "";
+    if (found.kind === "field") return fieldMarkdown(found.name, found.spec);
+    return found.kind === "check"
+      ? checkMarkdown(found.check, getPolicyCatalogue())
+      : paramMarkdown(found.check.id, found.path, found.spec);
+  }
+}

package/onHover/functions.md

@@ -473,6 +473,45 @@ Calls an internal Xano AI tool, it allows you to invoke internal tools within yo
 - `tool.call` takes the name of the tool as an argument.
 - `input`: The input parameters for the tool.
 
+# mcp.elicit
+
+```xs
+mcp.elicit {
+  key = "confirm"
+  message = "Delete order " ~ $input.order_id ~ "?"
+  input {
+    bool proceed
+    text reason?
+  }
+} as $answer
+```
+
+Asks the MCP client for input while a tool, prompt or resource runs. `$answer` is `{action, content}`, where `action` is `accept`, `decline` or `cancel`, and `content` holds the `input` fields on `accept`.
+
+- `key`: required. Identifies the answer across retries; use a distinct key per elicit.
+- `message`: required. The question shown to the user.
+- `input`: optional. The form fields, same grammar as a tool's `input` block.
+
+**Input is only collected from `2026-07-28` clients with form elicitation.** Every other client, and a run outside MCP, gets `{action: "cancel"}`, so always handle the `cancel` branch.
+
+The client retries the WHOLE request with each answer, so every statement before the elicit runs again on each round trip. Put writes (`db.add`, `db.edit`, a non-GET `api.request`, `util.send_email`, `function.run`) after the last `mcp.elicit`.
+
+# mcp.progress
+
+```xs
+mcp.progress {
+  progress = $index
+  total = $count
+  message = "Processing " ~ $index ~ " of " ~ $count
+}
+```
+
+Sends an MCP `notifications/progress` update to the client while a tool, prompt or resource runs. It does nothing outside an MCP request, or when the client sent no progress token.
+
+- `progress`: required. Must increase on every call; a value that does not is dropped.
+- `total`: optional. The expected final value.
+- `message`: optional. A short status line.
+
 # api.lambda
 
 ```xs

package/onHover/onHover.js

@@ -7,10 +7,12 @@ import { InputFilterMessageProvider } from "./InputFilterMessageProvider.js";
 import inputFiltersMd from "./inputFilters.md";
 import { InputVariableMessageProvider } from "./InputVariableMessageProvider.js";
 import { onHoverDocument } from "./onHoverDocument.js";
+import { PolicyMessageProvider } from "./PolicyMessageProvider.js";
 import { QueryFilterMessageProvider } from "./queryFilterMessageProvider.js";
 import queryFiltersMd from "./queryFilters.md";
 
 const hoverProviders = [
+  new PolicyMessageProvider(), // Check ids and params in a policy, from the check catalogue
   new InputVariableMessageProvider(),
   new FunctionMessageProvider(functionsMd),
   new InputFilterMessageProvider(inputFiltersMd), // Input filters (columnDefinition context)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/xanoscript-language-server",
-  "version": "12.16.6",
+  "version": "12.18.0",
   "description": "Language Server Protocol implementation for XanoScript",
   "type": "module",
   "main": "server.js",
@@ -18,6 +18,7 @@
     "onCheckError/",
     "onCompletion/contentAssist.js",
     "onCompletion/onCompletion.js",
+    "onCompletion/policyCompletion.js",
     "onDefinition/onDefinition.js",
     "onDidChangeContent/",
     "onHover/",
@@ -47,6 +48,7 @@
     "lint": "eslint . --ext .js",
     "lint:fix": "eslint . --ext .js --fix",
     "tm": "node ./toTmLanguage.js",
+    "gen:policy-catalogue": "node scripts/gen-policy-catalogue.mjs",
     "prepare": "husky"
   },
   "dependencies": {

package/parser/base_parser.js

@@ -306,6 +306,8 @@ export class XanoBaseParser extends CstParser {
     this.warnings = [];
     this.informations = [];
     this.hints = [];
+    // write-before-elicit lint state (parser/functions/mcp/elicitLint.js)
+    this.__mcpElicitLint = { mutations: [], checked: 0 };
     this.__symbolTable = {
       input: {},
       var: {},

package/parser/clauses/inputClause.js

@@ -6,7 +6,9 @@ import { InputToken, NewlineToken } from "../../lexer/tokens.js";
  * @param {import('../base_parser.js').XanoBaseParser} $
  */
 export function inputClause($) {
-  return () => {
+  // `fields` collects the top-level fields (not nested object schema fields),
+  // keyed by name: { typeToken, nameToken, iterable }
+  return (fields = {}) => {
     $.sectionStack.push("inputClause");
 
     let hasStatement = false;
@@ -24,11 +26,18 @@ export function inputClause($) {
         $.SUBRULE($.optionalCommentBlockFn);
 
         $.OR([
-          { ALT: () => $.SUBRULE($.objectColumnDefinition) },
-          { ALT: () => $.SUBRULE($.enumColumnDefinition) },
           {
             ALT: () =>
-              $.SUBRULE($.columnDefinition, { ARGS: [{ include_file: true }] }),
+              $.SUBRULE($.objectColumnDefinition, { ARGS: [fields] }),
+          },
+          {
+            ALT: () => $.SUBRULE($.enumColumnDefinition, { ARGS: [fields] }),
+          },
+          {
+            ALT: () =>
+              $.SUBRULE($.columnDefinition, {
+                ARGS: [{ include_file: true }, fields],
+              }),
           },
           {
             ALT: () => $.SUBRULE($.dbLinkColumnDefinition),

package/parser/clauses/mcpMetadataClauses.js

@@ -0,0 +1,252 @@
+import { EqualToken } from "../../lexer/control.js";
+import {
+  SingleQuotedStringLiteral,
+  StringLiteral,
+} from "../../lexer/literal.js";
+import { AnnotationsToken, IconsToken, TitleToken } from "../../lexer/mcp.js";
+import { MultiLineStringToken } from "../../lexer/multiline.js";
+
+// Shared MCP metadata blocks for `tool`, `prompt` and `resource` (MCP spec
+// 2026-07-28). The rules mirror cloud-client's decode checks so the editor
+// reports what a push would refuse:
+//   - `helper/mvp/mcpserver/ToolMetadata.php` (icons, tool annotations)
+//   - `helper/script/transform/Resource.php` (resource annotations)
+
+export const ICON_MIME_TYPES = ["image/png", "image/jpeg", "image/webp"];
+export const ICON_URL_MAX_LENGTH = 2048;
+export const ICON_DATA_MAX_BYTES = 65536;
+export const RESOURCE_AUDIENCES = ["user", "assistant"];
+
+const ICON_SCHEMA = {
+  src: "[string]",
+  // validated below: cloud-client compares it lowercased and allows ""
+  "mime_type?": "[string]",
+  "sizes?": ["[string]"],
+  "theme?": ["light", "dark"],
+};
+
+const ISO_8601 =
+  /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+
+/**
+ * The value of a token that `[string]` accepts ("...", '...' or a """ block),
+ * or null for anything else (an expression, a variable).
+ * @param {import('chevrotain').IToken} [token]
+ * @returns {string|null}
+ */
+function stringValue(token) {
+  switch (token?.tokenType) {
+    case StringLiteral:
+    case SingleQuotedStringLiteral:
+      return token.image.slice(1, -1);
+    case MultiLineStringToken:
+      return token.image.slice(3, -3).trim();
+    default:
+      return null;
+  }
+}
+
+/**
+ * Why an icon `src` is refused, or null. Same rules as ToolMetadata::srcProblem:
+ * `https:` or a base64 `data:` URI of png/jpeg/webp. SVG and every other scheme
+ * (`http:`, `javascript:`, `file:`, ...) are refused.
+ * @param {string} src
+ * @returns {string|null}
+ */
+export function iconSrcProblem(src) {
+  const lower = src.toLowerCase();
+
+  if (lower.startsWith("https://")) {
+    if (src.length > ICON_URL_MAX_LENGTH) {
+      return `icon src is longer than ${ICON_URL_MAX_LENGTH} characters`;
+    }
+    let host = "";
+    try {
+      host = new URL(src).hostname;
+    } catch {
+      host = "";
+    }
+    if (!host || /\s/.test(src)) {
+      return "icon src is not a valid https URL";
+    }
+    return null;
+  }
+
+  if (lower.startsWith("data:")) {
+    const match = src.match(/^data:([a-z0-9.+/-]+);base64,([A-Za-z0-9+/]*={0,2})$/i);
+    if (!match) {
+      return "icon data: src must be base64 image data";
+    }
+    const mime = match[1].toLowerCase();
+    if (!ICON_MIME_TYPES.includes(mime)) {
+      return `icon data: src must be ${ICON_MIME_TYPES.join(", ")} — got "${mime}"`;
+    }
+    const payload = match[2];
+    if (payload.length === 0) {
+      return "icon data: src must be base64 image data";
+    }
+    const padding = payload.endsWith("==") ? 2 : payload.endsWith("=") ? 1 : 0;
+    if ((payload.length * 3) / 4 - padding > ICON_DATA_MAX_BYTES) {
+      return `icon data: src is larger than ${ICON_DATA_MAX_BYTES} bytes`;
+    }
+    return null;
+  }
+
+  const scheme = src.includes(":") ? src.split(":")[0] + ":" : src.slice(0, 20);
+  return `icon src must be https: or a data: image — got "${scheme}"`;
+}
+
+/**
+ * title = "Human readable name"
+ * @param {import('../base_parser.js').XanoBaseParser} $
+ */
+export function mcpTitleClause($) {
+  return () => {
+    $.sectionStack.push("mcpTitleClause");
+    $.CONSUME(TitleToken); // "title"
+    $.CONSUME(EqualToken); // "="
+    const value = $.CONSUME(StringLiteral); // "..."
+    if (value.image === `""`) {
+      $.addMissingError(value, "title cannot be empty");
+    }
+    $.sectionStack.pop();
+  };
+}
+
+/**
+ * icons = [{ src: "https://...", mime_type: "image/png", sizes: ["48x48"], theme: "light" }]
+ * @param {import('../base_parser.js').XanoBaseParser} $
+ */
+export function mcpIconsClause($) {
+  return () => {
+    $.sectionStack.push("mcpIconsClause");
+    const parent = $.CONSUME(IconsToken); // "icons"
+    $.CONSUME(EqualToken); // "="
+
+    const captured = {};
+    $.SUBRULE($.schemaParseArrayFn, { ARGS: [parent, [ICON_SCHEMA], captured] });
+
+    $.ACTION(() => {
+      for (const icon of captured.value || []) {
+        const srcToken = icon.src?.value;
+        const src = stringValue(srcToken);
+        if (src !== null) {
+          const problem = iconSrcProblem(src);
+          if (problem) {
+            $.addInvalidValueError(srcToken, problem);
+          }
+        }
+
+        const mimeToken = icon.mime_type?.value;
+        const mime = stringValue(mimeToken);
+        if (mime !== null) {
+          if (mime !== "" && !ICON_MIME_TYPES.includes(mime.toLowerCase())) {
+            $.addInvalidValueError(
+              mimeToken,
+              `icon mime_type must be one of ${ICON_MIME_TYPES.join(", ")} — got "${mime}"`,
+            );
+          }
+        }
+
+        for (const size of icon.sizes?.value || []) {
+          const sizeToken = size?.value;
+          const value = stringValue(sizeToken);
+          if (value === null) continue;
+          if (!/^(\d{1,5}x\d{1,5}|any)$/.test(value)) {
+            $.addInvalidValueError(
+              sizeToken,
+              `icon size must be WxH or "any" — got "${value}"`,
+            );
+          }
+        }
+      }
+    });
+    $.sectionStack.pop();
+  };
+}
+
+/**
+ * annotations = { read_only_hint: true, destructive_hint: false, ... } (tool)
+ * @param {import('../base_parser.js').XanoBaseParser} $
+ */
+export function mcpToolAnnotationsClause($) {
+  return () => {
+    $.sectionStack.push("mcpToolAnnotationsClause");
+    const parent = $.CONSUME(AnnotationsToken); // "annotations"
+    $.CONSUME(EqualToken); // "="
+    $.SUBRULE($.schemaParseObjectFn, {
+      ARGS: [
+        parent,
+        {
+          "read_only_hint?": "[boolean]",
+          "destructive_hint?": "[boolean]",
+          "idempotent_hint?": "[boolean]",
+          "open_world_hint?": "[boolean]",
+        },
+      ],
+    });
+    $.sectionStack.pop();
+  };
+}
+
+/**
+ * annotations = { audience: ["user"], priority: 0.5, last_modified: "2025-01-12T15:00:58Z" } (resource)
+ * @param {import('../base_parser.js').XanoBaseParser} $
+ */
+export function mcpResourceAnnotationsClause($) {
+  return () => {
+    $.sectionStack.push("mcpResourceAnnotationsClause");
+    const parent = $.CONSUME(AnnotationsToken); // "annotations"
+    $.CONSUME(EqualToken); // "="
+
+    const captured = {};
+    $.SUBRULE($.schemaParseObjectFn, {
+      ARGS: [
+        parent,
+        {
+          "audience?": ["[string]"],
+          "priority?": "[number]",
+          "last_modified?": "[string]",
+        },
+        captured,
+      ],
+    });
+
+    $.ACTION(() => {
+      for (const role of captured.audience?.value || []) {
+        const roleToken = role?.value;
+        const value = stringValue(roleToken);
+        if (value === null) continue;
+        if (!RESOURCE_AUDIENCES.includes(value)) {
+          $.addInvalidValueError(
+            roleToken,
+            `resource annotation audience must be user or assistant — got "${value}"`,
+          );
+        }
+      }
+
+      const priorityToken = captured.priority?.value;
+      if (priorityToken) {
+        const priority = Number(priorityToken.image);
+        if (Number.isFinite(priority) && (priority < 0 || priority > 1)) {
+          $.addInvalidValueError(
+            priorityToken,
+            `resource annotation priority must be from 0 to 1 — got ${priorityToken.image}`,
+          );
+        }
+      }
+
+      const modifiedToken = captured.last_modified?.value;
+      const value = stringValue(modifiedToken);
+      if (value !== null) {
+        if (!ISO_8601.test(value) || Number.isNaN(Date.parse(value))) {
+          $.addInvalidValueError(
+            modifiedToken,
+            `resource annotation last_modified must be an ISO 8601 date, e.g. "2025-01-12T15:00:58Z"`,
+          );
+        }
+      }
+    });
+    $.sectionStack.pop();
+  };
+}

package/parser/clauses/nakedStackFn.js

@@ -2,6 +2,7 @@ import { ExclamationToken } from "../../lexer/cast.js";
 import { CommentToken } from "../../lexer/comment.js";
 import { LCurly, RCurly } from "../../lexer/control.js";
 import { NewlineToken } from "../../lexer/tokens.js";
+import { recordStatement } from "../functions/mcp/elicitLint.js";
 
 export const DEFAULT_OPTIONS = {
   allowCallStatements: false,
@@ -26,6 +27,10 @@ export function nakedStackFn($) {
         {
           ALT: () => {
             $.OPTION(() => $.CONSUME(ExclamationToken)); // optional "!" to continue on error
+            let startIdx;
+            $.ACTION(() => {
+              startIdx = $.exportLexerState() + 1;
+            });
             $.OR1([
               { ALT: () => $.SUBRULE($.aiFn) },
               { ALT: () => $.SUBRULE($.dbFn) },
@@ -37,6 +42,7 @@ export function nakedStackFn($) {
               { ALT: () => $.SUBRULE($.textFn) },
               { ALT: () => $.SUBRULE($.utilFn) },
               { ALT: () => $.SUBRULE($.realtimeFn) },
+              { ALT: () => $.SUBRULE($.mcpFn) },
               { ALT: () => $.SUBRULE($.preconditionFn) },
               { ALT: () => $.SUBRULE($.zipFn) },
               { ALT: () => $.SUBRULE($.objectFn) },
@@ -67,6 +73,8 @@ export function nakedStackFn($) {
               },
               { ALT: () => $.SUBRULE($.workflowExpectFn) },
             ]);
+            // write-before-elicit lint (see functions/mcp/elicitLint.js)
+            $.ACTION(() => recordStatement($, startIdx));
           },
         },
       ]);

package/parser/clauses/register.js

@@ -8,6 +8,12 @@ import { flexibleStringClause } from "./flexibleStringClause.js";
 import { historyClause } from "./historyClause.js";
 import { indexClause } from "./indexClause.js";
 import { inputClause } from "./inputClause.js";
+import {
+  mcpIconsClause,
+  mcpResourceAnnotationsClause,
+  mcpTitleClause,
+  mcpToolAnnotationsClause,
+} from "./mcpMetadataClauses.js";
 import { mcpServerClause } from "./mcpServerClause.js";
 import { middlewareClause } from "./middlewareClause.js";
 import { nakedStackFn } from "./nakedStackFn.js";
@@ -40,6 +46,16 @@ export const register = ($) => {
   $.inputClause = $.RULE("inputClause", inputClause($));
   $.outputClause = $.RULE("outputClause", outputClause($));
   $.mcpServerClause = $.RULE("mcpServerClause", mcpServerClause($));
+  $.mcpTitleClause = $.RULE("mcpTitleClause", mcpTitleClause($));
+  $.mcpIconsClause = $.RULE("mcpIconsClause", mcpIconsClause($));
+  $.mcpToolAnnotationsClause = $.RULE(
+    "mcpToolAnnotationsClause",
+    mcpToolAnnotationsClause($)
+  );
+  $.mcpResourceAnnotationsClause = $.RULE(
+    "mcpResourceAnnotationsClause",
+    mcpResourceAnnotationsClause($)
+  );
   $.realtimeServerClause = $.RULE(
     "realtimeServerClause",
     realtimeServerClause($)

package/parser/definitions/columnDefinition.js

@@ -142,6 +142,7 @@ export function columnDefinition($) {
     schema[getVarName(nameToken)] = {
       typeToken: inputTypeToken,
       nameToken: nameToken,
+      iterable,
     };
 
     // add the variable to the registry

package/parser/definitions/enumColumnDefinition.js

@@ -36,6 +36,7 @@ export function enumColumnDefinition($) {
     schema[getVarName(name)] = {
       typeToken: parent,
       nameToken: name,
+      iterable,
     };
 
     // ? (is it an optional field)

package/parser/definitions/objectColumnDefinition.js

@@ -41,6 +41,7 @@ export function objectColumnDefinition($) {
     schema[getVarName(name)] = {
       typeToken: parent,
       nameToken: name,
+      iterable,
     };
 
     // ? (is it an optional field)