@deadragdoll/tellymcp 0.0.10 → 0.0.12

package/STANDALONE.md

@@ -1,274 +0,0 @@
-# TellyMCP Standalone Guide
-
-[English](STANDALONE.md) | [Русский](STANDALONE-ru.md)
-
-This guide explains the simplest TellyMCP setup:
-
-- one machine
-- one Telegram bot
-- no shared gateway
-- no Postgres
-- no RabbitMQ
-
-This is the best way to start.
-
-## What you need
-
-Before installation, make sure you have:
-
-1. Node.js 24+
-2. `tmux`
-3. Redis
-4. a Telegram bot token from BotFather
-5. optional for `browser_*` tools: Playwright Chromium browser binaries
-
-Why these matter:
-
-- Node.js runs the service
-- `tmux` enables Live View, nudges, and direct Telegram-side interaction
-- Redis stores session state, inbox, pairing state, and menu state
-- Telegram bot token connects your bot to Telegram
-
-## Step 1. Install prerequisites
-
-Ubuntu / Debian example:
-
-```bash
-sudo apt-get update
-sudo apt-get install -y tmux redis-server
-node -v
-tmux -V
-redis-cli ping
-```
-
-Expected:
-
-- Node version is `24.x` or newer
-- `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:
-
-1. Open BotFather
-2. Run `/newbot`
-3. Choose a bot name
-4. Choose a bot username
-5. Save the token
-
-You will need:
-
-- `TELEGRAM_BOT_TOKEN`
-- `TELEGRAM_BOT_USERNAME`
-
-## Step 3. Install TellyMCP
-
-```bash
-npm install -g @deadragdoll/tellymcp
-```
-
-Check that the CLI works:
-
-```bash
-tellymcp help
-```
-
-## Step 4. Start a tmux session for the agent
-
-This part is important.
-
-Run the agent inside `tmux`, not in a plain shell, if you want the full experience.
-
-Create a session:
-
-```bash
-tmux new -s backend
-```
-
-Good session names:
-
-- `backend`
-- `frontend`
-- `review`
-- `ops`
-
-Why the session name matters:
-
-- it helps identify the agent in practice
-- it improves diagnostics
-- it makes Telegram and Live View easier to understand
-
-If you later detach:
-
-```bash
-tmux detach
-```
-
-and return:
-
-```bash
-tmux attach -t backend
-```
-
-## Step 5. Create the standalone config
-
-Inside the workspace where you want to run TellyMCP:
-
-```bash
-tellymcp init client
-```
-
-This creates a local `.env`.
-
-## Step 6. Fill `.env`
-
-At minimum, set:
-
-```env
-TELEGRAM_BOT_TOKEN=...
-TELEGRAM_BOT_USERNAME=@your_bot
-REDIS_HOST=127.0.0.1
-REDIS_PORT=6379
-REDIS_DB=1
-MCP_HTTP_HOST=127.0.0.1
-MCP_HTTP_PORT=8787
-MCP_HTTP_PATH=/mcp
-MCP_HTTP_BEARER_TOKEN=choose-a-secret-token
-DISTRIBUTED_MODE=client
-WEBAPP_ENABLED=true
-```
-
-If your tmux server uses a non-default socket:
-
-```env
-TMUX_SOCKET_PATH=/tmp/tmux-1000/default
-```
-
-## Step 7. Validate the setup
-
-```bash
-tellymcp doctor --env .env
-```
-
-In standalone `client` mode it should verify:
-
-- `tmux`
-- `.env`
-- Redis
-- local MCP bind
-- Playwright Chromium when browser tools are enabled
-
-## Step 8. Run the service
-
-```bash
-tellymcp run --env .env
-```
-
-Standalone MCP endpoint is normally:
-
-- `http://127.0.0.1:8787/mcp`
-
-## Step 9. Add MCP to your agent
-
-To get a ready-to-paste config snippet:
-
-```bash
-tellymcp mcp --help
-```
-
-Typical local MCP config target:
-
-- `http://127.0.0.1:8787/mcp`
-
-If you use bearer auth, configure your agent with the same token from `.env`.
-
-## Step 10. Pair the agent with Telegram
-
-Once MCP is connected, tell the agent something like:
-
-- `pair with Telegram`
-- `link to Telegram`
-- `connect this session to Telegram`
-- `create a Telegram pairing code`
-
-Expected flow:
-
-1. the agent calls `create_session_pair_code`
-2. it gives you a short code
-3. you send `/start <code>` or `/link <code>` to the bot
-4. after success, open `/menu`
-
-If the agent is running inside `tmux`, it should pass:
-
-- `cwd`
-- tmux session name
-- tmux window/pane attributes
-
-This lets Live View and tmux nudges work immediately.
-
-## Step 11. What you get after pairing
-
-After pairing, Telegram can be used for:
-
-- inbox messages
-- clarifying questions
-- local partner collaboration
-- session switching
-- storage inspection
-- Live View
-
-The agent can:
-
-- call `ask_user_telegram`
-- read unsolicited inbox messages
-- send notes and files
-- receive tmux nudges when new work arrives
-
-## What works without tmux
-
-TellyMCP can still run without `tmux`, but this is a reduced mode.
-
-You lose:
-
-- Live View
-- tmux nudges
-- direct Telegram Mini App controls
-
-Use this only if you accept a passive workflow.
-
-## Troubleshooting
-
-If `doctor` fails:
-
-- verify Redis is running
-- verify `tmux` is installed
-- verify the bot token is correct
-- verify your bearer token matches the MCP client config
-
-If pairing works but Live View does not:
-
-- make sure the agent is really inside `tmux`
-- make sure the tmux session has a stable name
-- if needed, set `TMUX_SOCKET_PATH`
-
-If the agent cannot connect to MCP:
-
-- confirm `tellymcp run --env .env` is running
-- confirm the endpoint is `http://127.0.0.1:8787/mcp`
-- confirm the bearer token matches
-
-## Next step
-
-After standalone is working, the next upgrade path is:
-
-- `gateway`
-- or `both`
-
-Use that only when you need cross-machine collaboration.

