junis 0.3.1 → 0.3.3

package/dist/server/mcp.js

@@ -104,11 +104,26 @@ var FilesystemTools = class {
   register(server) {
     server.tool(
       "execute_command",
-      "Execute terminal command",
+      [
+        "Execute a shell command on the user's local device.",
+        "",
+        "ROUTING:",
+        "- Use for system commands, package managers (npm, pip, brew), git, build tools, and scripting.",
+        "- For reading files prefer read_file, for editing prefer edit_block, for searching prefer search_code.",
+        "",
+        "BEHAVIOR:",
+        "- Safe, routine commands (ls, pwd, git status, echo): execute immediately without explanation.",
+        "- Destructive or irreversible commands (rm -rf, sudo, shutdown, mkfs): explain what will happen and get user confirmation first.",
+        "- If a command fails, analyze the error and suggest an alternative. Do not retry the identical command more than twice.",
+        "",
+        "SAFETY:",
+        "- Commands run with the user's full permissions. Never execute commands that could damage the system, expose credentials, or modify security settings without explicit user request.",
+        "- Avoid piping untrusted input into shells. Use absolute paths when possible. Quote paths containing spaces."
+      ].join("\n"),
       {
-        command: import_zod.z.string().describe("Shell command to execute"),
-        timeout_ms: import_zod.z.number().optional().default(3e4).describe("Timeout (ms)"),
-        background: import_zod.z.boolean().optional().default(false).describe("Run in background")
+        command: import_zod.z.string().describe("The shell command to execute. Use absolute paths when possible. Quote paths containing spaces."),
+        timeout_ms: import_zod.z.number().optional().default(3e4).describe("Maximum execution time in milliseconds (default: 30000). Increase for long-running builds or downloads."),
+        background: import_zod.z.boolean().optional().default(false).describe("Run in background without waiting for completion. Use for servers or long-running processes.")
       },
       async ({ command, timeout_ms, background }) => {
         checkPermission("execute_command");
@@ -140,10 +155,15 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "read_file",
-      "Read file",
+      [
+        "Read the contents of a file from the local filesystem.",
+        "",
+        "Returns file content as text (utf-8) or base64 for binary files. Supports any file type.",
+        "For searching within files, prefer search_code instead. For listing directory contents, use list_directory."
+      ].join("\n"),
       {
-        path: import_zod.z.string().describe("File path"),
-        encoding: import_zod.z.enum(["utf-8", "base64"]).optional().default("utf-8").describe("Encoding")
+        path: import_zod.z.string().describe("Absolute or relative file path to read"),
+        encoding: import_zod.z.enum(["utf-8", "base64"]).optional().default("utf-8").describe("'utf-8' for text files (default), 'base64' for binary files (images, PDFs, archives)")
       },
       async ({ path: filePath, encoding }) => {
         try {
@@ -160,10 +180,15 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "write_file",
-      "Write/create file",
+      [
+        "Create a new file or completely overwrite an existing file. Parent directories are created automatically.",
+        "",
+        "WARNING: This replaces the entire file content. For partial modifications, use edit_block instead.",
+        "Prefer edit_block over write_file for existing files \u2014 it's safer and preserves unmodified content."
+      ].join("\n"),
       {
-        path: import_zod.z.string().describe("File path"),
-        content: import_zod.z.string().describe("File content")
+        path: import_zod.z.string().describe("File path to create or overwrite. Parent directories are auto-created."),
+        content: import_zod.z.string().describe("Complete file content. This replaces the entire file.")
       },
       async ({ path: filePath, content }) => {
         checkPermission("write_file");
@@ -174,9 +199,12 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "list_directory",
-      "List directory contents",
+      [
+        "List files and subdirectories in the specified path. Returns entries with type indicators (\u{1F4C1} directory, \u{1F4C4} file).",
+        "Use this to explore project structure before reading or modifying files."
+      ].join("\n"),
       {
-        path: import_zod.z.string().describe("Directory path")
+        path: import_zod.z.string().describe("Directory path to list")
       },
       async ({ path: dirPath }) => {
         try {
@@ -194,11 +222,16 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "search_code",
-      "Search code/text",
+      [
+        "Search for text patterns across files using regex. Uses ripgrep for speed with glob fallback.",
+        "",
+        "Use this to find code definitions, function references, configuration values, or any text pattern.",
+        "Returns matching lines with file paths and line numbers for precise navigation."
+      ].join("\n"),
       {
-        pattern: import_zod.z.string().describe("Search pattern (regex supported)"),
-        directory: import_zod.z.string().optional().default(".").describe("Search directory"),
-        file_pattern: import_zod.z.string().optional().default("**/*").describe("File pattern")
+        pattern: import_zod.z.string().describe("Search pattern with full regex support (e.g. 'function\\s+\\w+', 'import.*from', 'TODO')"),
+        directory: import_zod.z.string().optional().default(".").describe("Root directory to search from (default: current working directory)"),
+        file_pattern: import_zod.z.string().optional().default("**/*").describe("Glob pattern to filter files (e.g. '**/*.ts', '*.py', 'src/**/*.js')")
       },
       async ({ pattern, directory, file_pattern }) => {
         try {
@@ -236,7 +269,7 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "list_processes",
-      "List running processes",
+      "List the top 30 running processes sorted by CPU usage. Use this to identify resource-heavy processes, find PIDs for kill_process, or diagnose performance issues.",
       {},
       async () => {
         const cmd = process.platform === "win32" ? "tasklist" : process.platform === "darwin" ? "ps aux | sort -rk 3 | head -30" : "ps aux --sort=-%cpu | head -30";
@@ -246,10 +279,14 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "kill_process",
-      "Kill process (SIGTERM then 3s wait, auto SIGKILL if still alive)",
+      [
+        "Terminate a process by PID. Default: sends SIGTERM (graceful shutdown), waits 3 seconds, then auto-applies SIGKILL if still alive.",
+        "",
+        "SAFETY: Only kill processes the user explicitly identifies. Never kill system-critical processes (init, systemd, loginwindow, WindowServer) without explicit instruction."
+      ].join("\n"),
       {
-        pid: import_zod.z.number().describe("PID of the process to kill"),
-        signal: import_zod.z.enum(["SIGTERM", "SIGKILL"]).optional().default("SIGTERM").describe("Initial signal (default: SIGTERM). SIGKILL for immediate force kill)")
+        pid: import_zod.z.number().describe("PID of the process to terminate (use list_processes to find PIDs)"),
+        signal: import_zod.z.enum(["SIGTERM", "SIGKILL"]).optional().default("SIGTERM").describe("SIGTERM (default): graceful shutdown with 3s auto-SIGKILL fallback. SIGKILL: immediate force kill.")
       },
       async ({ pid, signal }) => {
         const isWindows = process.platform === "win32";
@@ -295,12 +332,20 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "edit_block",
-      "Replace a specific text block in a file with new text (diff-based partial edit)",
+      [
+        "Replace a specific text block in a file with new text (diff-based partial edit).",
+        "",
+        "WORKFLOW: Always use read_file first to see current content, then use edit_block with the exact text to replace.",
+        "The old_string must match character-for-character including whitespace, indentation, and line breaks.",
+        "If multiple matches exist, include more surrounding context to make it unique, or set replace_all=true.",
+        "",
+        "Prefer this over write_file for modifying existing files \u2014 it only changes what you specify and preserves the rest."
+      ].join("\n"),
       {
-        path: import_zod.z.string().describe("File path"),
-        old_string: import_zod.z.string().describe("Existing text to replace (must match exactly)"),
-        new_string: import_zod.z.string().describe("New text"),
-        replace_all: import_zod.z.boolean().optional().default(false).describe("If true, replace all matches; if false, replace only the first")
+        path: import_zod.z.string().describe("Path to the file to edit. The file must already exist."),
+        old_string: import_zod.z.string().describe("The exact text to find and replace. Must match character-for-character including whitespace and newlines. Include enough context for uniqueness."),
+        new_string: import_zod.z.string().describe("The replacement text. Use empty string to delete the matched text."),
+        replace_all: import_zod.z.boolean().optional().default(false).describe("If true, replace ALL matches. If false (default), require exactly one match (errors on ambiguous multiple matches).")
       },
       async ({ path: filePath, old_string, new_string, replace_all }) => {
         const content = await import_promises.default.readFile(filePath, "utf-8");
@@ -335,11 +380,16 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "cron_create",
-      "Create a recurring cron job. schedule uses cron syntax (e.g. '0 9 * * 1-5' = weekdays 9am).",
+      [
+        "Create a recurring scheduled task (cron job) using standard cron syntax.",
+        "",
+        "Common schedules: '*/5 * * * *' (every 5 min), '0 9 * * 1-5' (weekdays 9am), '0 0 * * *' (daily midnight), '0 */2 * * *' (every 2 hours).",
+        "Duplicate commands are automatically detected and rejected. Use cron_list to see existing jobs."
+      ].join("\n"),
       {
-        schedule: import_zod.z.string().describe("Cron schedule expression (e.g. '*/5 * * * *' for every 5 min, '0 9 * * 1-5' for weekdays 9am)"),
-        command: import_zod.z.string().describe("Shell command to execute"),
-        label: import_zod.z.string().optional().describe("Optional label/comment for identification")
+        schedule: import_zod.z.string().describe("Cron schedule expression (5 fields: minute hour day month weekday). Examples: '*/5 * * * *' (every 5 min), '0 9 * * 1-5' (weekdays 9am)"),
+        command: import_zod.z.string().describe("Shell command to execute on schedule"),
+        label: import_zod.z.string().optional().describe("Human-readable label for identification (e.g. 'daily-backup', 'log-cleanup')")
       },
       async ({ schedule, command, label }) => {
         try {
@@ -381,7 +431,7 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "cron_list",
-      "List all cron jobs in the current user's crontab",
+      "List all scheduled cron jobs with their IDs, labels, schedules, and commands. Use the returned ID numbers with cron_delete to remove specific jobs.",
       {},
       async () => {
         try {
@@ -428,10 +478,10 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "cron_delete",
-      "Delete a cron job by its ID (from cron_list) or by matching command string",
+      "Delete a scheduled cron job by its ID (from cron_list output) or by matching command string. Associated comment labels are automatically cleaned up.",
       {
-        id: import_zod.z.number().optional().describe("Cron job ID from cron_list output"),
-        command: import_zod.z.string().optional().describe("Delete job matching this command string")
+        id: import_zod.z.number().optional().describe("Cron job ID from cron_list output (e.g. 1, 2, 3)"),
+        command: import_zod.z.string().optional().describe("Delete all jobs matching this command string")
       },
       async ({ id, command }) => {
         if (!id && !command) {
@@ -544,13 +594,22 @@ var BrowserTools = class {
     };
     server.tool(
       "browser_start",
-      "Start browser (BrowserClaw). mode='managed'(default) launches new Chromium; mode='remote-cdp' connects to existing Chrome via CDP URL.",
+      [
+        "Launch or connect to a web browser for automation.",
+        "",
+        "MODES:",
+        "- 'managed' (default): Launches a new Chromium instance. Use 'headless' for background operation, 'profile' for persistent sessions (cookies, logins preserved).",
+        "- 'remote-cdp': Connects to an already-running Chrome via CDP URL (e.g. from chrome://inspect). Use this to automate an existing browser session.",
+        "",
+        "WORKFLOW: browser_start \u2192 browser_navigate \u2192 browser_snapshot \u2192 interact (click/type/fill) \u2192 browser_stop.",
+        "Always call browser_stop when done to release system resources."
+      ].join("\n"),
       {
-        mode: import_zod2.z.enum(["managed", "remote-cdp"]).optional().default("managed").describe("'managed' = launch new browser, 'remote-cdp' = connect to existing Chrome"),
-        headless: import_zod2.z.boolean().optional().default(false).describe("Run headless (managed mode only)"),
-        cdpUrl: import_zod2.z.string().optional().describe("CDP URL for remote-cdp mode (e.g. http://localhost:9222)"),
-        profile: import_zod2.z.string().optional().describe("Profile name (managed mode only)"),
-        allowInternal: import_zod2.z.boolean().optional().default(false).describe("Allow localhost/internal URLs")
+        mode: import_zod2.z.enum(["managed", "remote-cdp"]).optional().default("managed").describe("'managed' = launch new browser, 'remote-cdp' = connect to existing Chrome via CDP"),
+        headless: import_zod2.z.boolean().optional().default(false).describe("Run without visible window (managed mode only). Use for background tasks."),
+        cdpUrl: import_zod2.z.string().optional().describe("Chrome DevTools Protocol URL for remote-cdp mode (e.g. http://localhost:9222)"),
+        profile: import_zod2.z.string().optional().describe("Browser profile name for persistent sessions \u2014 preserves cookies, logins, and history across restarts (managed mode only)"),
+        allowInternal: import_zod2.z.boolean().optional().default(false).describe("Allow navigation to localhost and internal network URLs")
       },
       ({ mode, headless, cdpUrl, profile, allowInternal }) => this.withLock(async () => {
         if (this.browser) {
@@ -571,7 +630,7 @@ var BrowserTools = class {
     );
     server.tool(
       "browser_stop",
-      "Stop browser and release resources",
+      "Stop the browser and release all associated resources (memory, connections, processes). Always call this when browser automation is complete.",
       {},
       () => this.withLock(async () => {
         await this.cleanup();
@@ -580,9 +639,9 @@ var BrowserTools = class {
     );
     server.tool(
       "browser_navigate",
-      "Navigate to URL. Opens new tab if browser started but no page yet.",
+      "Navigate the browser to a URL. Automatically opens a new tab if the browser is started but no page exists yet. Waits for the page to load before returning.",
       {
-        url: import_zod2.z.string().describe("URL to navigate to")
+        url: import_zod2.z.string().describe("Full URL to navigate to (include https://)")
       },
       ({ url }) => this.withLock(async () => {
         if (!this.browser) throw new Error("Browser not started. Call browser_start first.");
@@ -597,10 +656,17 @@ var BrowserTools = class {
     );
     server.tool(
       "browser_snapshot",
-      "Get Accessibility Tree snapshot with ref numbers. Use refs to interact with elements (e.g. browser_click with ref='e1').",
+      [
+        "Capture the page's Accessibility Tree with numbered ref IDs for each element. This is the primary way to 'see' and understand page content.",
+        "",
+        "WORKFLOW: Call browser_snapshot \u2192 find the target element's ref (e.g. 'e1', 'e5') \u2192 use that ref in browser_click, browser_type, or other interaction tools.",
+        "Refs change after page updates \u2014 always call browser_snapshot again after navigation or clicks that modify the page.",
+        "",
+        "Prefer this over browser_screenshot for understanding page structure \u2014 it's faster, structured, and machine-readable."
+      ].join("\n"),
       {
-        interactive: import_zod2.z.boolean().optional().default(true).describe("Only include interactive elements"),
-        compact: import_zod2.z.boolean().optional().default(true).describe("Remove empty containers")
+        interactive: import_zod2.z.boolean().optional().default(true).describe("true (default): only show clickable/typeable elements. false: show all elements including static text."),
+        compact: import_zod2.z.boolean().optional().default(true).describe("true (default): hide empty containers for cleaner output")
       },
       ({ interactive, compact }) => this.withLock(async () => {
         const result = await requirePage().snapshot({ interactive, compact });
@@ -620,11 +686,11 @@ ${refList}`
     );
     server.tool(
       "browser_click",
-      "Click element by ref number from browser_snapshot",
+      "Click an element by its ref number from browser_snapshot. Always call browser_snapshot first to get current refs \u2014 they change after page updates.",
       {
-        ref: import_zod2.z.string().describe("Ref number from snapshot (e.g. 'e1')"),
-        doubleClick: import_zod2.z.boolean().optional().default(false),
-        button: import_zod2.z.enum(["left", "right", "middle"]).optional().default("left")
+        ref: import_zod2.z.string().describe("Element ref from browser_snapshot (e.g. 'e1', 'e15'). Call browser_snapshot first to get current refs."),
+        doubleClick: import_zod2.z.boolean().optional().default(false).describe("Double-click instead of single click"),
+        button: import_zod2.z.enum(["left", "right", "middle"]).optional().default("left").describe("Mouse button to use")
       },
       ({ ref, doubleClick, button }) => this.withLock(async () => {
         await requirePage().click(ref, { doubleClick, button });
@@ -633,12 +699,12 @@ ${refList}`
     );
     server.tool(
       "browser_type",
-      "Type text into element by ref number",
+      "Type text into an input element by ref number. Use 'submit=true' to press Enter after typing (e.g. for search forms). Use 'slowly=true' for sites requiring keystroke-by-keystroke input.",
       {
-        ref: import_zod2.z.string().describe("Ref number from snapshot"),
-        text: import_zod2.z.string().describe("Text to type"),
-        submit: import_zod2.z.boolean().optional().default(false).describe("Press Enter after typing"),
-        slowly: import_zod2.z.boolean().optional().default(false).describe("Type slowly (75ms per char)")
+        ref: import_zod2.z.string().describe("Element ref from browser_snapshot (e.g. 'e3')"),
+        text: import_zod2.z.string().describe("Text to type into the element"),
+        submit: import_zod2.z.boolean().optional().default(false).describe("Press Enter after typing (useful for search boxes and forms)"),
+        slowly: import_zod2.z.boolean().optional().default(false).describe("Type slowly (75ms per char) for sites that process each keystroke")
       },
       ({ ref, text, submit, slowly }) => this.withLock(async () => {
         await requirePage().type(ref, text, { submit, slowly });
@@ -647,13 +713,13 @@ ${refList}`
     );
     server.tool(
       "browser_fill",
-      "Fill multiple form fields at once",
+      "Fill multiple form fields at once \u2014 more efficient than calling browser_type repeatedly. Each field needs a ref from browser_snapshot.",
       {
         fields: import_zod2.z.array(import_zod2.z.object({
           ref: import_zod2.z.string(),
           type: import_zod2.z.enum(["text", "checkbox", "radio"]),
           value: import_zod2.z.union([import_zod2.z.string(), import_zod2.z.boolean()])
-        })).describe("Array of {ref, type, value}")
+        })).describe("Array of {ref, type, value}. type='text': value is string. type='checkbox'/'radio': value is boolean.")
       },
       ({ fields }) => this.withLock(async () => {
         await requirePage().fill(fields);
@@ -662,9 +728,9 @@ ${refList}`
     );
     server.tool(
       "browser_select",
-      "Select dropdown option(s) by ref",
+      "Select one or more options from a dropdown/select element. Values should match the option value attributes, not display text.",
       {
-        ref: import_zod2.z.string().describe("Ref number from snapshot"),
+        ref: import_zod2.z.string().describe("Ref of the <select> element from browser_snapshot"),
         values: import_zod2.z.array(import_zod2.z.string()).describe("Option value(s) to select")
       },
       ({ ref, values }) => this.withLock(async () => {
@@ -674,9 +740,9 @@ ${refList}`
     );
     server.tool(
       "browser_press",
-      "Press keyboard key or combination (e.g. 'Enter', 'Control+a', 'Escape')",
+      "Press a keyboard key or key combination. Use for shortcuts (e.g. 'Control+a', 'Escape'), form submission ('Enter'), or navigation ('Tab'). Does not require a specific element ref.",
       {
-        key: import_zod2.z.string().describe("Key combination (e.g. 'Enter', 'Control+a', 'Escape', 'Tab')")
+        key: import_zod2.z.string().describe("Key or combination: 'Enter', 'Escape', 'Tab', 'Control+a', 'Meta+c', 'ArrowDown', 'Backspace'")
       },
       ({ key }) => this.withLock(async () => {
         await requirePage().press(key);
@@ -685,9 +751,9 @@ ${refList}`
     );
     server.tool(
       "browser_hover",
-      "Hover mouse over element by ref",
+      "Move the mouse cursor over an element by ref. Use to trigger hover menus, tooltips, or dropdown previews before clicking.",
       {
-        ref: import_zod2.z.string().describe("Ref number from snapshot")
+        ref: import_zod2.z.string().describe("Element ref from browser_snapshot")
       },
       ({ ref }) => this.withLock(async () => {
         await requirePage().hover(ref);
@@ -696,10 +762,10 @@ ${refList}`
     );
     server.tool(
       "browser_drag",
-      "Drag element from startRef to endRef",
+      "Drag an element from startRef to endRef. Both refs must come from a recent browser_snapshot. Use for drag-and-drop interfaces, sliders, or reorderable lists.",
       {
-        startRef: import_zod2.z.string().describe("Source element ref"),
-        endRef: import_zod2.z.string().describe("Target element ref")
+        startRef: import_zod2.z.string().describe("Source element ref to drag from"),
+        endRef: import_zod2.z.string().describe("Target element ref to drag to")
       },
       ({ startRef, endRef }) => this.withLock(async () => {
         await requirePage().drag(startRef, endRef);
@@ -708,10 +774,10 @@ ${refList}`
     );
     server.tool(
       "browser_upload",
-      "Upload file(s) to file input element by ref",
+      "Upload local files to a file input element (<input type='file'>). The ref must point to a file input from browser_snapshot.",
       {
-        ref: import_zod2.z.string().describe("Ref number of file input element"),
-        paths: import_zod2.z.array(import_zod2.z.string()).describe("Absolute file path(s) to upload")
+        ref: import_zod2.z.string().describe("Ref of the file input element from browser_snapshot"),
+        paths: import_zod2.z.array(import_zod2.z.string()).describe("Absolute file path(s) on the local device to upload")
       },
       ({ ref, paths }) => this.withLock(async () => {
         await requirePage().uploadFile(ref, paths);
@@ -720,11 +786,16 @@ ${refList}`
     );
     server.tool(
       "browser_screenshot",
-      "Take screenshot of current page",
+      [
+        "Capture a screenshot of the current page. Returns base64 image data (viewable by AI) or saves to a file.",
+        "",
+        "Prefer browser_snapshot (Accessibility Tree) for understanding page structure \u2014 it's faster and machine-readable.",
+        "Use browser_screenshot only when visual layout matters (charts, images, styling, visual verification)."
+      ].join("\n"),
       {
-        path: import_zod2.z.string().optional().describe("Save path (if omitted, returns base64)"),
-        fullPage: import_zod2.z.boolean().optional().default(false),
-        ref: import_zod2.z.string().optional().describe("Capture specific element by ref")
+        path: import_zod2.z.string().optional().describe("Save path for the screenshot. If omitted, returns base64 image data directly."),
+        fullPage: import_zod2.z.boolean().optional().default(false).describe("Capture the full scrollable page, not just the visible viewport"),
+        ref: import_zod2.z.string().optional().describe("Capture only a specific element by its ref from browser_snapshot")
       },
       ({ path: path2, fullPage, ref }) => this.withLock(async () => {
         const buffer = await requirePage().screenshot({ fullPage, ref });
@@ -743,9 +814,9 @@ ${refList}`
     );
     server.tool(
       "browser_pdf",
-      "Save current page as PDF",
+      "Save the current page as a PDF file. Renders the full page including below-the-fold content. Useful for archiving, sharing, or offline reading.",
       {
-        path: import_zod2.z.string().describe("Save path (.pdf)")
+        path: import_zod2.z.string().describe("Output file path (.pdf)")
       },
       ({ path: path2 }) => this.withLock(async () => {
         const buffer = await requirePage().pdf();
@@ -755,9 +826,14 @@ ${refList}`
     );
     server.tool(
       "browser_evaluate",
-      "Execute JavaScript in page context",
+      [
+        "Execute JavaScript code directly in the browser page context and return the result.",
+        "",
+        "Use for: extracting data not available in the Accessibility Tree, DOM manipulation, interacting with page APIs, or debugging.",
+        "Wrap complex logic in an IIFE: (function(){ ... })()"
+      ].join("\n"),
       {
-        code: import_zod2.z.string().describe("JavaScript code to execute (wrap in function if needed)")
+        code: import_zod2.z.string().describe("JavaScript code to execute in the page context. Return values are automatically serialized.")
       },
       ({ code }) => this.withLock(async () => {
         try {
@@ -778,13 +854,17 @@ ${refList}`
     );
     server.tool(
       "browser_wait",
-      "Wait for a condition: text appearance/disappearance, URL pattern, or fixed time",
+      [
+        "Wait for a specific condition before proceeding. Use between actions when the page needs time to update.",
+        "",
+        "OPTIONS (use one): 'text' (wait for text to appear), 'textGone' (wait for text to disappear), 'url' (URL matches glob), 'loadState' (page load state), 'timeMs' (fixed delay as last resort)."
+      ].join("\n"),
       {
-        text: import_zod2.z.string().optional().describe("Wait until this text appears"),
-        textGone: import_zod2.z.string().optional().describe("Wait until this text disappears"),
-        url: import_zod2.z.string().optional().describe("Wait until URL matches (glob pattern, e.g. '**/dashboard')"),
-        loadState: import_zod2.z.enum(["load", "domcontentloaded", "networkidle"]).optional().describe("Wait for load state"),
-        timeMs: import_zod2.z.number().optional().describe("Wait fixed milliseconds")
+        text: import_zod2.z.string().optional().describe("Wait until this text appears on the page"),
+        textGone: import_zod2.z.string().optional().describe("Wait until this text disappears from the page"),
+        url: import_zod2.z.string().optional().describe("Wait until URL matches this glob pattern (e.g. '**/dashboard', '**/success')"),
+        loadState: import_zod2.z.enum(["load", "domcontentloaded", "networkidle"]).optional().describe("Wait for page load state: 'load' (full), 'domcontentloaded' (DOM ready), 'networkidle' (no pending requests)"),
+        timeMs: import_zod2.z.number().optional().describe("Fixed wait in milliseconds \u2014 use as last resort when other conditions don't apply")
       },
       ({ text, textGone, url, loadState, timeMs }) => this.withLock(async () => {
         const condition = {};
@@ -799,9 +879,9 @@ ${refList}`
     );
     server.tool(
       "browser_cookies",
-      "Get, set, or clear cookies",
+      "Manage browser cookies: get all cookies, set a specific cookie, or clear all cookies. Useful for authentication state, session management, or testing.",
       {
-        action: import_zod2.z.enum(["get", "set", "clear"]).describe("Action to perform"),
+        action: import_zod2.z.enum(["get", "set", "clear"]).describe("'get': retrieve all cookies, 'set': add/update a cookie, 'clear': remove all cookies"),
         cookie: import_zod2.z.object({
           name: import_zod2.z.string(),
           value: import_zod2.z.string(),
@@ -809,7 +889,7 @@ ${refList}`
           path: import_zod2.z.string().optional(),
           httpOnly: import_zod2.z.boolean().optional(),
           secure: import_zod2.z.boolean().optional()
-        }).optional().describe("Cookie data (required for set action)")
+        }).optional().describe("Cookie data (required for 'set' action)")
       },
       ({ action, cookie }) => this.withLock(async () => {
         const page = requirePage();
@@ -828,12 +908,12 @@ ${refList}`
     );
     server.tool(
       "browser_storage",
-      "Read/write/clear localStorage or sessionStorage",
+      "Read, write, or clear browser localStorage/sessionStorage. Useful for managing client-side state, authentication tokens, or application preferences.",
       {
-        action: import_zod2.z.enum(["get", "set", "clear"]).describe("Action to perform"),
-        kind: import_zod2.z.enum(["local", "session"]).optional().default("local").describe("Storage type"),
-        key: import_zod2.z.string().optional().describe("Storage key (get/set)"),
-        value: import_zod2.z.string().optional().describe("Value to set (set action)")
+        action: import_zod2.z.enum(["get", "set", "clear"]).describe("'get': read value(s), 'set': write a key-value pair, 'clear': remove all entries"),
+        kind: import_zod2.z.enum(["local", "session"]).optional().default("local").describe("'local' (persistent) or 'session' (cleared on tab close)"),
+        key: import_zod2.z.string().optional().describe("Storage key to get or set. Omit key with 'get' to retrieve all entries."),
+        value: import_zod2.z.string().optional().describe("Value to store (required for 'set' action)")
       },
       ({ action, kind, key, value }) => this.withLock(async () => {
         const page = requirePage();
@@ -853,13 +933,13 @@ ${refList}`
     server.tool(
       "browser_dialog",
       [
-        "Handle JavaScript dialogs (alert/confirm/prompt).",
-        "Two-step usage:",
-        "  1. action='arm'  \u2014 register a one-shot handler (returns immediately, does NOT block).",
+        "Handle JavaScript dialogs (alert, confirm, prompt). Two-step pattern:",
+        "  1. action='arm' \u2014 register a one-shot handler (returns immediately, does NOT block).",
         "  2. Trigger the dialog (e.g. browser_click on the button that calls confirm()).",
         "  3. action='wait' \u2014 await the handler to confirm the dialog was handled.",
+        "",
         "The 'accept' and 'promptText' params are only used with action='arm'."
-      ].join(" "),
+      ].join("\n"),
       {
         action: import_zod2.z.enum(["arm", "wait"]).describe(
           "'arm' = register handler and return immediately; 'wait' = await the previously armed handler"
@@ -871,7 +951,7 @@ ${refList}`
           "Text to enter if the dialog is a prompt. Only used with action='arm'."
         ),
         timeoutMs: import_zod2.z.number().optional().describe(
-          "Timeout in ms for 'wait' action. Default: 30000."
+          "Timeout in ms for 'wait' action (default: 30000). Increase for slow-loading dialogs."
         )
       },
       ({ action, accept, promptText, timeoutMs }) => this.withLock(async () => {
@@ -922,8 +1002,8 @@ var NotebookTools = class {
   register(server) {
     server.tool(
       "notebook_read",
-      "Read .ipynb notebook",
-      { path: import_zod3.z.string().describe("Notebook file path") },
+      "Read a Jupyter notebook (.ipynb) and return all cells with their types (code/markdown), source content, and output counts. Use this to understand notebook structure before making edits.",
+      { path: import_zod3.z.string().describe("Path to the .ipynb notebook file") },
       async ({ path: filePath }) => {
         const nb = await readNotebook(filePath);
         const cells = nb.cells.map((cell, i) => ({
@@ -939,11 +1019,11 @@ var NotebookTools = class {
     );
     server.tool(
       "notebook_edit_cell",
-      "Edit a specific notebook cell",
+      "Replace the source code of a specific cell in a Jupyter notebook. Use notebook_read first to identify the correct cell index (0-based). Existing outputs for the cell are preserved \u2014 use notebook_execute to re-run.",
       {
-        path: import_zod3.z.string(),
-        cell_index: import_zod3.z.number().describe("Cell index (0-based)"),
-        source: import_zod3.z.string().describe("New source code")
+        path: import_zod3.z.string().describe("Path to the .ipynb notebook file"),
+        cell_index: import_zod3.z.number().describe("Cell index to edit (0-based). Use notebook_read to find the right index."),
+        source: import_zod3.z.string().describe("New source code/content for the cell (replaces entire cell content)")
       },
       async ({ path: filePath, cell_index, source }) => {
         const nb = await readNotebook(filePath);
@@ -959,10 +1039,15 @@ var NotebookTools = class {
     );
     server.tool(
       "notebook_execute",
-      "Execute notebook (nbconvert --execute)",
+      [
+        "Execute all cells in a Jupyter notebook using nbconvert. Results are saved in-place \u2014 the notebook file is updated with execution outputs.",
+        "",
+        "Requires Jupyter to be installed (pip install jupyter). The timeout applies per cell, not for the entire notebook.",
+        "If execution fails on a cell, the error is captured in the cell output and subsequent cells may not execute."
+      ].join("\n"),
       {
-        path: import_zod3.z.string().describe("Notebook file path"),
-        timeout: import_zod3.z.number().optional().default(300).describe("Timeout per cell (seconds)")
+        path: import_zod3.z.string().describe("Path to the .ipynb notebook file to execute"),
+        timeout: import_zod3.z.number().optional().default(300).describe("Maximum execution time per cell in seconds (default: 300). Increase for cells with heavy computation.")
       },
       async ({ path: filePath, timeout }) => {
         const nbconvertArgs = `nbconvert --to notebook --execute --inplace "${filePath}" --ExecutePreprocessor.timeout=${timeout}`;
@@ -991,12 +1076,12 @@ var NotebookTools = class {
     );
     server.tool(
       "notebook_add_cell",
-      "Add a new cell to notebook",
+      "Insert a new cell into a Jupyter notebook. If position is omitted, the cell is appended at the end. Use cell_type='code' for executable Python cells, 'markdown' for documentation/text cells.",
       {
-        path: import_zod3.z.string().describe(".ipynb file path"),
-        cell_type: import_zod3.z.enum(["code", "markdown"]).describe("Cell type"),
-        source: import_zod3.z.string().describe("Cell source content"),
-        position: import_zod3.z.number().optional().describe("Insert position (0-based). Appends to end if omitted")
+        path: import_zod3.z.string().describe("Path to the .ipynb notebook file"),
+        cell_type: import_zod3.z.enum(["code", "markdown"]).describe("'code' for executable cells, 'markdown' for text/documentation cells"),
+        source: import_zod3.z.string().describe("Cell source content (Python code or Markdown text)"),
+        position: import_zod3.z.number().optional().describe("Insert position (0-based index). Omit to append at the end. If position exceeds cell count, appends at end with a warning.")
       },
       async ({ path: filePath, cell_type: cellType, source, position }) => {
         const nb = await readNotebook(filePath);
@@ -1027,10 +1112,10 @@ var NotebookTools = class {
     );
     server.tool(
       "notebook_delete_cell",
-      "Delete a specific notebook cell",
+      "Delete a cell from a Jupyter notebook by its 0-based index. Use notebook_read first to verify the cell content before deletion. This action cannot be undone.",
       {
-        path: import_zod3.z.string().describe(".ipynb file path"),
-        cell_index: import_zod3.z.number().describe("Cell index to delete (0-based)")
+        path: import_zod3.z.string().describe("Path to the .ipynb notebook file"),
+        cell_index: import_zod3.z.number().describe("Cell index to delete (0-based). Use notebook_read first to verify content.")
       },
       async ({ path: filePath, cell_index }) => {
         const nb = await readNotebook(filePath);
@@ -1061,9 +1146,14 @@ var DeviceTools = class {
   register(server) {
     server.tool(
       "camera_capture",
-      "Camera photo capture",
+      [
+        "Capture a photo from the device's camera and return it as base64 image data.",
+        "",
+        "Platform-specific: macOS (imagesnap), Windows (ffmpeg/dshow), Linux (fswebcam).",
+        "Requires a connected camera with OS permissions granted. If output_path is provided, the file is also saved to disk."
+      ].join("\n"),
       {
-        output_path: import_zod4.z.string().optional()
+        output_path: import_zod4.z.string().optional().describe("File path to save the captured photo. If omitted, returns image data only (temp file auto-cleaned).")
       },
       async ({ output_path }) => {
         const p = platform();
@@ -1099,10 +1189,10 @@ Please check if a camera is connected.` }],
     );
     server.tool(
       "notification_send",
-      "Send OS notification",
+      "Send a native OS notification (banner/toast) to the user's desktop. Use for task completion alerts, reminders, or important status updates. The notification appears even when the terminal is not focused.",
       {
-        title: import_zod4.z.string().describe("Notification title"),
-        message: import_zod4.z.string().describe("Notification body")
+        title: import_zod4.z.string().describe("Notification title (displayed prominently)"),
+        message: import_zod4.z.string().describe("Notification body text")
       },
       async ({ title, message }) => {
         try {
@@ -1126,7 +1216,7 @@ Please check if a camera is connected.` }],
     );
     server.tool(
       "clipboard_read",
-      "Read clipboard",
+      "Read the current contents of the system clipboard (text). Use to access content the user has copied. Platform-specific: macOS (pbpaste), Windows (PowerShell), Linux (xclip).",
       {},
       async () => {
         const p = platform();
@@ -1137,8 +1227,10 @@ Please check if a camera is connected.` }],
     );
     server.tool(
       "clipboard_write",
-      "Write to clipboard",
-      { text: import_zod4.z.string() },
+      "Write text to the system clipboard, replacing its current contents. Use to prepare content for the user to paste elsewhere.",
+      {
+        text: import_zod4.z.string().describe("Text to copy to the clipboard")
+      },
       async ({ text }) => {
         const p = platform();
         const cmd = {
@@ -1152,10 +1244,15 @@ Please check if a camera is connected.` }],
     );
     server.tool(
       "screen_record",
-      "Start/stop screen recording (macOS: screencapture -v, others: ffmpeg)",
+      [
+        "Start or stop screen recording. Captures the full screen as MP4 video.",
+        "",
+        "Use action='start' to begin, action='stop' to end and save. Only one recording can be active at a time.",
+        "Platform-specific: macOS (screencapture -v), Windows/Linux (ffmpeg)."
+      ].join("\n"),
       {
-        action: import_zod4.z.enum(["start", "stop"]).describe("start: begin recording, stop: end recording"),
-        output_path: import_zod4.z.string().optional().describe("Output path (used on start, default: /tmp/junis_record_<timestamp>.mp4)")
+        action: import_zod4.z.enum(["start", "stop"]).describe("'start': begin recording, 'stop': end recording and save the file"),
+        output_path: import_zod4.z.string().optional().describe("Output file path (used with 'start'). Default: /tmp/junis_record_<timestamp>.mp4")
       },
       async ({ action, output_path }) => {
         const p = platform();
@@ -1186,7 +1283,12 @@ Please check if a camera is connected.` }],
     );
     server.tool(
       "location_get",
-      "Get current location (macOS: CoreLocation CLI, others: IP-based fallback)",
+      [
+        "Get the device's current geographic location.",
+        "",
+        "macOS: Uses CoreLocation (GPS-accurate) with IP-based fallback. Other platforms: IP-based geolocation (city-level accuracy only).",
+        "Returns latitude, longitude, and (when available) city and country."
+      ].join("\n"),
       {},
       async () => {
         const p = platform();
@@ -1213,9 +1315,9 @@ Please check if a camera is connected.` }],
     );
     server.tool(
       "audio_play",
-      "Play audio file (macOS: afplay, others: ffplay)",
+      "Play an audio file through the device's speakers. Supports MP3, WAV, AAC, and other common formats. Playback is synchronous \u2014 the tool returns after playback completes. Platform-specific: macOS (afplay), Windows/Linux (ffplay).",
       {
-        file_path: import_zod4.z.string().describe("Path to the audio file to play")
+        file_path: import_zod4.z.string().describe("Absolute path to the audio file to play")
       },
       async ({ file_path }) => {
         const p = platform();
@@ -1293,9 +1395,16 @@ var DesktopTools = class {
   register(server) {
     server.tool(
       "desktop_see",
-      "Capture macOS Accessibility Tree snapshot. Returns structured element list with IDs for interaction. Use returned snapshotId in subsequent desktop_click/type calls for 240x speed improvement.",
+      [
+        "Capture the macOS Accessibility Tree snapshot for a running application. Returns structured element list with IDs, roles, labels, and positions.",
+        "",
+        "WORKFLOW: Call desktop_see \u2192 find target element \u2192 use its ID in desktop_click or desktop_type.",
+        "Pass the returned snapshotId to subsequent calls for 240x speed improvement (cached lookup vs. full re-scan).",
+        "",
+        "SAFETY: Terminal, iTerm, and Finder are blocked. Two consecutive failures trigger an automatic safety stop."
+      ].join("\n"),
       {
-        app: import_zod5.z.string().optional().describe("App name to target (e.g. 'Safari', 'Finder'). Omit for frontmost app.")
+        app: import_zod5.z.string().optional().describe("App name to target (e.g. 'Safari', 'Notes', 'Google Chrome'). Omit for the frontmost app.")
       },
       async ({ app }) => {
         checkBlacklist(app);
@@ -1320,12 +1429,19 @@ var DesktopTools = class {
     );
     server.tool(
       "desktop_click",
-      "Click a UI element by label, accessibility ID, or coordinates",
+      [
+        "Click a macOS UI element by its accessibility label, ID, or x,y coordinates.",
+        "",
+        "The 'on' parameter accepts: element label text (e.g. 'Save'), accessibility ID from desktop_see, or coordinates as 'x,y' string.",
+        "For faster interaction, pass the snapshotId from a recent desktop_see call.",
+        "",
+        "SAFETY: Terminal, iTerm, and Finder are blocked. Two consecutive failures trigger automatic safety stop."
+      ].join("\n"),
       {
-        on: import_zod5.z.string().describe("Element label, ID, or 'x,y' coordinates to click"),
-        app: import_zod5.z.string().optional().describe("App name to target"),
-        snapshot: import_zod5.z.string().optional().describe("snapshotId from desktop_see for cached interaction (faster)"),
-        doubleClick: import_zod5.z.boolean().optional().default(false).describe("Double-click")
+        on: import_zod5.z.string().describe("Element label, accessibility ID, or 'x,y' coordinates to click"),
+        app: import_zod5.z.string().optional().describe("App name to target (e.g. 'Safari')"),
+        snapshot: import_zod5.z.string().optional().describe("snapshotId from desktop_see for cached interaction (240x faster)"),
+        doubleClick: import_zod5.z.boolean().optional().default(false).describe("Double-click instead of single click")
       },
       async ({ on, app, snapshot, doubleClick }) => {
         checkBlacklist(app);
@@ -1341,10 +1457,14 @@ var DesktopTools = class {
     );
     server.tool(
       "desktop_type",
-      "Type text into the currently focused element",
+      [
+        "Type text into the currently focused UI element on macOS. The text is sent as keyboard input character-by-character.",
+        "",
+        "SAFETY: Terminal, iTerm, and Finder are blocked. Use desktop_see first to verify the correct element is focused."
+      ].join("\n"),
       {
-        text: import_zod5.z.string().describe("Text to type"),
-        app: import_zod5.z.string().optional().describe("App name to target first")
+        text: import_zod5.z.string().describe("Text to type into the focused element"),
+        app: import_zod5.z.string().optional().describe("App name to focus before typing")
       },
       async ({ text, app }) => {
         checkBlacklist(app);
@@ -1358,9 +1478,15 @@ var DesktopTools = class {
     );
     server.tool(
       "desktop_hotkey",
-      "Press keyboard shortcut (e.g. 'cmd,c' for copy, 'cmd,shift,t' for new tab)",
+      [
+        "Press a keyboard shortcut on macOS. Keys are comma-separated.",
+        "",
+        "Common shortcuts: 'cmd,c' (copy), 'cmd,v' (paste), 'cmd,z' (undo), 'cmd,s' (save), 'cmd,w' (close tab), 'cmd,q' (quit), 'cmd,shift,t' (reopen tab), 'cmd,tab' (switch app).",
+        "",
+        "SAFETY: Terminal, iTerm, and Finder are blocked."
+      ].join("\n"),
       {
-        keys: import_zod5.z.string().describe("Comma-separated key combination (e.g. 'cmd,c', 'cmd,shift,t', 'escape')"),
+        keys: import_zod5.z.string().describe("Comma-separated key combination (e.g. 'cmd,c', 'cmd,shift,t', 'escape', 'cmd,option,i')"),
         app: import_zod5.z.string().optional().describe("App name to target")
       },
       async ({ keys, app }) => {
@@ -1375,11 +1501,11 @@ var DesktopTools = class {
     );
     server.tool(
       "desktop_scroll",
-      "Scroll in an app or specific element",
+      "Scroll within a macOS application or specific UI element. Use 'ticks' to control scroll distance (default: 3). Can target a specific element by label or ID with the 'on' parameter.",
       {
         direction: import_zod5.z.enum(["up", "down", "left", "right"]).describe("Scroll direction"),
-        ticks: import_zod5.z.number().optional().default(3).describe("Number of scroll ticks"),
-        on: import_zod5.z.string().optional().describe("Element label or ID to scroll within"),
+        ticks: import_zod5.z.number().optional().default(3).describe("Number of scroll ticks (default: 3). Higher = more scrolling."),
+        on: import_zod5.z.string().optional().describe("Element label or ID to scroll within (from desktop_see). Omit to scroll the active area."),
         app: import_zod5.z.string().optional().describe("App name to target")
       },
       async ({ direction, ticks, on, app }) => {
@@ -1395,7 +1521,7 @@ var DesktopTools = class {
     );
     server.tool(
       "desktop_list_apps",
-      "List all running applications on macOS",
+      "List all currently running applications on macOS. Returns app names that can be used as the 'app' parameter in other desktop tools (desktop_see, desktop_click, desktop_type, etc.).",
       {},
       async () => {
         try {
@@ -1411,9 +1537,9 @@ var DesktopTools = class {
     );
     server.tool(
       "desktop_list_windows",
-      "List all open windows on macOS",
+      "List all open windows on macOS, optionally filtered by app name. If no app is specified, lists windows for the frontmost application. Useful for identifying which windows are available for automation.",
       {
-        app: import_zod5.z.string().optional().describe("Filter by app name (omit to query frontmost app)")
+        app: import_zod5.z.string().optional().describe("Filter by app name. Omit to query the frontmost app.")
       },
       async ({ app }) => {
         checkBlacklist(app);
@@ -1439,10 +1565,15 @@ var DesktopTools = class {
     );
     server.tool(
       "desktop_screenshot",
-      "Take macOS screen screenshot using Peekaboo (Retina support, better quality than screen_capture)",
+      [
+        "Take a high-quality macOS screenshot using Peekaboo (Retina display support). Returns base64 image data.",
+        "",
+        "MODES: 'screen' captures the full display, 'window' captures a specific app window.",
+        "Prefer desktop_see (Accessibility Tree) for understanding UI structure \u2014 use screenshot only when visual appearance matters (layouts, images, colors)."
+      ].join("\n"),
       {
-        app: import_zod5.z.string().optional().describe("Capture specific app window"),
-        mode: import_zod5.z.enum(["screen", "window"]).optional().default("screen").describe("Capture mode")
+        app: import_zod5.z.string().optional().describe("Capture a specific app's window (by name)"),
+        mode: import_zod5.z.enum(["screen", "window"]).optional().default("screen").describe("'screen': full display capture, 'window': specific app window only")
       },
       async ({ app, mode }) => {
         checkBlacklist(app);
@@ -1469,10 +1600,15 @@ var DesktopTools = class {
     );
     server.tool(
       "desktop_menu",
-      "Click menu bar item (e.g. 'File > New Tab')",
+      [
+        "Click a menu bar item in a macOS application. Navigate nested menus by adding path segments.",
+        "",
+        "Examples: ['File', 'New Tab'], ['Edit', 'Find', 'Find...'], ['View', 'Enter Full Screen'].",
+        "The target app must be running and accessible."
+      ].join("\n"),
       {
-        path: import_zod5.z.array(import_zod5.z.string()).describe("Menu path as array (e.g. ['File', 'New Tab'])"),
-        app: import_zod5.z.string().optional().describe("App name to target")
+        path: import_zod5.z.array(import_zod5.z.string()).describe("Menu path as array (e.g. ['File', 'Save'], ['Edit', 'Find', 'Find...'])"),
+        app: import_zod5.z.string().optional().describe("App name to target. Omit for the frontmost app.")
       },
       async ({ path: path2, app }) => {
         checkBlacklist(app);
@@ -1736,16 +1872,58 @@ async function handleMCPRequest(id, payload) {
   if (!res.ok) {
     throw new Error(`MCP request failed: ${res.status} ${res.statusText}`);
   }
+  if (res.status === 202) {
+    return null;
+  }
+  const contentType = res.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    return res.json();
+  }
   const text = await res.text();
   const lines = text.split("\n");
+  let currentEventType = null;
+  const collectedResults = [];
+  let lastError = null;
   for (const line of lines) {
-    if (line.startsWith("data: ")) {
+    if (line.startsWith("event: ")) {
+      currentEventType = line.slice(7).trim();
+    } else if (line.startsWith("data: ")) {
+      const rawData = line.slice(6).trim();
+      if (rawData === "") {
+        currentEventType = null;
+        continue;
+      }
       try {
-        return JSON.parse(line.slice(6));
+        const parsed = JSON.parse(rawData);
+        if (currentEventType === "error") {
+          lastError = parsed;
+        } else if (currentEventType === "message" || currentEventType === null) {
+          collectedResults.push(parsed);
+        }
       } catch {
       }
+      currentEventType = null;
+    } else if (line === "") {
+      currentEventType = null;
     }
   }
+  if (collectedResults.length === 0 && lastError !== null) {
+    throw new Error(
+      `MCP error event: ${JSON.stringify(lastError)}`
+    );
+  }
+  if (collectedResults.length > 1 && payload !== null && typeof payload === "object" && "id" in payload) {
+    const requestId = payload.id;
+    const matched = collectedResults.find(
+      (r) => r !== null && typeof r === "object" && "id" in r && r.id === requestId
+    );
+    if (matched !== void 0) {
+      return matched;
+    }
+  }
+  if (collectedResults.length > 0) {
+    return collectedResults[collectedResults.length - 1];
+  }
   return null;
 }
 // Annotate the CommonJS export names for ESM import in node: