@deadragdoll/tellymcp 0.0.1 → 0.0.3

package/README-ru.md

@@ -1,6 +1,6 @@
 # TellyMCP
 
-[English](README.md) | [Русский](README-ru.md)
+[English](README.md) | [Русский](README-ru.md) | [Standalone Guide](STANDALONE.md) | [Standalone RU](STANDALONE-ru.md)
 
 [![npm version](https://img.shields.io/npm/v/%40deadragdoll%2Ftellymcp)](https://www.npmjs.com/package/@deadragdoll/tellymcp)
 [![npm downloads](https://img.shields.io/npm/dm/%40deadragdoll%2Ftellymcp)](https://www.npmjs.com/package/@deadragdoll/tellymcp)

package/README.md

@@ -1,6 +1,6 @@
 # TellyMCP
 
-[English](README.md) | [Русский](README-ru.md)
+[English](README.md) | [Русский](README-ru.md) | [Standalone Guide](STANDALONE.md) | [Standalone RU](STANDALONE-ru.md)
 
 [![npm version](https://img.shields.io/npm/v/%40deadragdoll%2Ftellymcp)](https://www.npmjs.com/package/@deadragdoll/tellymcp)
 [![npm downloads](https://img.shields.io/npm/dm/%40deadragdoll%2Ftellymcp)](https://www.npmjs.com/package/@deadragdoll/tellymcp)
@@ -60,6 +60,7 @@ Current tools:
 - a Telegram bot token from BotFather
 - for `gateway` / `both`: Postgres
 - optional for durable fanout on gateway: RabbitMQ
+- for `browser_*` tools: Playwright Chromium browser binaries
 
 ## tmux is strongly recommended
 
@@ -145,6 +146,12 @@ Typical local MCP endpoint in `client` mode:
 
 - `http://127.0.0.1:8787/mcp`
 
+If you plan to use `browser_*` tools, install Chromium once:
+
+```bash
+tellymcp browser install
+```
+
 Detailed step-by-step guide:
 
 - [STANDALONE.md](STANDALONE.md)
@@ -519,6 +526,8 @@ Recommended local dev settings:
 - `BROWSER_ADDRESS=http://localhost:5173`
 - start your SPA dev server on `0.0.0.0:5173`
 - open it through `browser_open`
+- install browser binaries once with `npx playwright install chromium`
+- install browser binaries once with `tellymcp browser install`
 
 Recommended Docker settings:
 

package/STANDALONE-ru.md

@@ -20,6 +20,7 @@
 2. `tmux`
 3. Redis
 4. Telegram bot token из BotFather
+5. опционально для `browser_*` tools: Playwright Chromium browser binaries
 
 Зачем это нужно:
 
@@ -46,6 +47,12 @@ redis-cli ping
 - `tmux -V` показывает версию
 - `redis-cli ping` возвращает `PONG`
 
+Если планируешь использовать browser automation tools, один раз выполни ещё:
+
+```bash
+tellymcp browser install
+```
+
 ## Шаг 2. Создать Telegram-бота
 
 В Telegram:
@@ -156,6 +163,7 @@ tellymcp doctor --env .env
 - `.env`
 - Redis
 - локальный MCP bind
+- Playwright Chromium, если browser tools включены
 
 ## Шаг 8. Запустить сервис
 

package/STANDALONE.md

@@ -20,6 +20,7 @@ Before installation, make sure you have:
 2. `tmux`
 3. Redis
 4. a Telegram bot token from BotFather
+5. optional for `browser_*` tools: Playwright Chromium browser binaries
 
 Why these matter:
 
@@ -46,6 +47,12 @@ Expected:
 - `tmux -V` prints a version
 - `redis-cli ping` returns `PONG`
 
+If you plan to use browser automation tools later, also run:
+
+```bash
+tellymcp browser install
+```
+
 ## Step 2. Create a Telegram bot
 
 In Telegram:
@@ -156,6 +163,7 @@ In standalone `client` mode it should verify:
 - `.env`
 - Redis
 - local MCP bind
+- Playwright Chromium when browser tools are enabled
 
 ## Step 8. Run the service
 

package/TOOLS.md

@@ -30,6 +30,12 @@ Browser tools:
 - `browser_screenshot`
 - `browser_close`
 
+Browser runtime rule:
+
+- Browser tools use Playwright Chromium.
+- If browser tools fail because the Playwright browser runtime is missing, install it with `tellymcp browser install`.
+- Do not stop at the installation error itself. Install the browser runtime first, then retry the browser tool.
+
 Collaboration tools:
 
 - `send_partner_note`
@@ -702,6 +708,9 @@ Input:
 
 Notes:
 
+- Browser tools require Playwright Chromium browser binaries.
+- If the runtime is missing, run `tellymcp browser install`, then retry `browser_open`.
+
 - the server always uses `TELEGRAM_INBOX_BATCH_SIZE`
 - the agent should not try to choose its own batch size
 

package/dist/cli.js

@@ -50,6 +50,34 @@ function getTmuxInstallHints() {
         "Arch:          sudo pacman -S tmux",
     ];
 }
+async function getPlaywrightBrowserStatus(browserEnabled) {
+    if (!browserEnabled) {
+        return { enabled: false };
+    }
+    try {
+        const playwright = await import("playwright");
+        const executablePath = playwright.chromium.executablePath();
+        if (executablePath && (0, node_fs_1.existsSync)(executablePath)) {
+            return {
+                enabled: true,
+                installed: true,
+                executablePath,
+            };
+        }
+        return {
+            enabled: true,
+            installed: false,
+            message: "Chromium browser binaries are missing.",
+        };
+    }
+    catch (error) {
+        return {
+            enabled: true,
+            installed: false,
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
 function printHelp() {
     const tmux = getTmuxStatus();
     printBanner("CLI", "Telegram Human-in-the-Loop MCP server");
@@ -58,6 +86,7 @@ function printHelp() {
         "  tellymcp run [--env <file>]",
         "  tellymcp run --env=<file>",
         "  tellymcp doctor [--env <file>]",
+        "  tellymcp browser install",
         "  tellymcp mcp [--url <url>] [--bearer <token>] [--format claude|legacy]",
         "  tellymcp help",
     ]);
@@ -67,6 +96,7 @@ function printHelp() {
         "  tellymcp run",
         "  tellymcp run --env .env.client",
         "  tellymcp doctor --env .env.client",
+        "  tellymcp browser install",
         "  tellymcp mcp --help",
     ]);
     if (tmux.found) {
@@ -146,6 +176,17 @@ function printMcpHelp() {
         "  tellymcp mcp --url https://builder.undoo.ru/api/mcp --format legacy",
     ]);
 }
+function printBrowserHelp() {
+    printBanner("browser helper", "Manage Playwright browser binaries used by browser_* tools");
+    printSection("Usage", [
+        "  tellymcp browser install",
+    ]);
+    printSection("What this command does", [
+        "  Installs the bundled Playwright Chromium browser.",
+        "  Uses the Playwright dependency shipped with TellyMCP.",
+        "  Avoids generic npx warnings about missing local project dependencies.",
+    ]);
+}
 function fail(message) {
     process.stderr.write(`${message}\n`);
     process.exit(1);
@@ -439,6 +480,7 @@ async function runDoctor(args) {
     const gatewayWsUrl = parsed.GATEWAY_WS_URL?.trim();
     const publicWebappUrl = parsed.WEBAPP_PUBLIC_URL?.trim();
     const mcpBearerToken = parsed.MCP_HTTP_BEARER_TOKEN?.trim();
+    const browserEnabled = (parsed.BROWSER_ENABLED || "true").trim().toLowerCase() !== "false";
     const externalHealthUrl = deriveGatewayHealthUrlFromPublicUrl(publicGatewayUrl || "") ??
         deriveGatewayHealthUrlFromPublicUrl(publicWebappUrl || "");
     printSection("env", [
@@ -455,6 +497,19 @@ async function runDoctor(args) {
     ]);
     const checks = [];
     const capabilities = [];
+    const playwrightStatus = await getPlaywrightBrowserStatus(browserEnabled);
+    if (!playwrightStatus.enabled) {
+        checks.push(`${picocolors_1.default.dim("  SKIP")} playwright: browser tools are disabled`);
+        capabilities.push(`${picocolors_1.default.dim("  SKIP")} browser tools: disabled`);
+    }
+    else if (playwrightStatus.installed) {
+        checks.push(`${picocolors_1.default.green("  OK")} playwright chromium: ${playwrightStatus.executablePath}`);
+        capabilities.push(`${picocolors_1.default.green("  OK")} browser tools: available`);
+    }
+    else {
+        checks.push(`${picocolors_1.default.red("  ERROR")} playwright chromium: ${playwrightStatus.message}`);
+        capabilities.push(`${picocolors_1.default.red("  ERROR")} browser tools: browsers are not installed`);
+    }
     const redisHost = (parsed.REDIS_HOST || "127.0.0.1").trim();
     const redisPort = Number(parsed.REDIS_PORT || 6379);
     const redisCheck = await checkTcpPort(redisHost, redisPort);
@@ -560,6 +615,39 @@ async function runDoctor(args) {
     else {
         printSection("notes", [`${picocolors_1.default.green("  OK")} No obvious local config issues detected.`]);
     }
+    if (browserEnabled && (!playwrightStatus.enabled || !playwrightStatus.installed)) {
+        printSection("playwright", [
+            `${picocolors_1.default.yellow("  ACTION")} Install browser binaries before using browser_* tools:`,
+            "    tellymcp browser install",
+        ]);
+    }
+}
+function runBrowserCommand(args) {
+    const [subcommand] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+        printBrowserHelp();
+        return;
+    }
+    if (subcommand !== "install") {
+        fail("Supported browser subcommands: install");
+    }
+    const cliPath = node_path_1.default.join(packageRoot, "node_modules", "playwright", "cli.js");
+    if (!(0, node_fs_1.existsSync)(cliPath)) {
+        fail(`Missing bundled Playwright CLI: ${cliPath}`);
+    }
+    printBanner("browser install", "Installing bundled Playwright Chromium");
+    const child = (0, node_child_process_1.spawn)(process.execPath, [cliPath, "install", "chromium"], {
+        cwd: process.cwd(),
+        stdio: "inherit",
+        env: process.env,
+    });
+    child.on("exit", (code, signal) => {
+        if (signal) {
+            process.kill(process.pid, signal);
+            return;
+        }
+        process.exit(code ?? 0);
+    });
 }
 function runRuntime(args) {
     const envPath = resolveRunEnvPath(args);
@@ -612,7 +700,7 @@ function runRuntime(args) {
 }
 async function main(argv) {
     const [rawCommand, firstArg, secondArg] = argv;
-    const command = rawCommand === "init" || rawCommand === "run" || rawCommand === "help" || rawCommand === "mcp" || rawCommand === "doctor"
+    const command = rawCommand === "init" || rawCommand === "run" || rawCommand === "help" || rawCommand === "mcp" || rawCommand === "doctor" || rawCommand === "browser"
         ? rawCommand
         : "help";
     if (command === "help" || !rawCommand || rawCommand === "--help" || rawCommand === "-h") {
@@ -631,6 +719,10 @@ async function main(argv) {
         await runDoctor(argv.slice(1));
         return;
     }
+    if (command === "browser") {
+        runBrowserCommand(argv.slice(1));
+        return;
+    }
     runRuntime(argv.slice(1));
 }
 void main(process.argv.slice(2));

package/dist/services/features/telegram-mcp/gateway-delivery.service.js

@@ -278,7 +278,7 @@ const TelegramMcpGatewayDeliveryService = {
             try {
                 await runtime.telegramTransport.sendNotification({
                     sessionId: targetSession.sessionId,
-                    ...(targetSession.label ? { sessionLabel: targetSession.label } : {}),
+                    sessionLabel: delivery.source_session_label,
                     recipient: {
                         telegramChatId: targetBinding.telegramChatId,
                         telegramUserId: targetBinding.telegramUserId,

package/dist/services/features/telegram-mcp/gateway-socket.service.js

@@ -554,7 +554,7 @@ const TelegramMcpGatewaySocketService = {
                     const action = typeof request.payload?.action === "string"
                         ? request.payload.action
                         : "";
-                    if (!["up", "down", "enter", "slash", "delete", "tab", "escape"].includes(action)) {
+                    if (!["up", "down", "enter", "slash", "delete", "tab", "escape", "interrupt"].includes(action)) {
                         throw new Error("Unsupported action");
                     }
                     const sessionId = request.local_session_id.trim();

package/dist/services/features/telegram-mcp/src/app/http.js

@@ -428,7 +428,7 @@ function createMcpHttpHandler(runtime, input) {
                     typeof Reflect.get(body, "action") === "string"
                     ? String(Reflect.get(body, "action"))
                     : "";
-                if (!["up", "down", "enter", "slash", "delete", "tab", "escape"].includes(action)) {
+                if (!["up", "down", "enter", "slash", "delete", "tab", "escape", "interrupt"].includes(action)) {
                     writeText(res, 400, "Unsupported action");
                     return;
                 }

package/dist/services/features/telegram-mcp/src/app/webapp/assets.js

@@ -168,6 +168,7 @@ const elements = {
   session: document.querySelector("[data-role=session]"),
   status: document.querySelector("[data-role=status]"),
   updated: document.querySelector("[data-role=updated]"),
+  interrupt: document.querySelector("[data-role=interrupt]"),
   esc: document.querySelector("[data-role=escape]"),
   tab: document.querySelector("[data-role=tab]"),
   slash: document.querySelector("[data-role=slash]"),
@@ -597,6 +598,10 @@ function startPolling() {
 }
 
 function bindUi() {
+  elements.interrupt.addEventListener("click", () => {
+    sendAction("interrupt").catch((error) => setStatus(error.message || String(error), true));
+  });
+
   elements.esc.addEventListener("click", () => {
     sendAction("escape").catch((error) => setStatus(error.message || String(error), true));
   });
@@ -664,6 +669,7 @@ async function main() {
       bootstrapPayload.session_label || bootstrapPayload.session_id;
 
     if (!bootstrapPayload.tmux_target) {
+      elements.interrupt.disabled = true;
       elements.esc.disabled = true;
       elements.tab.disabled = true;
       elements.slash.disabled = true;
@@ -704,6 +710,7 @@ function renderWebAppHtml(input) {
   <body>
     <div class="app">
       <div class="toolbar">
+        <button class="btn compact danger" data-role="interrupt" type="button">Ctrl+C</button>
         <button class="btn compact" data-role="escape" type="button">Esc</button>
         <button class="btn compact" data-role="tab" type="button">Tab</button>
         <button class="btn compact" data-role="slash" type="button">/</button>

package/dist/services/features/telegram-mcp/src/features/collaboration/model/localCollaborationBackend.js

@@ -248,7 +248,7 @@ class LocalCollaborationBackend {
         await this.inboxStore.createInboxMessage(inboxMessage);
         await this.telegramTransport.sendNotification({
             sessionId: targetSession.sessionId,
-            ...(targetSession.label ? { sessionLabel: targetSession.label } : {}),
+            sessionLabel: sourceLabel,
             recipient: {
                 telegramChatId: targetBinding.telegramChatId,
                 telegramUserId: targetBinding.telegramUserId,

package/dist/services/features/telegram-mcp/src/shared/integrations/tmux/client.js

@@ -253,7 +253,9 @@ async function sendAllowedTmuxAction(config, target, action) {
                         ? "Tab"
                         : action === "escape"
                             ? "Escape"
-                            : "Enter";
+                            : action === "interrupt"
+                                ? "C-c"
+                                : "Enter";
     await execFileAsync("tmux", buildTmuxArgs(config, ["send-keys", "-t", target, key]));
 }
 async function sendTmuxLiteralLine(config, target, text) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deadragdoll/tellymcp",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "TellyMCP - Telegram Human-in-the-Loop MCP Server",
   "main": "dist/services/features/telegram-mcp/runtime.service.js",
   "bin": {
@@ -34,6 +34,8 @@
   },
   "scripts": {
     "postinstall": "node ./scripts/postinstall.js",
+    "prepack": "yarn build",
+    "prepublishOnly": "yarn build && yarn lint && yarn test",
     "mcp:local": "codex mcp add telegramHuman --url http://127.0.0.1:8787/mcp",
     "dev:gw": "TS_NODE_TRANSPILE_ONLY=1 TS_NODE_EXPERIMENTAL_RESOLVER=1 NODE_OPTIONS=--openssl-legacy-provider ts-node ./node_modules/moleculer/bin/moleculer-runner.js src/services --config src/moleculer.config.ts --envfile ./.env-dev --hot --mask \"**/*.service.ts\"",
     "dev:builder": "TS_NODE_TRANSPILE_ONLY=1 TS_NODE_EXPERIMENTAL_RESOLVER=1 NODE_OPTIONS=--openssl-legacy-provider ts-node ./node_modules/moleculer/bin/moleculer-runner.js src/services --config src/moleculer.config.ts --envfile ./.env-builder --hot --mask \"**/*.service.ts\"",

package/scripts/postinstall.js

@@ -53,6 +53,11 @@ if (tmux.found) {
   }
 }
 
+line();
+line(`${pc.yellow("INFO")} Browser tools need Playwright browser binaries.`);
+line("If you plan to use browser_* tools, run:");
+line(`  ${pc.bold("tellymcp browser install")}`);
+
 line();
 line(`Check your local setup: ${pc.bold("tellymcp doctor")}`);
 line(`General help: ${pc.bold("tellymcp help")}`);