openpets 1.0.5 → 1.0.7

package/dist/src/core/mautrix-bridge.js

@@ -0,0 +1,1046 @@
+import { z } from "zod";
+import { exec } from "child_process";
+import { promisify } from "util";
+import { existsSync, mkdirSync, readFileSync } from "fs";
+import { join } from "path";
+const execAsync = promisify(exec);
+export function createBridgeConfig(bridgeType, bridgeUrl, sharedSecret) {
+    return {
+        baseUrl: bridgeUrl || "",
+        sharedSecret: sharedSecret || "",
+        enabled: !!(bridgeUrl && sharedSecret),
+        bridgeType
+    };
+}
+export function createBridgeFetcher(config) {
+    return async (endpoint, options = {}) => {
+        if (!config.enabled) {
+            throw new Error(`Mautrix ${config.bridgeType} bridge not configured. Set MAUTRIX_BRIDGE_URL and MAUTRIX_SHARED_SECRET.`);
+        }
+        const url = `${config.baseUrl}/_matrix/provision${endpoint}`;
+        const response = await fetch(url, {
+            ...options,
+            headers: {
+                "Authorization": `Bearer ${config.sharedSecret}`,
+                "Content-Type": "application/json",
+                ...options.headers
+            }
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: response.statusText }));
+            throw new Error(`Bridge API error: ${response.status} - ${error.error || error.errcode || JSON.stringify(error)}`);
+        }
+        return response.json();
+    };
+}
+export function createBridgeStatusTool(options) {
+    const { config, logger, serviceName, serviceNameLower } = options;
+    const fetchBridge = createBridgeFetcher(config);
+    return {
+        name: `${serviceNameLower}-bridge-status`,
+        description: `Check the status of the mautrix-${serviceNameLower} Matrix bridge connection. Use this to see if the bridge is configured and if you're logged in to ${serviceName} through it.`,
+        schema: z.object({
+            user_id: z.string().optional().describe("Matrix user ID to check status for (defaults to configured user)")
+        }),
+        async execute(args) {
+            if (!config.enabled) {
+                return JSON.stringify({
+                    success: false,
+                    error: `Mautrix ${serviceNameLower} bridge not configured`,
+                    help: {
+                        message: `Set MAUTRIX_BRIDGE_URL and MAUTRIX_SHARED_SECRET to enable Matrix bridge integration`,
+                        example: {
+                            MAUTRIX_BRIDGE_URL: `https://${serviceNameLower}-bridge.example.com`,
+                            MAUTRIX_SHARED_SECRET: "your-shared-secret"
+                        }
+                    }
+                }, null, 2);
+            }
+            logger.info("Checking bridge status", { user_id: args.user_id });
+            try {
+                const params = args.user_id ? `?user_id=${encodeURIComponent(args.user_id)}` : "";
+                const status = await fetchBridge(`/v1/whoami${params}`);
+                const remoteAccount = status[serviceNameLower];
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        bridge_url: config.baseUrl,
+                        bridge_type: config.bridgeType,
+                        matrix_user: status.mxid,
+                        [`${serviceNameLower}_account`]: remoteAccount || null,
+                        logged_in: status.logged_in,
+                        status: status.logged_in ? `Connected to ${serviceName}` : `Not logged in to ${serviceName}`
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error checking bridge status", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    };
+}
+export function createBridgeLogoutTool(options) {
+    const { config, logger, serviceName, serviceNameLower } = options;
+    const fetchBridge = createBridgeFetcher(config);
+    return {
+        name: `${serviceNameLower}-bridge-logout`,
+        description: `Log out from ${serviceName} through the mautrix bridge. This will disconnect your ${serviceName} account from the Matrix bridge.`,
+        schema: z.object({
+            user_id: z.string().optional().describe("Matrix user ID to log out (defaults to configured user)")
+        }),
+        async execute(args) {
+            if (!config.enabled) {
+                return JSON.stringify({
+                    success: false,
+                    error: `Mautrix ${serviceNameLower} bridge not configured. Set MAUTRIX_BRIDGE_URL and MAUTRIX_SHARED_SECRET.`
+                });
+            }
+            logger.info("Logging out from bridge", { user_id: args.user_id });
+            try {
+                const body = {};
+                if (args.user_id)
+                    body.user_id = args.user_id;
+                await fetchBridge("/v1/logout", {
+                    method: "POST",
+                    body: JSON.stringify(body)
+                });
+                return JSON.stringify({
+                    success: true,
+                    message: `Successfully logged out from ${serviceName} through the bridge`
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error logging out", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    };
+}
+export function createDiscordBridgeTools(options) {
+    const { config, logger } = options;
+    const fetchBridge = createBridgeFetcher(config);
+    const baseOptions = { ...options, serviceName: "Discord", serviceNameLower: "discord" };
+    const qrLoginTool = {
+        name: "discord-bridge-login-qr",
+        description: "Start QR code login flow for Discord through the mautrix bridge. This will generate a QR code that you can scan with the Discord mobile app to authenticate.",
+        schema: z.object({
+            user_id: z.string().optional().describe("Matrix user ID to log in (defaults to configured user)")
+        }),
+        async execute(args) {
+            if (!config.enabled) {
+                return JSON.stringify({
+                    success: false,
+                    error: "Mautrix discord bridge not configured. Set MAUTRIX_BRIDGE_URL and MAUTRIX_SHARED_SECRET."
+                });
+            }
+            logger.info("Starting QR login flow", { user_id: args.user_id });
+            try {
+                const body = {};
+                if (args.user_id)
+                    body.user_id = args.user_id;
+                const result = await fetchBridge("/v1/login/qr", {
+                    method: "POST",
+                    body: JSON.stringify(body)
+                });
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        status: result.status,
+                        qr_code: result.qr,
+                        instructions: [
+                            "1. Open the Discord mobile app",
+                            "2. Go to Settings > Scan QR Code",
+                            "3. Scan the QR code displayed above",
+                            "4. Approve the login request on your phone",
+                            "Note: If you encounter a CAPTCHA, you'll need to use token login instead"
+                        ]
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error starting QR login", { error: error instanceof Error ? error.message : String(error) });
+                const errorMsg = error instanceof Error ? error.message : String(error);
+                return JSON.stringify({
+                    success: false,
+                    error: errorMsg,
+                    fallback: errorMsg.includes("CAPTCHA") ? {
+                        message: "CAPTCHA detected. Use token login instead.",
+                        command: "Use discord-bridge-login-token with your Discord token"
+                    } : undefined
+                });
+            }
+        }
+    };
+    const tokenLoginTool = {
+        name: "discord-bridge-login-token",
+        description: "Log in to Discord through the mautrix bridge using a Discord token. Use this if QR login fails due to CAPTCHA.",
+        schema: z.object({
+            token: z.string().describe("Discord token (user token or bot token)"),
+            token_type: z.enum(["user", "bot"]).default("user").describe("Type of token: 'user' for personal account, 'bot' for bot account"),
+            user_id: z.string().optional().describe("Matrix user ID to log in (defaults to configured user)")
+        }),
+        async execute(args) {
+            if (!config.enabled) {
+                return JSON.stringify({
+                    success: false,
+                    error: "Mautrix discord bridge not configured. Set MAUTRIX_BRIDGE_URL and MAUTRIX_SHARED_SECRET."
+                });
+            }
+            logger.info("Starting token login", { token_type: args.token_type, user_id: args.user_id });
+            try {
+                const body = { token: args.token, type: args.token_type };
+                if (args.user_id)
+                    body.user_id = args.user_id;
+                const result = await fetchBridge("/v1/login/token", {
+                    method: "POST",
+                    body: JSON.stringify(body)
+                });
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        status: result.status || "Login successful",
+                        token_type: args.token_type,
+                        message: args.token_type === "bot"
+                            ? "Bot account connected. Add the bot to servers using OAuth2 URL."
+                            : "User account connected. You can now access your Discord servers through the bridge."
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error with token login", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    help: {
+                        user_token: {
+                            steps: [
+                                "1. Log into Discord in a browser (private window recommended)",
+                                "2. Open Developer Tools (F12 or Cmd+Shift+I)",
+                                "3. Go to Network tab, filter by 'api'",
+                                "4. Reload the page and click any successful request",
+                                "5. Find 'Authorization' header in Request Headers",
+                                "6. Copy the token value (without 'Bearer')"
+                            ]
+                        },
+                        bot_token: {
+                            steps: [
+                                "1. Go to https://discord.com/developers/applications",
+                                "2. Create or select your application",
+                                "3. Go to 'Bot' section",
+                                "4. Click 'Reset Token' and copy the new token"
+                            ]
+                        }
+                    }
+                });
+            }
+        }
+    };
+    const guildsTool = {
+        name: "discord-bridge-guilds",
+        description: "List Discord guilds/servers accessible through the mautrix bridge.",
+        schema: z.object({
+            user_id: z.string().optional().describe("Matrix user ID (defaults to configured user)")
+        }),
+        async execute(args) {
+            if (!config.enabled) {
+                return JSON.stringify({
+                    success: false,
+                    error: "Mautrix discord bridge not configured. Set MAUTRIX_BRIDGE_URL and MAUTRIX_SHARED_SECRET."
+                });
+            }
+            logger.info("Listing guilds through bridge", { user_id: args.user_id });
+            try {
+                const params = args.user_id ? `?user_id=${encodeURIComponent(args.user_id)}` : "";
+                const guilds = await fetchBridge(`/v1/guilds${params}`);
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        guilds: guilds.map(g => ({
+                            id: g.id,
+                            name: g.name,
+                            icon: g.icon ? `https://cdn.discordapp.com/icons/${g.id}/${g.icon}.png` : null
+                        })),
+                        count: guilds.length
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error listing guilds", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    };
+    const connectGuildTool = {
+        name: "discord-bridge-connect-guild",
+        description: "Bridge a Discord guild/server to Matrix. This creates Matrix rooms for the Discord channels.",
+        schema: z.object({
+            guild_id: z.string().describe("Discord guild ID to bridge"),
+            user_id: z.string().optional().describe("Matrix user ID (defaults to configured user)")
+        }),
+        async execute(args) {
+            if (!config.enabled) {
+                return JSON.stringify({
+                    success: false,
+                    error: "Mautrix discord bridge not configured. Set MAUTRIX_BRIDGE_URL and MAUTRIX_SHARED_SECRET."
+                });
+            }
+            logger.info("Connecting guild to bridge", { guild_id: args.guild_id, user_id: args.user_id });
+            try {
+                const body = { guild_id: args.guild_id };
+                if (args.user_id)
+                    body.user_id = args.user_id;
+                const result = await fetchBridge("/v1/guilds/bridge", {
+                    method: "POST",
+                    body: JSON.stringify(body)
+                });
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        guild_id: args.guild_id,
+                        matrix_space: result.room_id,
+                        channels_bridged: result.channels,
+                        message: "Guild connected. Discord channels are now bridged to Matrix rooms."
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error connecting guild", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    };
+    return [
+        createBridgeStatusTool(baseOptions),
+        qrLoginTool,
+        tokenLoginTool,
+        createBridgeLogoutTool(baseOptions),
+        guildsTool,
+        connectGuildTool
+    ];
+}
+export function createTelegramBridgeTools(options) {
+    const { config, logger } = options;
+    const fetchBridge = createBridgeFetcher(config);
+    const baseOptions = { ...options, serviceName: "Telegram", serviceNameLower: "telegram" };
+    const phoneLoginTool = {
+        name: "telegram-bridge-login-phone",
+        description: "Start phone number login flow for Telegram through the mautrix bridge. You will receive a code via Telegram.",
+        schema: z.object({
+            phone: z.string().describe("Phone number in international format (e.g., +1234567890)"),
+            user_id: z.string().optional().describe("Matrix user ID to log in (defaults to configured user)")
+        }),
+        async execute(args) {
+            if (!config.enabled) {
+                return JSON.stringify({
+                    success: false,
+                    error: "Mautrix telegram bridge not configured. Set MAUTRIX_BRIDGE_URL and MAUTRIX_SHARED_SECRET."
+                });
+            }
+            logger.info("Starting phone login flow", { user_id: args.user_id });
+            try {
+                const body = { phone: args.phone };
+                if (args.user_id)
+                    body.user_id = args.user_id;
+                const result = await fetchBridge("/v1/login/request_code", {
+                    method: "POST",
+                    body: JSON.stringify(body)
+                });
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        status: result.status || "code_requested",
+                        next_step: result.next_step || "enter_code",
+                        instructions: [
+                            "1. You will receive a code via Telegram (in-app notification or SMS)",
+                            "2. Use telegram-bridge-login-code to submit the code",
+                            "3. If 2FA is enabled, you'll need to provide your password afterwards"
+                        ]
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error starting phone login", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    };
+    const codeLoginTool = {
+        name: "telegram-bridge-login-code",
+        description: "Submit the verification code received via Telegram to complete login.",
+        schema: z.object({
+            code: z.string().describe("Verification code received via Telegram"),
+            user_id: z.string().optional().describe("Matrix user ID to log in (defaults to configured user)")
+        }),
+        async execute(args) {
+            if (!config.enabled) {
+                return JSON.stringify({
+                    success: false,
+                    error: "Mautrix telegram bridge not configured. Set MAUTRIX_BRIDGE_URL and MAUTRIX_SHARED_SECRET."
+                });
+            }
+            logger.info("Submitting verification code", { user_id: args.user_id });
+            try {
+                const body = { code: args.code };
+                if (args.user_id)
+                    body.user_id = args.user_id;
+                const result = await fetchBridge("/v1/login/send_code", {
+                    method: "POST",
+                    body: JSON.stringify(body)
+                });
+                if (result.next_step === "2fa" || result.status === "2fa_required") {
+                    return JSON.stringify({
+                        success: true,
+                        data: {
+                            status: "2fa_required",
+                            next_step: "password",
+                            message: "Two-factor authentication is enabled. Use telegram-bridge-login-2fa to submit your password."
+                        }
+                    }, null, 2);
+                }
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        status: result.status || "Login successful",
+                        message: "Successfully logged in to Telegram through the bridge."
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error submitting code", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    };
+    const twoFactorTool = {
+        name: "telegram-bridge-login-2fa",
+        description: "Submit 2FA password to complete Telegram login when two-factor authentication is enabled.",
+        schema: z.object({
+            password: z.string().describe("Your Telegram 2FA password"),
+            user_id: z.string().optional().describe("Matrix user ID to log in (defaults to configured user)")
+        }),
+        async execute(args) {
+            if (!config.enabled) {
+                return JSON.stringify({
+                    success: false,
+                    error: "Mautrix telegram bridge not configured. Set MAUTRIX_BRIDGE_URL and MAUTRIX_SHARED_SECRET."
+                });
+            }
+            logger.info("Submitting 2FA password", { user_id: args.user_id });
+            try {
+                const body = { password: args.password };
+                if (args.user_id)
+                    body.user_id = args.user_id;
+                const result = await fetchBridge("/v1/login/send_password", {
+                    method: "POST",
+                    body: JSON.stringify(body)
+                });
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        status: result.status || "Login successful",
+                        message: "Successfully logged in to Telegram with 2FA."
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error submitting 2FA password", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    };
+    const botTokenTool = {
+        name: "telegram-bridge-login-bot",
+        description: "Log in to Telegram through the mautrix bridge using a bot token. More limited than user accounts but provides privacy benefits.",
+        schema: z.object({
+            token: z.string().describe("Telegram bot token from @BotFather"),
+            user_id: z.string().optional().describe("Matrix user ID to log in (defaults to configured user)")
+        }),
+        async execute(args) {
+            if (!config.enabled) {
+                return JSON.stringify({
+                    success: false,
+                    error: "Mautrix telegram bridge not configured. Set MAUTRIX_BRIDGE_URL and MAUTRIX_SHARED_SECRET."
+                });
+            }
+            logger.info("Starting bot token login", { user_id: args.user_id });
+            try {
+                const body = { token: args.token };
+                if (args.user_id)
+                    body.user_id = args.user_id;
+                const result = await fetchBridge("/v1/login/bot_token", {
+                    method: "POST",
+                    body: JSON.stringify(body)
+                });
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        status: result.status || "Login successful",
+                        message: "Bot account connected. Note: Bot accounts have limited functionality compared to user accounts."
+                    },
+                    limitations: [
+                        "Cannot join groups without being added",
+                        "Cannot initiate conversations with users",
+                        "Cannot access message history before joining"
+                    ]
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error with bot token login", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    help: {
+                        steps: [
+                            "1. Open Telegram and search for @BotFather",
+                            "2. Send /newbot to create a new bot or /token to get existing bot's token",
+                            "3. Copy the token (format: 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ)"
+                        ]
+                    }
+                });
+            }
+        }
+    };
+    const chatsTool = {
+        name: "telegram-bridge-chats",
+        description: "List Telegram chats accessible through the mautrix bridge.",
+        schema: z.object({
+            user_id: z.string().optional().describe("Matrix user ID (defaults to configured user)")
+        }),
+        async execute(args) {
+            if (!config.enabled) {
+                return JSON.stringify({
+                    success: false,
+                    error: "Mautrix telegram bridge not configured. Set MAUTRIX_BRIDGE_URL and MAUTRIX_SHARED_SECRET."
+                });
+            }
+            logger.info("Listing chats through bridge", { user_id: args.user_id });
+            try {
+                const params = args.user_id ? `?user_id=${encodeURIComponent(args.user_id)}` : "";
+                const chats = await fetchBridge(`/v1/chats${params}`);
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        chats: chats.map(c => ({
+                            id: c.id,
+                            name: c.name,
+                            type: c.type || "unknown"
+                        })),
+                        count: chats.length
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error listing chats", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    };
+    const bridgeChatTool = {
+        name: "telegram-bridge-connect-chat",
+        description: "Bridge a Telegram chat to Matrix. This creates a Matrix room for the Telegram chat.",
+        schema: z.object({
+            chat_id: z.union([z.string(), z.number()]).describe("Telegram chat ID to bridge"),
+            user_id: z.string().optional().describe("Matrix user ID (defaults to configured user)")
+        }),
+        async execute(args) {
+            if (!config.enabled) {
+                return JSON.stringify({
+                    success: false,
+                    error: "Mautrix telegram bridge not configured. Set MAUTRIX_BRIDGE_URL and MAUTRIX_SHARED_SECRET."
+                });
+            }
+            logger.info("Connecting chat to bridge", { chat_id: args.chat_id, user_id: args.user_id });
+            try {
+                const body = { chat_id: args.chat_id };
+                if (args.user_id)
+                    body.user_id = args.user_id;
+                const result = await fetchBridge("/v1/pm/" + args.chat_id, {
+                    method: "POST",
+                    body: JSON.stringify(body)
+                });
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        chat_id: args.chat_id,
+                        matrix_room: result.room_id,
+                        message: "Chat connected. Telegram messages will now be bridged to the Matrix room."
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error connecting chat", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    };
+    return [
+        createBridgeStatusTool(baseOptions),
+        phoneLoginTool,
+        codeLoginTool,
+        twoFactorTool,
+        botTokenTool,
+        createBridgeLogoutTool(baseOptions),
+        chatsTool,
+        bridgeChatTool
+    ];
+}
+export const BRIDGE_ENV_VARS = {
+    required: [],
+    optional: [
+        {
+            name: "MAUTRIX_BRIDGE_URL",
+            description: "URL of your mautrix bridge instance (e.g., https://bridge.example.com). Enables Matrix bridge integration."
+        },
+        {
+            name: "MAUTRIX_SHARED_SECRET",
+            description: "Shared secret for mautrix provisioning API. Found in bridge config under provisioning.shared_secret"
+        }
+    ]
+};
+const DEFAULT_PORTS = {
+    telegram: 29317,
+    discord: 29334,
+    whatsapp: 29318,
+    signal: 29328,
+    slack: 29335
+};
+function getDefaultDataDir(bridgeType) {
+    const homeDir = process.env.HOME || process.env.USERPROFILE || "~";
+    return join(homeDir, ".mautrix", bridgeType);
+}
+function getContainerName(bridgeType) {
+    return `mautrix-${bridgeType}`;
+}
+function getImageName(bridgeType, tag) {
+    return `dock.mau.dev/mautrix/${bridgeType}:${tag}`;
+}
+export function createDockerBridgeTools(options) {
+    const { bridgeType, logger, dataDir, imageTag = "latest" } = options;
+    const defaultDataDir = dataDir || getDefaultDataDir(bridgeType);
+    const containerName = getContainerName(bridgeType);
+    const imageName = getImageName(bridgeType, imageTag);
+    const defaultPort = DEFAULT_PORTS[bridgeType];
+    const initBridgeTool = {
+        name: `${bridgeType}-docker-init`,
+        description: `Initialize mautrix-${bridgeType} bridge by pulling the Docker image and generating initial configuration. This is the first step in setting up the bridge.`,
+        schema: z.object({
+            data_dir: z.string().optional().describe(`Directory to store bridge data (default: ~/.mautrix/${bridgeType})`),
+            image_tag: z.string().optional().default("latest").describe("Docker image tag to use (e.g., 'latest', 'v0.15.0')")
+        }),
+        async execute(args) {
+            const targetDir = args.data_dir || defaultDataDir;
+            const tag = args.image_tag || imageTag;
+            const image = getImageName(bridgeType, tag);
+            logger.info("Initializing bridge", { bridgeType, targetDir, image });
+            try {
+                if (!existsSync(targetDir)) {
+                    mkdirSync(targetDir, { recursive: true });
+                    logger.info("Created data directory", { targetDir });
+                }
+                logger.info("Pulling Docker image", { image });
+                const { stdout: pullOutput } = await execAsync(`docker pull ${image}`);
+                logger.info("Generating initial configuration");
+                const { stdout: configOutput, stderr: configStderr } = await execAsync(`docker run --rm -v "${targetDir}:/data:z" ${image}`, { timeout: 60000 });
+                const configPath = join(targetDir, "config.yaml");
+                const configExists = existsSync(configPath);
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        bridge_type: bridgeType,
+                        data_dir: targetDir,
+                        image: image,
+                        config_generated: configExists,
+                        config_path: configPath,
+                        next_steps: [
+                            `1. Edit the configuration file at ${configPath}`,
+                            "2. Configure your Matrix homeserver address (avoid using 'localhost' inside Docker)",
+                            "3. Set up database connection (SQLite works for testing, PostgreSQL recommended for production)",
+                            "4. Configure Telegram API credentials (api_id and api_hash from my.telegram.org)",
+                            `5. Run ${bridgeType}-docker-generate-registration to create the appservice registration`,
+                            `6. Register the bridge with your homeserver`,
+                            `7. Run ${bridgeType}-docker-start to start the bridge`
+                        ],
+                        output: configOutput || configStderr
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error initializing bridge", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    help: {
+                        docker_not_found: "Ensure Docker is installed and running",
+                        permission_denied: "You may need to run with sudo or add your user to the docker group"
+                    }
+                });
+            }
+        }
+    };
+    const generateRegistrationTool = {
+        name: `${bridgeType}-docker-generate-registration`,
+        description: `Generate the appservice registration file for mautrix-${bridgeType}. Run this after configuring config.yaml.`,
+        schema: z.object({
+            data_dir: z.string().optional().describe(`Directory containing bridge data (default: ~/.mautrix/${bridgeType})`)
+        }),
+        async execute(args) {
+            const targetDir = args.data_dir || defaultDataDir;
+            logger.info("Generating registration", { bridgeType, targetDir });
+            try {
+                const { stdout, stderr } = await execAsync(`docker run --rm -v "${targetDir}:/data:z" ${imageName}`, { timeout: 60000 });
+                const registrationPath = join(targetDir, "registration.yaml");
+                const registrationExists = existsSync(registrationPath);
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        bridge_type: bridgeType,
+                        registration_generated: registrationExists,
+                        registration_path: registrationPath,
+                        next_steps: registrationExists ? [
+                            `1. Copy ${registrationPath} to your Matrix homeserver's appservice directory`,
+                            "2. Add the registration to your homeserver config (e.g., Synapse's app_service_config_files)",
+                            "3. Restart your Matrix homeserver",
+                            `4. Run ${bridgeType}-docker-start to start the bridge`
+                        ] : [
+                            "Registration file not found. Check the configuration and try again."
+                        ],
+                        output: stdout || stderr
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error generating registration", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    };
+    const startBridgeTool = {
+        name: `${bridgeType}-docker-start`,
+        description: `Start the mautrix-${bridgeType} bridge Docker container.`,
+        schema: z.object({
+            data_dir: z.string().optional().describe(`Directory containing bridge data (default: ~/.mautrix/${bridgeType})`),
+            port: z.number().optional().describe(`Port to expose the bridge on (default: ${defaultPort})`),
+            network: z.string().optional().describe("Docker network to connect to (e.g., 'synapse-net' for same network as homeserver)"),
+            detach: z.boolean().optional().default(true).describe("Run container in background (default: true)")
+        }),
+        async execute(args) {
+            const targetDir = args.data_dir || defaultDataDir;
+            const port = args.port || defaultPort;
+            const detachFlag = args.detach !== false ? "-d" : "";
+            logger.info("Starting bridge container", { bridgeType, targetDir, port });
+            try {
+                try {
+                    await execAsync(`docker rm -f ${containerName}`);
+                }
+                catch {
+                    // Container doesn't exist, that's fine
+                }
+                let cmd = `docker run ${detachFlag} --restart unless-stopped --name ${containerName} -v "${targetDir}:/data:z"`;
+                if (args.network) {
+                    cmd += ` --network=${args.network}`;
+                }
+                else {
+                    cmd += ` -p ${port}:${port}`;
+                }
+                cmd += ` ${imageName}`;
+                const { stdout, stderr } = await execAsync(cmd);
+                const { stdout: statusOutput } = await execAsync(`docker ps --filter name=${containerName} --format "{{.Status}}"`);
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        bridge_type: bridgeType,
+                        container_name: containerName,
+                        status: statusOutput.trim() || "starting",
+                        port: args.network ? "via network" : port,
+                        network: args.network || "bridge (default)",
+                        next_steps: [
+                            `Check logs with: docker logs ${containerName}`,
+                            `Or use ${bridgeType}-docker-logs tool`,
+                            "Connect to the bridge using the provisioning API or bot commands"
+                        ],
+                        container_id: stdout.trim()
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error starting bridge", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    };
+    const stopBridgeTool = {
+        name: `${bridgeType}-docker-stop`,
+        description: `Stop the mautrix-${bridgeType} bridge Docker container.`,
+        schema: z.object({
+            remove: z.boolean().optional().default(false).describe("Also remove the container after stopping")
+        }),
+        async execute(args) {
+            logger.info("Stopping bridge container", { bridgeType, remove: args.remove });
+            try {
+                await execAsync(`docker stop ${containerName}`);
+                if (args.remove) {
+                    await execAsync(`docker rm ${containerName}`);
+                }
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        bridge_type: bridgeType,
+                        container_name: containerName,
+                        action: args.remove ? "stopped and removed" : "stopped",
+                        message: `Bridge container ${args.remove ? "stopped and removed" : "stopped"}. Use ${bridgeType}-docker-start to restart.`
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error stopping bridge", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    };
+    const restartBridgeTool = {
+        name: `${bridgeType}-docker-restart`,
+        description: `Restart the mautrix-${bridgeType} bridge Docker container.`,
+        schema: z.object({}),
+        async execute() {
+            logger.info("Restarting bridge container", { bridgeType });
+            try {
+                await execAsync(`docker restart ${containerName}`);
+                const { stdout: statusOutput } = await execAsync(`docker ps --filter name=${containerName} --format "{{.Status}}"`);
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        bridge_type: bridgeType,
+                        container_name: containerName,
+                        status: statusOutput.trim(),
+                        message: "Bridge container restarted successfully"
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error restarting bridge", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    };
+    const statusTool = {
+        name: `${bridgeType}-docker-status`,
+        description: `Check the status of the mautrix-${bridgeType} Docker container.`,
+        schema: z.object({}),
+        async execute() {
+            logger.info("Checking bridge container status", { bridgeType });
+            try {
+                const { stdout: containerInfo } = await execAsync(`docker inspect ${containerName} --format '{"state":"{{.State.Status}}","running":{{.State.Running}},"started":"{{.State.StartedAt}}","health":"{{if .State.Health}}{{.State.Health.Status}}{{else}}no healthcheck{{end}}"}'`).catch(() => ({ stdout: "" }));
+                if (!containerInfo.trim()) {
+                    return JSON.stringify({
+                        success: true,
+                        data: {
+                            bridge_type: bridgeType,
+                            container_name: containerName,
+                            exists: false,
+                            status: "not found",
+                            message: `Container ${containerName} does not exist. Use ${bridgeType}-docker-init to set up the bridge.`
+                        }
+                    }, null, 2);
+                }
+                const info = JSON.parse(containerInfo);
+                const { stdout: portsInfo } = await execAsync(`docker port ${containerName} 2>/dev/null || echo ""`).catch(() => ({ stdout: "" }));
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        bridge_type: bridgeType,
+                        container_name: containerName,
+                        exists: true,
+                        state: info.state,
+                        running: info.running,
+                        started_at: info.started,
+                        health: info.health,
+                        ports: portsInfo.trim() || "none exposed"
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error checking bridge status", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    };
+    const logsTool = {
+        name: `${bridgeType}-docker-logs`,
+        description: `View logs from the mautrix-${bridgeType} Docker container.`,
+        schema: z.object({
+            lines: z.number().optional().default(50).describe("Number of log lines to show (default: 50)"),
+            follow: z.boolean().optional().default(false).describe("Follow log output (not recommended for tool use)")
+        }),
+        async execute(args) {
+            logger.info("Fetching bridge logs", { bridgeType, lines: args.lines });
+            try {
+                const { stdout, stderr } = await execAsync(`docker logs --tail ${args.lines} ${containerName} 2>&1`, { timeout: 30000 });
+                const logs = stdout || stderr;
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        bridge_type: bridgeType,
+                        container_name: containerName,
+                        lines_requested: args.lines,
+                        logs: logs.split("\n").slice(-args.lines)
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error fetching logs", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    };
+    const updateBridgeTool = {
+        name: `${bridgeType}-docker-update`,
+        description: `Update the mautrix-${bridgeType} Docker image to the latest version and restart the container.`,
+        schema: z.object({
+            data_dir: z.string().optional().describe(`Directory containing bridge data (default: ~/.mautrix/${bridgeType})`),
+            image_tag: z.string().optional().default("latest").describe("Docker image tag to pull")
+        }),
+        async execute(args) {
+            const targetDir = args.data_dir || defaultDataDir;
+            const tag = args.image_tag || imageTag;
+            const image = getImageName(bridgeType, tag);
+            logger.info("Updating bridge", { bridgeType, image });
+            try {
+                logger.info("Pulling latest image");
+                const { stdout: pullOutput } = await execAsync(`docker pull ${image}`);
+                const wasRunning = await execAsync(`docker ps -q --filter name=${containerName}`)
+                    .then(r => !!r.stdout.trim())
+                    .catch(() => false);
+                if (wasRunning) {
+                    logger.info("Stopping current container");
+                    await execAsync(`docker stop ${containerName}`);
+                    await execAsync(`docker rm ${containerName}`);
+                    logger.info("Starting updated container");
+                    await execAsync(`docker run -d --restart unless-stopped --name ${containerName} -v "${targetDir}:/data:z" -p ${defaultPort}:${defaultPort} ${image}`);
+                }
+                return JSON.stringify({
+                    success: true,
+                    data: {
+                        bridge_type: bridgeType,
+                        image: image,
+                        updated: true,
+                        restarted: wasRunning,
+                        message: wasRunning
+                            ? "Bridge updated and restarted with new image"
+                            : "Image pulled. Container was not running. Use start command to run with new image."
+                    }
+                }, null, 2);
+            }
+            catch (error) {
+                logger.error("Error updating bridge", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    };
+    const configTool = {
+        name: `${bridgeType}-docker-config`,
+        description: `View or get path to the mautrix-${bridgeType} bridge configuration file.`,
+        schema: z.object({
+            data_dir: z.string().optional().describe(`Directory containing bridge data (default: ~/.mautrix/${bridgeType})`),
+            show_content: z.boolean().optional().default(false).describe("Show the actual config content (may contain secrets)")
+        }),
+        async execute(args) {
+            const targetDir = args.data_dir || defaultDataDir;
+            const configPath = join(targetDir, "config.yaml");
+            logger.info("Getting bridge config", { bridgeType, configPath });
+            try {
+                const configExists = existsSync(configPath);
+                if (!configExists) {
+                    return JSON.stringify({
+                        success: false,
+                        error: "Configuration file not found",
+                        help: {
+                            message: `Run ${bridgeType}-docker-init first to generate the configuration`,
+                            expected_path: configPath
+                        }
+                    });
+                }
+                const result = {
+                    success: true,
+                    data: {
+                        bridge_type: bridgeType,
+                        config_path: configPath,
+                        exists: true
+                    }
+                };
+                if (args.show_content) {
+                    const content = readFileSync(configPath, "utf-8");
+                    result.data.content = content;
+                }
+                return JSON.stringify(result, null, 2);
+            }
+            catch (error) {
+                logger.error("Error reading config", { error: error instanceof Error ? error.message : String(error) });
+                return JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    };
+    return [
+        initBridgeTool,
+        generateRegistrationTool,
+        startBridgeTool,
+        stopBridgeTool,
+        restartBridgeTool,
+        statusTool,
+        logsTool,
+        updateBridgeTool,
+        configTool
+    ];
+}
+//# sourceMappingURL=mautrix-bridge.js.map