API design

[bwalderman]

Opening this issue to discuss the web platform API design for WebMCP. There are a couple approaches out there at the moment:

1. An object with registerTool(options) and unregisterTool(name) methods such as the AutomationDelegate from the original Script Tools API proposal, or the window.mcp object that MiguelsPizza/WebMCP provides
2. A single provideContext method which takes a collection of tools in a single call. The set of available tools can be updated by calling provideContext again with a different tool collection. See the current proposal here

Both of the above agree on the info needed for a tool registration: name, description, input schema, and optional annotations. They also all allow for dynamic enabling/disabling of tools but go about this in different ways.

[jasonjmcghee]

Have you thought at all about multi page web apps and/or persistence? What happens if I load the page that has the tools and navigate to another page, either manually or by using a tool? I.e. should registered tools exist outside the current window context? Or does every single page on a site need to facilitate mcp?

I approach this by persisting tools (resources, prompts, etc) to local storage in order to handle both multiple page and disconnect / reconnect scenarios (possibly not applicable if the agent exists inside the browser context, unlike my approach which communicates over authenticated websocket)

https://github.com/jasonjmcghee/WebMCP/blob/1de0c8c35171bc19a96911b1cd5fedbdf9412011/src/webmcp.js#L1580

[bokand]

Have you thought at all about multi page web apps and/or persistence?

Is it a significant burden on authors to re-register the tools in this case? (i.e. I assume this would be wrapped up in some common library).

My feeling is that trying to have some kind of out-of-window state will open up many cans of worms in spec and implementation since the tools ultimately rely on a JS execution context. e.g. what should happen if the agent tries to call a tool during a navigation when no execution context is available?

These are maybe solvable but will add complexity so would have to provide significant benefit.

Both of the above agree on the info needed for a tool registration: name, description, input schema, and optional annotations. They also all allow for dynamic enabling/disabling of tools but go about this in different ways.

I don't have a strong opinion but have a slight preference to the register/unregister pattern since it makes it clearer when specific tools are being enabled/disabled.

Also +@michaelwasserman who's working on prompt API tool calling and may have thoughts about how to make the two fit together.

[bwalderman]

Have you thought at all about multi page web apps and/or persistence? What happens if I load the page that has the tools and navigate to another page, either manually or by using a tool? I.e. should registered tools exist outside the current window context? Or does every single page on a site need to facilitate mcp?

I'm proposing adding service worker support in #19, which would let devs associate tools with a whole site instead of a specific tab. Anything that's meant to persist across navigations and work across multiple open tabs could potentially live in the site's service worker.

[bwalderman]

I don't have a strong opinion but have a slight preference to the register/unregister pattern since it makes it clearer when specific tools are being enabled/disabled.

The provideContext pattern is potentially useful for complex single-page apps with long sessions (say a photo editor). In these kinds of apps, the user will be constantly moving through different UI states, opening/closing dialogs, etc. Being able to push and pop small, focused toolsets as the user navigates would come in handy, versus toggling individual tools from a single larger toolset. A single API call would also mean fewer updates being pushed to the agent when multiple tools are being changed.

[khushalsagar]

We could consider supporting both flavours if they make the ergonomics better? The registerTool and unregisterTool option would add/remove to the existing set of tools. A setTools call could clear the existing set and replace it with the list passed in the API.

[jasonjmcghee]

Is it a significant burden on authors to re-register the tools in this case? (i.e. I assume this would be wrapped up in some common library).

@bokand The context for the registered tool could now be gone. Maybe a tool became available due to a specific action a user took etc. or has data based on something that happened. An example might be "undo" or "show me what I've done" etc. These are a bit contrived, but hopefully I've communicated the point.

Service workers could solve this though.

[khushalsagar]

@jasonjmcghee the example you mentioned is valid, there are tools which are context dependent. And that context has to outlive the page for MPAs or SPAs. But that seems like a problem authors already deal with for the UI today, I'm not seeing how WebMCP is introducing a new challenge here.

For instance, if the user did something and the author wants the user to have an "undo" option even after a navigation, wouldn't they be persisting that via session storage or cookies to decide whether to show a button in the UI? So they'd be able to use the same information to keep the tools up-to-date as well?

