flow-codeblock-rust-mcp 0.1.8 → 0.1.10

package/README.md

@@ -7,7 +7,7 @@ Local stdio MCP server for Flow Codeblock Rust+Bun. It calls the server-side Rus
 Bun 1.4.0 or newer is required:
 
 ```bash
-bunx --bun flow-codeblock-rust-mcp@0.1.8
+bunx --bun flow-codeblock-rust-mcp@0.1.10
 ```
 
 Configure the environment:
@@ -26,7 +26,7 @@ export FLOW_CODEBLOCK_TOKEN='<YOUR_INTERNAL_ACCESS_TOKEN>'
   "mcpServers": {
     "flow-codeblock-rust": {
       "command": "bunx",
-      "args": ["--bun", "flow-codeblock-rust-mcp@0.1.8"],
+      "args": ["--bun", "flow-codeblock-rust-mcp@0.1.10"],
       "env": {
         "FLOW_CODEBLOCK_BASE_URL": "https://flow.example.com",
         "FLOW_CODEBLOCK_TOKEN": "<YOUR_INTERNAL_ACCESS_TOKEN>"
@@ -38,6 +38,8 @@ export FLOW_CODEBLOCK_TOKEN='<YOUR_INTERNAL_ACCESS_TOKEN>'
 
 ## Tool boundaries
 
+Generated code treats `input` as a reserved, read-only runtime binding: never declare, rebind, or shadow it in any scope; use an alias such as `const payload = input` when a local name is needed. Review the complete source for input shadowing before every execution and retry.
+
 The code contract follows the current Rust+Bun module allowlist. `crypto-js` has been removed; use `node:crypto` for cryptography. Excel imports are limited to `read-excel-file/node`, `read-excel-file/universal`, `write-excel-file/node`, `write-excel-file/universal`, and `write-excel-file/utility`; these modules run in the server's shared heavy execution pool.
 
 The tools cover code-contract generation, unpublished-code tests, script listing, version reads, documentation validation/preview/save, script creation/update, locking/unlocking, and published-script execution. Creates and code updates can submit a complete interface document or RFC 6902 `interface_doc_patch`; preview calls `/flow/scripts/validate`, and apply re-submits patches with transactional `expected_version` conflict detection. Every script write requires a preview and explicit `confirm: true`.
@@ -54,6 +56,8 @@ At initialization the server sends complete tool selection, preview/confirmation
 
 Interface documents must include `schema_version`, `title`, `summary`, `endpoint`, `request`, `responses`, and `logic_description`. `endpoint` requires `methods` and `description`; `request.query` and `request.headers` must exist (use `[]` when empty). POST documents also require `request.body` with `content_type`, `schema`, and `example`. Every response requires `status`, `description`, `content_type`, `schema`, and `example`; every query/header parameter requires `name`, `type`, `required`, `description`, and `example`.
 
+Every nested schema property, array item, and object-form `additionalProperties` node requires `type`, `description`, and `example`, with examples covering declared fields. MCP accepts one legacy JSON-text parse, fills examples only from matching parent examples, and uses a neutral description when one is omitted.
+
 `endpoint.path` is relative: omit it when creating and use `/flow/codeblock/<actual-script-id>` when updating. Public request URLs combine the caller-provided service origin with `/flow/codeblock/{{script_id}}`. Never put real tokens, passwords, cookies, or Authorization values in code, documents, examples, or URLs.
 
 `interface_doc_patch` and `document_patch` require a positive integer `expected_version` and support at most 256 `add/remove/replace/move/copy/test` operations. Patch previews return operation counts, JSON Pointer paths, warnings, and version information, never the complete merged document.

package/dist/index.js

@@ -27896,6 +27896,7 @@ var interfaceDocNestedRules = [
 ];
 var interfaceDocInputDescription = [
   "A complete script-interface-doc.v1 document is required when creating a script, changing code, or saving documentation.",
+  "Submit interface_doc/document as a JSON object. Legacy JSON text is accepted and parsed once by MCP for compatibility. MCP fills nested examples only from matching parent examples, uses a neutral description when one is omitted, and never guesses a missing type.",
   `Required structure: ${Object.entries(interfaceDocRequiredFields).map(([key, fields]) => `${key}=[${fields.join(", ")}]`).join("; ")}.`,
   ...interfaceDocNestedRules,
   "endpoint.path is relative and must be /flow/codeblock/<actual-script-id> on update; the final public URL is the caller-provided domain followed by /flow/codeblock/<script-id>.",
@@ -27934,6 +27935,73 @@ var interfaceDocPatchJsonSchema = {
     ]
   }
 };
+var schemaNodeInputSchema;
+schemaNodeInputSchema = exports_external.lazy(() => exports_external.looseObject({
+  type: exports_external.string().min(1).describe("JSON Schema type such as object, array, string, integer, number, or boolean."),
+  description: exports_external.string().min(1).describe("Description of this nested field or data structure."),
+  example: exports_external.unknown().describe("A concrete value matching this nested schema node."),
+  properties: exports_external.record(exports_external.string(), schemaNodeInputSchema).optional().describe("Map fixed object field names to child schema nodes."),
+  items: schemaNodeInputSchema.optional().describe("Child schema node for each array item."),
+  additionalProperties: exports_external.union([exports_external.boolean(), schemaNodeInputSchema]).optional().describe("Boolean or child schema for dynamic object keys."),
+  required: exports_external.array(exports_external.string()).optional().describe("Runtime-required object field names.")
+}));
+var schemaRootInputSchema = exports_external.looseObject({
+  type: exports_external.string().min(1).describe("JSON Schema type such as object, array, string, integer, number, or boolean."),
+  description: exports_external.string().optional().describe("Description of the root data structure."),
+  example: exports_external.unknown().optional().describe("Complete example matching this root schema."),
+  properties: exports_external.record(exports_external.string(), schemaNodeInputSchema).optional().describe("Map fixed object field names to child schema nodes."),
+  items: schemaNodeInputSchema.optional().describe("Child schema node for each array item."),
+  additionalProperties: exports_external.union([exports_external.boolean(), schemaNodeInputSchema]).optional().describe("Boolean or child schema for dynamic object keys."),
+  required: exports_external.array(exports_external.string()).optional().describe("Runtime-required object field names.")
+});
+var parameterInputSchema = exports_external.looseObject({
+  name: exports_external.string().min(1).describe("Caller-facing query parameter or HTTP header name."),
+  type: exports_external.enum(["string", "integer", "number", "boolean", "array", "object"]).describe("Parameter JSON type."),
+  required: exports_external.boolean().describe("Whether the parameter is required at runtime."),
+  description: exports_external.string().min(1).describe("Purpose and constraints of the parameter."),
+  example: exports_external.unknown().describe("Concrete example value for the parameter."),
+  default: exports_external.unknown().optional().describe("Optional default value."),
+  format: exports_external.string().optional().describe("Optional format hint."),
+  enum_values: exports_external.array(exports_external.unknown()).optional().describe("Optional allowed values.")
+});
+var interfaceDocToolInputObjectSchema = exports_external.looseObject({
+  schema_version: exports_external.literal("script-interface-doc.v1").describe("Fixed document contract version."),
+  title: exports_external.string().min(1).describe("Interface document title."),
+  summary: exports_external.string().min(1).describe("One-sentence caller-facing summary."),
+  endpoint: exports_external.looseObject({
+    methods: exports_external.array(exports_external.enum(["GET", "POST"])).min(1).describe("HTTP methods supported by the endpoint."),
+    path: exports_external.string().optional().describe("Actual /flow/codeblock/{script_id} path on update."),
+    description: exports_external.string().min(1).describe("What the callable endpoint does.")
+  }).describe("HTTP endpoint contract."),
+  request: exports_external.looseObject({
+    query: exports_external.array(parameterInputSchema).describe("Caller-facing URL query parameters; use [] when empty."),
+    headers: exports_external.array(parameterInputSchema).describe("Caller-facing HTTP headers; use [] when empty."),
+    body: exports_external.looseObject({
+      content_type: exports_external.literal("application/json").describe("Must be application/json."),
+      schema: schemaRootInputSchema.describe("Request body JSON Schema."),
+      example: exports_external.unknown().describe("Complete request body example matching schema.")
+    }).optional().describe("POST request body.")
+  }).describe("Caller request contract."),
+  responses: exports_external.array(exports_external.looseObject({
+    status: exports_external.number().int().min(100).max(599).describe("HTTP status code from 100 through 599."),
+    description: exports_external.string().min(1).describe("Business meaning of this response branch."),
+    content_type: exports_external.literal("application/json").describe("Must be application/json."),
+    schema: schemaRootInputSchema.describe("Response body JSON Schema."),
+    example: exports_external.unknown().describe("Complete response example matching schema.")
+  })).min(1).describe("Complete response branches at the document root."),
+  logic_description: exports_external.string().min(20).describe("Endpoint processing logic; at least 20 characters."),
+  usage_refs: exports_external.array(exports_external.unknown()).optional().describe("Real application references only.")
+});
+function parseLegacyJsonDocument(value) {
+  if (typeof value !== "string")
+    return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+var interfaceDocToolInputSchema = exports_external.preprocess(parseLegacyJsonDocument, interfaceDocToolInputObjectSchema).describe(interfaceDocInputDescription);
 function assertInterfaceDocPatch(patch) {
   const parsed = interfaceDocPatchSchema.safeParse(patch);
   if (!parsed.success)
@@ -27945,18 +28013,82 @@ function isObject2(value) {
 function hasOwn(object4, key) {
   return Object.prototype.hasOwnProperty.call(object4, key);
 }
+function normalizeSchemaNode(schema, parentExample, fieldName, root = false) {
+  if (!root) {
+    if (typeof schema.description !== "string" || !schema.description.trim()) {
+      schema.description = `Value for field "${fieldName}".`;
+    }
+    if (!hasOwn(schema, "example") && parentExample !== undefined) {
+      schema.example = structuredClone(parentExample);
+    }
+  }
+  const example = hasOwn(schema, "example") ? schema.example : parentExample;
+  if (schema.type === "array") {
+    if (isObject2(schema.items)) {
+      const itemExample = Array.isArray(example) && example.length > 0 ? example[0] : undefined;
+      normalizeSchemaNode(schema.items, itemExample, `${fieldName} item`);
+    }
+    return;
+  }
+  if (schema.type !== "object")
+    return;
+  const properties = isObject2(schema.properties) ? schema.properties : undefined;
+  if (properties) {
+    for (const [key, propertySchema] of Object.entries(properties)) {
+      if (!isObject2(propertySchema))
+        continue;
+      const childExample = isObject2(example) && hasOwn(example, key) ? example[key] : undefined;
+      normalizeSchemaNode(propertySchema, childExample, key);
+    }
+  }
+  if (isObject2(schema.additionalProperties)) {
+    const knownKeys = new Set(properties ? Object.keys(properties) : []);
+    const dynamicExample = isObject2(example) ? Object.entries(example).find(([key]) => !knownKeys.has(key))?.[1] : undefined;
+    normalizeSchemaNode(schema.additionalProperties, dynamicExample, `${fieldName} value`);
+  }
+}
+function normalizeInterfaceDocument(document) {
+  if (!isObject2(document))
+    return document;
+  const normalized = structuredClone(document);
+  const containers = [];
+  if (isObject2(normalized.request) && isObject2(normalized.request.body)) {
+    containers.push(normalized.request.body);
+  }
+  if (Array.isArray(normalized.responses)) {
+    containers.push(...normalized.responses.filter(isObject2));
+  }
+  for (const container of containers) {
+    const schema = isObject2(container.schema) ? container.schema : undefined;
+    if (!schema)
+      continue;
+    if (!hasOwn(container, "example") && hasOwn(schema, "example")) {
+      container.example = structuredClone(schema.example);
+    }
+    normalizeSchemaNode(schema, container.example, "root", true);
+  }
+  return normalized;
+}
 function requireText(object4, key, path, issues, minLength = 1) {
   const value = object4[key];
   if (typeof value !== "string" || value.trim().length < minLength) {
     issues.push(`${path}.${key} must be a non-empty string with at least ${minLength} characters`);
   }
 }
-function validateSchemaExampleCoverage(schema, example, schemaPath, examplePath, issues) {
+function validateSchemaExampleCoverage(schema, example, schemaPath, examplePath, issues, requireMetadata = false) {
   if (typeof schema.type !== "string") {
     issues.push(`${schemaPath}.type is required`);
-    return;
+  }
+  if (requireMetadata) {
+    requireText(schema, "description", schemaPath, issues);
+    if (!hasOwn(schema, "example")) {
+      issues.push(`${schemaPath}.example is required`);
+    }
   }
   if (schema.type === "array") {
+    if (!isObject2(schema.items)) {
+      issues.push(`${schemaPath}.items is required for array schemas`);
+    }
     if (!Array.isArray(example)) {
       issues.push(`${examplePath} must be an array`);
       return;
@@ -27965,14 +28097,15 @@ function validateSchemaExampleCoverage(schema, example, schemaPath, examplePath,
       issues.push(`${schemaPath}.items must fully describe array elements`);
       return;
     }
-    example.forEach((item, index) => validateSchemaExampleCoverage(schema.items, item, `${schemaPath}.items`, `${examplePath}[${index}]`, issues));
+    example.forEach((item, index) => validateSchemaExampleCoverage(schema.items, item, `${schemaPath}.items`, `${examplePath}[${index}]`, issues, true));
     return;
   }
   if (schema.type !== "object")
     return;
   const properties = isObject2(schema.properties) ? schema.properties : undefined;
   const additionalProperties = isObject2(schema.additionalProperties) ? schema.additionalProperties : undefined;
-  if (!properties && !additionalProperties) {
+  const allowsAdditionalProperties = additionalProperties !== undefined || schema.additionalProperties === true;
+  if (!properties && !allowsAdditionalProperties) {
     issues.push(`${schemaPath} must define properties or an additionalProperties schema`);
     return;
   }
@@ -27985,7 +28118,7 @@ function validateSchemaExampleCoverage(schema, example, schemaPath, examplePath,
       if (!hasOwn(example, key)) {
         issues.push(`${examplePath} is missing ${key}`);
       } else if (isObject2(propertySchema)) {
-        validateSchemaExampleCoverage(propertySchema, example[key], `${schemaPath}.properties.${key}`, `${examplePath}.${key}`, issues);
+        validateSchemaExampleCoverage(propertySchema, example[key], `${schemaPath}.properties.${key}`, `${examplePath}.${key}`, issues, true);
       } else {
         issues.push(`${schemaPath}.properties.${key} must be a JSON Schema object`);
       }
@@ -27995,8 +28128,8 @@ function validateSchemaExampleCoverage(schema, example, schemaPath, examplePath,
     if (properties && hasOwn(properties, key))
       continue;
     if (additionalProperties) {
-      validateSchemaExampleCoverage(additionalProperties, value, `${schemaPath}.additionalProperties`, `${examplePath}.${key}`, issues);
-    } else {
+      validateSchemaExampleCoverage(additionalProperties, value, `${schemaPath}.additionalProperties`, `${examplePath}.${key}`, issues, true);
+    } else if (schema.additionalProperties !== true) {
       issues.push(`${schemaPath}.properties does not define example field ${key}`);
     }
   }
@@ -28128,7 +28261,7 @@ function interfaceDocCompletenessIssues(document, operation) {
       validateSchemaAndExample(response, path, issues);
     });
   }
-  return issues;
+  return [...new Set(issues)];
 }
 function assertCompleteInterfaceDoc(document, operation) {
   const issues = interfaceDocCompletenessIssues(document, operation);
@@ -28222,7 +28355,7 @@ var interfaceDocSchema = {
       additionalProperties: false,
       properties: {
         content_type: { const: "application/json" },
-        schema: {},
+        schema: { $ref: "#/$defs/schema_root" },
         example: {}
       }
     },
@@ -28234,30 +28367,68 @@ var interfaceDocSchema = {
         status: { type: "integer", minimum: 100, maximum: 599 },
         description: { type: "string", minLength: 1, maxLength: 4000 },
         content_type: { const: "application/json" },
-        schema: {},
+        schema: { $ref: "#/$defs/schema_root" },
         example: {}
       }
+    },
+    schema_root: {
+      type: "object",
+      required: ["type"],
+      additionalProperties: true,
+      properties: {
+        type: { type: "string", minLength: 1 },
+        description: { type: "string", minLength: 1 },
+        example: {},
+        properties: { type: "object", additionalProperties: { $ref: "#/$defs/schema_node" } },
+        items: { $ref: "#/$defs/schema_node" },
+        additionalProperties: { anyOf: [{ $ref: "#/$defs/schema_node" }, { type: "boolean" }] },
+        required: { type: "array", items: { type: "string" } }
+      }
+    },
+    schema_node: {
+      type: "object",
+      required: ["type", "description", "example"],
+      additionalProperties: true,
+      properties: {
+        type: { type: "string", minLength: 1 },
+        description: { type: "string", minLength: 1 },
+        example: {},
+        properties: { type: "object", additionalProperties: { $ref: "#/$defs/schema_node" } },
+        items: { $ref: "#/$defs/schema_node" },
+        additionalProperties: { anyOf: [{ $ref: "#/$defs/schema_node" }, { type: "boolean" }] },
+        required: { type: "array", items: { type: "string" } }
+      }
     }
   }
 };
-function schemaFromExample(value) {
+function schemaFromExample(value, fieldName = "value") {
+  const metadata = { description: `Value for ${fieldName}.`, example: structuredClone(value) };
   if (Array.isArray(value)) {
-    return { type: "array", items: value.length > 0 ? schemaFromExample(value[0]) : { type: "string" } };
+    return {
+      type: "array",
+      ...metadata,
+      items: value.length > 0 ? schemaFromExample(value[0], `${fieldName} item`) : {
+        type: "string",
+        description: `Value for ${fieldName} item.`,
+        example: ""
+      }
+    };
   }
   if (value !== null && typeof value === "object") {
     const entries = Object.entries(value);
     return {
       type: "object",
-      properties: Object.fromEntries(entries.map(([key, item]) => [key, schemaFromExample(item)])),
+      ...metadata,
+      properties: Object.fromEntries(entries.map(([key, item]) => [key, schemaFromExample(item, key)])),
       required: entries.map(([key]) => key),
       additionalProperties: false
     };
   }
   if (value === null)
-    return { type: "null" };
+    return { type: "null", ...metadata };
   if (typeof value === "number")
-    return { type: Number.isInteger(value) ? "integer" : "number" };
-  return { type: typeof value };
+    return { type: Number.isInteger(value) ? "integer" : "number", ...metadata };
+  return { type: typeof value, ...metadata };
 }
 function codeWriterContext(mode, requirement, inputExample, includeFullSchema, baseUrl) {
   const common = {
@@ -28294,6 +28465,7 @@ function codeWriterContext(mode, requirement, inputExample, includeFullSchema, b
     },
     code_rules: [
       "Read all business data from the global input only; do not read environment variables, persistent globals, or other external state. Return values must be JSON-serializable.",
+      "Treat input as a reserved, read-only runtime binding. Never declare, redeclare, rebind, or destructure a local binding named input in any scope, including const/let/var declarations, function parameters, catch bindings, and nested callbacks. If a local name is needed, alias it to payload or another name, for example const payload = input. Review the complete source for input shadowing before every execution and retry.",
       "Use top-level return by default. Use qf_output only for event-style/asynchronous flows or when explicitly requested, and assign it as a bare qf_output = { ... } object literal. Never mix it with top-level return or shadow the identifier.",
       "Prefer standard JavaScript, Bun-native fetch, real axios, and node:crypto. Network requests use Bun's native network stack. Use a whitelisted CommonJS literal require only when native capabilities cannot meet the requirement and the user explicitly requests it. crypto-js has been removed and must not be generated.",
       "Do not use import/export, dynamic require, browser APIs, timers, forbidden identifiers or members, or blacklisted Node modules. Never write real credentials.",
@@ -28534,10 +28706,11 @@ var serverInstructions = [
   "Tool routing: flow_write_code only generates code and its contract; flow_execute_code tests unpublished generated code; flow_execute_script runs published scripts. When the generated code and available safe input are sufficient for a meaningful runtime test, execute it immediately without waiting for user confirmation. If required input or credentials are missing, report that runtime verification was not performed instead of inventing them.",
   "Script workflow: read the current version with flow_get_script before updates; creates require a complete interface_doc, while code or document updates may use a complete interface_doc or an RFC 6902 interface_doc_patch (never both, and patches require expected_version). Preview with flow_preview_script_change, then call flow_apply_script_change(confirm=true) only after explicit user confirmation. Documentation-only changes use flow_preview_script_documentation -> flow_apply_script_documentation.",
   "Preview IDs are single-use and time-limited. On a version conflict, expired preview, or validation failure, stop, read again, and preview again; never retry an old preview_id. Every flow_apply_* call requires confirm=true.",
+  "Interface-document validation reports every discovered nested schema issue in one response; fix the complete list before making another preview call.",
   "script-interface-doc.v1 requires schema_version, title, summary, endpoint, request, responses, and logic_description. endpoint requires methods and description; request.query and request.headers are required arrays (use [] when empty); POST requires request.body and GET-only documents must omit it. JSON Patch supports at most 256 add/remove/replace/move/copy/test operations; preview responses show operation counts and paths, not merged documents.",
-  "Every query parameter and request header requires name, type, required, description, and example. Request bodies and responses require content_type=application/json, schema, and example; every response also requires status and description. Every JSON Schema node declares type, and object schemas and examples must cover each other.",
+  "Every query parameter and request header requires name, type, required, description, and example. Request bodies and responses require content_type=application/json, schema, and example; every response also requires status and description. Every root JSON Schema node declares type; every nested property, array item, and object-form additionalProperties node declares type, description, and example. Arrays must define items, fixed object properties must be covered by the complete example, and additionalProperties=true is reserved for opaque upstream JSON.",
   "Keep endpoint.path relative: omit it on create and use /flow/codeblock/<actual-script-id> on update. Public call URLs use the caller-provided domain plus /flow/codeblock/{{script_id}}; never put real tokens, passwords, cookies, or Authorization values in code, documents, examples, or URLs.",
-  "Script input comes from input.query, input.header, input.body, and input.cookies; for immediate non-script POST /flow/codeblock, body.input becomes global input unchanged. Use top-level return by default; use a bare qf_output assignment only for event-style/asynchronous flows or when explicitly requested, never both.",
+  "Script input comes from input.query, input.header, input.body, and input.cookies; for immediate non-script POST /flow/codeblock, body.input becomes global input unchanged. Treat input as a reserved, read-only runtime binding: never declare, redeclare, rebind, or destructure a local binding named input in any scope, including function parameters and nested callbacks. Use an alias such as const payload = input when a local name is needed. Use top-level return by default; use a bare qf_output assignment only for event-style/asynchronous flows or when explicitly requested, never both.",
   "For every initial generation and every later revision in non-script mode, final delivery always includes the complete latest generated JavaScript, even after runtime verification; never return only a patch, diff, or partial snippet. Also include caller-facing invocation instructions, parameters/examples, logic, success/error examples, and execution_url. Script delivery omits JavaScript and raw interface_doc by default and includes invocation instructions, parameters/examples, logic, success/error examples, and the published script_url unless the user asks for source or raw documentation. Code and interface_doc remain internal preview/validation/publication inputs.",
   "Prefer native JavaScript, URL/URLSearchParams, Bun-native fetch, and node:crypto; crypto-js has been removed. Treat every forbidden identifier as forbidden in every syntactic position, including property names and method calls. Never generate RegExp.exec or .exec(...); use text.match(regex) for capture groups or regex.test(text) for boolean checks. Before execution, review the complete source and rewrite every forbidden identifier, member, or module. Do not generate browser APIs, timers, dynamic module loading, constructor-based code generation, or blacklisted Node modules (including fs/node:fs). Excel imports are limited to read-excel-file/node, read-excel-file/universal, write-excel-file/node, write-excel-file/universal, and write-excel-file/utility. Check HTTP status and handle JSON, text, and empty responses; await or return every async task.",
   "Script execution accepts only GET or POST. MCP authentication, cookies, CSRF, proxy-source headers, and test-tool markers are filtered. There is no script deletion, emergency unlock, or arbitrary HTTP proxy tool; direct those requests to the web UI or controlled REST/operations flow."
@@ -28641,7 +28814,7 @@ function withApiErrors(handler) {
   };
 }
 var documentationFields = {
-  document: exports_external.unknown().optional().describe(`Normalized script-interface-doc.v1 JSON. Choose exactly one of document, raw_document, or document_patch; complete documents are required for saves and code updates. ${interfaceDocInputDescription}`),
+  document: interfaceDocToolInputSchema.optional().describe(`Normalized script-interface-doc.v1 JSON object. Choose exactly one of document, raw_document, or document_patch; complete documents are required for saves and code updates. ${interfaceDocInputDescription}`),
   raw_document: exports_external.string().optional().describe("JSON/OpenAPI document text for server parsing. Choose exactly one of document, raw_document, or document_patch; format=json parses JSON."),
   format: exports_external.literal("json").optional().describe("Format of raw_document; only json is supported."),
   document_patch: interfaceDocPatchSchema.optional().describe("RFC 6902 patch for an existing script only. Choose exactly one of document, raw_document, or document_patch."),
@@ -28654,7 +28827,7 @@ var changeSchema = exports_external.object({
   code_base64: exports_external.string().optional().describe("Non-empty Base64-encoded JavaScript, mutually exclusive with code."),
   description: exports_external.string().optional().describe("Script description. Can be updated without changing code."),
   ip_whitelist: exports_external.array(exports_external.string()).nullable().optional().describe("Source IP/CIDR allowlist. Omit on update to keep the current value; null or [] clears the restriction."),
-  interface_doc: exports_external.unknown().optional().describe(interfaceDocInputDescription),
+  interface_doc: interfaceDocToolInputSchema.optional().describe(interfaceDocInputDescription),
   interface_doc_patch: interfaceDocPatchSchema.optional().describe("RFC 6902 patch for update only; mutually exclusive with interface_doc and forbidden for create."),
   rollback_to_version: exports_external.number().int().positive().optional().describe("Historical version to restore. Use only as a standalone update and never with code, interface_doc, or interface_doc_patch."),
   expected_version: exports_external.number().int().positive().optional().describe("Required for update and must be the current_version from flow_get_script for concurrency protection; forbidden for create.")
@@ -28721,6 +28894,7 @@ function assertScriptChangeInput(input) {
     throw new Error("rollback_to_version cannot be combined with code, interface_doc, or interface_doc_patch");
   }
   if (input.interface_doc !== undefined) {
+    input.interface_doc = normalizeInterfaceDocument(input.interface_doc);
     assertCompleteInterfaceDoc(input.interface_doc, input.operation);
   }
   if (input.interface_doc_patch !== undefined)
@@ -28774,15 +28948,15 @@ function assertPreview(record3, operation) {
   return record3;
 }
 function createMcpServer({ api: api2, previews = new PreviewStore }) {
-  const server = new McpServer({ name: "flow-codeblock-rust", version: "0.1.8" }, { instructions: serverInstructions });
+  const server = new McpServer({ name: "flow-codeblock-rust", version: "0.1.10" }, { instructions: serverInstructions });
   server.registerTool("flow_write_code", {
     title: "Get the Flow JavaScript authoring contract",
-    description: "Call this before writing or revising Flow Codeblock JavaScript. It returns the mode-specific authoring contract, including forbidden-identifier replacement rules, and never writes the database, publishes a script, or executes code. For every non_script generation or revision, always deliver the complete latest generated JavaScript plus execution_url, never only a patch or partial snippet; use script for persistent GET/POST /flow/codeblock/{{script_id}} code with a complete script-interface-doc.v1 for preview, validation, and publication. Script delivery includes invocation instructions, parameters/examples, logic, success/error examples, and script_url rather than source or raw interface_doc unless requested. Set base_url only when a caller-facing URL template is needed.",
+    description: "Call this before writing or revising Flow Codeblock JavaScript. It returns the mode-specific authoring contract, including forbidden-identifier and reserved-input replacement rules, and never writes the database, publishes a script, or executes code. For every non_script generation or revision, always deliver the complete latest generated JavaScript plus execution_url, never only a patch or partial snippet; use script for persistent GET/POST /flow/codeblock/{{script_id}} code with a complete script-interface-doc.v1 for preview, validation, and publication. Script delivery includes invocation instructions, parameters/examples, logic, success/error examples, and script_url rather than source or raw interface_doc unless requested. Set base_url only when a caller-facing URL template is needed.",
     inputSchema: {
       mode: exports_external.enum(["non_script", "script"]).describe("Generation mode. Use non_script for immediate, non-persistent execution; use script for a persistent GET/POST endpoint or HTTP redirects."),
       requirement: exports_external.string().min(1).max(20000).describe("Complete business requirements, input fields, expected output, external APIs, synchronization/async needs, and error behavior. Include only requirements relevant to this code."),
       input_example: exports_external.unknown().optional().describe("Business input example. In script mode it helps generate request.body/schema/example; in non_script mode it supplies flow_execute_code test input. Never include real credentials."),
-      include_full_schema: exports_external.boolean().optional().describe("Whether to include the complete JSON Schema in the response; defaults to false. The generated interface document still contains all required fields."),
+      include_full_schema: exports_external.boolean().optional().describe("Whether to include the complete recursive JSON Schema in the response; defaults to true for script mode to avoid a follow-up schema call. Set false only when the caller already has the schema."),
       base_url: exports_external.string().url().refine((value) => {
         try {
           const parsed = new URL(value);
@@ -28793,7 +28967,7 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
       }, "base_url must be an http(s) URL without credentials or control characters").optional().describe("Optional caller service origin such as https://flow.example.com. Used only to render /flow/codeblock/{{script_id}}; credentials and control characters are forbidden.")
     }
   }, async ({ mode, requirement, input_example, include_full_schema, base_url }) => {
-    const context = codeWriterContext(mode, requirement, input_example, include_full_schema ?? false, base_url);
+    const context = codeWriterContext(mode, requirement, input_example, include_full_schema ?? mode === "script", base_url);
     return result(mode === "non_script" ? { ...context, execution_url: executionUrl(api2) } : context);
   });
   server.registerTool("flow_list_scripts", {
@@ -28855,6 +29029,7 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
   }, withApiErrors(async (input) => {
     const parsed = documentationSchema.parse(input);
     if (parsed.document !== undefined) {
+      parsed.document = normalizeInterfaceDocument(parsed.document);
       assertCompleteInterfaceDoc(parsed.document, "update");
     }
     if (parsed.document_patch !== undefined)
@@ -28955,6 +29130,8 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
     inputSchema: documentationSchema.shape
   }, withApiErrors(async (input) => {
     const parsed = documentationSchema.parse(input);
+    if (parsed.document !== undefined)
+      parsed.document = normalizeInterfaceDocument(parsed.document);
     const expectedVersion = await fetchCurrentVersion(api2, parsed.script_id);
     if (parsed.document_patch !== undefined && parsed.expected_version !== expectedVersion) {
       throw new Error(`Script version changed from ${parsed.expected_version} to ${expectedVersion}; read and preview again`);
@@ -29065,11 +29242,11 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
   }));
   server.registerTool("flow_execute_code", {
     title: "Execute unpublished code",
-    description: "Execute unpublished generated JavaScript when requested or when the available safe input is sufficient for a meaningful runtime test; execution-only verification does not require user confirmation. The result includes a complete execution_url. The request is always POST /flow/codeblock, and body.input is injected unchanged as global input; provide exactly one of code or code_base64. User-code failures preserve verified error.details source locations when available. MCP authentication is never written into user input, and this tool does not create or publish scripts.",
+    description: "Execute unpublished generated JavaScript when requested or when the available safe input is sufficient for a meaningful runtime test; execution-only verification does not require user confirmation. The result includes a complete execution_url. The request is always POST /flow/codeblock, and body.input is injected unchanged as global input; input is a reserved runtime binding and generated code must never declare, rebind, or shadow it; use an alias such as const payload = input. Provide exactly one of code or code_base64. User-code failures preserve verified error.details source locations when available. MCP authentication is never written into user input, and this tool does not create or publish scripts.",
     inputSchema: {
       code: exports_external.string().min(1).optional().describe("UTF-8 JavaScript source, mutually exclusive with code_base64."),
       code_base64: exports_external.string().min(1).optional().describe("Non-empty Base64-encoded JavaScript source, mutually exclusive with code."),
-      input: exports_external.unknown().optional().describe("Business data injected into global input; defaults to {}. Do not include tokens, passwords, cookies, or Authorization values."),
+      input: exports_external.unknown().optional().describe("Business data injected into global input; defaults to {}. Do not include tokens, passwords, cookies, or Authorization values. In generated code, input is a reserved binding; never declare, rebind, or shadow it."),
       timeout_ms: exports_external.number().int().positive().optional().describe("Test execution timeout in milliseconds; it must be within the server's allowed range.")
     }
   }, withApiErrors(async ({ code, code_base64, input, timeout_ms }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-codeblock-rust-mcp",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Flow Codeblock Rust+Bun stdio MCP Server for script management and execution.",
   "license": "MIT",
   "repository": {