Skip to content

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.zig
index 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.zig
index 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.zig
index 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);