@json-layout/core 2.4.0 → 2.5.1

package/src/webmcp/index.js

@@ -0,0 +1,283 @@
+/**
+ * @file WebMCP integration for JSON Layout StatefulLayout
+ * @description Provides MCP tool descriptors that work with browser's navigator.modelContext
+ */
+
+import debug from 'debug'
+
+import * as describeState from './tools/describe-state.js'
+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 fillFormSkill from './tools/fill-form-skill.js'
+
+/** @typedef {import('@mcp-b/webmcp-types').ToolDescriptor} ToolDescriptor */
+
+const log = debug('jl:webmcp')
+
+/**
+ * @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
+ */
+
+/**
+ * WebMCP class that provides MCP tool descriptors for a StatefulLayout instance
+ */
+export class WebMCP {
+  /**
+   * @readonly
+   * @type {import('../state/index.js').StatefulLayout}
+   */
+  _statefulLayout
+
+  /**
+   * @readonly
+   * @type {string}
+   */
+  _prefixName
+
+  /**
+   * @readonly
+   * @type {string}
+   */
+  _dataTitle
+
+  /**
+   * @readonly
+   * @type {string}
+   */
+  _skill
+
+  /**
+   * @readonly
+   * @type {object | null}
+   */
+  _schema = null
+
+  /**
+   * @type {string[]}
+   */
+  _registeredTools = []
+
+  /**
+   * @param {import('../state/index.js').StatefulLayout} statefulLayout
+   * @param {WebMCPOptions} [options]
+   */
+  constructor (statefulLayout, options = {}) {
+    this._statefulLayout = statefulLayout
+    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)
+  }
+
+  /**
+   * @param {string} name
+   * @returns {string}
+   */
+  _toolName (name) {
+    return this._prefixName + name
+  }
+
+  /**
+   * @returns {ToolDescriptor[]}
+   */
+  getTools () {
+    const dataTitle = this._dataTitle
+
+    /** @type {ToolDescriptor[]} */
+    const tools = [
+      {
+        name: this._toolName('fillFormSkill'),
+        description: fillFormSkill.getDescription(dataTitle),
+        outputSchema: { type: 'string' },
+        execute: async (args) => {
+          try {
+            return {
+              content: [{ type: 'text', text: this._skill }]
+            }
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err)
+            return {
+              content: [{ type: 'text', text: `Error: ${message}` }],
+              isError: true
+            }
+          }
+        }
+      },
+      {
+        name: this._toolName('getData'),
+        description: getData.getDescription(dataTitle),
+        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) }]
+            }
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err)
+            return {
+              content: [{ type: 'text', text: `Error: ${message}` }],
+              isError: true
+            }
+          }
+        }
+      },
+      {
+        name: this._toolName('setData'),
+        description: setData.getDescription(dataTitle),
+        inputSchema: setData.inputSchema,
+        outputSchema: setData.outputSchema,
+        execute: async (args) => {
+          try {
+            if (!args?.data) {
+              throw new Error('data is required')
+            }
+            const result = setData.execute(
+              this._statefulLayout,
+              /** @type {{ data: unknown }} */(args)
+            )
+            return {
+              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+            }
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err)
+            return {
+              content: [{ type: 'text', text: `Error: ${message}` }],
+              isError: true
+            }
+          }
+        }
+      },
+      {
+        name: this._toolName('describeState'),
+        description: describeState.getDescription(dataTitle),
+        inputSchema: describeState.inputSchema,
+        outputSchema: describeState.outputSchema,
+        execute: async (args) => {
+          try {
+            const result = describeState.execute(this._statefulLayout, args || {})
+            return {
+              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+            }
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err)
+            return {
+              content: [{ type: 'text', text: `Error: ${message}` }],
+              isError: true
+            }
+          }
+        }
+      },
+      {
+        name: this._toolName('setFieldValue'),
+        description: setFieldValue.getDescription(dataTitle),
+        inputSchema: setFieldValue.inputSchema,
+        outputSchema: setFieldValue.outputSchema,
+        execute: async (args) => {
+          try {
+            if (!args?.path) {
+              throw new Error('path is required')
+            }
+            const result = setFieldValue.execute(
+              this._statefulLayout,
+              /** @type {{ path: string, value: unknown }} */(args)
+            )
+            return {
+              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+            }
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err)
+            return {
+              content: [{ type: 'text', text: `Error: ${message}` }],
+              isError: true
+            }
+          }
+        }
+      },
+      {
+        name: this._toolName('getFieldSuggestions'),
+        description: getFieldSuggestions.getDescription(dataTitle),
+        inputSchema: getFieldSuggestions.inputSchema,
+        outputSchema: getFieldSuggestions.outputSchema,
+        execute: async (args) => {
+          try {
+            if (!args?.path) {
+              throw new Error('path is required')
+            }
+            const result = await getFieldSuggestions.execute(
+              this._statefulLayout,
+              /** @type {{ path: string, query?: string }} */(args)
+            )
+            return {
+              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+            }
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err)
+            return {
+              content: [{ type: 'text', text: `Error: ${message}` }],
+              isError: true
+            }
+          }
+        }
+      }
+    ]
+
+    if (this._schema) {
+      tools.push({
+        name: this._toolName('getSchema'),
+        description: `Get the the JSON schema that governs "${dataTitle}" form.`,
+        outputSchema: {
+          type: 'object',
+          properties: {
+            jsonSchema: {},
+          }
+        },
+        execute: async (args) => {
+          return {
+            jsonSchema: this._schema
+          }
+        }
+      })
+    }
+
+    return tools
+  }
+
+  /**
+   * @returns {Promise<void>}
+   */
+  async registerTools () {
+    if (typeof navigator === 'undefined' || !navigator.modelContext) {
+      throw new Error('navigator.modelContext is not available')
+    }
+
+    const tools = this.getTools()
+    for (const tool of tools) {
+      log('registering tool:', tool.name)
+      // @ts-ignore - complex generic types from webmcp-types
+      await navigator.modelContext.registerTool(tool)
+      this._registeredTools.push(tool.name)
+    }
+  }
+
+  /**
+   * @returns {Promise<void>}
+   */
+  async unregisterTools () {
+    if (typeof navigator === 'undefined' || !navigator.modelContext) {
+      throw new Error('navigator.modelContext is not available')
+    }
+
+    for (const name of this._registeredTools) {
+      log('unregistering tool:', name)
+      await navigator.modelContext.unregisterTool(name)
+    }
+    this._registeredTools = []
+  }
+}