package/dist/services/features/telegram-mcp/inbox.service.js

@@ -1,33 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TELEGRAM_MCP_INBOX_SERVICE_NAME = void 0;
-const runtime_service_1 = require("./runtime.service");
-const inboxService_1 = require("./src/features/inbox/model/inboxService");
-exports.TELEGRAM_MCP_INBOX_SERVICE_NAME = "telegramMcp.inbox";
-const TelegramMcpInboxService = {
-    name: exports.TELEGRAM_MCP_INBOX_SERVICE_NAME,
-    dependencies: [runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME],
-    created() {
-        this.inboxService = null;
-    },
-    methods: {
-        getInboxService() {
-            if (!this.inboxService) {
-                throw new Error("telegram_mcp inbox service is not initialized yet");
-            }
-            return this.inboxService;
-        },
-    },
-    async started() {
-        await this.broker.waitForServices([runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME]);
-        const runtimeService = this.broker.getLocalService(runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME);
-        if (!runtimeService) {
-            throw new Error(`Local Moleculer service '${runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME}' is unavailable`);
-        }
-        const runtime = await runtimeService.waitUntilReady();
-        this.logger.info("Starting telegram_mcp inbox service");
-        this.inboxService = new inboxService_1.InboxService(runtime.config, runtime.stateStore, runtime.stateStore, runtime.logger, runtime.projectIdentityResolver);
-        this.logger.info("telegram_mcp inbox service is ready");
-    },
-};
-exports.default = TelegramMcpInboxService;

package/dist/services/features/telegram-mcp/pair.service.js

