From 2b11f27963ad398944f44d998448116b0c858942 Mon Sep 17 00:00:00 2001 From: Brandon Walderman Date: Wed, 4 Feb 2026 16:24:33 -0800 Subject: [PATCH 1/6] Add initial WebIDL to spec. --- index.bs | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 73 insertions(+), 3 deletions(-) diff --git a/index.bs b/index.bs index 7867007..b1eafd8 100644 --- a/index.bs +++ b/index.bs @@ -107,18 +107,83 @@ https://github.com/webmachinelearning/webmcp/blob/main/docs/security-privacy-con

API

+ + +The {{Navigator}} interface is extended to provide access to the {{ModelContext}}. + partial interface Navigator { - [SecureContext, SameObject] readonly attribute ModelContextContainer modelContext; + [SecureContext, SameObject] readonly attribute ModelContext modelContext; +}; + + +

ModelContext Interface

+ +The {{ModelContext}} interface provides methods for web applications to register and manage tools that can be invoked by [=agents=]. + + +[Exposed=Window, SecureContext] +interface ModelContext { + undefined provideContext(optional ModelContextOptions options); + undefined registerTool(ModelContextTool tool); + undefined unregisterTool(DOMString name); +}; + + +

ModelContextOptions Dictionary

+ + +dictionary ModelContextOptions { + sequence<ModelContextTool> tools = []; +}; + + +

ModelContextTool Dictionary

+ +The {{ModelContextTool}} dictionary describes a tool that can be invoked by [=agents=]. +The {{ModelContextTool/inputSchema}} property is a JSON Schema [[!JSON-SCHEMA]] object that describes the expected input parameters for the tool. + + +dictionary ModelContextTool { + required DOMString name; + required DOMString description; + required object inputSchema; + ToolExecuteCallback execute; }; +callback ToolExecuteCallback = ToolResponse (object input, ModelContextClient client); + + +

ModelContextClient Interface

+ +The {{ModelContextClient}} interface represents an [=agent=] executing a tool provided by the site through the {{ModelContext}} API. + + [Exposed=Window, SecureContext] -interface ModelContextContainer { +interface ModelContextClient { + Promise<any> requestUserInteraction(UserInteractionCallback callback); +}; + +callback UserInteractionCallback = Promise<any> (); + + +

ToolResponse Dictionary

+ +The {{ToolResponse}} dictionary represents the structured content response returned by a tool execution. + + +dictionary ToolResponse { + sequence<ToolContent> content; +}; + +dictionary ToolContent { + required DOMString type; + DOMString text; }; @@ -128,6 +193,11 @@ interface ModelContextContainer { "href": "https://modelcontextprotocol.io/specification/latest", "title": "Model Context Protocol (MCP) Specification", "publisher": "The Linux Foundation" + }, + "json-schema": { + "href": "https://json-schema.org/draft/2020-12/json-schema-core.html", + "title": "JSON Schema: A Media Type for Describing JSON Documents", + "publisher": "JSON Schema" } } From ba7a8853aa10fab8360e21c2ca9f7ef583c9e901 Mon Sep 17 00:00:00 2001 From: Brandon Walderman Date: Wed, 4 Feb 2026 16:27:05 -0800 Subject: [PATCH 2/6] Add tool annotations. --- index.bs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/index.bs b/index.bs index b1eafd8..e4676a6 100644 --- a/index.bs +++ b/index.bs @@ -154,6 +154,11 @@ dictionary ModelContextTool { required DOMString description; required object inputSchema; ToolExecuteCallback execute; + ToolAnnotations annotations; +}; + +dictionary ToolAnnotations { + boolean readOnly; }; callback ToolExecuteCallback = ToolResponse (object input, ModelContextClient client); From 349ababffac5c0975516b5a1e1a6f7b0b006611b Mon Sep 17 00:00:00 2001 From: Brandon Walderman Date: Wed, 4 Feb 2026 16:36:16 -0800 Subject: [PATCH 3/6] Add definitions. --- index.bs | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 90 insertions(+), 1 deletion(-) diff --git a/index.bs b/index.bs index e4676a6..e37bad8 100644 --- a/index.bs +++ b/index.bs @@ -135,6 +135,23 @@ interface ModelContext { }; +
+
provideContext(options)
+
+ Registers the provided context (tools) with the browser. This method clears any pre-existing tools and other context before registering the new ones. +
+ +
registerTool(tool)
+
+ Registers a single tool without clearing the existing set of tools. If a tool with the same name already exists, the method throws an Error. +
+ +
unregisterTool(name)
+
+ Removes the tool with the specified name from the registered set. +
+
+

ModelContextOptions Dictionary

@@ -143,10 +160,16 @@ dictionary ModelContextOptions { }; +
+
tools
+
+ A list of tools to register with the browser. Each tool name in the list is expected to be unique. +
+
+