package/src/webmcp/project.js

@@ -0,0 +1,148 @@
+/**
+ * @file Projection functions for webmcp tools
+ */
+
+import { isItemsLayout } from '@json-layout/vocabulary'
+
+const constraintKeys = {
+  'number-field': ['min', 'max', 'step', 'precision'],
+  slider: ['min', 'max', 'step'],
+  'date-picker': ['min', 'max', 'format'],
+  'date-time-picker': ['min', 'max'],
+  'time-picker': ['min', 'max'],
+  combobox: ['separator'],
+  'number-combobox': ['separator']
+}
+
+/**
+ * @param {string} comp
+ * @returns {string[]|undefined}
+ */
+function getConstraintKeys (comp) {
+  // @ts-ignore - complex union type not fully represented
+  return constraintKeys[comp]
+}
+
+/**
+ * @param {import('../state/types.js').StateNode} node
+ * @param {import('../state/index.js').StatefulLayout} statefulLayout
+ * @returns {{
+ *   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>
+ *   getSuffections?: boolean
+ * }}
+ */
+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
+   * }}
+   */
+  const out = {
+    key: node.key,
+    path: node.fullKey,
+    comp: node.layout.comp,
+    data: node.data
+  }
+
+  const layout = /** @type {Record<string, unknown>} */(node.layout)
+  if (typeof layout.title === 'string') out.title = layout.title
+  if (typeof layout.label === 'string') out.label = layout.label
+  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 (isItemsLayout(node.layout, statefulLayout.compiledLayout.components)) out.getSuggestions = true
+
+  const keys = getConstraintKeys(node.layout.comp)
+  if (keys) {
+    /** @type {Record<string, unknown>} */
+    const constraints = {}
+    for (const k of keys) {
+      const v = layout[k]
+      if (v !== undefined && v !== null) constraints[k] = v
+    }
+    if (Object.keys(constraints).length > 0) out.constraints = constraints
+  }
+
+  if (node.layout.comp === 'one-of-select' && Array.isArray(layout.oneOfItems)) {
+    out.oneOfItems = layout.oneOfItems
+      .filter((item) => !item.header)
+      .map((item) => ({ key: item.key, title: item.title }))
+  }
+
+  if (node.children) {
+    out.children = node.children
+      .filter((c) => c.layout.comp !== 'none')
+      .map(node => projectNode(node, statefulLayout))
+  }
+
+  return out
+}
+
+/**
+ * @param {import('../state/types.js').StateTree} stateTree
+ * @param {import('../state/index.js').StatefulLayout} statefulLayout
+ * @returns {{ root: ReturnType<typeof projectNode>, valid: boolean }}
+ */
+export function projectStateTree (stateTree, statefulLayout) {
+  return {
+    root: projectNode(stateTree.root, statefulLayout),
+    valid: stateTree.valid
+  }
+}
+
+/**
+ * @param {import('../state/types.js').StateNode} node
+ * @returns {Array<{path: string, message: string}>}
+ */
+export function collectErrors (node) {
+  /** @type {Array<{path: string, message: string}>} */
+  const errors = []
+  collectErrorsRecurse(node, errors)
+  return errors
+}
+
+/**
+ * @param {import('../state/types.js').StateNode} node
+ * @param {Array<{path: string, message: string}>} errors
+ */
+function collectErrorsRecurse (node, errors) {
+  if (node.error) {
+    errors.push({ path: node.fullKey, message: node.error })
+  }
+  if (node.children) {
+    for (const child of node.children) {
+      collectErrorsRecurse(child, errors)
+    }
+  }
+}

