@flrande/browserctl 0.1.0

package/packages/protocol/src/envelope.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+
+import { ErrorCode } from "./errors";
+import { createErr, createOk } from "./envelope";
+
+describe("createOk", () => {
+  it("returns a success envelope", () => {
+    expect(createOk({ value: 42 })).toEqual({
+      ok: true,
+      data: { value: 42 }
+    });
+  });
+});
+
+describe("createErr", () => {
+  it("returns an error envelope", () => {
+    expect(createErr(ErrorCode.E_INVALID_ARG, "bad input")).toEqual({
+      ok: false,
+      error: {
+        code: "E_INVALID_ARG",
+        message: "bad input"
+      }
+    });
+  });
+});

package/packages/protocol/src/envelope.ts

@@ -0,0 +1,31 @@
+import type { ErrorCode } from "./errors";
+
+export type ToolSuccessEnvelope<TData> = {
+  ok: true;
+  data: TData;
+};
+
+export type ToolErrorEnvelope = {
+  ok: false;
+  error: {
+    code: ErrorCode;
+    message: string;
+  };
+};
+
+export function createOk<TData>(data: TData): ToolSuccessEnvelope<TData> {
+  return {
+    ok: true,
+    data
+  };
+}
+
+export function createErr(code: ErrorCode, message: string): ToolErrorEnvelope {
+  return {
+    ok: false,
+    error: {
+      code,
+      message
+    }
+  };
+}

package/packages/protocol/src/errors.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+
+import { ErrorCode } from "./errors";
+
+describe("ErrorCode", () => {
+  it("contains the canonical error code registry", () => {
+    expect(ErrorCode).toEqual({
+      E_INVALID_ARG: "E_INVALID_ARG",
+      E_NOT_FOUND: "E_NOT_FOUND",
+      E_CONFLICT: "E_CONFLICT",
+      E_TIMEOUT: "E_TIMEOUT",
+      E_DRIVER_UNAVAILABLE: "E_DRIVER_UNAVAILABLE",
+      E_PERMISSION: "E_PERMISSION",
+      E_INTERNAL: "E_INTERNAL"
+    });
+  });
+});

package/packages/protocol/src/errors.ts

@@ -0,0 +1,11 @@
+export const ErrorCode = {
+  E_INVALID_ARG: "E_INVALID_ARG",
+  E_NOT_FOUND: "E_NOT_FOUND",
+  E_CONFLICT: "E_CONFLICT",
+  E_TIMEOUT: "E_TIMEOUT",
+  E_DRIVER_UNAVAILABLE: "E_DRIVER_UNAVAILABLE",
+  E_PERMISSION: "E_PERMISSION",
+  E_INTERNAL: "E_INTERNAL"
+} as const;
+
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];

package/packages/protocol/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./errors";
+export * from "./envelope";
+export * from "./tools";

package/packages/protocol/src/tools.ts

@@ -0,0 +1,3 @@
+import type { ToolErrorEnvelope, ToolSuccessEnvelope } from "./envelope";
+
+export type ToolResponse<TData> = ToolSuccessEnvelope<TData> | ToolErrorEnvelope;

package/packages/transport-mcp-stdio/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./tool-map";
+export * from "./server";
+export * from "./sdk-server";

package/packages/transport-mcp-stdio/src/sdk-server.ts

