Lightpanda: the headless browser designed for AI and automation
mcp: carry the navigation outcome as structuredContent
Adrià Arrufat01273a2af416
diff --git a/src/browser/tools.zig b/src/browser/tools.zigindex e2e7381b1..0f4783b92 100644--- a/src/browser/tools.zig+++ b/src/browser/tools.zig@@ -328,6 +328,18 @@ pub const Tool = enum {};}+ /// The result is a navigation outcome and nothing else, so `PageState` is+ /// a faithful machine-readable form of it. `evaluate` is excluded though+ /// it reports the same facts: there they are a suffix on the payload that+ /// is the real answer, and a client following the usual "prefer+ /// `structuredContent`" rule would keep the suffix and drop the payload.+ pub fn reportsPageState(self: Tool) bool {+ return switch (self) {+ .goto, .click, .fill, .scroll, .hover, .press, .selectOption, .setChecked => true,+ .search, .markdown, .html, .links, .evaluate, .extract, .tree, .nodeDetails, .interactiveElements, .structuredData, .detectForms, .findElement, .consoleLogs, .getUrl, .getCookies, .getEnv, .screenshot, .waitForSelector, .waitForScript, .waitForState => false,+ };+ }+/// Per-tool LLM-facing metadata. Tool identity (name + predicates) lives/// on the enclosing `Tool` enum; this struct just carries the strings.pub const Definition = struct {@@ -828,8 +840,28 @@ pub const ToolResult = struct {/// Resolved before the action runs, because a navigation takes the node/// with it.selector: ?[]const u8 = null,+ /// Set for the tools `Tool.reportsPageState` names.+ page_state: ?PageState = null,+};++/// Where a call left the page. MCP serializes it as `structuredContent` so a+/// client reads the status without regexing `Navigated successfully. HTTP 404+/// Not Found.` back apart. The transport drops null optionals rather than+/// writing them, so the matching `outputSchema` requires `url` alone.+pub const PageState = struct {+ url: []const u8,+ httpStatus: ?u16,+ title: ?[]const u8,};+fn pageState(frame: *lp.Frame) PageState {+ return .{+ .url = frame.url,+ .httpStatus = frame._http_status,+ .title = frame.getTitle() catch null,+ };+}+const GotoParams = struct {url: [:0]const u8,timeout: ?u32 = null,@@ -911,6 +943,9 @@ pub fn call(return err;};result.selector = selector;+ if (tool.reportsPageState()) {+ if (session.currentFrame()) |frame| result.page_state = pageState(frame);+ }return result;}diff --git a/src/mcp/protocol.zig b/src/mcp/protocol.zigindex e3b4b6c46..5b2efc198 100644--- a/src/mcp/protocol.zig+++ b/src/mcp/protocol.zig@@ -127,6 +127,9 @@ pub const Tool = struct {title: ?[]const u8 = null,description: ?[]const u8 = null,inputSchema: []const u8,+ /// Declaring one obliges every call to answer with a conforming+ /// `structuredContent`, so only the tools that always can carry it.+ outputSchema: ?[]const u8 = null,annotations: ?ToolAnnotations = null,pub fn jsonStringify(self: @This(), jw: anytype) !void {@@ -145,6 +148,12 @@ pub const Tool = struct {_ = try jw.beginWriteRaw();try jw.writer.writeAll(self.inputSchema);jw.endWriteRaw();+ if (self.outputSchema) |s| {+ try jw.objectField("outputSchema");+ _ = try jw.beginWriteRaw();+ try jw.writer.writeAll(s);+ jw.endWriteRaw();+ }if (self.annotations) |a| {try jw.objectField("annotations");try jw.write(a);@@ -191,6 +200,16 @@ pub fn CallToolResult(comptime Content: type) type {};}+/// The text block stays alongside `structuredContent`: it is what the model+/// reads, and the spec asks for the serialized form next to it anyway.+pub fn StructuredCallToolResult(comptime Content: type, comptime Structured: type) type {+ return struct {+ content: Content,+ structuredContent: Structured,+ isError: bool = false,+ };+}+pub const JsonEscapingWriter = struct {inner_writer: *std.Io.Writer,writer: std.Io.Writer,diff --git a/src/mcp/tools.zig b/src/mcp/tools.zigindex 5a0ba03ca..b6d9b917c 100644--- a/src/mcp/tools.zig+++ b/src/mcp/tools.zig@@ -21,6 +21,7 @@ const browser_tool_list = blk: {.title = td.summary,.description = td.description,.inputSchema = td.input_schema,+ .outputSchema = if (@field(BrowserTool, f.name).reportsPageState()) page_state_schema else null,.annotations = annotations(@field(BrowserTool, f.name)),};}@@ -47,6 +48,20 @@ fn annotations(tool: BrowserTool) protocol.ToolAnnotations {};}+/// Mirrors `browser_tools.PageState`. Inlined once per declaring tool, so it+/// stays terse: every client pays for it on `tools/list`.+const page_state_schema = browser_tools.minify(+ \\{+ \\ "type": "object",+ \\ "properties": {+ \\ "url": { "type": "string", "description": "URL of the page the call left loaded." },+ \\ "httpStatus": { "type": "integer", "description": "Response status of that page's own document. Absent when no response has arrived. 4xx/5xx means an error page, not the content." },+ \\ "title": { "type": "string", "description": "Document title. Empty or absent when the page has none." }+ \\ },+ \\ "required": ["url"]+ \\}+);+const save_schema = browser_tools.minify(\\{\\ "type": "object",@@ -179,6 +194,15 @@ fn dispatchBrowserTool(.isError = result.is_error,});}+ if (result.page_state) |page_state| {+ const Content = []const protocol.TextContent([]const u8);+ const content = [_]protocol.TextContent([]const u8){.{ .text = result.text }};+ return server.sendResult(id, protocol.StructuredCallToolResult(Content, browser_tools.PageState){+ .content = &content,+ .structuredContent = page_state,+ .isError = result.is_error,+ });+ }try sendToolResultText(server, id, result.text, result.is_error);}@@ -335,6 +359,90 @@ test "MCP - tools/list carries titles and annotations" {try testing.expectEqual(expected.len, found);}+test "MCP - outputSchema is declared exactly where structuredContent follows" {+ const json = try std.json.Stringify.valueAlloc(testing.allocator, all_tools, .{});+ defer testing.allocator.free(json);+ const parsed = try std.json.parseFromSlice(std.json.Value, testing.allocator, json, .{});+ defer parsed.deinit();++ for (parsed.value.array.items) |tool| {+ const name = tool.object.get("name").?.string;+ const declares = tool.object.get("outputSchema") != null;+ // `save`/`session_*` are MCP-only and have no `BrowserTool` tag.+ const expected = if (std.meta.stringToEnum(BrowserTool, name)) |t| t.reportsPageState() else false;+ try testing.expectEqual(expected, declares);+ if (!declares) continue;+ const schema = tool.object.get("outputSchema").?.object;+ try testing.expectEqual("object", schema.get("type").?.string);+ try testing.expectEqual(@as(usize, 1), schema.get("required").?.array.items.len);+ try testing.expectEqual("url", schema.get("required").?.array.items[0].string);+ }+}++test "MCP - structuredContent on a navigation" {+ var out: std.Io.Writer.Allocating = .init(testing.arena_allocator);+ const server = try testLoadPage("about:blank", &out.writer);+ defer server.deinit();++ const goto =+ \\{+ \\ "jsonrpc": "2.0",+ \\ "id": 1,+ \\ "method": "tools/call",+ \\ "params": {+ \\ "name": "goto",+ \\ "arguments": { "url": "http://localhost:9582/src/browser/tests/mcp_actions.html" }+ \\ }+ \\}+ ;+ try router.handleMessage(server, testing.arena_allocator, goto);+ // The fixture has no <title>, so `title` is empty rather than absent.+ try testing.expectJson(.{ .id = 1, .result = .{+ .content = &.{.{ .type = "text", .text = "Navigated successfully. HTTP 200 OK." }},+ .structuredContent = .{+ .url = "http://localhost:9582/src/browser/tests/mcp_actions.html",+ .httpStatus = 200,+ .title = "",+ },+ } }, out.written());++ // A read tool reports no page state, so no `structuredContent` to mistake+ // for its payload.+ out.clearRetainingCapacity();+ const get_url =+ \\{+ \\ "jsonrpc": "2.0",+ \\ "id": 2,+ \\ "method": "tools/call",+ \\ "params": { "name": "getUrl", "arguments": {} }+ \\}+ ;+ try router.handleMessage(server, testing.arena_allocator, get_url);+ try testing.expect(std.mem.indexOf(u8, out.written(), "structuredContent") == null);++ // An action reports where it left the page, navigation or not.+ out.clearRetainingCapacity();+ const click =+ \\{+ \\ "jsonrpc": "2.0",+ \\ "id": 3,+ \\ "method": "tools/call",+ \\ "params": {+ \\ "name": "click",+ \\ "arguments": { "selector": "#btn" }+ \\ }+ \\}+ ;+ try router.handleMessage(server, testing.arena_allocator, click);+ try testing.expectJson(.{ .id = 3, .result = .{+ .structuredContent = .{+ .url = "http://localhost:9582/src/browser/tests/mcp_actions.html",+ .httpStatus = 200,+ .title = "",+ },+ } }, out.written());+}+test "MCP - evaluate error reporting" {var out: std.Io.Writer.Allocating = .init(testing.arena_allocator);const server = try testLoadPage("about:blank", &out.writer);