package/src/webmcp/resolve.js

@@ -0,0 +1,25 @@
+/**
+ * @file Node resolution for webmcp tools
+ */
+
+/**
+ * Navigate from a root StateNode to a descendant node by path.
+ * @param {import('../state/types.js').StateNode} root
+ * @param {string} path
+ * @returns {import('../state/types.js').StateNode|undefined}
+ */
+export function resolveNode (root, path) {
+  if (!path || path === '/') return root
+
+  const segments = path.replace(/^\//, '').split('/')
+  /** @type {import('../state/types.js').StateNode|undefined} */
+  let current = root
+
+  for (const segment of segments) {
+    if (!current?.children) return undefined
+    const key = /^\d+$/.test(segment) ? parseInt(segment, 10) : segment
+    current = current.children.find((c) => c.key === key)
+  }
+
+  return current
+}

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

@@ -0,0 +1,74 @@
+/**
+ * @file describeState tool
+ */
+
+import { projectStateTree, projectNode, collectErrors } from '../project.js'
+import { resolveNode } from '../resolve.js'
+
+export const inputSchema = {
+  type: 'object',
+  properties: {
+    path: {
+      type: 'string',
+      description: 'Path to a specific node (e.g. "/address/city"). Omit for full tree.'
+    }
+  }
+}
+
+export const outputSchema = {
+  type: 'object',
+  properties: {
+    state: {
+      type: 'object',
+      description: 'Projected state tree or single node'
+    },
+    valid: {
+      type: 'boolean'
+    },
+    errors: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          message: { type: 'string' }
+        }
+      }
+    }
+  }
+}
+
+/**
+ * @param {string} dataTitle
+ * @returns {string}
+ */
+export function getDescription (dataTitle) {
+  return `Describe the current "${dataTitle}" state tree. Optionally focus on a subtree by path to reduce output size.`
+}
+
+/**
+ * @param {import('../../state/index.js').StatefulLayout} statefulLayout
+ * @param {{ path?: string }} args
+ * @returns {{state: ReturnType<typeof projectStateTree>|ReturnType<typeof projectNode>, valid: boolean, errors: Array<{path: string, message: string}>}}
+ */
+export function execute (statefulLayout, args) {
+  const errors = collectErrors(statefulLayout.stateTree.root)
+
+  if (args.path) {
+    const node = resolveNode(statefulLayout.stateTree.root, args.path)
+    if (!node) {
+      throw new Error(`node not found at path: ${args.path}`)
+    }
+    return {
+      state: projectNode(node, statefulLayout),
+      valid: statefulLayout.valid,
+      errors
+    }
+  }
+
+  return {
+    state: projectStateTree(statefulLayout.stateTree, statefulLayout),
+    valid: statefulLayout.valid,
+    errors
+  }
+}