[reillyeon]

My concern with a single provideContext method is that real-world sites are built out of a collection of components which may or may not be well-coordinated. It seems likely that a single method which replaces the entire context makes it easy for developers to stomp on each others' usage of the API. I think we should take a cue from the design of HTML event listeners are allow tools to be individually registered and removed.

[khushalsagar]

Summary of the discussion today.

RESOLUTION: Continue use with the provideContext design and explore adding support for registerTool(options) and unregisterTool(name) to complement the API informed by implementation experience.

08:41 ... Brandon outlines two API design approaches:
08:41 ... 1) An object with registerTool(options) and unregisterTool(name) methods
08:41 ... 2) A single provideContext method which takes a collection of tools in a single call.
08:41 ... Alex' implementation and Google's Script Tools API proposal used (1), while the current WebMCP proposal uses (2)
08:42 ... Jason asked about multi page web apps and persistence, his implementation persists tools to local storage, there seems to be agreement Service Workers could solve this
08:42 Jason: I'm not advocating for local storage for the spec, it is an implementation detail
08:42 q+
08:42 * Zakim sees kush on the speaker queue
08:42 q+
08:42 * Zakim sees kush, brwalder on the speaker queue
08:42 ack kush
08:42 * Zakim sees brwalder on the speaker queue
08:43 Khushal: we have a set of tools, the question is can I addFoo and removeFoo or do it via an entire list
08:43 Anssi: do we have consensus on this issue to stay with the current proposal (2)?
08:44 q+
08:44 * Zakim sees brwalder on the speaker queue
08:44 Anssi: what are the obstacles in supporting both (1) and (2) and do we need more experience to understand the developer ergonomics improvement better?
08:44 Alex: for dynamic web sites, React-based (1) is beneficial, I will try to polyfill to provide implementation experience
08:45 q+
08:45 * Zakim sees brwalder, reillyg on the speaker queue
08:45 Khushal: we could have both (1) and (2)
08:45 ack brwalder
08:45 * Zakim sees reillyg on the speaker queue
08:45 Brandon: in Chromium our plan is to implement both (1) and (2) and allow developers to experiment and gather feedback
08:46 ... I actually pitched (2) with React in mind, with some state you can compute what is available and batch send them
08:47 * anssik proposed RESOLUTION: Continue use with the provideContext design and explore adding support for registerTool(options) and unregisterTool(name) to complement the API informed by implementation experience.
08:47 Khushal +1
08:47 Brandon +1
08:47 Alex +1
08:48 RESOLUTION: Continue use with the provideContext design and explore adding support for registerTool(options) and unregisterTool(name) to complement the API informed by implementation experience.

[bwalderman]

My concern with a single provideContext method is that real-world sites are built out of a collection of components which may or may not be well-coordinated. It seems likely that a single method which replaces the entire context makes it easy for developers to stomp on each others' usage of the API. I think we should take a cue from the design of HTML event listeners are allow tools to be individually registered and removed.

For the Chromium implementation, we're exposing both the provideContext method and the register/unregisterTool methods so that web devs can try out both and we can see what patterns emerge.

[43081j]

in our implementation right now we have a custom elements registry style interface:

interface Window {
  agent: {
    tools: ToolsRegistry;
  }
}

interface ToolsRegistry {
  whenDefined(name: string): Promise<ToolDefinition | undefined>;
  define(name: string, definition: ToolDefinition);
  get(name: string): ToolDefinition | undefined;
}

i think this works a lot better than a generic "context".

its basically the register/unregisterTool API but following prior art of the CE registry structure.

@bwalderman is the chromium implementation available anywhere? would give better understanding to see some of the implementation

[bwalderman]

@43081j , the current JS API for Chromium was added in these changelists:
https://chromium-review.googlesource.com/c/chromium/src/+/6762977
https://chromium-review.googlesource.com/c/chromium/src/+/6961420

The API naming is still a little out of date. It uses the name window.automationDelegate from Google's Script Tools proposal until we resolve #24.

The implementation doesn't do anything in Edge yet. @khushalsagar, is there a publicly available way to test these in Chrome/Chromium?