@@ -0,0 +1,139 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { CallToolResult, Implementation } from "@modelcontextprotocol/sdk/types.js";
+import { Readable, Writable } from "node:stream";
+import * as z from "zod/v4";
+
+import { ErrorCode } from "../../protocol/src/index";
+
+import {
+  createMcpStdioServer,
+  type McpStdioServer,
+  type McpToolCallEnvelope
+} from "./server";
+import { buildToolMap, type ToolMap } from "./tool-map";
+
+const UNKNOWN_TRACE_ID = "trace:unknown";
+const DEFAULT_SERVER_INFO: Implementation = {
+  name: "browserd",
+  version: "0.1.0"
+};
+
+export type McpSdkServerOptions = {
+  toolMap?: ToolMap;
+  serverInfo?: Implementation;
+};
+
+export type McpSdkStdioTransport = {
+  input?: Readable;
+  output?: Writable;
+};
+
+export type McpSdkServer = {
+  readonly mcpServer: McpServer;
+  readonly mcpStdioServer: McpStdioServer;
+  listTools(): string[];
+  connect(transport: Transport): Promise<void>;
+  connectStdio(transport?: McpSdkStdioTransport): Promise<void>;
+  close(): Promise<void>;
+};
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function resolveTraceId(rawArgs: unknown): string {
+  if (!isObjectRecord(rawArgs)) {
+    return UNKNOWN_TRACE_ID;
+  }
+
+  const traceId = rawArgs.traceId;
+  if (typeof traceId !== "string") {
+    return UNKNOWN_TRACE_ID;
+  }
+
+  const trimmedTraceId = traceId.trim();
+  return trimmedTraceId.length > 0 ? trimmedTraceId : UNKNOWN_TRACE_ID;
+}
+
+function stringifyContent(value: unknown): string {
+  if (typeof value === "string") {
+    return value;
+  }
+
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function toCallToolResult(envelope: McpToolCallEnvelope): CallToolResult {
+  if (envelope.ok) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: stringifyContent(envelope.data ?? {})
+        }
+      ],
+      structuredContent: envelope
+    };
+  }
+
+  const code = envelope.error?.code ?? ErrorCode.E_INTERNAL;
+  const message = envelope.error?.message ?? "Unexpected tool failure.";
+  return {
+    content: [
+      {
+        type: "text",
+        text: `${code}: ${message}`
+      }
+    ],
+    structuredContent: envelope,
+    isError: true
+  };
+}
+
+export function createMcpSdkServer(options: McpSdkServerOptions = {}): McpSdkServer {
+  const toolMap = options.toolMap ?? buildToolMap();
+  const mcpStdioServer = createMcpStdioServer(toolMap);
+  const mcpServer = new McpServer(options.serverInfo ?? DEFAULT_SERVER_INFO);
+
+  for (const toolName of mcpStdioServer.listTools()) {
+    mcpServer.registerTool(
+      toolName,
+      {
+        description: `Browser control tool: ${toolName}`,
+        inputSchema: z.object({}).passthrough()
+      },
+      async (rawArgs) => {
+        const response = await mcpStdioServer.callTool({
+          name: toolName,
+          traceId: resolveTraceId(rawArgs),
+          arguments: rawArgs
+        });
+        return toCallToolResult(response);
+      }
+    );
+  }
+
+  return {
+    mcpServer,
+    mcpStdioServer,
+    listTools() {
+      return mcpStdioServer.listTools();
+    },
+    connect(transport: Transport) {
+      return mcpServer.connect(transport);
+    },
+    connectStdio(transport: McpSdkStdioTransport = {}) {
+      const stdioTransport = new StdioServerTransport(transport.input, transport.output);
+      return mcpServer.connect(stdioTransport);
+    },
+    close() {
+      return mcpServer.close();
+    }
+  };
+}

package/packages/transport-mcp-stdio/src/server.test.ts

