@solvvn/mcp-simple-browser 1.0.0

package/README.md

@@ -0,0 +1,115 @@
+# MCP Simple Browser
+
+An MCP (Model Context Protocol) server that provides browser automation tools powered by CloakBrowser.
+
+## Features
+
+- **Headless Browser**: Automatically launches a stealth browser via CloakBrowser
+
+## Quick Start
+
+```bash
+# Add to Claude Desktop
+claude mcp add simple-browser npx @solvvn/mcp-simple-browser
+```
+
+## Installation (Manual)
+
+```bash
+npm install
+# or
+yarn install
+```
+
+## Usage
+
+### As MCP Server
+
+```bash
+# Development
+yarn dev
+
+# Production
+yarn build
+yarn start
+```
+
+The server runs on stdio and can be connected to any MCP-compatible client (Claude Desktop, etc.).
+
+### Claude Desktop Configuration
+
+Add to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "simple-browser": {
+      "command": "node",
+      "args": ["/path/to/mcp-simple-browser/dist/index.js"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `browser_navigate` | Navigate to a URL and wait for it to load |
+| `browser_screenshot` | Take a screenshot (returns base64) |
+| `browser_save_screenshot` | Take a screenshot and save to file |
+| `browser_click` | Click an element by CSS selector |
+| `browser_type` | Type text into an input field |
+| `browser_get_content` | Get HTML content of the page |
+| `browser_get_text` | Get text content from page or element |
+| `browser_evaluate` | Execute JavaScript in page context |
+| `browser_search` | Search the web (Google, DuckDuckGo, Bing) |
+| `browser_wait` | Wait for specified milliseconds |
+| `browser_print_to_pdf` | Print page to PDF |
+| `browser_close` | Close browser and cleanup |
+
+## Examples
+
+### Navigate and Screenshot
+
+```javascript
+// Navigate to a page
+await browser_navigate({ url: "https://example.com" })
+
+// Take screenshot
+await browser_screenshot({ fullPage: true })
+```
+
+### Search
+
+```javascript
+// Search with default engine (DuckDuckGo)
+await browser_search({ query: "TypeScript MCP" })
+
+// Search with specific engine
+await browser_search({ query: "CloakBrowser", engine: "google" })
+```
+
+### Interact with Elements
+
+```javascript
+// Type in search box
+await browser_type({ selector: "input[name='q']", text: "hello" })
+
+// Click a button
+await browser_click({ selector: "button[type='submit']" })
+```
+
+## Development
+
+```bash
+# Type check
+yarn typecheck
+
+# Build
+yarn build
+```
+
+## License
+
+MIT

package/dist/browser.d.ts

@@ -0,0 +1,7 @@
+import { launch } from "cloakbrowser";
+type Browser = Awaited<ReturnType<typeof launch>>;
+type Page = Awaited<ReturnType<Browser["newPage"]>>;
+export declare function getPage(): Promise<Page>;
+export declare function closeBrowser(): Promise<void>;
+export {};
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,KAAK,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC;AAClD,KAAK,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AASpD,wBAAsB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAQ7C;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAKlD"}

package/dist/browser.js

@@ -0,0 +1,22 @@
+import { launch } from "cloakbrowser";
+let browserInstance = null;
+let pageInstance = null;
+function createBrowser() {
+    return launch({ headless: true, humanize: true });
+}
+export async function getPage() {
+    if (!browserInstance) {
+        browserInstance = await createBrowser();
+    }
+    if (!pageInstance) {
+        pageInstance = await browserInstance.newPage();
+    }
+    return pageInstance;
+}
+export async function closeBrowser() {
+    await pageInstance?.close().catch(() => { });
+    await browserInstance?.close().catch(() => { });
+    pageInstance = null;
+    browserInstance = null;
+}
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAKtC,IAAI,eAAe,GAAmB,IAAI,CAAC;AAC3C,IAAI,YAAY,GAAgB,IAAI,CAAC;AAErC,SAAS,aAAa;IACpB,OAAO,MAAM,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO;IAC3B,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,eAAe,GAAG,MAAM,aAAa,EAAE,CAAC;IAC1C,CAAC;IACD,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,YAAY,GAAG,MAAM,eAAe,CAAC,OAAO,EAAE,CAAC;IACjD,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,MAAM,YAAY,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAC5C,MAAM,eAAe,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAC/C,YAAY,GAAG,IAAI,CAAC;IACpB,eAAe,GAAG,IAAI,CAAC;AACzB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,16 @@
+import * as dotenv from "dotenv";
+dotenv.config();
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools.js";
+async function main() {
+    const server = new McpServer({ name: "simple-browser", version: "1.0.0" });
+    registerTools(server);
+    await server.connect(new StdioServerTransport());
+    console.error("SimpleBrowser MCP Server running on stdio");
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,MAAM,CAAC,MAAM,EAAE,CAAC;AAEhB,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3E,aAAa,CAAC,MAAM,CAAC,CAAC;IACtB,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;IACjD,OAAO,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;AAC7D,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerTools(server: McpServer): void;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA8LzE,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAiBrD"}

package/dist/tools.js

@@ -0,0 +1,187 @@
+import { z } from "zod";
+import { writeFile } from "fs/promises";
+import { closeBrowser, getPage } from "./browser.js";
+function createTool(def) {
+    return def;
+}
+function success(extra) {
+    return { success: true, ...extra };
+}
+const SearchEngines = {
+    google: (q) => `https://www.google.com/search?q=${q}`,
+    duckduckgo: (q) => `https://duckduckgo.com/?q=${q}`,
+    bing: (q) => `https://www.bing.com/search?q=${q}`,
+};
+const tools = [
+    createTool({
+        name: "browser_navigate",
+        description: "Navigate to a URL and wait for it to load.",
+        schema: {
+            url: z.string().describe("The URL to navigate to"),
+            waitUntil: z
+                .enum(["load", "domcontentloaded", "networkidle", "commit"])
+                .default("networkidle"),
+        },
+        handler: async ({ url, waitUntil }) => {
+            const page = await getPage();
+            await page.goto(url, { waitUntil });
+            return success({ url: page.url(), title: await page.title() });
+        },
+    }),
+    createTool({
+        name: "browser_screenshot",
+        description: "Take a screenshot of the current page.",
+        schema: {
+            fullPage: z.boolean().default(false).describe("Capture full scrollable page"),
+        },
+        handler: async ({ fullPage }) => {
+            const buffer = await (await getPage()).screenshot({ fullPage });
+            return success({ format: "png", data: buffer.toString("base64") });
+        },
+    }),
+    createTool({
+        name: "browser_click",
+        description: "Click an element by CSS selector.",
+        schema: { selector: z.string().describe("CSS selector") },
+        handler: async ({ selector }) => {
+            await (await getPage()).click(selector);
+            return success({});
+        },
+    }),
+    createTool({
+        name: "browser_type",
+        description: "Type text into an input field.",
+        schema: {
+            selector: z.string(),
+            text: z.string(),
+            delay: z.number().default(50).describe("Delay between keystrokes (ms)"),
+        },
+        handler: async ({ selector, text, delay }) => {
+            await (await getPage()).type(selector, text, { delay });
+            return success({});
+        },
+    }),
+    createTool({
+        name: "browser_get_content",
+        description: "Get the HTML content of the page.",
+        schema: {},
+        handler: async () => ({ html: await (await getPage()).content() }),
+    }),
+    createTool({
+        name: "browser_get_text",
+        description: "Get text content from the page or a specific element.",
+        schema: {
+            selector: z.string().optional().describe("CSS selector (defaults to body)"),
+        },
+        handler: async ({ selector }) => {
+            const el = selector || "body";
+            const text = await (await getPage()).$eval(el, (el) => el.textContent);
+            return { text: text ?? "" };
+        },
+    }),
+    createTool({
+        name: "browser_evaluate",
+        description: "Execute JavaScript in the page context.",
+        schema: { script: z.string().describe("JavaScript code to execute") },
+        handler: async ({ script }) => ({ result: await (await getPage()).evaluate(script) }),
+    }),
+    createTool({
+        name: "browser_search",
+        description: "Search the web using a search engine.",
+        schema: {
+            query: z.string(),
+            engine: z.enum(["google", "duckduckgo", "bing"]).default("duckduckgo"),
+        },
+        handler: async ({ query, engine }) => {
+            const page = await getPage();
+            const searchUrl = SearchEngines[engine](encodeURIComponent(query));
+            await page.goto(searchUrl, { waitUntil: "networkidle" });
+            const results = await page.evaluate(() => {
+                const out = [];
+                const selectors = ["div.g a[href^='http']", "div[data-srg] a[href^='http']", ".result a[href^='http']"];
+                for (const sel of selectors) {
+                    document.querySelectorAll(sel).forEach((a) => {
+                        if (!a.href || /google|bing|duckduckgo/.test(a.href))
+                            return;
+                        const titleEl = a.querySelector("h3") || a;
+                        out.push({
+                            title: titleEl.textContent?.trim() ?? "",
+                            url: a.href,
+                            snippet: a.textContent?.trim() ?? "",
+                        });
+                    });
+                    if (out.length)
+                        break;
+                }
+                return out.slice(0, 10);
+            });
+            return success({ engine, query, results });
+        },
+    }),
+    createTool({
+        name: "browser_wait",
+        description: "Wait for a specified time.",
+        schema: { milliseconds: z.number().describe("Time to wait in ms") },
+        handler: async ({ milliseconds }) => {
+            await new Promise((resolve) => setTimeout(resolve, milliseconds));
+            return success({ waited: milliseconds });
+        },
+    }),
+    createTool({
+        name: "browser_close",
+        description: "Close the browser and clean up resources.",
+        schema: {},
+        handler: async () => {
+            await closeBrowser();
+            return success({});
+        },
+    }),
+    createTool({
+        name: "browser_save_screenshot",
+        description: "Take a screenshot and save it to a file.",
+        schema: {
+            filepath: z.string().describe("Path where to save the screenshot"),
+            fullPage: z.boolean().default(false).describe("Capture full scrollable page"),
+        },
+        handler: async ({ filepath, fullPage }) => {
+            const buffer = await (await getPage()).screenshot({ fullPage });
+            await writeFile(filepath, buffer);
+            return success({ filepath, size: buffer.length });
+        },
+    }),
+    createTool({
+        name: "browser_print_to_pdf",
+        description: "Print the current page to PDF and save to a file.",
+        schema: {
+            filepath: z.string().describe("Path where to save the PDF"),
+            landscape: z.boolean().default(false).describe("Use landscape orientation"),
+            printBackground: z.boolean().default(true).describe("Print background graphics"),
+        },
+        handler: async ({ filepath, landscape, printBackground }) => {
+            const pdf = await (await getPage()).pdf({
+                landscape,
+                printBackground,
+                format: "A4",
+            });
+            await writeFile(filepath, pdf);
+            return success({ filepath, size: pdf.length });
+        },
+    }),
+];
+function toResult(value, isError = false) {
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    return { content: [{ type: "text", text }], ...(isError && { isError }) };
+}
+export function registerTools(server) {
+    for (const tool of tools) {
+        server.registerTool(tool.name, { description: tool.description, inputSchema: tool.schema }, async (args) => {
+            try {
+                return toResult(await tool.handler(args));
+            }
+            catch (err) {
+                return toResult({ error: err instanceof Error ? err.message : String(err) }, true);
+            }
+        });
+    }
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/docker-compose.yml

@@ -0,0 +1,10 @@
+services:
+  cloakbrowser-manager:
+    image: cloakhq/cloakbrowser-manager
+    ports:
+      - "8081:8080"
+    volumes:
+      - cloakprofiles:/data
+
+volumes:
+  cloakprofiles:

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@solvvn/mcp-simple-browser",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "mcp-simple-browser": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Huy Le Tien <huy@macbook.local>",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "cloakbrowser": "^0.3.30",
+    "dotenv": "^17.4.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.3"
+  }
+}

package/src/browser.ts

@@ -0,0 +1,28 @@
+import { launch } from "cloakbrowser";
+
+type Browser = Awaited<ReturnType<typeof launch>>;
+type Page = Awaited<ReturnType<Browser["newPage"]>>;
+
+let browserInstance: Browser | null = null;
+let pageInstance: Page | null = null;
+
+function createBrowser(): Promise<Browser> {
+  return launch({ headless: true, humanize: true });
+}
+
+export async function getPage(): Promise<Page> {
+  if (!browserInstance) {
+    browserInstance = await createBrowser();
+  }
+  if (!pageInstance) {
+    pageInstance = await browserInstance.newPage();
+  }
+  return pageInstance;
+}
+
+export async function closeBrowser(): Promise<void> {
+  await pageInstance?.close().catch(() => {});
+  await browserInstance?.close().catch(() => {});
+  pageInstance = null;
+  browserInstance = null;
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+import * as dotenv from "dotenv";
+dotenv.config();
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools.js";
+
+async function main() {
+  const server = new McpServer({ name: "simple-browser", version: "1.0.0" });
+  registerTools(server);
+  await server.connect(new StdioServerTransport());
+  console.error("SimpleBrowser MCP Server running on stdio");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/tools.ts

@@ -0,0 +1,210 @@
+import { z } from "zod";
+import { writeFile } from "fs/promises";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { closeBrowser, getPage } from "./browser.js";
+
+type ToolHandler<T extends z.ZodRawShape> = (args: z.infer<z.ZodObject<T>>) => Promise<unknown>;
+
+interface ToolDefinition<S extends z.ZodRawShape> {
+  name: string;
+  description: string;
+  schema: S;
+  handler: ToolHandler<S>;
+}
+
+function createTool<S extends z.ZodRawShape>(def: ToolDefinition<S>) {
+  return def as unknown as ToolDefinition<z.ZodRawShape>;
+}
+
+function success<T extends Record<string, unknown>>(extra: T) {
+  return { success: true, ...extra };
+}
+
+const SearchEngines = {
+  google: (q: string) => `https://www.google.com/search?q=${q}`,
+  duckduckgo: (q: string) => `https://duckduckgo.com/?q=${q}`,
+  bing: (q: string) => `https://www.bing.com/search?q=${q}`,
+} as const;
+
+const tools = [
+  createTool({
+    name: "browser_navigate",
+    description: "Navigate to a URL and wait for it to load.",
+    schema: {
+      url: z.string().describe("The URL to navigate to"),
+      waitUntil: z
+        .enum(["load", "domcontentloaded", "networkidle", "commit"])
+        .default("networkidle"),
+    },
+    handler: async ({ url, waitUntil }) => {
+      const page = await getPage();
+      await page.goto(url, { waitUntil });
+      return success({ url: page.url(), title: await page.title() });
+    },
+  }),
+  createTool({
+    name: "browser_screenshot",
+    description: "Take a screenshot of the current page.",
+    schema: {
+      fullPage: z.boolean().default(false).describe("Capture full scrollable page"),
+    },
+    handler: async ({ fullPage }) => {
+      const buffer = await (await getPage()).screenshot({ fullPage });
+      return success({ format: "png", data: buffer.toString("base64") });
+    },
+  }),
+  createTool({
+    name: "browser_click",
+    description: "Click an element by CSS selector.",
+    schema: { selector: z.string().describe("CSS selector") },
+    handler: async ({ selector }) => {
+      await (await getPage()).click(selector);
+      return success({});
+    },
+  }),
+  createTool({
+    name: "browser_type",
+    description: "Type text into an input field.",
+    schema: {
+      selector: z.string(),
+      text: z.string(),
+      delay: z.number().default(50).describe("Delay between keystrokes (ms)"),
+    },
+    handler: async ({ selector, text, delay }) => {
+      await (await getPage()).type(selector, text, { delay });
+      return success({});
+    },
+  }),
+  createTool({
+    name: "browser_get_content",
+    description: "Get the HTML content of the page.",
+    schema: {},
+    handler: async () => ({ html: await (await getPage()).content() }),
+  }),
+  createTool({
+    name: "browser_get_text",
+    description: "Get text content from the page or a specific element.",
+    schema: {
+      selector: z.string().optional().describe("CSS selector (defaults to body)"),
+    },
+    handler: async ({ selector }) => {
+      const el = selector || "body";
+      const text = await (await getPage()).$eval(el, (el: HTMLElement) => el.textContent);
+      return { text: text ?? "" };
+    },
+  }),
+  createTool({
+    name: "browser_evaluate",
+    description: "Execute JavaScript in the page context.",
+    schema: { script: z.string().describe("JavaScript code to execute") },
+    handler: async ({ script }) => ({ result: await (await getPage()).evaluate(script) }),
+  }),
+  createTool({
+    name: "browser_search",
+    description: "Search the web using a search engine.",
+    schema: {
+      query: z.string(),
+      engine: z.enum(["google", "duckduckgo", "bing"]).default("duckduckgo"),
+    },
+    handler: async ({ query, engine }) => {
+      const page = await getPage();
+      const searchUrl = SearchEngines[engine](encodeURIComponent(query));
+      await page.goto(searchUrl, { waitUntil: "networkidle" });
+
+      const results = await page.evaluate(() => {
+        const out: Array<{ title: string; url: string; snippet: string }> = [];
+        const selectors = ["div.g a[href^='http']", "div[data-srg] a[href^='http']", ".result a[href^='http']"];
+
+        for (const sel of selectors) {
+          document.querySelectorAll<HTMLAnchorElement>(sel).forEach((a) => {
+            if (!a.href || /google|bing|duckduckgo/.test(a.href)) return;
+            const titleEl = a.querySelector("h3") || a;
+            out.push({
+              title: titleEl.textContent?.trim() ?? "",
+              url: a.href,
+              snippet: a.textContent?.trim() ?? "",
+            });
+          });
+          if (out.length) break;
+        }
+        return out.slice(0, 10);
+      });
+
+      return success({ engine, query, results });
+    },
+  }),
+  createTool({
+    name: "browser_wait",
+    description: "Wait for a specified time.",
+    schema: { milliseconds: z.number().describe("Time to wait in ms") },
+    handler: async ({ milliseconds }) => {
+      await new Promise((resolve) => setTimeout(resolve, milliseconds));
+      return success({ waited: milliseconds });
+    },
+  }),
+  createTool({
+    name: "browser_close",
+    description: "Close the browser and clean up resources.",
+    schema: {},
+    handler: async () => {
+      await closeBrowser();
+      return success({});
+    },
+  }),
+  createTool({
+    name: "browser_save_screenshot",
+    description: "Take a screenshot and save it to a file.",
+    schema: {
+      filepath: z.string().describe("Path where to save the screenshot"),
+      fullPage: z.boolean().default(false).describe("Capture full scrollable page"),
+    },
+    handler: async ({ filepath, fullPage }) => {
+      const buffer = await (await getPage()).screenshot({ fullPage });
+      await writeFile(filepath, buffer);
+      return success({ filepath, size: buffer.length });
+    },
+  }),
+  createTool({
+    name: "browser_print_to_pdf",
+    description: "Print the current page to PDF and save to a file.",
+    schema: {
+      filepath: z.string().describe("Path where to save the PDF"),
+      landscape: z.boolean().default(false).describe("Use landscape orientation"),
+      printBackground: z.boolean().default(true).describe("Print background graphics"),
+    },
+    handler: async ({ filepath, landscape, printBackground }) => {
+      const pdf = await (await getPage()).pdf({
+        landscape,
+        printBackground,
+        format: "A4",
+      });
+      await writeFile(filepath, pdf);
+      return success({ filepath, size: pdf.length });
+    },
+  }),
+];
+
+function toResult(value: unknown, isError = false): CallToolResult {
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  return { content: [{ type: "text", text }], ...(isError && { isError }) };
+}
+
+export function registerTools(server: McpServer): void {
+  for (const tool of tools) {
+    server.registerTool(
+      tool.name,
+      { description: tool.description, inputSchema: tool.schema },
+      async (args) => {
+        try {
+          return toResult(await tool.handler(args as never));
+        } catch (err) {
+          return toResult(
+            { error: err instanceof Error ? err.message : String(err) },
+            true,
+          );
+        }
+      },
+    );
+  }
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}