@@ -1,33 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TELEGRAM_MCP_PAIR_SERVICE_NAME = void 0;
-const runtime_service_1 = require("./runtime.service");
-const generatePairCode_1 = require("./src/features/pair-session/model/generatePairCode");
-exports.TELEGRAM_MCP_PAIR_SERVICE_NAME = "telegramMcp.pair";
-const TelegramMcpPairService = {
-    name: exports.TELEGRAM_MCP_PAIR_SERVICE_NAME,
-    dependencies: [runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME],
-    created() {
-        this.pairSessionService = null;
-    },
-    methods: {
-        getPairSessionService() {
-            if (!this.pairSessionService) {
-                throw new Error("telegram_mcp pair service is not initialized yet");
-            }
-            return this.pairSessionService;
-        },
-    },
-    async started() {
-        await this.broker.waitForServices([runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME]);
-        const runtimeService = this.broker.getLocalService(runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME);
-        if (!runtimeService) {
-            throw new Error(`Local Moleculer service '${runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME}' is unavailable`);
-        }
-        const runtime = await runtimeService.waitUntilReady();
-        this.logger.info("Starting telegram_mcp pair service");
-        this.pairSessionService = new generatePairCode_1.PairSessionService(runtime.config, runtime.stateStore, runtime.stateStore, runtime.stateStore, runtime.logger, runtime.projectIdentityResolver);
-        this.logger.info("telegram_mcp pair service is ready");
-    },
-};
-exports.default = TelegramMcpPairService;

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

@@ -1,10 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.sendTmuxLiteralText = exports.sendAllowedTmuxAction = exports.isTmuxUnavailableError = exports.getTmuxWindowHeight = exports.captureVisibleTmuxPane = exports.captureTmuxPaneRange = void 0;
-var client_1 = require("../../shared/integrations/tmux/client");
-Object.defineProperty(exports, "captureTmuxPaneRange", { enumerable: true, get: function () { return client_1.captureTmuxPaneRange; } });
-Object.defineProperty(exports, "captureVisibleTmuxPane", { enumerable: true, get: function () { return client_1.captureVisibleTmuxPane; } });
-Object.defineProperty(exports, "getTmuxWindowHeight", { enumerable: true, get: function () { return client_1.getTmuxWindowHeight; } });
-Object.defineProperty(exports, "isTmuxUnavailableError", { enumerable: true, get: function () { return client_1.isTmuxUnavailableError; } });
-Object.defineProperty(exports, "sendAllowedTmuxAction", { enumerable: true, get: function () { return client_1.sendAllowedTmuxAction; } });
-Object.defineProperty(exports, "sendTmuxLiteralText", { enumerable: true, get: function () { return client_1.sendTmuxLiteralText; } });

package/dist/services/features/telegram-mcp/src/features/inbox/model/deleteTelegramInboxMessageTool.js

@@ -1,33 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DeleteTelegramInboxMessageTool = void 0;
-const schema_1 = require("../../../entities/request/model/schema");
-function createContent(output) {
-    return [
-        {
-            type: "text",
-            text: JSON.stringify(output, null, 2),
-        },
-    ];
-}
-class DeleteTelegramInboxMessageTool {
-    inboxService;
-    constructor(inboxService) {
-        this.inboxService = inboxService;
-    }
-    register(server) {
-        server.registerTool("delete_telegram_inbox_message", {
-            title: "Delete Telegram Inbox Message",
-            description: "Use this only after you have fully processed an ordinary human Telegram inbox message. Pass session_id explicitly after pairing; do not rely on implicit defaults unless cwd is also correct for this agent workspace. Delete the message so future inbox reads do not return it again.",
-            inputSchema: schema_1.deleteTelegramInboxMessageInputSchema,
-            outputSchema: schema_1.deleteTelegramInboxMessageOutputSchema,
-        }, async (args) => {
-            const output = await this.inboxService.deleteInboxMessage(args);
-            return {
-                content: createContent(output),
-                structuredContent: output,
-            };
-        });
-    }
-}
-exports.DeleteTelegramInboxMessageTool = DeleteTelegramInboxMessageTool;

package/dist/services/features/telegram-mcp/src/features/inbox/model/getTelegramInboxCountTool.js

