Skip to content

Commit 971aa24

Browse files
domfarolinobwalderman
domfarolino
and
bwalderman
authored
Add WebIDL and descriptions to spec draft
We'll land follow-ups a necessary to resolve unresolved comments here. Co-authored-by: Brandon Walderman <brwalder@microsoft.com> Co-authored-by: Dominic Farolino <domfarolino@gmail.com>
2 parents 78ae4d7 + 98b1ba3 commit 971aa24

1 file changed

Lines changed: 175 additions & 3 deletions

File tree

‎index.bs‎

Lines changed: 175 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -107,27 +107,199 @@ https://github.com/webmachinelearning/webmcp/blob/main/docs/security-privacy-con
107107
<h2 id="api">API</h2>
108108

109109
<!--
110-
TODO: Convert API described in proposal.md into WebIDL, sketch initial algorithms, define attributes and methods etc.
110+
TODO: Sketch initial algorithms, define attributes and methods etc.
111111
https://github.com/webmachinelearning/webmcp/blob/main/docs/proposal.md#api
112112
https://dlaliberte.github.io/bikeshed-intro/#a-strategy-for-incremental-development
113113
-->
114114

115+
<h3 id="navigator-extension">Extensions to the {{Navigator}} Interface</h3>
116+
117+
The {{Navigator}} interface is extended to provide access to the {{ModelContext}}.
118+
115119
<xmp class="idl">
116120
partial interface Navigator {
117-
[SecureContext, SameObject] readonly attribute ModelContextContainer modelContext;
121+
[SecureContext, SameObject] readonly attribute ModelContext modelContext;
118122
};
123+
</xmp>
124+
125+
<h3 id="model-context-container">ModelContext Interface</h3>
119126

