Skip to content

Lightpanda: the headless browser designed for AI and automation

7.8 KB
Raw Blame
// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
//
// Francis Bouvier <[email protected]>
// Pierre Tachoire <[email protected]>
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as
// published by the Free Software Foundation, either version 3 of the
// License, or (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.
const std = @import("std");
const lp = @import("lightpanda");

const App = @import("../App.zig");
const testing = @import("../testing.zig");

const tools = @import("tools.zig");
const router = @import("router.zig");
const protocol = @import("protocol.zig");
const resources = @import("resources.zig");
const Transport = @import("Transport.zig");
const HttpServer = @import("HttpServer.zig");

const Self = @This();

/// The session an un-scoped request lands on: the only one over stdio, and
/// the one the HTTP transport routes to when a client sends no
/// `Mcp-Session-Id`.
pub const default_session_id = "default";

allocator: std.mem.Allocator,
app: *App,

/// The one session this server drives; the HTTP transport runs one server
/// per session.
active_session: *lp.ToolSession,
/// `default`, or the name the HTTP transport gave this session.
session_id: []const u8,
/// The HTTP transport, for the session tools. Null over stdio, where a
/// request can't name a session, so those tools are refused.
directory: ?*HttpServer = null,
transport: Transport,

pub fn init(allocator: std.mem.Allocator, app: *App, writer: *std.Io.Writer) !*Self {
    return initSession(allocator, app, writer, default_session_id);
}

/// A server for the session named `id`, which must outlive it.
pub fn initSession(allocator: std.mem.Allocator, app: *App, writer: *std.Io.Writer, id: []const u8) !*Self {
    const self = try allocator.create(Self);
    errdefer allocator.destroy(self);

    // Heap-allocated and never moved: `Browser` registers self-pointers.
    const entry = try allocator.create(lp.ToolSession);
    errdefer allocator.destroy(entry);

    try entry.init(app);
    errdefer entry.deinit();

    // Only the default session is backed by the on-disk cookie file; named
    // sessions start clean so agents stay isolated by default.
    if (isDefault(id)) {
        if (app.config.cookieFile()) |cookie_path| {
            lp.cookies.loadFromFile(entry.session, cookie_path);
        }
    }
    entry.exitIsolate();

    self.* = .{
        .allocator = allocator,
        .app = app,
        .active_session = entry,
        .session_id = id,
        .transport = .init(allocator, writer),
    };
    return self;
}

pub fn deinit(self: *Self) void {
    const entry = self.active_session;
    if (isDefault(self.session_id)) {
        if (self.app.config.cookieJarFile()) |cookie_jar_path| {
            lp.cookies.saveToFile(&entry.session.cookie_jar, cookie_jar_path);
        }
    }
    entry.enterIsolate();
    entry.deinit();
    self.allocator.destroy(entry);

    self.transport.deinit();
    self.allocator.destroy(self);
}

pub fn isDefault(id: []const u8) bool {
    return std.mem.eql(u8, id, default_session_id);
}

/// Pump the session's pending transfers and return how long the
/// caller may block before pumping again. See `Session.idleSlice`.
pub fn idle(self: *Self) u31 {
    // Pumping may resume JS (e.g. a completed script fetch), so it needs
    // the session's isolate current.
    const entry = self.active_session;
    entry.enterIsolate();
    defer entry.exitIsolate();
    return entry.session.idleSlice();
}

pub fn sendError(self: *Self, id: std.json.Value, code: protocol.ErrorCode, message: []const u8) !void {
    return self.transport.sendError(id, code, message);
}

pub fn sendResult(self: *Self, id: std.json.Value, result: anytype) !void {
    return self.transport.sendResult(id, result);
}

pub fn handleInitialize(self: *Self, req: protocol.Request) !void {
    const id = req.id orelse return;
    if (protocol.clientName(req.params)) |name| {
        self.app.telemetry.record(.{ .mcp_client = .fromName(name) });
    }
    try self.sendResult(id, protocol.InitializeResult{
        .protocolVersion = @tagName(protocol.Version.negotiate(req.params)),
        .capabilities = .{
            .resources = .{},
            .tools = .{},
        },
        .serverInfo = .{ .name = "lightpanda", .version = "0.1.0" },
        .instructions = lp.tools.driver_guidance,
    });
}

pub fn handleToolList(self: *Self, arena: std.mem.Allocator, req: protocol.Request) !void {
    return tools.handleList(self, arena, req);
}

pub fn handleToolCall(self: *Self, arena: std.mem.Allocator, req: protocol.Request) !void {
    // Dispatch runs page JS, so enter the target isolate around it.
    const entry = self.active_session;
    entry.enterIsolate();
    defer entry.exitIsolate();
    return tools.handleCall(self, arena, req);
}

pub fn handleResourceList(self: *Self, req: protocol.Request) !void {
    return resources.handleList(self, req);
}

pub fn handleResourceRead(self: *Self, arena: std.mem.Allocator, req: protocol.Request) !void {
    const entry = self.active_session;
    entry.enterIsolate();
    defer entry.exitIsolate();
    return resources.handleRead(self, arena, req);
}

test "MCP.Server - Integration: synchronous smoke test" {
    const allocator = testing.allocator;
    const app = testing.test_app;

    const input =
        \\{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}
    ;

    var in_reader: std.Io.Reader = .fixed(input);
    var out_alloc: std.Io.Writer.Allocating = .init(testing.arena_allocator);
    defer out_alloc.deinit();

    var server = try Self.init(allocator, app, &out_alloc.writer);
    defer server.deinit();

    try router.processRequests(server, &in_reader, null);

    try testing.expectJson(.{ .jsonrpc = "2.0", .id = 1, .result = .{ .protocolVersion = "2024-11-05" } }, out_alloc.writer.buffered());
}

test "MCP.Server - initialize negotiates the protocol version" {
    var out_alloc: std.Io.Writer.Allocating = .init(testing.arena_allocator);
    defer out_alloc.deinit();

    var server = try Self.init(testing.allocator, testing.test_app, &out_alloc.writer);
    defer server.deinit();

    const aa = testing.arena_allocator;

    // A supported version is echoed back.
    try router.handleMessage(server, aa,
        \\{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"1"}}}
    );
    try testing.expectJson(.{ .jsonrpc = "2.0", .id = 1, .result = .{ .protocolVersion = "2025-06-18" } }, out_alloc.writer.buffered());
    out_alloc.writer.end = 0;

    // An unknown one gets the latest supported.
    try router.handleMessage(server, aa,
        \\{"jsonrpc":"2.0","id":2,"method":"initialize","params":{"protocolVersion":"2099-01-01","capabilities":{},"clientInfo":{"name":"c","version":"1"}}}
    );
    try testing.expectJson(.{ .jsonrpc = "2.0", .id = 2, .result = .{ .protocolVersion = "2025-11-25" } }, out_alloc.writer.buffered());
    out_alloc.writer.end = 0;

    // So does a request with no version at all.
    try router.handleMessage(server, aa,
        \\{"jsonrpc":"2.0","id":3,"method":"initialize","params":{"capabilities":{},"clientInfo":{"name":"c","version":"1"}}}
    );
    try testing.expectJson(.{ .jsonrpc = "2.0", .id = 3, .result = .{ .protocolVersion = "2025-11-25" } }, out_alloc.writer.buffered());
}