@@ -0,0 +1,281 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { describe, expect, it } from "vitest";
+
+import { ErrorCode, createOk } from "../../protocol/src/index";
+
+import { createMcpSdkServer } from "./sdk-server";
+import { createMcpStdioServer } from "./server";
+import { buildToolMap } from "./tool-map";
+
+describe("tool map", () => {
+  it("includes browser.status", () => {
+    const map = buildToolMap();
+
+    expect(map.has("browser.status")).toBe(true);
+  });
+});
+
+describe("createMcpStdioServer", () => {
+  it("returns success envelope for a successful handler result", async () => {
+    const server = createMcpStdioServer(
+      new Map([
+        [
+          "browser.status",
+          async () =>
+            createOk({
+              status: "ok"
+            })
+        ]
+      ])
+    );
+
+    const response = await server.callTool({
+      name: "browser.status",
+      traceId: "trace:test",
+      arguments: {
+        sessionId: "session:alpha",
+        profile: "profile:alpha",
+        targetId: "target:alpha"
+      }
+    });
+
+    expect(response).toEqual({
+      ok: true,
+      traceId: "trace:test",
+      sessionId: "session:alpha",
+      profile: "profile:alpha",
+      targetId: "target:alpha",
+      data: {
+        status: "ok"
+      }
+    });
+  });
+
+  it("returns validation errors through the common envelope", async () => {
+    const server = createMcpStdioServer();
+
+    const response = await server.callTool({
+      name: "browser.status",
+      traceId: "trace:validation",
+      arguments: {
+        sessionId: ""
+      }
+    });
+
+    expect(response).toEqual({
+      ok: false,
+      traceId: "trace:validation",
+      sessionId: "session:unknown",
+      error: {
+        code: ErrorCode.E_INVALID_ARG,
+        message: "sessionId is required and must be a non-empty string."
+      }
+    });
+  });
+
+  it("returns not found for unknown tools", async () => {
+    const server = createMcpStdioServer();
+
+    const response = await server.callTool({
+      name: "browser.unknown",
+      traceId: "trace:unknown",
+      arguments: {
+        sessionId: "session:alpha"
+      }
+    });
+
+    expect(response).toEqual({
+      ok: false,
+      traceId: "trace:unknown",
+      sessionId: "session:alpha",
+      error: {
+        code: ErrorCode.E_NOT_FOUND,
+        message: "Unknown tool: browser.unknown"
+      }
+    });
+  });
+
+  it("returns a dedicated code for not implemented tools", async () => {
+    const server = createMcpStdioServer();
+
+    const response = await server.callTool({
+      name: "browser.profile.list",
+      traceId: "trace:not-implemented",
+      arguments: {
+        sessionId: "session:alpha"
+      }
+    });
+
+    expect(response).toEqual({
+      ok: false,
+      traceId: "trace:not-implemented",
+      sessionId: "session:alpha",
+      error: {
+        code: ErrorCode.E_DRIVER_UNAVAILABLE,
+        message: "Tool is not implemented: browser.profile.list"
+      }
+    });
+  });
+
+  it("wraps thrown handler errors as E_INTERNAL envelopes", async () => {
+    const server = createMcpStdioServer(
+      new Map([
+        [
+          "browser.status",
+          async () => {
+            throw new Error("boom");
+          }
+        ]
+      ])
+    );
+
+    const response = await server.callTool({
+      name: "browser.status",
+      traceId: "trace:throw",
+      arguments: {
+        sessionId: "session:alpha"
+      }
+    });
+
+    expect(response).toEqual({
+      ok: false,
+      traceId: "trace:throw",
+      sessionId: "session:alpha",
+      error: {
+        code: ErrorCode.E_INTERNAL,
+        message: "boom"
+      }
+    });
+  });
+
+  it("uses the provided toolMap override instead of defaults", async () => {
+    const server = createMcpStdioServer(
+      new Map([
+        [
+          "custom.ping",
+          async () =>
+            createOk({
+              pong: true
+            })
+        ]
+      ])
+    );
+
+    expect(server.listTools()).toEqual(["custom.ping"]);
+
+    const response = await server.callTool({
+      name: "custom.ping",
+      traceId: "trace:override",
+      arguments: {
+        sessionId: "session:alpha"
+      }
+    });
+
+    expect(response).toEqual({
+      ok: true,
+      traceId: "trace:override",
+      sessionId: "session:alpha",
+      data: {
+        pong: true
+      }
+    });
+  });
+});
+
+describe("createMcpSdkServer", () => {
+  it("registers tool names and returns structured envelopes through MCP", async () => {
+    const sdkServer = createMcpSdkServer({
+      toolMap: new Map([
+        [
+          "browser.status",
+          async (args) =>
+            createOk({
+              status: "ok",
+              sessionId: args.sessionId
+            })
+        ]
+      ]),
+      serverInfo: {
+        name: "browserctl-test-server",
+        version: "0.0.0-test"
+      }
+    });
+
+    const client = new Client({
+      name: "browserctl-test-client",
+      version: "0.0.0-test"
+    });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    await Promise.all([sdkServer.connect(serverTransport), client.connect(clientTransport)]);
+
+    try {
+      const toolsResult = await client.listTools();
+      expect(toolsResult.tools.map((tool) => tool.name)).toEqual(["browser.status"]);
+
+      const result = await client.callTool({
+        name: "browser.status",
+        arguments: {
+          sessionId: "session:alpha",
+          traceId: "trace:alpha"
+        }
+      });
+
+      expect("structuredContent" in result).toBe(true);
+      if (!("structuredContent" in result)) {
+        throw new Error("Expected a CallToolResult payload with structuredContent.");
+      }
+
+      expect(result.isError).not.toBe(true);
+      expect(result.structuredContent).toMatchObject({
+        ok: true,
+        traceId: "trace:alpha",
+        sessionId: "session:alpha",
+        data: {
+          status: "ok",
+          sessionId: "session:alpha"
+        }
+      });
+    } finally {
+      await client.close();
+      await sdkServer.close();
+    }
+  });
+
+  it("maps envelope validation errors to MCP tool errors", async () => {
+    const sdkServer = createMcpSdkServer();
+    const client = new Client({
+      name: "browserctl-test-client",
+      version: "0.0.0-test"
+    });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    await Promise.all([sdkServer.connect(serverTransport), client.connect(clientTransport)]);
+
+    try {
+      const result = await client.callTool({
+        name: "browser.status",
+        arguments: {
+          sessionId: ""
+        }
+      });
+
+      expect("structuredContent" in result).toBe(true);
+      if (!("structuredContent" in result)) {
+        throw new Error("Expected a CallToolResult payload with structuredContent.");
+      }
+
+      expect(result.isError).toBe(true);
+      expect(result.structuredContent).toMatchObject({
+        ok: false,
+        sessionId: "session:unknown",
+        error: {
+          code: ErrorCode.E_INVALID_ARG,
+          message: "sessionId is required and must be a non-empty string."
+        }
+      });
+    } finally {
+      await client.close();
+      await sdkServer.close();
+    }
+  });
+});