ModelContextTool Dictionary

The {{ModelContextTool}} dictionary describes a tool that can be invoked by [=agents=]. -The {{ModelContextTool/inputSchema}} property is a JSON Schema [[!JSON-SCHEMA]] object that describes the expected input parameters for the tool. dictionary ModelContextTool { @@ -164,6 +187,43 @@ dictionary ToolAnnotations { callback ToolExecuteCallback = ToolResponse (object input, ModelContextClient client); +
+
name
+
+ A unique identifier for the tool. This is used by [=agents=] to reference the tool when making tool calls. +
+ +
description
+
+ A natural language description of the tool's functionality. This helps [=agents=] understand when and how to use the tool. +
+ +
inputSchema
+
+ A JSON Schema [[!JSON-SCHEMA]] object describing the expected input parameters for the tool. +
+ +
execute
+
+ A callback function that is invoked when an [=agent=] calls the tool. The function receives the input parameters and a {{ModelContextClient}} object. + The function can be asynchronous and return a promise, in which case the [=agent=] will receive the result once the promise is resolved. +
+ +
annotations
+
+ Optional annotations providing additional metadata about the tool's behavior. +
+
+ +The {{ToolAnnotations}} dictionary provides optional metadata about a tool: + +
+
readOnly
+
+ 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. +
+
+

ModelContextClient Interface

The {{ModelContextClient}} interface represents an [=agent=] executing a tool provided by the site through the {{ModelContext}} API. @@ -177,6 +237,14 @@ interface ModelContextClient { callback UserInteractionCallback = Promise (); +
+
requestUserInteraction(callback)
+
+ Asynchronously requests user input during the execution of a tool. + 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. +
+
+

ToolResponse Dictionary

The {{ToolResponse}} dictionary represents the structured content response returned by a tool execution. @@ -192,6 +260,27 @@ dictionary ToolContent { }; +
+
content
+
+ An array of content items representing the tool's response to the [=agent=]. +
+
+ +The {{ToolContent}} dictionary represents an individual content item in a tool response: + +
+
type
+
+ The type of content. For example, "text" for plain text content. +
+ +
text
+
+ The text content of the response when {{ToolContent/type}} is "text". +
+
+ 
 {
   "mcp": {

From 1680392d6be6b88d9c2581a63c486918d000c066 Mon Sep 17 00:00:00 2001
From: Brandon Walderman 
Date: Wed, 4 Feb 2026 23:12:46 -0800
Subject: [PATCH 4/6] Fix WebIDL error.

---
 index.bs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.bs b/index.bs
index e37bad8..239dcea 100644
--- a/index.bs
+++ b/index.bs
@@ -129,7 +129,7 @@ The {{ModelContext}} interface provides methods for web applications to register
 
 [Exposed=Window, SecureContext]
 interface ModelContext {
-  undefined provideContext(optional ModelContextOptions options);
+  undefined provideContext(optional ModelContextOptions options = {});
   undefined registerTool(ModelContextTool tool);
   undefined unregisterTool(DOMString name);
 };

From 987678113c1fc77e199b628f4ca0529546ccdd62 Mon Sep 17 00:00:00 2001
From: Brandon Walderman <brwalder@microsoft.com>
Date: Thu, 5 Feb 2026 11:03:35 -0800
Subject: [PATCH 5/6] Respond to PR feedback.

---
 index.bs | 140 ++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 86 insertions(+), 54 deletions(-)

diff --git a/index.bs b/index.bs
index 239dcea..b20a902 100644
--- a/index.bs
+++ b/index.bs
@@ -112,7 +112,7 @@ https://github.com/webmachinelearning/webmcp/blob/main/docs/proposal.md#api
 https://dlaliberte.github.io/bikeshed-intro/#a-strategy-for-incremental-development
 -->
 
-<h3 id="navigator-extension">Extensions to the Navigator Interface</h3>
+<h3 id="navigator-extension">Extensions to the {{Navigator}} Interface</h3>
 
 The {{Navigator}} interface is extended to provide access to the {{ModelContext}}.
 
@@ -130,29 +130,47 @@ The {{ModelContext}} interface provides methods for web applications to register
 [Exposed=Window, SecureContext]
 interface ModelContext {
   undefined provideContext(optional ModelContextOptions options = {});
+  undefined clearContext();
   undefined registerTool(ModelContextTool tool);
   undefined unregisterTool(DOMString name);
 };
 
 
+

+  
navigator.{{Navigator/modelContext}}.{{ModelContext/provideContext(options)}}

+  

+    
Registers the provided context (tools) with the browser. This method clears any pre-existing tools and other context before registering the new ones.
+  

+
+  
navigator.{{Navigator/modelContext}}.{{ModelContext/registerTool(tool)}}

+  

+    
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.
+  

+
+  
navigator.{{Navigator/modelContext}}.{{ModelContext/unregisterTool(name)}}

+  

+    
Removes the tool with the specified name from the registered set.
+  

+

+
 

   
provideContext(options)

   

-    Registers the provided context (tools) with the browser. This method clears any pre-existing tools and other context before registering the new ones.
+    
TODO: fill this out

   

 
   
registerTool(tool)

   

-    Registers a single tool without clearing the existing set of tools. If a tool with the same name already exists, the method throws an Error.
+    
TODO: fill this out

   

 
   
unregisterTool(name)

   

-    Removes the tool with the specified name from the registered set.
+    
TODO: fill this out

   

 

 
-
ModelContextOptions Dictionary

+
ModelContextOptions Dictionary

 
 
 dictionary ModelContextOptions {
@@ -160,14 +178,21 @@ dictionary ModelContextOptions {
 };
 
 
+

+  
options["{{ModelContextOptions/tools}}"]

+  

+    
A list of {{ModelContextOptions/tools}} to register with the browser. Each tool name in the list is expected to be unique.
+  

+

+
 

   
tools

   

-    A list of tools to register with the browser. Each tool name in the list is expected to be unique.
+    
TODO: fill this out

   

 

 
-
ModelContextTool Dictionary

+
ModelContextTool Dictionary

 
 The {{ModelContextTool}} dictionary describes a tool that can be invoked by [=agents=].
 
@@ -175,56 +200,91 @@ The {{ModelContextTool}} dictionary describes a tool that can be invoked by [=ag
 dictionary ModelContextTool {
   required DOMString name;
   required DOMString description;
-  required object inputSchema;
-  ToolExecuteCallback execute;
+  object inputSchema;
+  required ToolExecuteCallback execute;
   ToolAnnotations annotations;
 };
 
 dictionary ToolAnnotations {
-  boolean readOnly;
+  boolean readOnlyHint;
 };
 
-callback ToolExecuteCallback = ToolResponse (object input, ModelContextClient client);
+callback ToolExecuteCallback = Promise (object input, ModelContextClient client);
 
 
+

+  
tool["{{ModelContextTool/name}}"]

+  

+    
A unique identifier for the tool. This is used by [=agents=] to reference the tool when making tool calls.
+  

+
+  
tool["{{ModelContextTool/description}}"]

+  

+    
A natural language description of the tool's functionality. This helps [=agents=] understand when and how to use the tool.
+  

+
+  
tool["{{ModelContextTool/inputSchema}}"]

+  

+    
A JSON Schema [[!JSON-SCHEMA]] object describing the expected input parameters for the tool.
+  

+
+  
tool["{{ModelContextTool/execute}}"]

+  

+    
A callback function that is invoked when an [=agent=] calls the tool. The function receives the input parameters and a {{ModelContextClient}} object.
+
+    
The function can be asynchronous and return a promise, in which case the [=agent=] will receive the result once the promise is resolved.
+  

+
+  
tool["{{ModelContextTool/annotations}}"]

+  

+    
Optional annotations providing additional metadata about the tool's behavior.
+  

+

+
 

   
name

   

-    A unique identifier for the tool. This is used by [=agents=] to reference the tool when making tool calls.
+    
TODO: fill this out

   

 
   
description

   

-    A natural language description of the tool's functionality. This helps [=agents=] understand when and how to use the tool.
+    
TODO: fill this out

   

 
   
inputSchema

   

-    A JSON Schema [[!JSON-SCHEMA]] object describing the expected input parameters for the tool.
+    
TODO: fill this out

   

 
   
execute

   

-    A callback function that is invoked when an [=agent=] calls the tool. The function receives the input parameters and a {{ModelContextClient}} object.
-    The function can be asynchronous and return a promise, in which case the [=agent=] will receive the result once the promise is resolved.
+    
TODO: fill this out

   

 
   
annotations

   

-    Optional annotations providing additional metadata about the tool's behavior.
+    
TODO: fill this out

   

 

 
 The {{ToolAnnotations}} dictionary provides optional metadata about a tool:
 
+

+  
annotations["{{ToolAnnotations/readOnlyHint}}"]

+  

+    
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.
+  

+

+
 

-  
readOnly

+  
readOnlyHint

   

-    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.
+    
TODO: fill this out

   

 

 
-
ModelContextClient Interface

+
ModelContextClient Interface

 
 The {{ModelContextClient}} interface represents an [=agent=] executing a tool provided by the site through the {{ModelContext}} API.
 
@@ -237,47 +297,19 @@ interface ModelContextClient {
 callback UserInteractionCallback = Promise ();
 
 
-

-  
requestUserInteraction(callback)

+

+  
client.{{ModelContextClient/requestUserInteraction(callback)}}

   

-    Asynchronously requests user input during the execution of a tool.
-    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.
-  

-

-
-
ToolResponse Dictionary

-
-The {{ToolResponse}} dictionary represents the structured content response returned by a tool execution.
+    
Asynchronously requests user input during the execution of a tool.
 
-

-dictionary ToolResponse {
-  sequence<ToolContent> content;
-};
-
-dictionary ToolContent {
-  required DOMString type;
-  DOMString text;
-};
-
-
-

-  
content

-  

-    An array of content items representing the tool's response to the [=agent=].
+    
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.
   

 

 
-The {{ToolContent}} dictionary represents an individual content item in a tool response:
-
 

-  
type

-  

-    The type of content. For example, "text" for plain text content.
-  

-
-  
text

+  
requestUserInteraction(callback)

   

-    The text content of the response when {{ToolContent/type}} is "text".
+    
TODO: fill this out

   

 

 

From 98b1ba3fe974e1aa43455b9b3404b5392a7210c5 Mon Sep 17 00:00:00 2001
From: Dominic Farolino 
Date: Wed, 11 Feb 2026 16:28:32 -0500
Subject: [PATCH 6/6] Remove unnecessary dict dfns, and add correct method dfns

This commit resolves the
https://github.com/webmachinelearning/webmcp/pull/75#discussion_r2769474538
review comment, and also adds the domintro box for `clearContext()`, resolving
https://github.com/webmachinelearning/webmcp/pull/75#discussion_r2772926015.

This commit also removes unnecessary dictionary member re-definitions, resolving
https://github.com/webmachinelearning/webmcp/pull/75#discussion_r2769502021.
---
 index.bs | 98 +++++++++++++++++++++-----------------------------------
 1 file changed, 37 insertions(+), 61 deletions(-)

diff --git a/index.bs b/index.bs
index b20a902..a60ba3d 100644
--- a/index.bs
+++ b/index.bs
@@ -142,6 +142,11 @@ interface ModelContext {
     
Registers the provided context (tools) with the browser. This method clears any pre-existing tools and other context before registering the new ones.
   
 
+  
navigator.{{Navigator/modelContext}}.{{ModelContext/clearContext()}}

+  

+    
Unregisters all context (tools) with the browser.
+  

+
   
navigator.{{Navigator/modelContext}}.{{ModelContext/registerTool(tool)}}

   

     
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,22 +158,34 @@ interface ModelContext {
   

 

 
-

-  
provideContext(options)

-  

-    
TODO: fill this out

-  

+

+The provideContext(options) method steps are:
 
-  
registerTool(tool)

-  

-    
TODO: fill this out

-  

+1. TODO: fill this out.
 
-  
unregisterTool(name)

-  

-    
TODO: fill this out

-  

-

+
+
+

+The clearContext() method steps are:
+
+1. TODO: fill this out.
+
+

+
+
+

+The registerTool(tool) method steps are:
+
+1. TODO: fill this out.
+
+

+
+

+The unregisterTool(name) method steps are:
+
+1. TODO: fill this out.
+
+

 
 
ModelContextOptions Dictionary

 
@@ -185,13 +202,6 @@ dictionary ModelContextOptions {
   
 
 
-

-  
tools

-  

-    
TODO: fill this out

-  

-

-
 
ModelContextTool Dictionary

 
 The {{ModelContextTool}} dictionary describes a tool that can be invoked by [=agents=].
@@ -241,33 +251,6 @@ callback ToolExecuteCallback = Promise (object input, ModelContextClient cl
   
 
 
-

-  
name

-  

-    
TODO: fill this out

-  

-
-  
description

-  

-    
TODO: fill this out

-  

-
-  
inputSchema

-  

-    
TODO: fill this out

-  

-
-  
execute

-  

-    
TODO: fill this out

-  

-
-  
annotations

-  

-    
TODO: fill this out

-  

-

-
 The {{ToolAnnotations}} dictionary provides optional metadata about a tool:
 
 

@@ -277,13 +260,6 @@ The {{ToolAnnotations}} dictionary provides optional metadata about a tool:
   
 

 
-

-  
readOnlyHint

-  

-    
TODO: fill this out

-  

-

-
 
ModelContextClient Interface

 
 The {{ModelContextClient}} interface represents an [=agent=] executing a tool provided by the site through the {{ModelContext}} API.
@@ -306,12 +282,12 @@ callback UserInteractionCallback = Promise ();
   
 
 
-

-  
requestUserInteraction(callback)

-  

-    
TODO: fill this out

-  

-

+

+The requestUserInteraction(callback) method steps are:
+
+1. TODO: fill this out.
+
+

 
 
 {