@json-layout/core 2.5.1 → 2.6.0

package/src/webmcp/index.js

@@ -10,18 +10,53 @@ import * as setFieldValue from './tools/set-field-value.js'
 import * as setData from './tools/set-data.js'
 import * as getData from './tools/get-data.js'
 import * as getFieldSuggestions from './tools/get-field-suggestions.js'
+import * as editArray from './tools/edit-array.js'
 import * as fillFormSkill from './tools/fill-form-skill.js'
+import { formatMutationResult, formatSuggestions } from './project.js'
 
 /** @typedef {import('@mcp-b/webmcp-types').ToolDescriptor} ToolDescriptor */
 
 const log = debug('jl:webmcp')
 
+/**
+ * If value is a JSON string representing an object or array, parse it.
+ * Otherwise return value unchanged.
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function parseIfJsonString (value) {
+  if (typeof value !== 'string') return value
+  const trimmed = value.trim()
+  if ((trimmed[0] === '{' && trimmed[trimmed.length - 1] === '}') ||
+      (trimmed[0] === '[' && trimmed[trimmed.length - 1] === ']')) {
+    try {
+      return JSON.parse(trimmed)
+    } catch {
+      return value
+    }
+  }
+  return value
+}
+
 /**
  * @typedef {object} WebMCPOptions
  * @property {string} [prefixName] - Prefix for all tool names
  * @property {string} [dataTitle] - Title used in descriptions (default: 'form')
  * @property {object} [schema] - The original JSON schema
+ * @property {boolean} [includeFillFormSkill] - Include the fillFormSkill tool (default: false)
+ * @property {boolean} [includeSubAgent] - Include a subagent_ tool wrapping all form tools (default: false)
+ */
+
+/**
+ * @param {import('../state/index.js').StatefulLayout} statefulLayout
+ * @returns {"small"|"medium"|"large"}
  */
+function getComplexity (statefulLayout) {
+  const nbNormalizedLayouts = Object.keys(statefulLayout.compiledLayout.normalizedLayouts).length
+  if (nbNormalizedLayouts > 50) return 'large'
+  if (nbNormalizedLayouts > 15) return 'medium'
+  return 'small'
+}
 
 /**
  * WebMCP class that provides MCP tool descriptors for a StatefulLayout instance
@@ -47,9 +82,9 @@ export class WebMCP {
 
   /**
    * @readonly
-   * @type {string}
+   * @type {"small"|"medium"|"large"}
    */
-  _skill
+  _complexity
 
   /**
    * @readonly
@@ -57,6 +92,18 @@ export class WebMCP {
    */
   _schema = null
 
+  /**
+   * @readonly
+   * @type {boolean}
+   */
+  _includeFillFormSkill = false
+
+  /**
+   * @readonly
+   * @type {boolean}
+   */
+  _includeSubAgent = false
+
   /**
    * @type {string[]}
    */