@@ -1,33 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.GetTelegramInboxCountTool = void 0;
-const schema_1 = require("../../../entities/request/model/schema");
-function createContent(output) {
-    return [
-        {
-            type: "text",
-            text: JSON.stringify(output, null, 2),
-        },
-    ];
-}
-class GetTelegramInboxCountTool {
-    inboxService;
-    constructor(inboxService) {
-        this.inboxService = inboxService;
-    }
-    register(server) {
-        server.registerTool("get_telegram_inbox_count", {
-            title: "Get Telegram Inbox Count",
-            description: "Use this to cheaply check whether ordinary human Telegram messages are waiting for the session. Pass session_id explicitly after pairing; do not rely on implicit defaults unless cwd is also correct for this agent workspace. Do not use it for partner-note wakeups; partner notes must be read from .mcp-xchange/SHARED_INDEX.md instead.",
-            inputSchema: schema_1.getTelegramInboxCountInputSchema,
-            outputSchema: schema_1.getTelegramInboxCountOutputSchema,
-        }, async (args) => {
-            const output = await this.inboxService.getInboxCount(args);
-            return {
-                content: createContent(output),
-                structuredContent: output,
-            };
-        });
-    }
-}
-exports.GetTelegramInboxCountTool = GetTelegramInboxCountTool;

package/dist/services/features/telegram-mcp/src/features/inbox/model/getTelegramInboxTool.js

@@ -1,33 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.GetTelegramInboxTool = void 0;
-const schema_1 = require("../../../entities/request/model/schema");
-function createContent(output) {
-    return [
-        {
-            type: "text",
-            text: JSON.stringify(output, null, 2),
-        },
-    ];
-}
-class GetTelegramInboxTool {
-    inboxService;
-    constructor(inboxService) {
-        this.inboxService = inboxService;
-    }
-    register(server) {
-        server.registerTool("get_telegram_inbox", {
-            title: "Get Telegram Inbox",
-            description: "Use this to read unsolicited Telegram inbox messages stored for the session. Pass session_id explicitly after pairing; do not rely on implicit defaults unless cwd is also correct for this agent workspace. Each item now includes message_kind: human or system. Treat system messages as operational instructions from the service, not as normal user prompts. Returned items may also include local attachment paths from .mcp-xchange when the human message contained a photo or document. Do not use this first for partner-note wakeups; partner collaboration notes must be read from .mcp-xchange/SHARED_INDEX.md and the referenced note files.",
-            inputSchema: schema_1.getTelegramInboxInputSchema,
-            outputSchema: schema_1.getTelegramInboxOutputSchema,
-        }, async (args) => {
-            const output = await this.inboxService.getInbox(args);
-            return {
-                content: createContent(output),
-                structuredContent: output,
-            };
-        });
-    }
-}
-exports.GetTelegramInboxTool = GetTelegramInboxTool;

package/dist/services/features/telegram-mcp/src/features/inbox/model/inboxService.js