package/src/webmcp/tools/fill-form-skill.js

@@ -0,0 +1,67 @@
+/**
+ * @file fillFormSkill tool
+ */
+
+export const outputSchema = {
+  type: 'object',
+  properties: {
+    content: { type: 'string' }
+  }
+}
+
+/**
+ * @param {string} dataTitle
+ * @returns {string}
+ */
+export function getDescription (dataTitle) {
+  return `Get guidance on how to interact with the form "${dataTitle}" using the available tools.`
+}
+
+/**
+ * Generate skill content with dataTitle injected
+ * @param {string} dataTitle
+ * @param {string} prefixName
+ * @param {boolean} hasSchema
+ * @param {import('../../state/index.js').StatefulLayout} statefulLayout
+ * @returns {string}
+ */
+export function generateSkill (dataTitle, prefixName, hasSchema, statefulLayout) {
+  /** @type {"small" | "medium" | "large"} */
+  let complexity = 'small'
+  const nbNormalizedLayouts = Object.keys(statefulLayout.compiledLayout.normalizedLayouts).length
+  if (nbNormalizedLayouts > 15) complexity = 'medium'
+  if (nbNormalizedLayouts > 50) complexity = 'large'
+  let skill = `# JSON ${dataTitle.charAt(0).toUpperCase() + dataTitle.slice(1)} Form-Filling Guide
+
+This guide teaches you how to use tools to fill the data of a form in the user's page.
+
+Always start by getting the current data using ${prefixName}getData.
+`
+
+  if (complexity === 'small') {
+    skill += `
+Given the small complexity of this form you should start by reading the full schema definition using ${prefixName}${hasSchema ? 'getSchema' : 'describeState'} and attempt updating the whole data using ${prefixName}setData.
+Only use ${prefixName}describeState and iterate with ${prefixName}setFieldValue if you encounter some difficulties with ${prefixName}setData.
+`
+  }
+
+  if (complexity === 'small') {
+    skill += `
+Given the medium complexity of this form you should start by reading the full schema definition using ${prefixName}${hasSchema ? 'getSchema' : 'describeState'}, if you have a satisfying understanding of the schema you can attempt updating the whole data using ${prefixName}setData at least once.
+Then use ${prefixName}describeState and iterate with ${prefixName}setFieldValue.
+`
+  }
+
+  if (complexity === 'large') {
+    skill += `
+Given the large complexity of this form you should avoid reading the full schema definition using ${prefixName}${hasSchema ? 'getSchema' : 'describeState'}.
+Prefer using ${prefixName}describeState and iterating with ${prefixName}setFieldValue.
+`
+  }
+
+  skill += `
+If you encounter getItems definitions in the schema or getSuggestions flags in the state. You must use ${prefixName}getFieldSuggestions to fetch the accepted values.
+`
+
+  return skill
+}

package/src/webmcp/tools/get-data.js

@@ -0,0 +1,36 @@
+/**
+ * @file getData tool
+ */
+
+export const inputSchema = {
+  type: 'object',
+  properties: {}
+}
+
+export const outputSchema = {
+  type: 'object',
+  properties: {
+    data: {},
+    valid: { type: 'boolean' }
+  }
+}
+
+/**
+ * @param {string} dataTitle
+ * @returns {string}
+ */
+export function getDescription (dataTitle) {
+  return `Get the current "${dataTitle}" data and validity status.`
+}
+
+/**
+ * @param {import('../../state/index.js').StatefulLayout} statefulLayout
+ * @param {{}} _args
+ * @returns {{ data: unknown, valid: boolean }}
+ */
+export function execute (statefulLayout, _args) {
+  return {
+    data: statefulLayout.data,
+    valid: statefulLayout.valid
+  }
+}