@symbiotejs/symbiote 3.10.2 → 3.10.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/core/PubSub.js +18 -5
- package/core/Symbiote.js +9 -5
- package/core/dictionary.js +5 -22
- package/core/extensions.js +17 -0
- package/core/itemizeProcessor-keyed.js +2 -2
- package/core/itemizeProcessor.js +3 -3
- package/core/itemizeSetup.js +4 -4
- package/core/tpl-processors.js +17 -92
- package/core/webmcp-bindings.js +59 -0
- package/core/webmcp-dictionary.js +17 -0
- package/core/webmcp.js +216 -51
- package/docs/webmcp.md +80 -0
- package/html-app/BaseClass.js +2 -2
- package/html-app/README.md +15 -0
- package/html-app/actions.js +4 -2
- package/html-app/collection-items.js +1 -1
- package/html-app/examples/assets/actions.html +10 -10
- package/html-app/examples/assets/collections.html +19 -19
- package/html-app/examples/assets/components.html +1 -1
- package/html-app/examples/assets/conditional.html +2 -2
- package/html-app/examples/assets/data.html +5 -5
- package/html-app/examples/assets/guide.html +1 -1
- package/html-app/examples/assets/not-found.html +1 -1
- package/html-app/examples/assets/routing.html +2 -2
- package/html-app/examples/assets/state.html +2 -2
- package/html-app/examples/assets/storage.html +6 -6
- package/html-app/examples/full-app.html +3 -2
- package/package.json +13 -1
- package/scripts/check-html-app-size.js +2 -0
- package/skills/symbiote/SKILL.md +24 -1
- package/types/core/PubSub.d.ts.map +1 -1
- package/types/core/Symbiote.d.ts.map +1 -1
- package/types/core/dictionary.d.ts +3 -11
- package/types/core/extensions.d.ts +13 -0
- package/types/core/extensions.d.ts.map +1 -0
- package/types/core/itemizeSetup.d.ts +1 -1
- package/types/core/itemizeSetup.d.ts.map +1 -1
- package/types/core/tpl-processors.d.ts +0 -7
- package/types/core/tpl-processors.d.ts.map +1 -1
- package/types/core/webmcp-bindings.d.ts +18 -0
- package/types/core/webmcp-bindings.d.ts.map +1 -0
- package/types/core/webmcp-dictionary.d.ts +36 -0
- package/types/core/webmcp-dictionary.d.ts.map +1 -0
- package/types/core/webmcp.d.ts.map +1 -1
- package/types/html-app/actions.d.ts.map +1 -1
- package/types/utils/reassignDictionary.d.ts +3 -11
- package/types/utils/reassignDictionary.d.ts.map +1 -1
package/core/webmcp.js
CHANGED
|
@@ -3,6 +3,9 @@ import Symbiote from './Symbiote.js';
|
|
|
3
3
|
import { devState } from './warn.js';
|
|
4
4
|
import { DICT } from './dictionary.js';
|
|
5
5
|
import { parseProp } from './parseProp.js';
|
|
6
|
+
import { extensions } from './extensions.js';
|
|
7
|
+
import { WEBMCP_DICT as MCP } from './webmcp-dictionary.js';
|
|
8
|
+
import { isToolDescriptor, webMCPBindings } from './webmcp-bindings.js';
|
|
6
9
|
|
|
7
10
|
/**
|
|
8
11
|
* @typedef {Object} WebMCPToolResultText
|
|
@@ -58,10 +61,6 @@ let pendingOwnerSync = new WeakSet();
|
|
|
58
61
|
let ownerVersions = new WeakMap();
|
|
59
62
|
let _modelContext;
|
|
60
63
|
|
|
61
|
-
function isToolDescriptor(val) {
|
|
62
|
-
return !!val?.[DICT.MCP_TOOL_DESCRIPTOR_MARKER];
|
|
63
|
-
}
|
|
64
|
-
|
|
65
64
|
function isElementOwner(owner) {
|
|
66
65
|
return typeof HTMLElement !== 'undefined' && owner instanceof HTMLElement;
|
|
67
66
|
}
|
|
@@ -173,7 +172,7 @@ function ownerToolName(owner) {
|
|
|
173
172
|
if (!isElementOwner(owner)) {
|
|
174
173
|
return name;
|
|
175
174
|
}
|
|
176
|
-
let identity = owner[DICT.
|
|
175
|
+
let identity = owner[DICT.ITEM_KEY_KEY] ?? owner[DICT.ITEM_INDEX_KEY];
|
|
177
176
|
let clean = identity === undefined ? '' : cleanIdentity(identity);
|
|
178
177
|
return clean ? `${name}_${clean}` : name;
|
|
179
178
|
}
|
|
@@ -264,10 +263,10 @@ function ownerType(owner) {
|
|
|
264
263
|
}
|
|
265
264
|
|
|
266
265
|
function ownerId(owner) {
|
|
267
|
-
if (!owner[
|
|
268
|
-
owner[
|
|
266
|
+
if (!owner[MCP.OWNER_ID_KEY]) {
|
|
267
|
+
owner[MCP.OWNER_ID_KEY] = `${ownerType(owner)}-${++ownerIdCount}`;
|
|
269
268
|
}
|
|
270
|
-
return owner[
|
|
269
|
+
return owner[MCP.OWNER_ID_KEY];
|
|
271
270
|
}
|
|
272
271
|
|
|
273
272
|
function getModelContext() {
|
|
@@ -428,6 +427,7 @@ function makeEntryWithComponentDescription(publicName, key, descriptor, owner, e
|
|
|
428
427
|
let schema = readInputSchema(descriptor, owner);
|
|
429
428
|
let entry = {
|
|
430
429
|
name: publicName,
|
|
430
|
+
baseName: publicName,
|
|
431
431
|
key,
|
|
432
432
|
ownerId: id,
|
|
433
433
|
ownerType: ownerType(owner),
|
|
@@ -475,18 +475,173 @@ function createExplicitDesired(owner, key, descriptor) {
|
|
|
475
475
|
};
|
|
476
476
|
}
|
|
477
477
|
|
|
478
|
-
function
|
|
478
|
+
function normalizeText(value) {
|
|
479
|
+
return String(value ?? '').replace(/\s+/g, ' ').trim();
|
|
480
|
+
}
|
|
481
|
+
|
|
482
|
+
function textAttribute(el, name) {
|
|
483
|
+
return normalizeText(el?.getAttribute?.(name));
|
|
484
|
+
}
|
|
485
|
+
|
|
486
|
+
function controlLabel(el) {
|
|
487
|
+
let root = el?.getRootNode?.() || el?.ownerDocument;
|
|
488
|
+
let references = textAttribute(el, 'aria-labelledby').split(' ').filter(Boolean);
|
|
489
|
+
let label = references.map((id) => root?.getElementById?.(id)?.textContent || '').join(' ');
|
|
490
|
+
label = normalizeText(label) || textAttribute(el, 'aria-label');
|
|
491
|
+
if (!label) {
|
|
492
|
+
label = normalizeText(Array.from(el?.labels || [], (label) => {
|
|
493
|
+
let content = label.cloneNode(true);
|
|
494
|
+
content.querySelectorAll('input, textarea, select, button, meter, output, progress').forEach((control) => control.remove());
|
|
495
|
+
return content.textContent;
|
|
496
|
+
}).join(' '));
|
|
497
|
+
}
|
|
498
|
+
if (!label && (['button', 'a'].includes(el?.localName) || textAttribute(el, 'role') === 'button')) {
|
|
499
|
+
label = normalizeText(el.textContent);
|
|
500
|
+
}
|
|
501
|
+
if (!label && el?.localName === 'input' && ['button', 'submit', 'reset'].includes(el.type)) {
|
|
502
|
+
label = normalizeText(el.value);
|
|
503
|
+
}
|
|
504
|
+
label ||= textAttribute(el, 'title');
|
|
505
|
+
return label.length > 200 ? `${label.slice(0, 199)}…` : label;
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
function submissionForm(owner, binding) {
|
|
509
|
+
let el = binding.el;
|
|
510
|
+
if (binding.prop === 'onsubmit' && el?.localName === 'form') {
|
|
511
|
+
return el;
|
|
512
|
+
}
|
|
513
|
+
// A separately bound submit control duplicates the form only when it uses
|
|
514
|
+
// the same handler. Independent click operations keep their own tools.
|
|
515
|
+
if (binding.prop === 'onclick' && ['button', 'input'].includes(el?.localName)
|
|
516
|
+
&& ['submit', 'image'].includes(el.type) && el.form?.onsubmit === owner.$?.[binding.key]) {
|
|
517
|
+
return el.form;
|
|
518
|
+
}
|
|
519
|
+
return null;
|
|
520
|
+
}
|
|
521
|
+
|
|
522
|
+
function hasNativeFormTools(form) {
|
|
523
|
+
let doc = form.ownerDocument;
|
|
524
|
+
let prototype = doc?.defaultView?.SubmitEvent?.prototype;
|
|
525
|
+
// SubmitEvent's WebMCP extensions are gated by declarative support,
|
|
526
|
+
// independently of the imperative modelContext API.
|
|
527
|
+
return !!(doc?.modelContext?.registerTool && prototype
|
|
528
|
+
&& 'agentInvoked' in prototype && typeof prototype.respondWith === 'function');
|
|
529
|
+
}
|
|
530
|
+
|
|
531
|
+
function autoBindingAvailable(owner, binding) {
|
|
532
|
+
let el = binding.el;
|
|
533
|
+
if (!Object.hasOwn(MCP.TOOL_EVENTS, binding.prop) || el?.isConnected === false
|
|
534
|
+
|| binding.sourceOwner?.isConnected === false) {
|
|
535
|
+
return false;
|
|
536
|
+
}
|
|
537
|
+
let form = submissionForm(owner, binding);
|
|
538
|
+
if (form && textAttribute(form, MCP.TOOL_NAME_ATTR) && textAttribute(form, MCP.TOOL_DESCRIPTION_ATTR)) {
|
|
539
|
+
if (hasNativeFormTools(form) || !form.hasAttribute(MCP.TOOL_AUTOSUBMIT_ATTR)) {
|
|
540
|
+
return false;
|
|
541
|
+
}
|
|
542
|
+
}
|
|
543
|
+
if (binding.prop === 'oninput' || binding.prop === 'onchange') {
|
|
544
|
+
return !el?.matches?.(':disabled') && !el?.readOnly && !el?.closest?.('[inert], [aria-disabled="true"]');
|
|
545
|
+
}
|
|
546
|
+
return true;
|
|
547
|
+
}
|
|
548
|
+
|
|
549
|
+
function autoControlInput(el, prop) {
|
|
550
|
+
let editing = prop === 'oninput' || prop === 'onchange';
|
|
551
|
+
let supported = ['input', 'textarea', 'select'].includes(el?.localName);
|
|
552
|
+
if (!editing || !supported) {
|
|
553
|
+
return prop === 'oninput' ? null : { inputSchema: emptySchema(), apply() {} };
|
|
554
|
+
}
|
|
555
|
+
if (el.localName === 'input' && ['file', 'hidden', 'button', 'submit', 'reset', 'image'].includes(el.type)) {
|
|
556
|
+
return null;
|
|
557
|
+
}
|
|
558
|
+
let checked = el.localName === 'input' && ['checkbox', 'radio'].includes(el.type);
|
|
559
|
+
let multiple = el.localName === 'select' && el.multiple;
|
|
560
|
+
let numeric = el.localName === 'input' && ['number', 'range'].includes(el.type);
|
|
561
|
+
let property = checked ? 'checked' : 'value';
|
|
562
|
+
let type = checked ? 'boolean' : multiple ? 'array' : numeric ? ['string', 'number'] : 'string';
|
|
563
|
+
let field = { type, description: checked ? 'Checked state to apply to the control.' : 'Value to insert into the control.' };
|
|
564
|
+
let options = el.localName === 'select'
|
|
565
|
+
? Array.from(el.options).filter((option) => !option.disabled && !option.parentElement?.disabled).map((option) => option.value)
|
|
566
|
+
: null;
|
|
567
|
+
let valueSchema = multiple ? { ...field, items: { type: 'string', enum: options } }
|
|
568
|
+
: options ? { ...field, enum: options } : field;
|
|
569
|
+
return {
|
|
570
|
+
inputSchema: {
|
|
571
|
+
...emptySchema(),
|
|
572
|
+
properties: { [property]: valueSchema },
|
|
573
|
+
required: prop === 'oninput' ? [property] : [],
|
|
574
|
+
},
|
|
575
|
+
apply(args) {
|
|
576
|
+
if (!Object.hasOwn(args, property)) {
|
|
577
|
+
if (prop === 'oninput') {
|
|
578
|
+
throw new TypeError(`Input tool requires "${property}".`);
|
|
579
|
+
}
|
|
580
|
+
return;
|
|
581
|
+
}
|
|
582
|
+
let value = args[property];
|
|
583
|
+
let valid = checked ? typeof value === 'boolean'
|
|
584
|
+
: multiple ? Array.isArray(value) && value.every((item) => typeof item === 'string')
|
|
585
|
+
: typeof value === 'string' || (numeric && typeof value === 'number' && Number.isFinite(value));
|
|
586
|
+
if (!valid) {
|
|
587
|
+
throw new TypeError(`Invalid control "${property}".`);
|
|
588
|
+
}
|
|
589
|
+
// Check current options, since a tool can outlive a change to the select.
|
|
590
|
+
if (options) {
|
|
591
|
+
let allowed = Array.from(el.options).filter((option) => !option.disabled && !option.parentElement?.disabled).map((option) => option.value);
|
|
592
|
+
if (!(multiple ? value : [value]).every((item) => allowed.includes(item))) {
|
|
593
|
+
throw new TypeError('Unknown or disabled select option.');
|
|
594
|
+
}
|
|
595
|
+
}
|
|
596
|
+
if (multiple) {
|
|
597
|
+
for (let option of el.options) {
|
|
598
|
+
option.selected = value.includes(option.value);
|
|
599
|
+
}
|
|
600
|
+
} else {
|
|
601
|
+
let previous = el[property];
|
|
602
|
+
el[property] = checked ? value : String(value);
|
|
603
|
+
if (!checked && el.value !== String(value)) {
|
|
604
|
+
el[property] = previous;
|
|
605
|
+
throw new TypeError('The control cannot accept this value.');
|
|
606
|
+
}
|
|
607
|
+
}
|
|
608
|
+
},
|
|
609
|
+
};
|
|
610
|
+
}
|
|
611
|
+
|
|
612
|
+
function autoMetadata(owner, binding) {
|
|
613
|
+
let el = binding.el;
|
|
614
|
+
let operation = MCP.TOOL_EVENTS[binding.prop];
|
|
615
|
+
let name = textAttribute(el, MCP.TOOL_NAME_ATTR);
|
|
616
|
+
let description = textAttribute(el, MCP.TOOL_DESCRIPTION_ATTR);
|
|
617
|
+
let label = controlLabel(el);
|
|
618
|
+
let handler = owner.$?.[binding.key];
|
|
619
|
+
let authoredKey = !handler?.[DICT.GENERATED_HANDLER_KEY];
|
|
620
|
+
let priority = description ? 4 : label ? 3 : name ? 2 : authoredKey ? 1 : 0;
|
|
621
|
+
let input = autoControlInput(el, binding.prop);
|
|
622
|
+
if (!priority || !input) {
|
|
623
|
+
return null;
|
|
624
|
+
}
|
|
625
|
+
description ||= `${operation.description}: ${label || name || binding.key}.`;
|
|
626
|
+
let control = el?.localName ? ` Control: <${el.localName}>${label ? ` ${JSON.stringify(label)}` : ''}.` : '';
|
|
627
|
+
let id = textAttribute(el, 'id');
|
|
628
|
+
description += `\nEvent: ${operation.event}.${control}${id ? ` ID: ${id}.` : ''} Component: <${ownerToolName(owner)}>.`;
|
|
629
|
+
return { name, description, priority, ...input };
|
|
630
|
+
}
|
|
631
|
+
|
|
632
|
+
function createAutoDesired(owner, key, eventBinding, metadata) {
|
|
479
633
|
let tagName = ownerName(owner);
|
|
480
634
|
let toolOwnerName = ownerToolName(owner);
|
|
481
635
|
let sourceName = sourceToolName(eventBinding?.sourceOwner);
|
|
482
636
|
let sourceSuffix = sourceName ? `_${sourceName}` : '';
|
|
483
|
-
let publicName = `${key}_in_${toolOwnerName}${sourceSuffix}`;
|
|
637
|
+
let publicName = metadata.name || `${key}_in_${toolOwnerName}${sourceSuffix}`;
|
|
484
638
|
let sourceDescription = sourceName ? ` Source binding: <${sourceName}>.` : '';
|
|
485
639
|
let descriptor = new ToolDescriptor({
|
|
486
640
|
name: publicName,
|
|
487
|
-
description:
|
|
488
|
-
inputSchema:
|
|
489
|
-
|
|
641
|
+
description: `${metadata.description}${sourceDescription}`,
|
|
642
|
+
inputSchema: metadata.inputSchema,
|
|
643
|
+
when: () => autoBindingAvailable(owner, eventBinding),
|
|
644
|
+
execute: (input) => {
|
|
490
645
|
let handler = owner.$?.[key];
|
|
491
646
|
if (isToolDescriptor(handler)) {
|
|
492
647
|
return handler.execute({}, owner);
|
|
@@ -494,6 +649,7 @@ function createAutoDesired(owner, key, eventBinding = null) {
|
|
|
494
649
|
if (typeof handler !== 'function') {
|
|
495
650
|
throw new Error(`Handler "${key}" is not available on <${tagName}>.`);
|
|
496
651
|
}
|
|
652
|
+
metadata.apply(input);
|
|
497
653
|
let result = handler.call(owner, syntheticEvent(eventBinding?.el));
|
|
498
654
|
let respond = (value) => {
|
|
499
655
|
let suffix = value ? `: ${value}` : '';
|
|
@@ -507,6 +663,7 @@ function createAutoDesired(owner, key, eventBinding = null) {
|
|
|
507
663
|
return {
|
|
508
664
|
key: sourceName ? `auto:${key}@${sourceName}` : `auto:${key}`,
|
|
509
665
|
baseName: publicName,
|
|
666
|
+
priority: metadata.priority,
|
|
510
667
|
descriptor,
|
|
511
668
|
executor(input) {
|
|
512
669
|
return descriptor.execute(input || {}, owner);
|
|
@@ -530,17 +687,19 @@ function collectAutoTools(owner, explicitKeys) {
|
|
|
530
687
|
if (!isElementOwner(owner) || !(owner.mcpToolMode || owner.constructor?.mcpToolMode)) {
|
|
531
688
|
return [];
|
|
532
689
|
}
|
|
533
|
-
let handlers = owner[
|
|
534
|
-
let result =
|
|
535
|
-
let seen = new Set();
|
|
690
|
+
let handlers = owner[MCP.EVENTS_KEY] || [];
|
|
691
|
+
let result = new Map();
|
|
536
692
|
let seenCtx = new Set();
|
|
537
693
|
for (let item of handlers) {
|
|
694
|
+
if (!autoBindingAvailable(owner, item)) {
|
|
695
|
+
continue;
|
|
696
|
+
}
|
|
538
697
|
if (item.sourceOwner && (!item.sourceOwner.isConnected || explicitKeys.has(item.key))) {
|
|
539
698
|
continue;
|
|
540
699
|
}
|
|
541
700
|
let sourceName = sourceToolName(item.sourceOwner);
|
|
542
701
|
let toolKey = sourceName ? `${item.key}@${sourceName}` : item.key;
|
|
543
|
-
if (explicitKeys.has(item.key)
|
|
702
|
+
if (explicitKeys.has(item.key)) {
|
|
544
703
|
continue;
|
|
545
704
|
}
|
|
546
705
|
let parsed = parseProp(item.key, owner);
|
|
@@ -550,13 +709,15 @@ function collectAutoTools(owner, explicitKeys) {
|
|
|
550
709
|
syncWebMCPTools(parsed.ctx);
|
|
551
710
|
}
|
|
552
711
|
}
|
|
553
|
-
if (parsed?.scope !== 'local') {
|
|
712
|
+
if (parsed?.scope !== 'local' || typeof owner.$?.[item.key] !== 'function') {
|
|
554
713
|
continue;
|
|
555
714
|
}
|
|
556
|
-
|
|
557
|
-
result.
|
|
715
|
+
let metadata = autoMetadata(owner, item);
|
|
716
|
+
if (metadata && (!result.has(toolKey) || result.get(toolKey).priority < metadata.priority)) {
|
|
717
|
+
result.set(toolKey, createAutoDesired(owner, item.key, item, metadata));
|
|
718
|
+
}
|
|
558
719
|
}
|
|
559
|
-
return result;
|
|
720
|
+
return [...result.values()];
|
|
560
721
|
}
|
|
561
722
|
|
|
562
723
|
function collectDesiredTools(owner) {
|
|
@@ -627,7 +788,7 @@ export class ToolDescriptor {
|
|
|
627
788
|
|
|
628
789
|
/** @param {ToolDescriptorOptions} options */
|
|
629
790
|
constructor(options = {}) {
|
|
630
|
-
this[
|
|
791
|
+
this[MCP.TOOL_DESCRIPTOR_MARKER] = true;
|
|
631
792
|
this.name = options.name;
|
|
632
793
|
this.description = options.description || 'Symbiote WebMCP tool.';
|
|
633
794
|
this.inputSchema = options.inputSchema || emptySchema();
|
|
@@ -726,11 +887,17 @@ function applyDesiredTools(owner, id, ownerEntry, desired, componentDescription)
|
|
|
726
887
|
}
|
|
727
888
|
continue;
|
|
728
889
|
}
|
|
729
|
-
let
|
|
890
|
+
let oldName = ownerEntry.toolsByKey[item.key];
|
|
891
|
+
if (oldName && webMCPRegistry.store.tools.read(oldName)?.baseName !== item.baseName) {
|
|
892
|
+
unregisterToolName(oldName);
|
|
893
|
+
oldName = null;
|
|
894
|
+
}
|
|
895
|
+
let publicName = oldName || resolveName(item.baseName, id, item.key);
|
|
730
896
|
if (hasToolName(publicName)) {
|
|
731
897
|
unregisterToolName(publicName);
|
|
732
898
|
}
|
|
733
899
|
let entry = makeEntryWithComponentDescription(publicName, item.key, item.descriptor, owner, item.executor, componentDescription);
|
|
900
|
+
entry.baseName = item.baseName;
|
|
734
901
|
ownerEntry.toolsByKey[item.key] = publicName;
|
|
735
902
|
webMCPRegistry.store.tools.add(publicName, entry, true);
|
|
736
903
|
}
|
|
@@ -782,11 +949,11 @@ export function syncWebMCPTools(owner) {
|
|
|
782
949
|
export function unregisterWebMCPTools(owner) {
|
|
783
950
|
if (!owner) return;
|
|
784
951
|
bumpOwnerVersion(owner);
|
|
785
|
-
let targets = owner[
|
|
952
|
+
let targets = owner[MCP.EVENT_TARGET_OWNERS_KEY];
|
|
786
953
|
if (targets) {
|
|
787
954
|
for (let target of targets) {
|
|
788
|
-
if (target[
|
|
789
|
-
target[
|
|
955
|
+
if (target[MCP.EVENTS_KEY]) {
|
|
956
|
+
target[MCP.EVENTS_KEY] = target[MCP.EVENTS_KEY].filter((entry) => entry.sourceOwner !== owner);
|
|
790
957
|
}
|
|
791
958
|
syncWebMCPTools(target);
|
|
792
959
|
}
|
|
@@ -829,31 +996,29 @@ export function installWebMCP(SymbioteClass = Symbiote) {
|
|
|
829
996
|
return;
|
|
830
997
|
}
|
|
831
998
|
installedClasses.add(SymbioteClass);
|
|
832
|
-
globalThis[
|
|
833
|
-
globalThis[
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
syncWebMCPTools
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
851
|
-
|
|
852
|
-
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
syncWebMCPTools(ctx);
|
|
856
|
-
};
|
|
999
|
+
globalThis[MCP.SYNC_OWNER_KEY] = syncWebMCPTools;
|
|
1000
|
+
globalThis[MCP.UNREGISTER_OWNER_KEY] = unregisterWebMCPTools;
|
|
1001
|
+
extensions.set('webmcp', {
|
|
1002
|
+
...webMCPBindings,
|
|
1003
|
+
syncOwner: syncWebMCPTools,
|
|
1004
|
+
disconnectOwner: unregisterWebMCPTools,
|
|
1005
|
+
contextRegistered(ctx, uid) {
|
|
1006
|
+
if (uid !== REGISTRY_UID) syncWebMCPTools(ctx);
|
|
1007
|
+
},
|
|
1008
|
+
contextDeleted(ctx, uid) {
|
|
1009
|
+
if (uid !== REGISTRY_UID) unregisterWebMCPTools(ctx);
|
|
1010
|
+
},
|
|
1011
|
+
contextChanged(ctx, prop) {
|
|
1012
|
+
if (!ctx.uid || ctx === webMCPRegistry || ctx === webMCPRegistry.store.tools
|
|
1013
|
+
|| ctx === webMCPRegistry.store.owners || ctx === webMCPRegistry.store.diagnostics) {
|
|
1014
|
+
return;
|
|
1015
|
+
}
|
|
1016
|
+
let existingOwner = webMCPRegistry.store.owners.read(ownerId(ctx));
|
|
1017
|
+
if (isToolDescriptor(ctx.store[prop]) || existingOwner?.toolsByKey?.[prop]) {
|
|
1018
|
+
syncWebMCPTools(ctx);
|
|
1019
|
+
}
|
|
1020
|
+
},
|
|
1021
|
+
});
|
|
857
1022
|
}
|
|
858
1023
|
|
|
859
1024
|
installWebMCP(Symbiote);
|
package/docs/webmcp.md
CHANGED
|
@@ -11,6 +11,8 @@ import Symbiote, { html } from '@symbiotejs/symbiote';
|
|
|
11
11
|
import '@symbiotejs/symbiote/webmcp';
|
|
12
12
|
```
|
|
13
13
|
|
|
14
|
+
The operation dictionary and WebMCP binding processors load with this extension. The core entry does not import them; its generic extension hooks also handle component and context lifecycle notifications.
|
|
15
|
+
|
|
14
16
|
## Automatic Tools
|
|
15
17
|
|
|
16
18
|
Enable `mcpToolMode` globally or per component to generate tools from bound event handlers:
|
|
@@ -35,6 +37,17 @@ WebmcpCounter.template = html`
|
|
|
35
37
|
WebmcpCounter.reg('webmcp-counter');
|
|
36
38
|
```
|
|
37
39
|
|
|
40
|
+
Automatic discovery uses an operation dictionary:
|
|
41
|
+
|
|
42
|
+
| Binding | Operation |
|
|
43
|
+
| --- | --- |
|
|
44
|
+
| `onclick` | Activate a control |
|
|
45
|
+
| `onsubmit` | Submit a form |
|
|
46
|
+
| `onchange` | Commit a control value or selection |
|
|
47
|
+
| `oninput` | Insert data into a control |
|
|
48
|
+
|
|
49
|
+
Mouseup, pointer movement, hover, focus, blur, scroll, and individual keyboard events do not create automatic tools. These events continue to work as ordinary UI bindings. Use an explicit `ToolDescriptor` for additional authored operations.
|
|
50
|
+
|
|
38
51
|
The generated tool name keeps the handler key and custom element tag:
|
|
39
52
|
|
|
40
53
|
```text
|
|
@@ -53,6 +66,73 @@ Popup bindings such as `^removeItem` are registered on the ancestor component th
|
|
|
53
66
|
removeItem_in_task-list_task-item_alpha
|
|
54
67
|
```
|
|
55
68
|
|
|
69
|
+
### Action metadata
|
|
70
|
+
|
|
71
|
+
Use the [WebMCP declarative API proposal's](https://github.com/webmachinelearning/webmcp/blob/main/declarative-api-explainer.md#form-attributes) `toolname` and `tooldescription` attributes on an eligible event-bound element:
|
|
72
|
+
|
|
73
|
+
```html
|
|
74
|
+
<button id="details-toggle"
|
|
75
|
+
bind="onclick: toggleDetails"
|
|
76
|
+
toolname="toggle_details"
|
|
77
|
+
tooldescription="Expand or collapse the details panel.">
|
|
78
|
+
Details
|
|
79
|
+
</button>
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
The proposal defines these attributes for forms; Symbiote also reads them on other controls for its automatic event tools. HTML attributes do not enable excluded event types. Explicit `ToolDescriptor` names and descriptions remain authoritative.
|
|
83
|
+
|
|
84
|
+
Description resolution uses `tooldescription`, then the control label, then an authored `toolname`, then an authored handler key. Labels use `aria-labelledby`, `aria-label`, associated labels, button/link text, or `title`; fallback label text is limited to 200 characters. Unlabeled framework-generated handlers are skipped when neither description nor tool name is supplied.
|
|
85
|
+
|
|
86
|
+
The description includes the event, control tag and label, existing element ID when non-empty, and component/list-item identity. For example:
|
|
87
|
+
|
|
88
|
+
```text
|
|
89
|
+
Expand or collapse the details panel.
|
|
90
|
+
Event: click. Control: <button> "Details". ID: details-toggle. Component: <details-panel>.
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Bindings sharing a handler and source component produce one tool. An explicit description takes priority when choosing its binding; metadata and invocation target always come from that same binding. Call `component.syncWebMCPTools()` after changing labels or attributes to refresh descriptions, names, and eligibility. Name collisions use the existing `-N` suffix.
|
|
94
|
+
|
|
95
|
+
### Data insertion
|
|
96
|
+
|
|
97
|
+
Input tools update the selected DOM control before calling its bound handler, so that handler can publish the new data through normal state bindings:
|
|
98
|
+
|
|
99
|
+
```js
|
|
100
|
+
class QueryEditor extends Symbiote {
|
|
101
|
+
query = '';
|
|
102
|
+
updateQuery(event) {
|
|
103
|
+
this.$.query = event.target.value;
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
QueryEditor.template = html`
|
|
107
|
+
<label>Query
|
|
108
|
+
<input toolname="edit_query" bind="value: query; oninput: updateQuery">
|
|
109
|
+
</label>
|
|
110
|
+
`;
|
|
111
|
+
QueryEditor.reg('query-editor');
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
After mounting the component, invoke `executeWebMCPTool('edit_query', { value: 'New query' })` or its native WebMCP counterpart.
|
|
115
|
+
|
|
116
|
+
| Control | Tool input |
|
|
117
|
+
| --- | --- |
|
|
118
|
+
| Text input or textarea | `{ value: string }` |
|
|
119
|
+
| Number or range input | `{ value: string \| number }` |
|
|
120
|
+
| Checkbox or radio | `{ checked: boolean }` |
|
|
121
|
+
| Single select | `{ value: string }` from enabled options |
|
|
122
|
+
| Multiple select | `{ value: string[] }` from enabled options |
|
|
123
|
+
|
|
124
|
+
`oninput` requires a value. `onchange` also accepts an empty object to invoke the handler against the current control state. Invalid input, unsupported select options, and disabled/read-only/inert controls cannot insert data. File inputs and controls without a supported value interface need explicit tools. Automatic handlers retain the synthetic event with `type: 'webmcp'` and the selected control as `target` and `currentTarget`.
|
|
125
|
+
|
|
126
|
+
### Native forms
|
|
127
|
+
|
|
128
|
+
Annotated forms with both `toolname` and `tooldescription` use the browser's declarative WebMCP implementation when available. Symbiote checks the document's imperative API and the declarative `SubmitEvent.agentInvoked` / `respondWith()` extensions. Imperative support alone does not cause forms to be skipped.
|
|
129
|
+
|
|
130
|
+
Symbiote omits a duplicate automatic submission tool for the form, including an associated submit control bound to the same handler. Independent control actions remain eligible. The browser owns form schemas, `toolparamdescription`, submission responses, and the user-review behavior controlled by `toolautosubmit`.
|
|
131
|
+
|
|
132
|
+
Without native declarative support, an annotated form can use the bound-handler fallback when `toolautosubmit` is present. Otherwise the fallback submission tool is omitted because it cannot represent the browser's user-review flow. Ordinary UI submission continues to work. Unannotated forms retain normal automatic handler discovery.
|
|
133
|
+
|
|
134
|
+
Browser-owned forms appear in native WebMCP discovery. `getActiveWebMCPTools()` and `executeWebMCPTool()` cover Symbiote-created tools; they do not mirror browser-owned form tools.
|
|
135
|
+
|
|
56
136
|
## Explicit Tool Descriptors
|
|
57
137
|
|
|
58
138
|
Use `ToolDescriptor` for descriptions, input schemas, execution logic, and dynamic visibility:
|
package/html-app/BaseClass.js
CHANGED
|
@@ -141,7 +141,7 @@ export class BaseClass extends Symbiote {
|
|
|
141
141
|
* @param {boolean} [force]
|
|
142
142
|
*/
|
|
143
143
|
set$(values, force = false) {
|
|
144
|
-
let itemUpdate = Reflect.has(this, DICT.
|
|
144
|
+
let itemUpdate = Reflect.has(this, DICT.ITEM_INDEX_KEY) && Object.keys(values).some(isDataKey);
|
|
145
145
|
if (itemUpdate) {
|
|
146
146
|
this.actionBindings.invalidate();
|
|
147
147
|
}
|
|
@@ -154,7 +154,7 @@ export class BaseClass extends Symbiote {
|
|
|
154
154
|
* @param {boolean} [rewrite]
|
|
155
155
|
*/
|
|
156
156
|
add$(values, rewrite = false) {
|
|
157
|
-
if (Reflect.has(this, DICT.
|
|
157
|
+
if (Reflect.has(this, DICT.ITEM_INDEX_KEY) && Object.keys(values).some(isDataKey)) {
|
|
158
158
|
this.actionBindings.invalidate();
|
|
159
159
|
}
|
|
160
160
|
super.add$(values, rewrite);
|
package/html-app/README.md
CHANGED
|
@@ -53,6 +53,21 @@ Enable automatic UI tools on the external entry script:
|
|
|
53
53
|
|
|
54
54
|
The literal `"true"` loads WebMCP and enables automatic tools for foundation components before they initialize, including generated items and imported fragments. At startup, the entry reads `document.currentScript` when available, otherwise the first external module script marked `webmcp-mode="true"`. This also supports CDN module wrappers whose URL differs from the imported implementation. The flag is read before asynchronous loading; an available current script takes precedence, including an absent or `"false"` flag. Without an opted-in loader, existing WebMCP settings stay unchanged. The full example opts in; the compact Todo keeps the default. Programmatic imports can use the native [WebMCP activation API](../docs/webmcp.md#activation).
|
|
55
55
|
|
|
56
|
+
Automatic tools cover click, submit, change, and input operations. Incidental events such as mouseup and focus retain normal UI behavior without creating tools. Set `toolname` and `tooldescription` on an operation's control to provide a useful public name and description. Generated handlers without a description, label, or authored tool name are skipped. Descriptions include the event, control label, existing element ID, and component context.
|
|
57
|
+
|
|
58
|
+
For an existing `UI/note` property:
|
|
59
|
+
|
|
60
|
+
```html
|
|
61
|
+
<label>Note
|
|
62
|
+
<input id="note-editor" toolname="edit_note" tooldescription="Edit the current note."
|
|
63
|
+
bind="value: UI/note; oninput: [pub-to]UI/note">
|
|
64
|
+
</label>
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Calling `executeWebMCPTool('edit_note', { value: 'New note' })` inserts the text and invokes the declared publication handler. Change tools also support checkbox/radio `checked` booleans and select values. See [data insertion](../docs/webmcp.md#data-insertion) for schemas and control support.
|
|
68
|
+
|
|
69
|
+
Forms with native declarative WebMCP support own their submission tools; Symbiote avoids registering the same submission twice. `toolparamdescription` and `toolautosubmit` retain their native meanings. Without native support, annotated forms that require user review do not receive an immediate-submit fallback. See [native forms](../docs/webmcp.md#native-forms) for discovery and fallback behavior. WebMCP's dictionary and binding implementation remain optional imports.
|
|
70
|
+
|
|
56
71
|
## Examples
|
|
57
72
|
|
|
58
73
|
- [todo-ref.html](./examples/todo-ref.html): a compact, unstyled Todo with creation, editing, completion and removal.
|
package/html-app/actions.js
CHANGED
|
@@ -120,7 +120,9 @@ export class ActionBindings {
|
|
|
120
120
|
subscriptions: [],
|
|
121
121
|
};
|
|
122
122
|
this.bindings.push(binding);
|
|
123
|
-
|
|
123
|
+
let handler = (/** @type {ActionEvent} */ event) => this.activate(binding, event);
|
|
124
|
+
handler[DICT.GENERATED_HANDLER_KEY] = true;
|
|
125
|
+
this.owner.localCtx.add(key, handler);
|
|
124
126
|
if (element instanceof HTMLFormElement && property === 'onsubmit') {
|
|
125
127
|
configuredForms.add(element);
|
|
126
128
|
}
|
|
@@ -212,7 +214,7 @@ export class ActionBindings {
|
|
|
212
214
|
let node = this.owner;
|
|
213
215
|
while (node) {
|
|
214
216
|
let runtime = Reflect.get(node, 'actionBindings');
|
|
215
|
-
if (Reflect.has(node, DICT.
|
|
217
|
+
if (Reflect.has(node, DICT.ITEM_INDEX_KEY) && runtime instanceof ActionBindings) {
|
|
216
218
|
return {
|
|
217
219
|
runtime,
|
|
218
220
|
version: runtime.version,
|
|
@@ -15,38 +15,38 @@
|
|
|
15
15
|
</script>
|
|
16
16
|
<div class="grid gap-4 md:grid-cols-3">
|
|
17
17
|
<div class="panel grid content-start gap-3">
|
|
18
|
-
<label>Immediate<input bind="value: immediate; oninput: [pub-to]immediate"></label>
|
|
18
|
+
<label>Immediate<input toolname="edit_immediate_value" tooldescription="Edit the immediate publication example; publish the new text immediately." bind="value: immediate; oninput: [pub-to]immediate"></label>
|
|
19
19
|
<code class="text-sm text-muted">[pub-to]</code>
|
|
20
20
|
<p class="break-words text-sm">Published: <strong>{{immediate}}</strong></p>
|
|
21
21
|
</div>
|
|
22
22
|
<div class="panel grid content-start gap-3">
|
|
23
|
-
<label>200 ms<input bind="value: delay200; oninput: [pub-to-200]delay200"></label>
|
|
23
|
+
<label>200 ms<input toolname="edit_200ms_value" tooldescription="Edit the 200 ms debounce example; publish the text after 200 ms without further input." bind="value: delay200; oninput: [pub-to-200]delay200"></label>
|
|
24
24
|
<code class="text-sm text-muted">[pub-to-200]</code>
|
|
25
25
|
<p class="break-words text-sm">Published: <strong>{{delay200}}</strong></p>
|
|
26
26
|
</div>
|
|
27
27
|
<div class="panel grid content-start gap-3">
|
|
28
|
-
<label>1000 ms<input bind="value: delay1000; oninput: [pub-to-1000]delay1000"></label>
|
|
28
|
+
<label>1000 ms<input toolname="edit_1000ms_value" tooldescription="Edit the 1000 ms debounce example; publish the text after 1000 ms without further input." bind="value: delay1000; oninput: [pub-to-1000]delay1000"></label>
|
|
29
29
|
<code class="text-sm text-muted">[pub-to-1000]</code>
|
|
30
30
|
<p class="break-words text-sm">Published: <strong>{{delay1000}}</strong></p>
|
|
31
31
|
</div>
|
|
32
32
|
</div>
|
|
33
33
|
<div class="grid gap-5 lg:grid-cols-2">
|
|
34
|
-
<form class="panel grid gap-4" action-data="ACTIONS/draft" bind="onsubmit: [set]ACTIONS/submitted">
|
|
34
|
+
<form class="panel grid gap-4" toolname="submit_demo_message" tooldescription="Submit the current draft message, flushing its pending text publication first." action-data="ACTIONS/draft" bind="onsubmit: [set]ACTIONS/submitted">
|
|
35
35
|
<h2 class="font-semibold">Debounced input and native submission</h2>
|
|
36
|
-
<label>Message<input required placeholder="Type, then submit immediately" bind="value: draft; oninput: [pub-to-200]draft"></label>
|
|
36
|
+
<label>Message<input required placeholder="Type, then submit immediately" toolname="edit_demo_message" tooldescription="Edit the draft message; publish after 200 ms or when the form is submitted." bind="value: draft; oninput: [pub-to-200]draft"></label>
|
|
37
37
|
<div class="field-row">
|
|
38
38
|
<button class="primary">Submit</button>
|
|
39
|
-
<button type="button" value="" bind="onclick: [set]submitted">Clear result</button>
|
|
39
|
+
<button type="button" value="" toolname="clear_submitted_message" tooldescription="Clear the submitted message result." bind="onclick: [set]submitted">Clear result</button>
|
|
40
40
|
</div>
|
|
41
41
|
<p>Submitted: <strong>{{submitted}}</strong></p>
|
|
42
42
|
</form>
|
|
43
43
|
<div class="panel grid content-start gap-4">
|
|
44
44
|
<h2 class="font-semibold">Typed values and boolean actions</h2>
|
|
45
|
-
<label>Amount<input type="number" min="0" bind="value: amount; oninput: [pub-to]amount"></label>
|
|
46
|
-
<label class="field-row"><input type="checkbox" bind="checked: ready; onchange: [pub-to]ready">Ready</label>
|
|
45
|
+
<label>Amount<input type="number" min="0" toolname="edit_demo_amount" tooldescription="Edit the nonnegative numeric amount in the typed-values example." bind="value: amount; oninput: [pub-to]amount"></label>
|
|
46
|
+
<label class="field-row"><input type="checkbox" toolname="set_demo_ready" tooldescription="Set the ready flag in the typed-values example." bind="checked: ready; onchange: [pub-to]ready">Ready</label>
|
|
47
47
|
<div class="field-row flex-wrap">
|
|
48
|
-
<button type="button" value="true" bind="onclick: [set]ready">Set ready</button>
|
|
49
|
-
<button type="button" bind="onclick: [toggle]open">Toggle message</button>
|
|
48
|
+
<button type="button" value="true" toolname="mark_demo_ready" tooldescription="Set the ready flag to true." bind="onclick: [set]ready">Set ready</button>
|
|
49
|
+
<button type="button" toolname="toggle_demo_message" tooldescription="Show or hide the boolean-toggle example message." bind="onclick: [toggle]open">Toggle message</button>
|
|
50
50
|
</div>
|
|
51
51
|
<p class="text-sm text-muted">Amount: {{amount}} / ready: {{ready}}</p>
|
|
52
52
|
<sym-conditional when="ACTIONS/open"><p class="rounded-lg bg-accent/10 p-3 text-accent">Shown by a boolean toggle.</p></sym-conditional>
|