@@ -71,7 +118,9 @@ export class WebMCP {
     this._prefixName = options.prefixName || ''
     this._dataTitle = options.dataTitle || 'form'
     this._schema = options.schema || null
-    this._skill = fillFormSkill.generateSkill(this._dataTitle, this._prefixName, !!this._schema, this._statefulLayout)
+    this._includeFillFormSkill = options.includeFillFormSkill || false
+    this._includeSubAgent = options.includeSubAgent || false
+    this._complexity = getComplexity(statefulLayout)
   }
 
   /**
@@ -87,17 +136,21 @@ export class WebMCP {
    */
   getTools () {
     const dataTitle = this._dataTitle
+    const complexity = this._complexity
 
     /** @type {ToolDescriptor[]} */
-    const tools = [
-      {
+    const tools = []
+
+    if (this._includeFillFormSkill) {
+      const skill = fillFormSkill.generateSkill(dataTitle, this._prefixName, !!this._schema, this._statefulLayout)
+      tools.push({
         name: this._toolName('fillFormSkill'),
         description: fillFormSkill.getDescription(dataTitle),
         outputSchema: { type: 'string' },
         execute: async (args) => {
           try {
             return {
-              content: [{ type: 'text', text: this._skill }]
+              content: [{ type: 'text', text: skill }]
             }
           } catch (err) {
             const message = err instanceof Error ? err.message : String(err)
@@ -107,17 +160,21 @@ export class WebMCP {
             }
           }
         }
-      },
+      })
+    }
+
+    tools.push(
       {
         name: this._toolName('getData'),
-        description: getData.getDescription(dataTitle),
+        description: `Get current "${dataTitle}" data and validity status. Call this first to see what data already exists.`,
         inputSchema: getData.inputSchema,
         outputSchema: getData.outputSchema,
         execute: async (args) => {
           try {
             const result = getData.execute(this._statefulLayout, args || {})
             return {
-              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+              content: [{ type: 'text', text: JSON.stringify(result) }],
+              structuredContent: result
             }
           } catch (err) {
             const message = err instanceof Error ? err.message : String(err)
@@ -130,7 +187,7 @@ export class WebMCP {
       },
       {
         name: this._toolName('setData'),
-        description: setData.getDescription(dataTitle),
+        description: setData.getDescription(dataTitle, complexity),
         inputSchema: setData.inputSchema,
         outputSchema: setData.outputSchema,
         execute: async (args) => {
@@ -138,12 +195,14 @@ export class WebMCP {
             if (!args?.data) {
               throw new Error('data is required')
             }
+            args.data = parseIfJsonString(args.data)
             const result = setData.execute(
               this._statefulLayout,
               /** @type {{ data: unknown }} */(args)
             )
             return {
-              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+              content: [{ type: 'text', text: formatMutationResult(result.valid, result.errors) }],
+              structuredContent: result
             }
           } catch (err) {
             const message = err instanceof Error ? err.message : String(err)
@@ -156,14 +215,16 @@ export class WebMCP {
       },
       {
         name: this._toolName('describeState'),
-        description: describeState.getDescription(dataTitle),
+        description: describeState.getDescription(dataTitle, complexity),
         inputSchema: describeState.inputSchema,
         outputSchema: describeState.outputSchema,
         execute: async (args) => {
           try {
             const result = describeState.execute(this._statefulLayout, args || {})
+            const text = describeState.toMarkdown(this._statefulLayout, args || {})
             return {
-              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+              content: [{ type: 'text', text }],
+              structuredContent: result
             }
           } catch (err) {
             const message = err instanceof Error ? err.message : String(err)
@@ -184,12 +245,15 @@ export class WebMCP {
             if (!args?.path) {
               throw new Error('path is required')
             }
+            args.value = parseIfJsonString(args.value)
             const result = setFieldValue.execute(
               this._statefulLayout,
               /** @type {{ path: string, value: unknown }} */(args)
             )
+            const fieldInfo = `${result.field.path} (${result.field.type}) = ${JSON.stringify(result.field.data)}`
             return {
-              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+              content: [{ type: 'text', text: formatMutationResult(result.valid, result.errors, fieldInfo) }],
+              structuredContent: result
             }
           } catch (err) {
             const message = err instanceof Error ? err.message : String(err)
@@ -202,7 +266,7 @@ export class WebMCP {
       },
       {
         name: this._toolName('getFieldSuggestions'),
-        description: getFieldSuggestions.getDescription(dataTitle),
+        description: `Get allowed values for a dropdown or autocomplete field in "${dataTitle}". Required when describeState shows "suggestions" for a field. Pass the returned value directly to setFieldValue or include it in setData.`,
         inputSchema: getFieldSuggestions.inputSchema,
         outputSchema: getFieldSuggestions.outputSchema,
         execute: async (args) => {
@@ -215,7 +279,41 @@ export class WebMCP {
               /** @type {{ path: string, query?: string }} */(args)
             )
             return {
-              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+              content: [{ type: 'text', text: formatSuggestions(result.items) }],
+              structuredContent: result
+            }
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err)
+            return {
+              content: [{ type: 'text', text: `Error: ${message}` }],
+              isError: true
+            }
+          }
+        }
+      },
+      {
+        name: this._toolName('editArray'),
+        description: editArray.getDescription(dataTitle),
+        inputSchema: editArray.inputSchema,
+        outputSchema: editArray.outputSchema,
+        execute: async (args) => {
+          try {
+            if (!args?.path || !args?.action) {
+              throw new Error('path and action are required')
+            }
+            if (args.value !== undefined) {
+              args.value = parseIfJsonString(args.value)
+            }
+            const result = editArray.execute(
+              this._statefulLayout,
+              /** @type {{ path: string, action: 'add'|'remove', index?: number, value?: unknown }} */(args)
+            )
+            const actionInfo = args.action === 'add'
+              ? `added item, ${result.itemCount} total`
+              : `removed item, ${result.itemCount} remaining`
+            return {
+              content: [{ type: 'text', text: formatMutationResult(result.valid, result.errors, actionInfo) }],
+              structuredContent: result
             }
           } catch (err) {
             const message = err instanceof Error ? err.message : String(err)
@@ -226,21 +324,42 @@ export class WebMCP {
           }
         }
       }
-    ]
+    )
 
     if (this._schema) {
       tools.push({
         name: this._toolName('getSchema'),
-        description: `Get the the JSON schema that governs "${dataTitle}" form.`,
+        description: `Get the JSON schema that governs the "${dataTitle}" form.`,
         outputSchema: {
           type: 'object',
-          properties: {
-            jsonSchema: {},
-          }
+          description: 'The JSON schema definition'
         },
         execute: async (args) => {
           return {
-            jsonSchema: this._schema
+            content: [{ type: 'text', text: JSON.stringify(this._schema) }],
+            structuredContent: this._schema
+          }
+        }
+      })
+    }
+
+    if (this._includeSubAgent) {
+      const toolNames = tools.map(t => t.name)
+      const prompt = fillFormSkill.generateSkill(dataTitle, this._prefixName, !!this._schema, this._statefulLayout)
+      tools.push({
+        name: `subagent_${this._toolName('form')}`,
+        description: `Delegate a form-filling task for "${dataTitle}" to a specialized sub-agent`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            task: { type: 'string', description: 'The task to delegate to this sub-agent' }
+          },
+          required: ['task']
+        },
+        execute: async () => {
+          return {
+            content: [{ type: 'text', text: JSON.stringify({ prompt, tools: toolNames }) }],
+            structuredContent: { prompt, tools: toolNames }
           }
         }
       })

package/src/webmcp/project.js

@@ -14,6 +14,28 @@ const constraintKeys = {
   'number-combobox': ['separator']
 }
 
+/** @type {Record<string, string>} */
+const compToType = {
+  'text-field': 'text',
+  'number-field': 'number',
+  textarea: 'textarea',
+  checkbox: 'boolean',
+  'date-picker': 'date',
+  'date-time-picker': 'datetime',
+  'time-picker': 'time',
+  select: 'select',
+  autocomplete: 'autocomplete',
+  combobox: 'combobox',
+  'number-combobox': 'number-combobox',
+  'one-of-select': 'variant-selector',
+  list: 'array',
+  section: 'section',
+  slider: 'slider',
+  'file-input': 'file',
+  slot: 'slot',
+  'composite-slot': 'composite-slot'
+}
+
 /**
  * @param {string} comp
  * @returns {string[]|undefined}
@@ -24,50 +46,35 @@ function getConstraintKeys (comp) {
 }
 
 /**
- * @param {import('../state/types.js').StateNode} node
- * @param {import('../state/index.js').StatefulLayout} statefulLayout
- * @returns {{
- *   key: string|number,
+ * @typedef {{
  *   path: string,
- *   comp: string,
+ *   type: string,
  *   data: unknown,
  *   title?: string,
  *   label?: string,
  *   help?: string,
  *   error?: string,
- *   childError?: boolean,
  *   required?: boolean,
  *   readOnly?: boolean,
+ *   modified?: boolean,
  *   constraints?: Record<string, unknown>,
- *   oneOfItems?: Array<{key: number, title: string}>,
- *   children?: Array<any>
- *   getSuffections?: boolean
- * }}
+ *   variants?: Array<{index: number, title: string}>,
+ *   selectedVariant?: number,
+ *   children?: Array<ProjectedNode>,
+ *   getSuggestions?: boolean
+ * }} ProjectedNode
+ */
+
+/**
+ * @param {import('../state/types.js').StateNode} node
+ * @param {import('../state/index.js').StatefulLayout} statefulLayout
+ * @returns {ProjectedNode}
  */
 export function projectNode (node, statefulLayout) {
-  /**
-   * @type {{
-   *   key: string|number,
-   *   path: string,
-   *   comp: string,
-   *   data: unknown,
-   *   title?: string,
-   *   label?: string,
-   *   help?: string,
-   *   error?: string,
-   *   childError?: boolean,
-   *   required?: boolean,
-   *   readOnly?: boolean,
-   *   constraints?: Record<string, unknown>,
-   *   oneOfItems?: Array<{key: number, title: string}>,
-   *   children?: Array<any>
-   *   getSuggestions?: boolean
-   * }}
-   */
+  /** @type {ProjectedNode} */
   const out = {
-    key: node.key,
     path: node.fullKey,
-    comp: node.layout.comp,
+    type: compToType[node.layout.comp] || node.layout.comp,
     data: node.data
   }
 
@@ -77,10 +84,10 @@ export function projectNode (node, statefulLayout) {
   if (node.layout.help) out.help = node.layout.help
 
   if (node.error) out.error = node.error
-  if (node.childError) out.childError = true
 
   if (node.skeleton.required) out.required = true
   if (node.options.readOnly) out.readOnly = true
+  if (node.modified) out.modified = true
   if (isItemsLayout(node.layout, statefulLayout.compiledLayout.components)) out.getSuggestions = true
 
   const keys = getConstraintKeys(node.layout.comp)
@@ -95,9 +102,12 @@ export function projectNode (node, statefulLayout) {
   }
 
   if (node.layout.comp === 'one-of-select' && Array.isArray(layout.oneOfItems)) {
-    out.oneOfItems = layout.oneOfItems
+    out.variants = layout.oneOfItems
       .filter((item) => !item.header)
-      .map((item) => ({ key: item.key, title: item.title }))
+      .map((item) => ({ index: item.key, title: item.title }))
+    // find selected variant
+    const selected = layout.oneOfItems.find((item) => item.selected)
+    if (selected) out.selectedVariant = selected.key
   }
 
   if (node.children) {
@@ -109,10 +119,27 @@ export function projectNode (node, statefulLayout) {
   return out
 }
 
+/**
+ * Project a single field result for slim mutation responses
+ * @param {import('../state/types.js').StateNode} node
+ * @param {import('../state/index.js').StatefulLayout} statefulLayout
+ * @returns {{ path: string, type: string, data: unknown, error?: string }}
+ */
+export function projectFieldResult (node, statefulLayout) {
+  /** @type {{ path: string, type: string, data: unknown, error?: string }} */
+  const out = {
+    path: node.fullKey,
+    type: compToType[node.layout.comp] || node.layout.comp,
+    data: node.data
+  }
+  if (node.error) out.error = node.error
+  return out
+}
+
 /**
  * @param {import('../state/types.js').StateTree} stateTree
  * @param {import('../state/index.js').StatefulLayout} statefulLayout
- * @returns {{ root: ReturnType<typeof projectNode>, valid: boolean }}
+ * @returns {{ root: ProjectedNode, valid: boolean }}
  */
 export function projectStateTree (stateTree, statefulLayout) {
   return {
@@ -121,6 +148,154 @@ export function projectStateTree (stateTree, statefulLayout) {
   }
 }
 
+/**
+ * Format a projected node as a markdown line for LLM-readable output.
+ * @param {import('../state/types.js').StateNode} node
+ * @param {import('../state/index.js').StatefulLayout} statefulLayout
+ * @param {number} [depth]
+ * @returns {string}
+ */
+export function projectNodeToMarkdown (node, statefulLayout, depth = 0) {
+  const indent = '  '.repeat(depth)
+  const type = compToType[node.layout.comp] || node.layout.comp
+  const layout = /** @type {Record<string, unknown>} */(node.layout)
+
+  // build metadata tags
+  const meta = [type]
+  if (node.skeleton.required) meta.push('required')
+  if (node.options.readOnly) meta.push('readOnly')
+  if (node.error) meta.push('error')
+  if (node.modified) meta.push('modified')
+
+  // constraints
+  const keys = getConstraintKeys(node.layout.comp)
+  if (keys) {
+    for (const k of keys) {
+      const v = layout[k]
+      if (v !== undefined && v !== null) meta.push(`${k}=${v}`)
+    }
+  }
+
+  // variants
+  if (node.layout.comp === 'one-of-select' && Array.isArray(layout.oneOfItems)) {
+    const selected = layout.oneOfItems.find((item) => item.selected)
+    if (selected) meta.push(`selected=${selected.key}`)
+  }
+
+  if (isItemsLayout(node.layout, statefulLayout.compiledLayout.components)) meta.push('suggestions')
+
+  // array item count
+  if (node.layout.comp === 'list' && Array.isArray(node.data)) {
+    meta.push(`${node.data.length} items`)
+  }
+
+  const path = node.fullKey || '/'
+  let line = `${indent}- ${path} (${meta.join(', ')})`
+
+  if (typeof layout.label === 'string') line += ` label="${layout.label}"`
+  else if (typeof layout.title === 'string') line += ` title="${layout.title}"`
+
+  // value for leaf nodes (no children or empty children)
+  if (!node.children || node.children.length === 0) {
+    line += ` value=${JSON.stringify(node.data)}`
+  }
+
+  if (node.error) line += ` — ${node.error}`
+
+  const lines = [line]
+
+  // variants list
+  if (node.layout.comp === 'one-of-select' && Array.isArray(layout.oneOfItems)) {
+    const variants = layout.oneOfItems.filter((item) => !item.header)
+    for (const v of variants) {
+      lines.push(`${indent}  - variant ${v.key}: ${v.title}`)
+    }
+  }
+
+  // recurse children
+  if (node.children) {
+    for (const child of node.children) {
+      if (child.layout.comp === 'none') continue
+      lines.push(projectNodeToMarkdown(child, statefulLayout, depth + 1))
+    }
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Format a state tree as markdown for LLM-readable output.
+ * @param {import('../state/types.js').StateTree} stateTree
+ * @param {import('../state/index.js').StatefulLayout} statefulLayout
+ * @returns {string}
+ */
+export function projectStateTreeToMarkdown (stateTree, statefulLayout) {
+  const errors = collectErrors(stateTree.root)
+  const validLine = stateTree.valid
+    ? 'valid: true, no errors'
+    : `valid: false, ${errors.length} error(s)`
+
+  const lines = [validLine, '']
+
+  if (!stateTree.valid && errors.length > 0) {
+    lines.push('Errors:')
+    for (const e of errors) {
+      lines.push(`- ${e.path}: ${e.message}`)
+    }
+    lines.push('')
+  }
+
+  lines.push('Fields:')
+  lines.push(projectNodeToMarkdown(stateTree.root, statefulLayout, 0))
+
+  return lines.join('\n')
+}
+
+/**
+ * Format a mutation result as concise text for LLM-readable output.
+ * @param {boolean} valid
+ * @param {Array<{path: string, message: string}>} errors
+ * @param {string} [prefix] - optional prefix line (e.g. field info)
+ * @returns {string}
+ */
+export function formatMutationResult (valid, errors, prefix) {
+  const lines = []
+  if (prefix) lines.push(prefix)
+
+  if (valid) {
+    lines.push('valid, no errors')
+  } else {
+    lines.push(`invalid, ${errors.length} error(s)`)
+    if (errors.length > 0) {
+      lines.push('Errors:')
+      for (const e of errors) {
+        lines.push(`- ${e.path}: ${e.message}`)
+      }
+    }
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Format field suggestions as markdown for LLM-readable output.
+ * @param {Array<{value: unknown, title: string, key?: string}>} items
+ * @returns {string}
+ */
+export function formatSuggestions (items) {
+  if (items.length === 0) return 'No suggestions available'
+  const lines = ['Suggestions (use the value with setFieldValue or setData):']
+  for (const item of items) {
+    const val = JSON.stringify(item.value)
+    if (item.key && item.key !== item.title) {
+      lines.push(`- value=${val} — ${item.title} (${item.key})`)
+    } else {
+      lines.push(`- value=${val} — ${item.title}`)
+    }
+  }
+  return lines.join('\n')
+}
+
 /**
  * @param {import('../state/types.js').StateNode} node
  * @returns {Array<{path: string, message: string}>}

package/src/webmcp/tools/describe-state.js

@@ -2,7 +2,7 @@
  * @file describeState tool
  */
 
-import { projectStateTree, projectNode, collectErrors } from '../project.js'
+import { projectStateTree, projectNode, collectErrors, projectNodeToMarkdown, projectStateTreeToMarkdown, formatMutationResult } from '../project.js'
 import { resolveNode } from '../resolve.js'
 
 export const inputSchema = {
@@ -40,10 +40,15 @@ export const outputSchema = {
 
 /**
  * @param {string} dataTitle
+ * @param {"small"|"medium"|"large"} [complexity]
  * @returns {string}
  */
-export function getDescription (dataTitle) {
-  return `Describe the current "${dataTitle}" state tree. Optionally focus on a subtree by path to reduce output size.`
+export function getDescription (dataTitle, complexity) {
+  let desc = `Describe the "${dataTitle}" form structure, field types, constraints, and current errors.`
+  if (complexity === 'large') {
+    desc += ' Use the "path" parameter to focus on a subtree — avoid calling without a path on large forms.'
+  }
+  return desc
 }
 
 /**
@@ -72,3 +77,23 @@ export function execute (statefulLayout, args) {
     errors
   }
 }
+
+/**
+ * @param {import('../../state/index.js').StatefulLayout} statefulLayout
+ * @param {{ path?: string }} args
+ * @returns {string}
+ */
+export function toMarkdown (statefulLayout, args) {
+  if (args.path) {
+    const node = resolveNode(statefulLayout.stateTree.root, args.path)
+    if (!node) {
+      throw new Error(`node not found at path: ${args.path}`)
+    }
+    const errors = collectErrors(node)
+    return formatMutationResult(statefulLayout.valid, errors,
+      projectNodeToMarkdown(node, statefulLayout)
+    )
+  }
+
+  return projectStateTreeToMarkdown(statefulLayout.stateTree, statefulLayout)
+}