@@ -1,77 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.InboxService = void 0;
-class InboxService {
-    config;
-    inboxStore;
-    _sessionStore;
-    logger;
-    projectIdentityResolver;
-    constructor(config, inboxStore, _sessionStore, logger, projectIdentityResolver) {
-        this.config = config;
-        this.inboxStore = inboxStore;
-        this._sessionStore = _sessionStore;
-        this.logger = logger;
-        this.projectIdentityResolver = projectIdentityResolver;
-    }
-    async getInboxCount(input) {
-        const resolved = this.projectIdentityResolver.resolveSessionDefaults(input);
-        const total = await this.inboxStore.countInboxMessages(resolved.sessionId);
-        this.logger.info("Telegram inbox count fetched", {
-            sessionId: resolved.sessionId,
-            sessionIdDerived: resolved.sessionIdDerived,
-            total,
-        });
-        return {
-            session_id: resolved.sessionId,
-            total,
-        };
-    }
-    async getInbox(input) {
-        const resolved = this.projectIdentityResolver.resolveSessionDefaults(input);
-        const limit = this.config.telegram.inboxBatchSize;
-        const messages = await this.inboxStore.listInboxMessages(resolved.sessionId, limit);
-        const total = await this.inboxStore.countInboxMessages(resolved.sessionId);
-        this.logger.info("Telegram inbox fetched", {
-            sessionId: resolved.sessionId,
-            sessionIdDerived: resolved.sessionIdDerived,
-            limit,
-            returned: messages.length,
-            total,
-        });
-        return {
-            session_id: resolved.sessionId,
-            total,
-            has_more: total > messages.length,
-            messages: messages.map((message) => ({
-                message_id: message.id,
-                source: "telegram",
-                message_kind: message.sourceTelegramMessageId > 0 ? "human" : "system",
-                telegram_chat_id: message.telegramChatId,
-                telegram_user_id: message.telegramUserId,
-                telegram_message_id: message.sourceTelegramMessageId,
-                text: message.text,
-                ...(message.attachments?.length
-                    ? { attachments: message.attachments }
-                    : {}),
-                received_at: message.receivedAt,
-            })),
-        };
-    }
-    async deleteInboxMessage(input) {
-        const resolved = this.projectIdentityResolver.resolveSessionDefaults(input);
-        const deleted = await this.inboxStore.deleteInboxMessage(resolved.sessionId, input.message_id);
-        this.logger.info("Telegram inbox message deleted", {
-            sessionId: resolved.sessionId,
-            sessionIdDerived: resolved.sessionIdDerived,
-            messageId: input.message_id,
-            deleted,
-        });
-        return {
-            deleted,
-            session_id: resolved.sessionId,
-            message_id: input.message_id,
-        };
-    }
-}
-exports.InboxService = InboxService;

package/dist/services/features/telegram-mcp/src/features/pair-session/model/clearSessionPairingTool.js

@@ -1,33 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ClearSessionPairingTool = void 0;
-const schema_1 = require("../../../entities/request/model/schema");
-function createContent(output) {
-    return [
-        {
-            type: "text",
-            text: JSON.stringify(output, null, 2),
-        },
-    ];
-}
-class ClearSessionPairingTool {
-    pairSessionService;
-    constructor(pairSessionService) {
-        this.pairSessionService = pairSessionService;
-    }
-    register(server) {
-        server.registerTool("clear_session_pairing", {
-            title: "Clear Session Pairing",
-            description: "Use this when the user asks to unpair, unlink, detach, or reset Telegram binding for the current session. Remove Telegram binding for a session so it can be paired again.",
-            inputSchema: schema_1.clearSessionPairingInputSchema,
-            outputSchema: schema_1.clearSessionPairingOutputSchema,
-        }, async (args) => {
-            const output = await this.pairSessionService.clearPairing(args);
-            return {
-                content: createContent(output),
-                structuredContent: output,
-            };
-        });
-    }
-}
-exports.ClearSessionPairingTool = ClearSessionPairingTool;

package/dist/services/features/telegram-mcp/src/features/pair-session/model/createSessionPairCodeTool.js

@@ -1,33 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CreateSessionPairCodeTool = void 0;
-const schema_1 = require("../../../entities/request/model/schema");
-function createContent(output) {
-    return [
-        {
-            type: "text",
-            text: JSON.stringify(output, null, 2),
-        },
-    ];
-}
-class CreateSessionPairCodeTool {
-    pairSessionService;
-    constructor(pairSessionService) {
-        this.pairSessionService = pairSessionService;
-    }
-    register(server) {
-        server.registerTool("create_session_pair_code", {
-            title: "Create Session Pair Code",
-            description: "Use this when the user asks to link, pair, register, or connect the current agent/session to Telegram. Before calling it, determine the correct workspace cwd and, if tmux is available, collect current tmux attributes. Then create a short-lived Telegram pairing code for that session. After success, remember the returned session_id and pass it explicitly to later session-scoped tools.",
-            inputSchema: schema_1.createSessionPairCodeInputSchema,
-            outputSchema: schema_1.createSessionPairCodeOutputSchema,
-        }, async (args) => {
-            const output = await this.pairSessionService.createPairCode(args);
-            return {
-                content: createContent(output),
-                structuredContent: output,
-            };
-        });
-    }
-}
-exports.CreateSessionPairCodeTool = CreateSessionPairCodeTool;