@deadragdoll/tellymcp 0.0.13 → 0.0.15

package/dist/services/features/telegram-mcp/src/shared/integrations/terminal/ptyRegistry.js

@@ -54,6 +54,8 @@ exports.resizePtyTarget = resizePtyTarget;
 exports.subscribePtyTarget = subscribePtyTarget;
 exports.stopPtyTarget = stopPtyTarget;
 exports.stopAllPtyTargets = stopAllPtyTargets;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_pty_1 = require("node-pty");
 const XtermHeadless = __importStar(require("@xterm/headless"));
@@ -73,6 +75,97 @@ function buildExitLine(record) {
     }
     return `${parts.join(" ")}]`;
 }
+function sanitizeFileNameSegment(value) {
+    const sanitized = value.trim().replace(/[^a-zA-Z0-9._-]+/gu, "-");
+    return sanitized || "session";
+}
+function shellSingleQuote(value) {
+    return `'${value.replace(/'/gu, `'\\''`)}'`;
+}
+function buildContextPromptPrefix(record) {
+    return `[TELLY ${record.sessionId}]`;
+}
+function buildContextEnv(record) {
+    return {
+        ...process.env,
+        TELLYMCP_TERMINAL_CONTEXT: "1",
+        TELLYMCP_SESSION_ID: record.sessionId,
+        TELLYMCP_TERMINAL_TARGET: record.target,
+        TELLYMCP_TERMINAL_CWD: record.cwd,
+    };
+}
+function prepareBashLaunch(record) {
+    const tempDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "tellymcp-pty-bash-"));
+    const rcPath = node_path_1.default.join(tempDir, `${sanitizeFileNameSegment(record.sessionId)}.bashrc`);
+    const promptPrefix = buildContextPromptPrefix(record);
+    const script = [
+        'if [ -r "$HOME/.profile" ]; then . "$HOME/.profile"; fi',
+        'if [ -r "$HOME/.bashrc" ]; then . "$HOME/.bashrc"; fi',
+        `export TELLYMCP_TERMINAL_CONTEXT=${shellSingleQuote("1")}`,
+        `export TELLYMCP_SESSION_ID=${shellSingleQuote(record.sessionId)}`,
+        `export TELLYMCP_TERMINAL_TARGET=${shellSingleQuote(record.target)}`,
+        `export TELLYMCP_TERMINAL_CWD=${shellSingleQuote(record.cwd)}`,
+        `PS1=${shellSingleQuote(`${promptPrefix} \\u@\\h:\\w\\$ `)}`,
+    ].join("\n");
+    node_fs_1.default.writeFileSync(rcPath, `${script}\n`, "utf8");
+    return {
+        args: ["--rcfile", rcPath, "-i"],
+        env: buildContextEnv(record),
+        tempPaths: [tempDir],
+    };
+}
+function prepareZshLaunch(record) {
+    const tempDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "tellymcp-pty-zsh-"));
+    const promptPrefix = buildContextPromptPrefix(record);
+    node_fs_1.default.writeFileSync(node_path_1.default.join(tempDir, ".zshenv"), [
+        'if [[ -r "$HOME/.zshenv" ]]; then source "$HOME/.zshenv"; fi',
+        `export TELLYMCP_TERMINAL_CONTEXT=${shellSingleQuote("1")}`,
+        `export TELLYMCP_SESSION_ID=${shellSingleQuote(record.sessionId)}`,
+        `export TELLYMCP_TERMINAL_TARGET=${shellSingleQuote(record.target)}`,
+        `export TELLYMCP_TERMINAL_CWD=${shellSingleQuote(record.cwd)}`,
+        "",
+    ].join("\n"), "utf8");
+    node_fs_1.default.writeFileSync(node_path_1.default.join(tempDir, ".zshrc"), [
+        'if [[ -r "$HOME/.zprofile" ]]; then source "$HOME/.zprofile"; fi',
+        'if [[ -r "$HOME/.zshrc" ]]; then source "$HOME/.zshrc"; fi',
+        `PROMPT=${shellSingleQuote(`${promptPrefix} %n@%m:%~%# `)}`,
+        "RPROMPT=''",
+        "",
+    ].join("\n"), "utf8");
+    return {
+        args: ["-i"],
+        env: {
+            ...buildContextEnv(record),
+            ZDOTDIR: tempDir,
+        },
+        tempPaths: [tempDir],
+    };
+}
+function prepareShellLaunch(record) {
+    const shellName = getShellDisplayName(record.shell).toLowerCase();
+    if (shellName === "bash") {
+        return prepareBashLaunch(record);
+    }
+    if (shellName === "zsh") {
+        return prepareZshLaunch(record);
+    }
+    return {
+        args: [],
+        env: buildContextEnv(record),
+        tempPaths: [],
+    };
+}
+function cleanupRecordTempPaths(record) {
+    for (const tempPath of record.tempPaths) {
+        try {
+            node_fs_1.default.rmSync(tempPath, { recursive: true, force: true });
+        }
+        catch {
+            // ignore cleanup failures
+        }
+    }
+    record.tempPaths = [];
+}
 function createHeadlessTerminal(config) {
     return new XtermHeadless.Terminal({
         cols: config.cols,
@@ -97,13 +190,16 @@ function createSessionRecord(config, input) {
         pendingWrite: Promise.resolve(),
         pty: null,
         exited: false,
+        tempPaths: [],
     };
-    const pty = (0, node_pty_1.spawn)(record.shell, [], {
+    const launch = prepareShellLaunch(record);
+    record.tempPaths = [...launch.tempPaths];
+    const pty = (0, node_pty_1.spawn)(record.shell, launch.args, {
         name: "xterm-color",
         cols: record.cols,
         rows: record.rows,
         cwd: record.cwd,
-        env: process.env,
+        env: launch.env,
     });
     pty.onData((data) => {
         record.pendingWrite = record.pendingWrite.then(() => new Promise((resolve) => {
@@ -115,6 +211,7 @@ function createSessionRecord(config, input) {
         record.exited = true;
         record.exitCode = exitCode;
         record.signal = signal;
+        cleanupRecordTempPaths(record);
         record.pendingWrite = record.pendingWrite.then(() => new Promise((resolve) => {
             record.terminal.writeln(buildExitLine(record), resolve);
         }));
@@ -533,6 +630,7 @@ function stopPtyTarget(target) {
     record.pty?.kill();
     record.pty = null;
     record.exited = true;
+    cleanupRecordTempPaths(record);
     record.terminal.dispose();
     return true;
 }

package/dist/services/features/telegram-mcp/src/shared/lib/bodyLimits.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readLimitedJsonBody = exports.assertSerializedBodySize = exports.assertStringBodySize = exports.assertBodySize = exports.isBodySizeLimitError = exports.BodySizeLimitError = exports.MAX_BASE64_SOURCE_SIZE_BYTES = exports.MAX_BODY_SIZE_BYTES = exports.MAX_BODY_SIZE = void 0;
+exports.MAX_BODY_SIZE = 16;
+exports.MAX_BODY_SIZE_BYTES = exports.MAX_BODY_SIZE * 1024 * 1024;
+exports.MAX_BASE64_SOURCE_SIZE_BYTES = Math.floor((exports.MAX_BODY_SIZE_BYTES * 3) / 4);
+class BodySizeLimitError extends Error {
+    actualBytes;
+    maxBytes;
+    statusCode = 413;
+    constructor(actualBytes, maxBytes = exports.MAX_BODY_SIZE_BYTES) {
+        const maxMiB = maxBytes / (1024 * 1024);
+        super(`Body size ${actualBytes} bytes exceeds the ${maxMiB} MiB limit.`);
+        this.actualBytes = actualBytes;
+        this.maxBytes = maxBytes;
+        this.name = "BodySizeLimitError";
+    }
+}
+exports.BodySizeLimitError = BodySizeLimitError;
+const isBodySizeLimitError = (error) => error instanceof BodySizeLimitError;
+exports.isBodySizeLimitError = isBodySizeLimitError;
+const assertBodySize = (actualBytes, maxBytes = exports.MAX_BODY_SIZE_BYTES) => {
+    if (actualBytes > maxBytes) {
+        throw new BodySizeLimitError(actualBytes, maxBytes);
+    }
+};
+exports.assertBodySize = assertBodySize;
+const assertStringBodySize = (value, maxBytes = exports.MAX_BODY_SIZE_BYTES) => {
+    (0, exports.assertBodySize)(Buffer.byteLength(value, "utf8"), maxBytes);
+};
+exports.assertStringBodySize = assertStringBodySize;
+const assertSerializedBodySize = (value) => {
+    if (value === undefined) {
+        return;
+    }
+    (0, exports.assertStringBodySize)(JSON.stringify(value));
+};
+exports.assertSerializedBodySize = assertSerializedBodySize;
+const readLimitedJsonBody = async (req) => {
+    const contentLength = req.headers["content-length"];
+    if (typeof contentLength === "string" && /^\d+$/u.test(contentLength)) {
+        (0, exports.assertBodySize)(Number(contentLength));
+    }
+    const chunks = [];
+    let totalBytes = 0;
+    for await (const chunk of req) {
+        const buffer = Buffer.isBuffer(chunk)
+            ? chunk
+            : Buffer.from(chunk);
+        totalBytes += buffer.byteLength;
+        (0, exports.assertBodySize)(totalBytes);
+        chunks.push(buffer);
+    }
+    if (chunks.length === 0) {
+        return undefined;
+    }
+    const raw = Buffer.concat(chunks, totalBytes).toString("utf8").trim();
+    if (!raw) {
+        return undefined;
+    }
+    return JSON.parse(raw);
+};
+exports.readLimitedJsonBody = readLimitedJsonBody;

package/dist/services/features/telegram-mcp/src/shared/lib/gatewayAuth.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isGatewayAuthorizationValid = isGatewayAuthorizationValid;
+const node_crypto_1 = require("node:crypto");
+function digest(value) {
+    return (0, node_crypto_1.createHash)("sha256").update(value, "utf8").digest();
+}
+function isGatewayAuthorizationValid(authorization, authToken) {
+    if (typeof authorization !== "string" || !authToken) {
+        return false;
+    }
+    return (0, node_crypto_1.timingSafeEqual)(digest(authorization), digest(`Bearer ${authToken}`));
+}

package/dist/services/features/telegram-mcp/src/shared/lib/gatewayScope.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeGatewayToken = normalizeGatewayToken;
-exports.gatewayTokenToScopeKey = gatewayTokenToScopeKey;
+exports.gatewayScopeTokenToScopeKey = gatewayScopeTokenToScopeKey;
 exports.resolveGatewayScopeKey = resolveGatewayScopeKey;
 const node_crypto_1 = require("node:crypto");
 function normalizeGatewayToken(value) {
@@ -11,13 +11,13 @@ function normalizeGatewayToken(value) {
     const token = value.trim();
     return token ? token : null;
 }
-function gatewayTokenToScopeKey(token) {
+function gatewayScopeTokenToScopeKey(token) {
     return (0, node_crypto_1.createHash)("sha256").update(token).digest("hex");
 }
 function resolveGatewayScopeKey(input) {
-    const gatewayToken = normalizeGatewayToken(input.gateway_token);
-    if (gatewayToken) {
-        return gatewayTokenToScopeKey(gatewayToken);
+    const gatewayScopeToken = normalizeGatewayToken(input.gateway_token);
+    if (gatewayScopeToken) {
+        return gatewayScopeTokenToScopeKey(gatewayScopeToken);
     }
     const scopeKey = normalizeGatewayToken(input.scope_key);
     return scopeKey;

package/dist/services/features/telegram-mcp/src/shared/lib/project-identity/projectIdentity.js

@@ -117,6 +117,10 @@ function readSessionMarkerState(inputCwd, logger) {
                 parsed.last_notified_tools_hash.trim()
                 ? { lastNotifiedToolsHash: parsed.last_notified_tools_hash.trim() }
                 : {}),
+            ...(typeof parsed.gateway_client_uuid === "string" &&
+                parsed.gateway_client_uuid.trim()
+                ? { gatewayClientUuid: parsed.gateway_client_uuid.trim() }
+                : {}),
             ...(typeof parsed.updated_at === "string" && parsed.updated_at.trim()
                 ? { updatedAt: parsed.updated_at.trim() }
                 : {}),
@@ -166,6 +170,12 @@ function writeSessionMarkerState(input) {
                 : current?.lastNotifiedToolsHash
                     ? { last_notified_tools_hash: current.lastNotifiedToolsHash }
                     : {}),
+            ...(typeof input.gatewayClientUuid === "string" &&
+                input.gatewayClientUuid.trim()
+                ? { gateway_client_uuid: input.gatewayClientUuid.trim() }
+                : current?.gatewayClientUuid
+                    ? { gateway_client_uuid: current.gatewayClientUuid }
+                    : {}),
             created_at: now,
             updated_at: now,
             ...(current ? { first_seen_local_session_id: current.localSessionId } : {}),

package/dist/services/features/telegram-mcp/src/shared/lib/time/localTimestamp.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatLocalTimestamp = formatLocalTimestamp;
+exports.formatLocalDateSegment = formatLocalDateSegment;
+exports.formatLocalTimeSegment = formatLocalTimeSegment;
+exports.formatLocalTimestampForFileName = formatLocalTimestampForFileName;
+function padNumber(value, length = 2) {
+    return String(value).padStart(length, "0");
+}
+function formatLocalTimestamp(date = new Date()) {
+    return `${date.getFullYear()}-${padNumber(date.getMonth() + 1)}-${padNumber(date.getDate())}T${padNumber(date.getHours())}:${padNumber(date.getMinutes())}:${padNumber(date.getSeconds())}.${padNumber(date.getMilliseconds(), 3)}`;
+}
+function formatLocalDateSegment(date = new Date()) {
+    return `${date.getFullYear()}-${padNumber(date.getMonth() + 1)}-${padNumber(date.getDate())}`;
+}
+function formatLocalTimeSegment(date = new Date()) {
+    return `${padNumber(date.getHours())}-${padNumber(date.getMinutes())}-${padNumber(date.getSeconds())}`;
+}
+function formatLocalTimestampForFileName(date = new Date()) {
+    return formatLocalTimestamp(date).replace(/[:.]/gu, "-");
+}

package/docs/CHAT_CONNECTOR.md

@@ -0,0 +1,134 @@
+# ChatGPT and Claude connector
+
+TellyMCP can expose its Streamable HTTP MCP endpoint to ChatGPT and Claude
+through an OAuth 2.0 authorization-code facade with PKCE. The facade coexists
+with `MCP_HTTP_BEARER_TOKEN`; existing internal clients can continue to use the
+static bearer token.
+
+## Configure the gateway
+
+Add the following to the gateway environment file:
+
+```bash
+TELLYMCP_PUBLIC_URL=https://mcp.example.com/api
+TELLYMCP_OAUTH_ISSUER=https://mcp.example.com/api
+TELLYMCP_OAUTH_AUDIENCE=https://mcp.example.com/api
+TELLYMCP_MAGIC_TOKEN=replace_with_a_private_human_login_token
+TELLYMCP_OAUTH_PRIVATE_KEY_PEM="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
+```
+
+Generate the stable signing key with:
+
+```bash
+tellymcp oauth key
+```
+
+The command prints a dotenv-ready `TELLYMCP_OAUTH_PRIVATE_KEY_PEM` assignment.
+If the private key is omitted, TellyMCP generates an ephemeral key and existing
+OAuth access tokens stop working after a restart.
+
+For a hashed magic token, configure
+`TELLYMCP_MAGIC_TOKEN_HASH=sha256:<64-hex-digest>` instead of the raw token.
+Never configure both forms.
+
+Optional restrictions:
+
+```bash
+TELLYMCP_OAUTH_CLIENT_ID=tellymcp
+TELLYMCP_OAUTH_CLIENT_SECRET=replace_with_client_secret
+TELLYMCP_ALLOWED_REDIRECT_URIS=https://chatgpt.com/connector/oauth/...,https://claude.ai/api/mcp/auth_callback
+TELLYMCP_AUTH_CODE_TTL_SECONDS=300
+TELLYMCP_OAUTH_SCOPES=tellymcp:read tellymcp:write
+TELLYMCP_OAUTH_KEY_ID=tellymcp-oauth
+```
+
+OAuth is enabled when a connector identity, credential, redirect, or signing-key
+setting is present. `TELLYMCP_PUBLIC_URL` and one magic-token form are then
+required. Redirect URIs are matched exactly when the allowlist is configured.
+
+## Reverse proxy
+
+Proxy all `/api/` routes to TellyMCP and disable response buffering on
+`/api/mcp`. Claude also needs root path-insertion discovery routes such as:
+
+```text
+/.well-known/oauth-authorization-server/api
+/.well-known/openid-configuration/api
+/.well-known/oauth-protected-resource/api/mcp
+```
+
+The complete Nginx example is in `docs/tellymcp.gw.conf`.
+
+## Connect the chat host
+
+Use the concrete MCP endpoint in the host's `Connection` field:
+
+```text
+https://mcp.example.com/api/mcp
+```
+
+Do not enter `https://mcp.example.com/api` as the connection URL. That URL is
+the OAuth issuer/audience base, not an MCP endpoint. With the correct
+connection URL, discovery may legitimately show two related resources:
+
+```text
+OAuth issuer/audience: https://mcp.example.com/api
+MCP resource:          https://mcp.example.com/api/mcp
+```
+
+For the production deployment used while implementing this feature, the
+working ChatGPT values are:
+
+```text
+Connection:                https://drd.undoo.ru/api/mcp
+Authorization server base: https://drd.undoo.ru/api
+Resource:                  https://drd.undoo.ru/api/mcp
+OIDC configuration URL:    https://drd.undoo.ru/.well-known/openid-configuration/api
+```
+
+The `/api` suffix in the root discovery URL is expected RFC 8414
+path-insertion behavior for an issuer whose path is `/api`.
+
+Do not give the host `MCP_HTTP_BEARER_TOKEN` or the magic token. The magic token
+is entered only into the authorization page opened by the host. If a client ID
+or client secret is configured in the host, it must match the gateway values.
+
+TellyMCP tool names already use Claude-compatible letters, digits, and
+underscores, and the tools publish output schemas.
+
+## Verify before connecting
+
+```bash
+curl -fsS https://mcp.example.com/api/.well-known/oauth-protected-resource/mcp
+curl -fsS https://mcp.example.com/api/.well-known/oauth-authorization-server
+curl -fsS https://mcp.example.com/.well-known/oauth-authorization-server/api
+curl -fsS https://mcp.example.com/api/.well-known/jwks.json
+curl -i https://mcp.example.com/api/mcp
+```
+
+The last response must be `401` and include a `WWW-Authenticate` header whose
+`resource_metadata` value points to the protected-resource metadata endpoint.
+
+Access tokens are RS256 JWTs without `exp`, matching the trusted internal
+connector model. Authorization codes remain short-lived, PKCE-bound, and
+one-time-use. Failed magic-token attempts are rate-limited per source address.
+
+## Diagnostics
+
+OAuth discovery, authorization, token exchange, MCP `initialize`, and
+`tools/list` milestones are logged at `info`. Rejections are logged at `warn`
+without credentials, authorization codes, PKCE verifiers, or access tokens.
+When OAuth is enabled, every HTTP request and completed response is also logged
+with its normalized path, status, user agent, content types, MCP session id,
+and whether an Authorization header was present. Header values and tokens are
+never logged.
+
+The production Nginx sample writes connector traffic to:
+
+```text
+/var/log/nginx/tellymcp.access.log
+/var/log/nginx/tellymcp.error.log
+```
+
+If refresh stops after OAuth metadata and never logs an MCP `initialize`, first
+verify that the host's `Connection` value ends in `/api/mcp`.

package/docs/STANDALONE-ru.md

@@ -24,7 +24,17 @@
 ## 1. Установка
 
 ```bash
-npm install -g @deadragdoll/tellymcp
+sudo apt install -y python3 make g++
+npm config set ignore-scripts false
+npm install -g @deadragdoll/tellymcp --foreground-scripts
+```
+
+На Linux native addon `node-pty` собирается локально; для Linux ARM64 это
+обязательно, потому что зависимость не поставляет подходящий готовый binary.
+Если после предыдущей установки `pty.node` отсутствует, выполни:
+
+```bash
+npm rebuild -g @deadragdoll/tellymcp --foreground-scripts
 ```
 
 Опционально:
@@ -64,7 +74,8 @@ DB_PASSWORD=
 DB_NAME=
 GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
 GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
-GATEWAY_TOKEN=change_me_gateway_token
+GATEWAY_SCOPE_TOKEN=change_me_scope_token
+GATEWAY_AUTH_TOKEN=put_strong_shared_transport_token_here
 ROOT_PREFIX=/api
 PORT=8080
 DISTRIBUTED_MODE=gateway
@@ -82,10 +93,19 @@ DISTRIBUTED_MODE=gateway
 DISTRIBUTED_MODE=client
 GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
 GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
-GATEWAY_TOKEN=change_me_gateway_token
+GATEWAY_SCOPE_TOKEN=change_me_scope_token
+GATEWAY_AUTH_TOKEN=put_strong_shared_transport_token_here
 GATEWAY_USER_UUID=put_owner_uuid_here
 ```
 
+На машине agent/client Redis не нужен. Временное runtime-состояние хранится
+локально, а стабильный gateway client UUID — в `.mcpsession.json`.
+
+Используйте один и тот же стойкий `GATEWAY_AUTH_TOKEN` на gateway и всех клиентах.
+Не смешивайте его с `GATEWAY_SCOPE_TOKEN`: последний разделяет данные gateway по scope,
+но не аутентифицирует HTTP- или WebSocket-транспорт. Сгенерируйте токен один раз,
+например командой `openssl rand -hex 32`, и не используйте пример значения выше.
+
 Для первого запуска также желательно задать:
 
 ```env
@@ -164,9 +184,15 @@ TELEGRAM_WEBHOOK_SECRET=change_me_webhook_secret
 
 - `/api/telegram/webhook`
 - `/api/gateway`
+- `/api/files` для короткоживущих upload/download запросов `get_file(type="url")`
 - `/api/webapp`
 - `/api/healthz`
 
+Отдельный `location ^~ /api/files/` рекомендуется, хотя для самой маршрутизации
+он не обязателен. В нём следует отключить access log, потому что путь содержит
+токен, задать `client_max_body_size 32m` и отключить buffering запросов и
+ответов. Канонический блок приведён в `nginx/tellymcp.gw.conf`.
+
 ## 8. MCP
 
 Локальный client-mode MCP endpoint:
@@ -179,10 +205,22 @@ http://127.0.0.1:8787/mcp
 
 ## 9. Проверки
 
+Настройка dotenv через локальный web-конфигуратор:
+
+```bash
+tellymcp configure
+```
+
 ```bash
 tellymcp doctor --env .env
 ```
 
+Перед запуском старый env можно нормализовать командой:
+
+```bash
+tellymcp migrate-env ./old.env > ./.migrated-env
+```
+
 Разрушительная очистка:
 
 ```bash

package/docs/STANDALONE.md

@@ -24,7 +24,17 @@ The recommended topology is:
 ## 1. Install
 
 ```bash
-npm install -g @deadragdoll/tellymcp
+sudo apt install -y python3 make g++
+npm config set ignore-scripts false
+npm install -g @deadragdoll/tellymcp --foreground-scripts
+```
+
+Linux installs compile the native `node-pty` addon locally; this is required on
+Linux ARM64 because the dependency does not ship a matching prebuilt binary.
+If `pty.node` is missing after an earlier install, run:
+
+```bash
+npm rebuild -g @deadragdoll/tellymcp --foreground-scripts
 ```
 
 Optional:
@@ -64,7 +74,8 @@ DB_PASSWORD=
 DB_NAME=
 GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
 GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
-GATEWAY_TOKEN=change_me_gateway_token
+GATEWAY_SCOPE_TOKEN=change_me_scope_token
+GATEWAY_AUTH_TOKEN=put_strong_shared_transport_token_here
 ROOT_PREFIX=/api
 PORT=8080
 DISTRIBUTED_MODE=gateway
@@ -82,10 +93,19 @@ Minimum client settings:
 DISTRIBUTED_MODE=client
 GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
 GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
-GATEWAY_TOKEN=change_me_gateway_token
+GATEWAY_SCOPE_TOKEN=change_me_scope_token
+GATEWAY_AUTH_TOKEN=put_strong_shared_transport_token_here
 GATEWAY_USER_UUID=put_owner_uuid_here
 ```
 
+The agent/client machine does not need Redis. Its transient runtime state is
+local, while the stable gateway client UUID is stored in `.mcpsession.json`.
+
+Use the same strong `GATEWAY_AUTH_TOKEN` on the gateway and every client. Keep it
+separate from `GATEWAY_SCOPE_TOKEN`, which scopes gateway data but does not authenticate
+the HTTP or WebSocket transport. Generate it once, for example with
+`openssl rand -hex 32`, and do not use the illustrative value above.
+
 For the first run, also set:
 
 ```env
@@ -164,9 +184,15 @@ If nginx already proxies `location /api/ { ... }` to the standalone listener, th
 
 - `/api/telegram/webhook`
 - `/api/gateway`
+- `/api/files` for short-lived `get_file(type="url")` uploads and downloads
 - `/api/webapp`
 - `/api/healthz`
 
+A dedicated `location ^~ /api/files/` is recommended, though not required for
+routing. It should disable access logs because the path contains a token, set
+`client_max_body_size 32m`, and disable proxy request/response buffering. See
+`nginx/tellymcp.gw.conf` for the canonical block.
+
 ## 8. MCP
 
 Local client-mode MCP:
@@ -179,10 +205,22 @@ Use the MCP HTTP endpoint exposed by `tellymcp run`.
 
 ## 9. Health Checks
 
+Guided dotenv setup:
+
+```bash
+tellymcp configure
+```
+
 ```bash
 tellymcp doctor --env .env
 ```
 
+Normalize a legacy env before startup:
+
+```bash
+tellymcp migrate-env ./old.env > ./.migrated-env
+```
+
 Destructive cleanup:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deadragdoll/tellymcp",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "TellyMCP - Telegram control plane for MCP-connected coding agents",
   "main": "dist/services/features/telegram-mcp/runtime.service.js",
   "bin": {
@@ -17,6 +17,7 @@
     "README-ru.md",
     "docs/STANDALONE.md",
     "docs/STANDALONE-ru.md",
+    "docs/CHAT_CONNECTOR.md",
     "VERSION.md",
     "CHANGELOG.md",
     "TOOLS.md",
@@ -76,7 +77,8 @@
   "dependencies": {
     "@grammyjs/menu": "^1.3.1",
     "@grammyjs/storage-redis": "^2.5.1",
-    "@modelcontextprotocol/sdk": "^1.18.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@xterm/addon-fit": "0.10.0",
     "@xterm/headless": "5.5.0",
     "@xterm/xterm": "5.5.0",
     "amqplib": "0.10.9",
@@ -96,7 +98,7 @@
     "pino-pretty": "^13.1.3",
     "playwright": "^1.60.0",
     "socks-proxy-agent": "^8.0.5",
-    "ws": "8.20.1",
+    "ws": "8.21.0",
     "zod": "4.4.3"
   },
   "devDependencies": {