127+
The {{ModelContext}} interface provides methods for web applications to register and manage tools that can be invoked by [=agents=].
128+
129+
<xmp class="idl">
120130
[Exposed=Window, SecureContext]
121-
interface ModelContextContainer {
131+
interface ModelContext {
132+
undefined provideContext(optional ModelContextOptions options = {});
133+
undefined clearContext();
134+
undefined registerTool(ModelContextTool tool);
135+
undefined unregisterTool(DOMString name);
136+
};
137+
</xmp>
138+
139+
<dl class="domintro">
140+
<dt><code><var ignore>navigator</var>.{{Navigator/modelContext}}.{{ModelContext/provideContext(options)}}</code></dt>
141+
<dd>
142+
<p>Registers the provided context (tools) with the browser. This method clears any pre-existing tools and other context before registering the new ones.
143+
</dd>
144+
145+
<dt><code><var ignore>navigator</var>.{{Navigator/modelContext}}.{{ModelContext/clearContext()}}</code></dt>
146+
<dd>
147+
<p>Unregisters all context (tools) with the browser.
148+
</dd>
149+
150+
<dt><code><var ignore>navigator</var>.{{Navigator/modelContext}}.{{ModelContext/registerTool(tool)}}</code></dt>
151+
<dd>
152+
<p>Registers a single tool without clearing the existing set of tools. The method throws an error, if a tool with the same name already exists, or if the {{ModelContextTool/inputSchema}} is invalid.
153+
</dd>
154+
155+
<dt><code><var ignore>navigator</var>.{{Navigator/modelContext}}.{{ModelContext/unregisterTool(name)}}</code></dt>
156+
<dd>
157+
<p>Removes the tool with the specified name from the registered set.
158+
</dd>
159+
</dl>
160+
161+
<div algorithm>
162+
The <dfn method for=ModelContext>provideContext(<var ignore>options</var>)</dfn> method steps are:
163+
164+
1. TODO: fill this out.
165+
166+
</div>
167+
168+
<div algorithm>
169+
The <dfn method for=ModelContext>clearContext()</dfn> method steps are:
170+
171+
1. TODO: fill this out.
172+
173+
</div>
174+
175+
176+
<div algorithm>
177+
The <dfn method for=ModelContext>registerTool(<var ignore>tool</var>)</dfn> method steps are:
178+
179+
1. TODO: fill this out.
180+
181+
</div>
182+
183+
<div algorithm>
184+
The <dfn method for=ModelContext>unregisterTool(<var ignore>name</var>)</dfn> method steps are:
185+
186+
1. TODO: fill this out.
187+
188+
</div>
189+
190+
<h4 id="model-context-options">ModelContextOptions Dictionary</h4>
191+
192+
<xmp class="idl">
193+
dictionary ModelContextOptions {
194+
sequence<ModelContextTool> tools = [];
122195
};
123196
</xmp>
124197

198+
<dl class="domintro">
199+
<dt><code><var ignore>options</var>["{{ModelContextOptions/tools}}"]</code></dt>
200+
<dd>
201+
<p>A list of {{ModelContextOptions/tools}} to register with the browser. Each tool name in the list is expected to be unique.
202+
</dd>
203+
</dl>
204+
205+
<h4 id="model-context-tool">ModelContextTool Dictionary</h4>
206+
207+
The {{ModelContextTool}} dictionary describes a tool that can be invoked by [=agents=].
208+
209+
<xmp class="idl">
210+
dictionary ModelContextTool {
211+
required DOMString name;
212+
required DOMString description;
213+
object inputSchema;
214+
required ToolExecuteCallback execute;
215+
ToolAnnotations annotations;
216+
};
217+
218+
dictionary ToolAnnotations {
219+
boolean readOnlyHint;
220+
};
221+
222+
callback ToolExecuteCallback = Promise<any> (object input, ModelContextClient client);
223+
</xmp>
224+
225+
<dl class="domintro">
226+
<dt><code><var ignore>tool</var>["{{ModelContextTool/name}}"]</code></dt>
227+
<dd>
228+
<p>A unique identifier for the tool. This is used by [=agents=] to reference the tool when making tool calls.
229+
</dd>
230+
231+
<dt><code><var ignore>tool</var>["{{ModelContextTool/description}}"]</code></dt>
232+
<dd>
233+
<p>A natural language description of the tool's functionality. This helps [=agents=] understand when and how to use the tool.
234+
</dd>
235+
236+
<dt><code><var ignore>tool</var>["{{ModelContextTool/inputSchema}}"]</code></dt>
237+
<dd>
238+
<p>A JSON Schema [[!JSON-SCHEMA]] object describing the expected input parameters for the tool.
239+
</dd>
240+
241+
<dt><code><var ignore>tool</var>["{{ModelContextTool/execute}}"]</code></dt>
242+
<dd>
243+
<p>A callback function that is invoked when an [=agent=] calls the tool. The function receives the input parameters and a {{ModelContextClient}} object.
244+
245+
<p>The function can be asynchronous and return a promise, in which case the [=agent=] will receive the result once the promise is resolved.
246+
</dd>
247+
248+
<dt><code><var ignore>tool</var>["{{ModelContextTool/annotations}}"]</code></dt>
249+
<dd>
250+
<p>Optional annotations providing additional metadata about the tool's behavior.
251+
</dd>
252+
</dl>
253+
254+
The {{ToolAnnotations}} dictionary provides optional metadata about a tool:
255+
256+
<dl class="domintro">
257+
<dt><code><var ignore>annotations</var>["{{ToolAnnotations/readOnlyHint}}"]</code></dt>
258+
<dd>
259+
<p>If true, indicates that the tool does not modify any state and only reads data. This hint can help [=agents=] make decisions about when it is safe to call the tool.
260+
</dd>
261+
</dl>
262+
263+
<h4 id="model-context-client">ModelContextClient Interface</h4>
264+
265+
The {{ModelContextClient}} interface represents an [=agent=] executing a tool provided by the site through the {{ModelContext}} API.
266+
267+
<xmp class="idl">
268+
[Exposed=Window, SecureContext]
269+
interface ModelContextClient {
270+
Promise<any> requestUserInteraction(UserInteractionCallback callback);
271+
};
272+
273+
callback UserInteractionCallback = Promise<any> ();
274+
</xmp>
275+
276+
<dl class="domintro">
277+
<dt><code><var ignore>client</var>.{{ModelContextClient/requestUserInteraction(callback)}}</code></dt>
278+
<dd>
279+
<p>Asynchronously requests user input during the execution of a tool.
280+
281+
<p>The callback function is invoked to perform the user interaction (e.g., showing a confirmation dialog), and the promise resolves with the result of the callback.
282+
</dd>
283+
</dl>
284+
285+
<div algorithm>
286+
The <dfn method for=ModelContextClient>requestUserInteraction(<var ignore>callback</var>)</dfn> method steps are:
287+
288+
1. TODO: fill this out.
289+
290+
</div>
291+
125292
<pre class="biblio">
126293
{
127294
"mcp": {
128295
"href": "https://modelcontextprotocol.io/specification/latest",
129296
"title": "Model Context Protocol (MCP) Specification",
130297
"publisher": "The Linux Foundation"
298+
},
299+
"json-schema": {
300+
"href": "https://json-schema.org/draft/2020-12/json-schema-core.html",
301+
"title": "JSON Schema: A Media Type for Describing JSON Documents",
302+
"publisher": "JSON Schema"
131303
}
132304
}
133305
</pre>

0 commit comments

Comments
 (0)