New Feature: Add WebMcpTool.ExecuteAsync() method (#14851) (#3421)

Implements upstream PR #14851 which adds direct tool execution support
to WebMcpTool. Includes the full WebMCP API infrastructure (from #14814)
plus the execute capability.

WebMcpTool.ExecuteAsync(input) invokes the tool via CDP and returns a
Task<WebMcpToolCallResult> that completes when the toolresponded event
fires with a matching invocation ID.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: kblok

lib/PuppeteerSharp.Tests/WebMcpTests/PageWebMcpTests.cs

@@ -1,3 +1,4 @@
+using System;
 using System.Threading.Tasks;
 using NUnit.Framework;
 using PuppeteerSharp.Cdp;
@@ -110,6 +111,52 @@ await page.EvaluateFunctionAsync(@"() => {
             Assert.That(removed, Has.Length.GreaterThanOrEqualTo(1));
         }
 
+        [Test, PuppeteerTest("webmcp.spec", "Page.webmcp", "should invoke tool")]
+        public async Task ShouldInvokeTool()
+        {
+            await using var browser = await Puppeteer.LaunchAsync(WebMcpOptions(), TestConstants.LoggerFactory);
+            var page = (CdpPage)await browser.NewPageAsync();
+            await page.GoToAsync(TestConstants.HttpsPrefix + "/empty.html");
+
+            Assert.That(page.WebMcp, Is.Not.Null);
+
+            var toolAddedTcs = new TaskCompletionSource<bool>();
+            page.WebMcp.ToolsAdded += (_, _) => toolAddedTcs.TrySetResult(true);
+
+            await page.EvaluateFunctionAsync(@"() => {
+                window.navigator.modelContext.registerTool({
+                    name: 'test-tool-1',
+                    description: 'A test tool 1',
+                    inputSchema: {
+                        type: 'object',
+                        properties: { text: { type: 'string', description: 'Some text' } },
+                        required: ['text'],
+                    },
+                    execute: (params) => {
+                        return `hello ${params.text}`;
+                    },
+                });
+            }");
+
+            await toolAddedTcs.Task.WaitAsync(TimeSpan.FromSeconds(5));
+
+            var tools = page.WebMcp.Tools();
+            var tool = tools[0];
+
+            var toolCalledTcs = new TaskCompletionSource<WebMcpToolCall>();
+            page.WebMcp.ToolInvoked += (_, call) => toolCalledTcs.TrySetResult(call);
+
+            var response = await tool.ExecuteAsync(new { text = "world" });
+            var call = await toolCalledTcs.Task.WaitAsync(TimeSpan.FromSeconds(5));
+
+            Assert.That(response.Id, Is.EqualTo(call.Id));
+            Assert.That(response.Call, Is.SameAs(call));
+            Assert.That(response.Status, Is.EqualTo(WebMcpInvocationStatus.Completed));
+            Assert.That(response.Output?.ToString(), Contains.Substring("hello world"));
+            Assert.That(response.ErrorText, Is.Null);
+            Assert.That(response.Exception, Is.Null);
+        }
+
         [Test, PuppeteerTest("webmcp.spec", "Page.webmcp", "should remove tools on frame navigation")]
         public async Task ShouldRemoveToolsOnFrameNavigation()
         {

lib/PuppeteerSharp/Cdp/CdpWebMcp.cs

@@ -168,6 +168,7 @@ private void OnToolsAdded(WebMcpToolsAddedProtocolEvent e)
                 },
                 Frame = frame,
                 Location = location,
+                WebMcp = this,
             };
 
             frameTools[tool.Name] = webMcpTool;

lib/PuppeteerSharp/Cdp/WebMcpTool.cs

@@ -20,6 +20,9 @@
 //  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 //  * SOFTWARE.
 
+using System;
+using System.Threading.Tasks;
+
 namespace PuppeteerSharp.Cdp;
 
 /// <summary>
@@ -44,4 +47,32 @@ public class WebMcpTool
 
     /// <summary>Source location that defined the tool (if available).</summary>
     public ConsoleMessageLocation Location { get; init; }
+
+    internal CdpWebMcp WebMcp { get; init; }
+
+    /// <summary>
+    /// Executes the tool with the given input parameters.
+    /// </summary>
+    /// <param name="input">Input object matching the tool's <c>inputSchema</c>. Defaults to empty object.</param>
+    /// <returns>A task resolving to the tool call result.</returns>
+    public async Task<WebMcpToolCallResult> ExecuteAsync(object input = null)
+    {
+        var invocationId = await WebMcp.InvokeToolAsync(this, input ?? new { }).ConfigureAwait(false);
+
+        var tcs = new TaskCompletionSource<WebMcpToolCallResult>(TaskCreationOptions.RunContinuationsAsynchronously);
+
+        EventHandler<WebMcpToolCallResult> handler = null;
+        handler = (_, result) =>
+        {
+            if (result.Id == invocationId)
+            {
+                WebMcp.ToolResponded -= handler;
+                tcs.TrySetResult(result);
+            }
+        };
+
+        WebMcp.ToolResponded += handler;
+
+        return await tcs.Task.ConfigureAwait(false);
+    }
 }