package/packages/transport-mcp-stdio/src/server.ts

@@ -0,0 +1,183 @@
+import { ErrorCode, createErr, createOk, type ToolResponse } from "../../protocol/src/index";
+
+import { buildToolMap, type ToolCallArgs, type ToolMap } from "./tool-map";
+
+const UNKNOWN_TRACE_ID = "trace:unknown";
+const UNKNOWN_SESSION_ID = "session:unknown";
+
+export type McpToolCallRequest = {
+  name: string;
+  arguments?: unknown;
+  traceId?: string;
+};
+
+export type McpToolCallEnvelope<TData = Record<string, unknown>> = {
+  ok: boolean;
+  traceId: string;
+  sessionId: string;
+  profile?: string;
+  targetId?: string;
+  data?: TData;
+  error?: {
+    code: string;
+    message: string;
+  };
+};
+
+export type McpStdioServer = {
+  readonly toolMap: ToolMap;
+  listTools(): string[];
+  callTool(request: McpToolCallRequest): Promise<McpToolCallEnvelope>;
+};
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function resolveTraceId(value: string | undefined): string {
+  if (typeof value !== "string") {
+    return UNKNOWN_TRACE_ID;
+  }
+
+  const trimmedValue = value.trim();
+  return trimmedValue.length === 0 ? UNKNOWN_TRACE_ID : trimmedValue;
+}
+
+function toErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return "Unexpected tool failure.";
+}
+
+export function validateToolCallArgs(value: unknown): ToolResponse<ToolCallArgs> {
+  if (!isObjectRecord(value)) {
+    return createErr(ErrorCode.E_INVALID_ARG, "Tool arguments must be an object.");
+  }
+
+  const sessionIdValue = value.sessionId;
+  if (typeof sessionIdValue !== "string" || sessionIdValue.trim().length === 0) {
+    return createErr(ErrorCode.E_INVALID_ARG, "sessionId is required and must be a non-empty string.");
+  }
+
+  const profileValue = value.profile;
+  if (profileValue !== undefined && (typeof profileValue !== "string" || profileValue.trim().length === 0)) {
+    return createErr(ErrorCode.E_INVALID_ARG, "profile must be a non-empty string when provided.");
+  }
+
+  const targetIdValue = value.targetId;
+  if (targetIdValue !== undefined && (typeof targetIdValue !== "string" || targetIdValue.trim().length === 0)) {
+    return createErr(ErrorCode.E_INVALID_ARG, "targetId must be a non-empty string when provided.");
+  }
+
+  const timeoutMsValue = value.timeoutMs;
+  if (
+    timeoutMsValue !== undefined &&
+    (typeof timeoutMsValue !== "number" || !Number.isFinite(timeoutMsValue) || timeoutMsValue < 0)
+  ) {
+    return createErr(
+      ErrorCode.E_INVALID_ARG,
+      "timeoutMs must be a non-negative finite number when provided."
+    );
+  }
+
+  const normalizedArgs: ToolCallArgs = {
+    ...value,
+    sessionId: sessionIdValue.trim()
+  };
+
+  if (typeof profileValue === "string") {
+    normalizedArgs.profile = profileValue.trim();
+  }
+
+  if (typeof targetIdValue === "string") {
+    normalizedArgs.targetId = targetIdValue.trim();
+  }
+
+  if (typeof timeoutMsValue === "number") {
+    normalizedArgs.timeoutMs = timeoutMsValue;
+  }
+
+  return createOk(normalizedArgs);
+}
+
+export function adaptToolResponse<TData>(
+  context: Pick<ToolCallArgs, "sessionId" | "profile" | "targetId">,
+  traceId: string,
+  response: ToolResponse<TData>
+): McpToolCallEnvelope<TData> {
+  if (response.ok) {
+    return {
+      ok: true,
+      traceId,
+      sessionId: context.sessionId,
+      profile: context.profile,
+      targetId: context.targetId,
+      data: response.data
+    };
+  }
+
+  return {
+    ok: false,
+    traceId,
+    sessionId: context.sessionId,
+    profile: context.profile,
+    targetId: context.targetId,
+    error: response.error
+  };
+}
+
+export function createMcpStdioServer(toolMap: ToolMap = buildToolMap()): McpStdioServer {
+  return {
+    toolMap,
+    listTools() {
+      return [...toolMap.keys()];
+    },
+    async callTool(request) {
+      const traceId = resolveTraceId(request.traceId);
+      const rawToolName = request.name;
+      if (typeof rawToolName !== "string" || rawToolName.trim().length === 0) {
+        return adaptToolResponse(
+          {
+            sessionId: UNKNOWN_SESSION_ID
+          },
+          traceId,
+          createErr(ErrorCode.E_INVALID_ARG, "Tool name must be a non-empty string.")
+        );
+      }
+
+      const validatedArgs = validateToolCallArgs(request.arguments);
+      if (!validatedArgs.ok) {
+        return adaptToolResponse(
+          {
+            sessionId: UNKNOWN_SESSION_ID
+          },
+          traceId,
+          validatedArgs
+        );
+      }
+
+      const toolName = rawToolName.trim();
+      const handler = toolMap.get(toolName);
+      if (handler === undefined) {
+        return adaptToolResponse(
+          validatedArgs.data,
+          traceId,
+          createErr(ErrorCode.E_NOT_FOUND, `Unknown tool: ${toolName}`)
+        );
+      }
+
+      try {
+        const response = await handler(validatedArgs.data);
+        return adaptToolResponse(validatedArgs.data, traceId, response);
+      } catch (error) {
+        return adaptToolResponse(
+          validatedArgs.data,
+          traceId,
+          createErr(ErrorCode.E_INTERNAL, toErrorMessage(error))
+        );
+      }
+    }
+  };
+}