@xano/xanoscript-language-server 12.16.6 → 12.18.0

package/parser/functions/mcp/elicitLint.js

@@ -0,0 +1,100 @@
+import { PipeToken } from "../../../lexer/control.js";
+import { StringLiteral } from "../../../lexer/literal.js";
+import { getVarName } from "../../generic/utils.js";
+
+// The write-before-elicit lint (plan KTD9). `mcp.elicit` asks the client for
+// input by ending the request with `input_required`; the client then RETRIES
+// the whole request with the answer, so every statement before the elicit runs
+// once per round trip. A write placed before the first elicit repeats.
+//
+// The mutating set is deliberately conservative: the `db.*` writes, raw SQL
+// (`db.direct_query`, `db.external.<driver>.direct_query`), an `api.request`
+// whose method is not a plain literal GET/HEAD, `util.send_email`, and
+// `function.run` (which may write anything).
+
+const DB_WRITES = [
+  "add",
+  "add_or_edit",
+  "edit",
+  "patch",
+  "del",
+  "delete",
+  "truncate",
+  "increment",
+  "bulk",
+  // raw SQL may write
+  "direct_query",
+  "external",
+];
+
+const READ_METHODS = ["GET", "HEAD"];
+
+/**
+ * The name of the mutating statement spanning `input[start..end]`, or null.
+ * Reads tokens in place: this runs for every stack statement on every parse.
+ * @param {import('chevrotain').IToken[]} input the parser's token vector
+ * @param {number} start index of the statement's first token
+ * @param {number} end index of the statement's last token
+ * @returns {string|null}
+ */
+export function mutatingStatementName(input, start, end) {
+  const ns = input[start]?.image;
+  const dot = input[start + 1]?.image;
+  const name = input[start + 2]?.image;
+  if (dot !== "." || !ns || !name) return null;
+
+  if (ns === "db" && DB_WRITES.includes(name)) return `db.${name}`;
+  if (ns === "util" && name === "send_email") return "util.send_email";
+  if (ns === "function" && name === "run") return "function.run";
+
+  if (ns === "api" && name === "request") {
+    for (let i = start + 3; i <= end - 2; i++) {
+      if (input[i].image !== "method" || input[i + 1].image !== "=") continue;
+      const value = input[i + 2];
+      // a filtered or compound method ("GET"|replace:...) is not a plain GET
+      const isPlain = input[i + 3]?.tokenType !== PipeToken;
+      if (
+        isPlain &&
+        value.tokenType === StringLiteral &&
+        READ_METHODS.includes(getVarName(value).toUpperCase())
+      ) {
+        return null;
+      }
+      return "api.request";
+    }
+    // no method: api.request defaults to GET
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Record a statement that just finished parsing (called from nakedStackFn).
+ * @param {import('../../base_parser.js').XanoBaseParser} $
+ * @param {number} startIdx lexer index of the statement's first token
+ */
+export function recordStatement($, startIdx) {
+  const name = mutatingStatementName($.input, startIdx, $.exportLexerState());
+  if (name) {
+    $.__mcpElicitLint.mutations.push({ name, token: $.input[startIdx] });
+  }
+}
+
+/**
+ * Called when an `mcp.elicit` is parsed: warn when a write ran since the
+ * previous elicit (or since the start of the stack, for the first one).
+ * @param {import('../../base_parser.js').XanoBaseParser} $
+ * @param {import('chevrotain').IToken} elicitToken
+ */
+export function checkElicit($, elicitToken) {
+  const lint = $.__mcpElicitLint;
+  const first = lint.mutations[lint.checked];
+  lint.checked = lint.mutations.length;
+  if (!first) return;
+
+  $.addWarning(
+    `\`${first.name}\` runs before this mcp.elicit. The client retries the whole request with each answer, so every statement before the elicit runs again on each round trip. Move writes after the last mcp.elicit.`,
+    elicitToken,
+  );
+}

package/parser/functions/mcp/mcpElicitFn.js

@@ -0,0 +1,103 @@
+import { EqualToken, LCurly, RCurly } from "../../../lexer/control.js";
+import { ElicitToken } from "../../../lexer/mcp.js";
+import { Identifier, NewlineToken } from "../../../lexer/tokens.js";
+import { getVarName } from "../../generic/utils.js";
+import { checkElicit } from "./elicitLint.js";
+
+// mcp.elicit {
+//   key = "confirm"                 // required: the answer's identity across retries
+//   message = "Delete " ~ $input.name ~ "?"   // required
+//   input {                         // optional: the form the client shows
+//     bool proceed
+//     text reason?
+//   }
+// } as $answer
+//
+// Asks the MCP client for input (cloud-client mvp:mcp_elicit). Input is only
+// collected from 2026-07-28 clients with form elicitation; every other client
+// (and a non-MCP run) resolves to {action: "cancel"}. The `input` block is the
+// same grammar as a tool's `input` block.
+
+const REQUIRED = ["key", "message"];
+const OPTIONAL = ["description", "disabled"];
+
+/**
+ * @param {import('../../base_parser.js').XanoBaseParser} $
+ */
+export function mcpElicitFn($) {
+  return () => {
+    const defined = [];
+    let hasInput = false;
+    let hasMock = false;
+
+    $.sectionStack.push("mcpElicitFn");
+    const fnToken = $.CONSUME(ElicitToken); // "elicit"
+
+    $.CONSUME(LCurly); // "{"
+    $.MANY(() => {
+      $.AT_LEAST_ONE(() => $.CONSUME(NewlineToken)); // one attribute per line
+      $.OR([
+        { ALT: () => $.SUBRULE($.commentBlockFn) },
+        {
+          // input { ... } -- the elicitation form. Its fields describe the
+          // ANSWER, not the object's own $input, so they must not register as
+          // document inputs.
+          GATE: () => !hasInput,
+          ALT: () => {
+            hasInput = true;
+            let savedInputs;
+            $.ACTION(() => {
+              savedInputs = { ...$.__symbolTable.input };
+            });
+            $.SUBRULE($.inputClause);
+            $.ACTION(() => {
+              $.__symbolTable.input = savedInputs;
+            });
+          },
+        },
+        {
+          GATE: () => !hasMock,
+          ALT: () => {
+            hasMock = true;
+            $.SUBRULE($.mockAttribute);
+          },
+        },
+        {
+          // key = ..., message = ..., description = "...", disabled = true
+          ALT: () => {
+            const identifier = $.CONSUME(Identifier);
+            $.CONSUME(EqualToken); // "="
+            $.SUBRULE($.expressionFn, { ARGS: [identifier] });
+
+            $.ACTION(() => {
+              const name = getVarName(identifier);
+              if (![...REQUIRED, ...OPTIONAL].includes(name)) {
+                $.addIllegalAttributeError(
+                  identifier,
+                  `Attribute \`${name}\` is not allowed in mcp.elicit (expected ${[...REQUIRED, ...OPTIONAL, "input"].join(", ")})`,
+                );
+              } else if (defined.includes(name)) {
+                $.addDuplicateAttributeError(identifier);
+              }
+              defined.push(name);
+            });
+          },
+        },
+      ]);
+    });
+    $.MANY1(() => $.CONSUME1(NewlineToken));
+    $.CONSUME(RCurly); // "}"
+
+    $.ACTION(() => {
+      const missing = REQUIRED.filter((name) => !defined.includes(name));
+      if (missing.length) {
+        $.addMissingAttributeError(fnToken, missing);
+      }
+      checkElicit($, fnToken);
+    });
+
+    // `as $answer` is optional: an elicit may be used only for its side effect.
+    $.SUBRULE($.asVariable);
+    $.sectionStack.pop();
+  };
+}

package/parser/functions/mcp/mcpProgressFn.js

@@ -0,0 +1,34 @@
+import { ProgressToken } from "../../../lexer/mcp.js";
+
+// mcp.progress {
+//   progress = $i
+//   total = 100          // optional
+//   message = "Working"  // optional
+// }
+//
+// Emits `notifications/progress` on the current MCP response stream
+// (cloud-client mvp:mcp_progress). A value that does not strictly increase is
+// dropped at run time. NO `as $var` binding.
+
+/**
+ * @param {import('../../base_parser.js').XanoBaseParser} $
+ */
+export function mcpProgressFn($) {
+  const requiredAttrs = ["progress"];
+  const optionalAttrs = [
+    "total",
+    "message",
+    "description",
+    "disabled",
+    "mock",
+  ];
+
+  return () => {
+    $.sectionStack.push("mcpProgressFn");
+    const fnToken = $.CONSUME(ProgressToken); // "progress"
+    $.SUBRULE($.functionAttrReq, {
+      ARGS: [fnToken, requiredAttrs, optionalAttrs],
+    });
+    $.sectionStack.pop();
+  };
+}

package/parser/functions/mcp/register.js

@@ -0,0 +1,11 @@
+import { mcpElicitFn } from "./mcpElicitFn.js";
+import { mcpProgressFn } from "./mcpProgressFn.js";
+
+/**
+ * Registers all the parsers in this folder
+ * @param {import('../../base_parser.js').XanoBaseParser} $
+ */
+export const register = ($) => {
+  $.mcpElicitFn = $.RULE("mcpElicitFn", mcpElicitFn($));
+  $.mcpProgressFn = $.RULE("mcpProgressFn", mcpProgressFn($));
+};

package/parser/functions/mcpFn.js

@@ -0,0 +1,19 @@
+import { McpToken } from "../../lexer/ai.js";
+import { DotToken } from "../../lexer/tokens.js";
+
+/**
+ * mcp.elicit, mcp.progress
+ * @param {import('../base_parser.js').XanoBaseParser} $
+ */
+export function mcpFn($) {
+  return () => {
+    $.sectionStack.push("mcp");
+    $.CONSUME(McpToken); // "mcp"
+    $.CONSUME(DotToken); // "."
+    $.OR([
+      { ALT: () => $.SUBRULE($.mcpElicitFn) }, // "mcp.elicit"
+      { ALT: () => $.SUBRULE($.mcpProgressFn) }, // "mcp.progress"
+    ]);
+    $.sectionStack.pop();
+  };
+}

package/parser/functions/register.js

@@ -19,6 +19,8 @@ import { debugFn } from "./debugFn.js";
 import { register as register_expect } from "./expect/register.js";
 import { register as register_math } from "./math/register.js";
 import { mathFn } from "./mathFn.js";
+import { register as register_mcp } from "./mcp/register.js";
+import { mcpFn } from "./mcpFn.js";
 import { middlewareCallFn } from "./middlewareCallFn.js";
 import { register as register_object } from "./object/register.js";
 import { objectFn } from "./objectFn.js";
@@ -66,6 +68,7 @@ export const register = ($) => {
   $.mathFn = $.RULE("mathFn", mathFn($));
   $.objectFn = $.RULE("objectFn", objectFn($));
   $.realtimeFn = $.RULE("realtimeFn", realtimeFn($));
+  $.mcpFn = $.RULE("mcpFn", mcpFn($));
   $.redisFn = $.RULE("redisFn", redisFn($));
   $.securityFn = $.RULE("securityFn", securityFn($));
   $.storageFn = $.RULE("storageFn", storageFn($));
@@ -88,6 +91,7 @@ export const register = ($) => {
   register_db($);
   register_debug($);
   register_math($);
+  register_mcp($);
   register_object($);
   register_realtime($);
   register_redis($);

package/parser/mcp_primitive_parser.js

@@ -0,0 +1,343 @@
+import { EqualToken, LCurly, RCurly } from "../lexer/control.js";
+import { StringLiteral } from "../lexer/literal.js";
+import {
+  MimeTypeToken,
+  PromptToken,
+  ResourceToken,
+  UriToken,
+} from "../lexer/mcp.js";
+import { Identifier, NewlineToken } from "../lexer/tokens.js";
+import { getVarName } from "./generic/utils.js";
+
+// First-class MCP `prompt` and `resource` workspace objects (MCP 2026-07-28),
+// attached to an `mcp_server` through its `prompts` / `resources` blocks.
+// Grounded against cloud-client's `script/kind/schema/core/{prompt,resource}.yaml`.
+//
+//   prompt code_review {                 resource regional_order {
+//     title = "Code review"                uri = "orders://{region}/{order_id}"
+//     icons = [...]                        mime_type = "application/json"
+//     input { text code }                  annotations = {audience: ["user"]}
+//     stack { ... }                        input { enum region {...} int order_id }
+//     response = $messages                 stack { ... }
+//   }                                      response = $order
+//                                        }
+
+/** The input field types a resource uri variable can be bound to (ResourceUri::VARIABLE_TYPES). */
+export const RESOURCE_URI_VARIABLE_TYPES = [
+  "text",
+  "int",
+  "decimal",
+  "bool",
+  "enum",
+  "email",
+  "uuid",
+];
+
+const URI_OPERATORS = "+#./;?&=,!@|";
+const MIME_TYPE =
+  /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*\/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*(\s*;.*)?$/;
+
+/**
+ * Parse a resource uri: a literal URI, or an RFC 6570 LEVEL-1 template.
+ * Mirrors cloud-client's `ResourceUri::parse`.
+ * @param {string} uri
+ * @returns {{ problem: string|null, variables: string[] }}
+ */
+export function parseResourceUri(uri) {
+  const fail = (problem) => ({ problem, variables: [] });
+
+  if (uri === "") return fail("a resource needs a uri");
+  if (/\s/.test(uri)) return fail(`resource uri "${uri}" must not contain whitespace`);
+  if (!/^[A-Za-z][A-Za-z0-9+.-]*:/.test(uri)) {
+    return fail(`resource uri "${uri}" must start with a scheme, e.g. docs://readme`);
+  }
+
+  const variables = [];
+  let i = 0;
+  let lastEnd = -1;
+  while (i < uri.length) {
+    const ch = uri[i];
+    if (ch === "}") return fail(`resource uri "${uri}" has a "}" with no matching "{"`);
+    if (ch !== "{") {
+      i++;
+      continue;
+    }
+    const close = uri.indexOf("}", i + 1);
+    const nextOpen = uri.indexOf("{", i + 1);
+    if (close === -1 || (nextOpen !== -1 && nextOpen < close)) {
+      return fail(`resource uri "${uri}" has an unclosed "{"`);
+    }
+    const expression = uri.slice(i + 1, close);
+    if (expression === "") return fail(`resource uri "${uri}" has an empty "{}"`);
+    if (URI_OPERATORS.includes(expression[0])) {
+      return fail(
+        `resource uri template "{${expression}}" uses an operator; only level-1 {name} variables are supported`,
+      );
+    }
+    if (expression.includes(",")) {
+      return fail(
+        `resource uri template "{${expression}}" lists several variables; use one {name} per variable`,
+      );
+    }
+    if (expression.includes("*") || expression.includes(":")) {
+      return fail(
+        `resource uri template "{${expression}}" uses a modifier; only level-1 {name} variables are supported`,
+      );
+    }
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(expression)) {
+      return fail(`resource uri variable "${expression}" must be letters, digits and _`);
+    }
+    if (variables.includes(expression)) {
+      return fail(`resource uri variable "${expression}" appears more than once`);
+    }
+    if (lastEnd === i - 1) {
+      return fail(`resource uri "${uri}" has two adjacent variables, which cannot be told apart`);
+    }
+    variables.push(expression);
+    lastEnd = close;
+    i = close + 1;
+  }
+
+  return { problem: null, variables };
+}
+
+/**
+ * Why a resource's uri variables and its input block disagree, or null.
+ * Mirrors cloud-client's `ResourceUri::inputProblem`.
+ * @param {string[]} variables
+ * @param {Object<string, {type: string, iterable: boolean}>} inputs
+ * @returns {string|null}
+ */
+export function resourceInputProblem(variables, inputs) {
+  for (const variable of variables) {
+    const field = inputs[variable];
+    if (!field) {
+      return `resource uri variable "${variable}" must be declared in the input block`;
+    }
+    if (!RESOURCE_URI_VARIABLE_TYPES.includes(field.type)) {
+      return `resource uri variable "${variable}" must be one of ${RESOURCE_URI_VARIABLE_TYPES.join(", ")} — got "${field.type}"`;
+    }
+    if (field.iterable) {
+      return `resource uri variable "${variable}" must be a single value, not a list`;
+    }
+  }
+
+  for (const name of Object.keys(inputs)) {
+    if (!variables.includes(name)) {
+      return variables.length === 0
+        ? `input "${name}" cannot be set: a static resource has no inputs (use a {${name}} uri template)`
+        : `input "${name}" is not a variable of the resource uri`;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * @param {import('./base_parser.js').XanoBaseParser} $
+ */
+export function promptDeclaration($) {
+  return mcpPrimitiveDeclaration($, "prompt");
+}
+
+/**
+ * @param {import('./base_parser.js').XanoBaseParser} $
+ */
+export function resourceDeclaration($) {
+  return mcpPrimitiveDeclaration($, "resource");
+}
+
+/**
+ * @param {import('./base_parser.js').XanoBaseParser} $
+ * @param {"prompt"|"resource"} kind
+ */
+function mcpPrimitiveDeclaration($, kind) {
+  const isResource = kind === "resource";
+
+  return () => {
+    let hasAnnotations = false;
+    let hasDescription = false;
+    let hasDocs = false;
+    let hasGuid = false;
+    let hasHistory = false;
+    let hasIcons = false;
+    let hasInput = false;
+    let hasMiddleware = false;
+    let hasMimeType = false;
+    let hasResponse = false;
+    let hasStack = false;
+    let hasTags = false;
+    let hasTitle = false;
+    let uriToken = null;
+    const inputFields = {};
+
+    $.sectionStack.push(`${kind}Declaration`);
+    // Allow leading comments and newlines before the declaration
+    $.SUBRULE($.optionalCommentBlockFn);
+
+    const parent = $.OR([
+      { GATE: () => !isResource, ALT: () => $.CONSUME(PromptToken) },
+      { GATE: () => isResource, ALT: () => $.CONSUME(ResourceToken) },
+    ]);
+    const nameToken = $.OR1([
+      { ALT: () => $.CONSUME(StringLiteral) },
+      { ALT: () => $.CONSUME(Identifier) },
+    ]);
+    $.validateDeclarationName(nameToken, kind);
+    $.CONSUME(LCurly); // "{"
+    $.MANY(() => {
+      $.AT_LEAST_ONE(() => $.CONSUME(NewlineToken)); // at least one new line
+      $.OR2([
+        { ALT: () => $.SUBRULE($.commentBlockFn) },
+        {
+          GATE: () => isResource && !hasAnnotations,
+          ALT: () => {
+            hasAnnotations = true;
+            $.SUBRULE($.mcpResourceAnnotationsClause);
+          },
+        },
+        {
+          GATE: () => !hasDescription,
+          ALT: () => {
+            hasDescription = true;
+            $.SUBRULE($.descriptionFieldAttribute);
+          },
+        },
+        {
+          GATE: () => !hasDocs,
+          ALT: () => {
+            hasDocs = true;
+            $.SUBRULE($.docsFieldAttribute);
+          },
+        },
+        {
+          GATE: () => !hasGuid,
+          ALT: () => {
+            hasGuid = true;
+            $.SUBRULE($.guidFieldAttribute);
+          },
+        },
+        {
+          GATE: () => !hasHistory,
+          ALT: () => {
+            hasHistory = true;
+            $.SUBRULE($.historyClause);
+          },
+        },
+        {
+          GATE: () => !hasIcons,
+          ALT: () => {
+            hasIcons = true;
+            $.SUBRULE($.mcpIconsClause);
+          },
+        },
+        {
+          GATE: () => !hasInput,
+          ALT: () => {
+            hasInput = true;
+            $.SUBRULE($.inputClause, { ARGS: [inputFields] });
+          },
+        },
+        {
+          GATE: () => !hasMiddleware,
+          ALT: () => {
+            hasMiddleware = true;
+            $.SUBRULE($.middlewareClause);
+          },
+        },
+        {
+          GATE: () => isResource && !hasMimeType,
+          ALT: () => {
+            hasMimeType = true;
+            $.CONSUME(MimeTypeToken); // "mime_type"
+            $.CONSUME(EqualToken); // "="
+            const value = $.CONSUME1(StringLiteral);
+            if (!MIME_TYPE.test(getVarName(value))) {
+              $.addInvalidValueError(
+                value,
+                `resource mime_type must be a MIME type such as text/markdown — got "${getVarName(value)}"`,
+              );
+            }
+          },
+        },
+        {
+          GATE: () => !hasResponse,
+          ALT: () => {
+            hasResponse = true;
+            $.SUBRULE($.responseClause);
+          },
+        },
+        {
+          GATE: () => !hasStack,
+          ALT: () => {
+            hasStack = true;
+            $.SUBRULE($.stackClause);
+          },
+        },
+        {
+          GATE: () => !hasTags,
+          ALT: () => {
+            hasTags = true;
+            $.SUBRULE($.tagsAttribute);
+          },
+        },
+        {
+          GATE: () => !hasTitle,
+          ALT: () => {
+            hasTitle = true;
+            $.SUBRULE($.mcpTitleClause);
+          },
+        },
+        {
+          GATE: () => isResource && !uriToken,
+          ALT: () => {
+            $.CONSUME(UriToken); // "uri"
+            $.CONSUME1(EqualToken); // "="
+            uriToken = $.CONSUME2(StringLiteral);
+          },
+        },
+      ]);
+    });
+
+    if (!isResource && !hasInput) {
+      $.addMissingError(
+        parent,
+        `{} ${nameToken.image} is missing an input clause`,
+      );
+    }
+
+    if (!hasStack) {
+      $.addMissingError(
+        parent,
+        `{} ${nameToken.image} is missing a stack clause`,
+      );
+    }
+
+    if (isResource) {
+      $.ACTION(() => {
+        if (!uriToken) {
+          $.addMissingError(parent, `{} ${nameToken.image} is missing a uri`);
+          return;
+        }
+        const { problem, variables } = parseResourceUri(getVarName(uriToken));
+        // the top-level fields only; the symbol table also holds nested
+        // object fields, and records an object input's type as "enum"
+        const inputs = {};
+        for (const [name, field] of Object.entries(inputFields)) {
+          inputs[name] = { type: field.typeToken.image, iterable: field.iterable };
+        }
+        const inputProblem = problem
+          ? problem
+          : resourceInputProblem(variables, inputs);
+        if (inputProblem) {
+          $.addInvalidValueError(uriToken, inputProblem);
+        }
+      });
+    }
+
+    $.MANY1(() => $.CONSUME1(NewlineToken)); // optional new line
+    $.CONSUME(RCurly); // "}"
+    $.MANY2(() => $.CONSUME2(NewlineToken)); // optional new line
+    $.sectionStack.pop();
+  };
+}