claudegram

<h1 align="center">Claudegram</h1> <p align="center"> <em>Личный Telegram-аккаунт как полноценный инструмент Claude Code — через MTProto, не Bot API.</em> </p> <p align="center"> <a href="https://github.com/sanjar-x/claudegram/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/sanjar-x/claudegram/actions/workflows/ci.yml/badge.svg"></a> <a href="https://github.com/sanjar-x/claudegram/actions/workflows/codeql.yml"><img alt="CodeQL" src="https://github.com/sanjar-x/claudegram/actions/workflows/codeql.yml/badge.svg"></a> <a href="https://github.com/sanjar-x/claudegram/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a> <a href="https://www.python.org/downloads/release/python-3140/"><img alt="Python 3.14+" src="https://img.shields.io/badge/python-3.14%2B-blue.svg"></a> <a href="https://github.com/astral-sh/ruff"><img alt="Code style: ruff" src="https://img.shields.io/badge/code%20style-ruff-261230.svg"></a> <a href="https://github.com/astral-sh/uv"><img alt="uv" src="https://img.shields.io/badge/managed%20by-uv-261230.svg"></a> <a href="https://modelcontextprotocol.io"><img alt="MCP" src="https://img.shields.io/badge/MCP-1.27%2B-8A2BE2.svg"></a> <a href="https://code.claude.com/docs/en/plugins-reference"><img alt="Claude Code Plugin" src="https://img.shields.io/badge/Claude%20Code-Plugin-D97757.svg"></a> </p> <p align="center"> <strong>120 MCP-tools</strong> · <strong>9 resources</strong> · <strong>6 templates</strong> · <strong>7 prompts</strong> · <strong>6 skills</strong> · <strong>4 уровня PreToolUse-гейтов</strong> </p> --- ## TL;DR Claudegram — production-grade плагин Claude Code, превращающий личный Telegram в управляемый AI-инструмент: - **MTProto, не Bot API** — видит **всю** переписку, истории, поиск, медиа, статистику. - **120 типизированных MCP-tools** через FastMCP, разбиты на 9 доменов; покрыты `safe_tool` middleware с FloodWait/RPCError handling и санитизацией секретов. - **Channel-режим**: входящие сообщения push-ятся в активную сессию Claude как `<channel>` теги с permission relay (yes/no через `<id>`). - **4-слойная safety net**: PreToolUse hooks (`guard-delete`, `guard-destructive`, `guard-confirm`) + `disable-model-invocation` для отправки сообщений + sensitive userConfig в системный keychain. - **Skills + Prompts**: `tg-digest`, `tg-search`, `tg-history`, `tg-send`, `tg-reply`, `telegram-workflow` — готовые сценарии для рекрутерского тестового запуска. Полный список возможностей — в таблице ниже. ## Why this project - Реальный production-ready MCP-сервер: типизированные tools, structured output, prompt templates, completions, resource templates. - Безопасность спроектирована up-front: модель угроз, hook-гейты, allowlist, sanitize в логах. См. [SECURITY.md](SECURITY.md). - Чистая архитектура: 75 модулей, ~6.3k строк server-кода, ~900 строк тестов, ruff + mypy, CI на GitHub Actions, Codecov, CodeQL. - Каждое решение объяснено docstring'ом и CHANGELOG'ом, без «магии». ## Quick start ```bash git clone https://github.com/sanjar-x/claudegram.git && cd claudegram uv sync cp .env.example .env # вставь api_id/api_hash/phone с https://my.telegram.org uv run claudegram-auth # затем в Claude Code: /plugin add . && /plugin install claudegram ``` Подробнее — в разделе «Установка» ниже. В отличие от Bot API, Claudegram видит **всю историю**, **все чаты** и поддерживает **поиск**. Архитектура и компоненты выровнены под официальную [спеку Claude Code Plugins](https://code.claude.com/docs/en/plugins-reference). ## Возможности | Слой | Что внутри | |-------------------|------------------------------------------------------------------------| | **MCP-сервер** | **118 типизированных tool'ов** через FastMCP + Telethon, разбиты по 9 доменам с подпакетами в `server/tools/` | | **Production middleware** | `safe_tool` decorator с graceful FloodWait/RPCError handling, latency logging, sensitive-sanitization | | **Health probe** | `health_check` + `get_server_version` для readiness/liveness | | **Channel-режим** | Push входящих Telegram-сообщений в активную сессию Claude как `<channel source="claudegram">` теги + permission relay (yes/no `<id>`) | | **Skills** | 6 skill'ов: `tg-digest`, `tg-search`, `tg-history`, `tg-send`, `tg-reply` + фоновые `telegram-workflow` и `tg-channel-incoming` | | **Hooks** | `SessionStart` — авто-проверка авторизации; `PreToolUse` — гейт перед `delete revoke=true` (с jq/python3 fallback) | | **bin/** | `claudegram-auth` — попадает в PATH **Bash tool** Claude Code (не в shell хоста); снаружи — `uv run claudegram-auth` | | **userConfig** | Креденшелы + sender-allowlist запрашиваются GUI-промптом плагина, сенситивные в системном keychain | | **Persistent data** | `*.session` живёт в `${CLAUDE_PLUGIN_DATA}` — не теряется при апдейте плагина | | **Marketplace** | `.claude-plugin/marketplace.json` — каталог из одного плагина для `/plugin install` | ## Структура ``` Claudegram/ ├── .claude-plugin/ │ └── plugin.json # манифест с userConfig (api_id/hash/phone/2fa) ├── .mcp.json # MCP stdio-сервер, env через ${user_config.*} ├── hooks/ │ ├── hooks.json # SessionStart auth-check, PreToolUse delete-guard │ └── scripts/ │ ├── check-auth.sh │ └── guard-delete.sh ├── skills/ # каждая команда — отдельный каталог с SKILL.md │ ├── telegram-workflow/SKILL.md # фоновые правила (user-invocable: false) │ ├── tg-channel-incoming/SKILL.md # обработка <channel source="claudegram"> тегов │ ├── tg-digest/SKILL.md # /claudegram:tg-digest [N] │ ├── tg-search/SKILL.md # /claudegram:tg-search <запрос> [@chat] │ ├── tg-history/SKILL.md # /claudegram:tg-history <@chat> [limit] │ ├── tg-send/SKILL.md # /claudegram:tg-send <@chat> <текст> (disable-model-invocation) │ └── tg-reply/SKILL.md # /claudegram:tg-reply <@chat> <id> <текст> ├── bin/ │ └── claudegram-auth # шелл-обёртка над server.auth ├── server/ # Python MCP-сервер (FastMCP + Telethon) │ ├── __init__.py │ ├── config.py # plugin-mode + standalone-mode env loading │ ├── auth.py # одноразовый интерактивный логин │ ├── client.py # singleton TelegramClient │ ├── formatters.py # сериализация в JSON │ ├── channel.py # channel-режим: push + permission relay │ ├── main.py # FastMCP entry + custom stdio runner с experimental caps │ └── tools/ # 92 tools в 8 доменах с подпакетами │ ├── __init__.py # register_all(mcp) — диспатчит по доменам │ ├── _common.py # shared utils (ParseMode, normalize_chat, clamp, to_jsonable) │ ├── identity/ # account, sessions │ │ ├── account.py # get_me, update_profile, set_online, update_username, get_full_user │ │ └── sessions.py # get_authorizations, terminate_authorization │ ├── peers/ # discovery + метаданные сущностей │ │ ├── lookup.py # resolve_username, get_chat_info, search_global, get_top_peers, get_input_peer │ │ ├── users.py # get_profile_photos, download_profile_photo, get_common_chats │ │ └── contacts.py # CRUD + block/unblock + import + get_blocked │ ├── messaging/ # send/edit/history/pins/reactions │ │ ├── messages.py # send/edit/delete/forward │ │ ├── history.py # get_history (+filter_type), search_messages │ │ ├── pins.py # pin_message, unpin_message │ │ └── reactions.py # react_message │ ├── dialogs/ # список и состояния диалогов │ │ ├── list_.py # list_chats, get_drafts │ │ ├── folders.py # archive/unarchive/pin_dialog │ │ └── notify.py # mark_read, mute, unmute, delete_dialog │ ├── chats/ # управление группами/каналами │ │ ├── create.py # create_group, create_channel │ │ ├── settings.py # title/about/photo/forum_mode │ │ ├── members.py # participants, kick, ban, unban, restrict, promote, demote │ │ ├── invites.py # join, leave, export_invite │ │ └── admin.py # admin_log, stats │ ├── media/ # файлы и attachments │ │ ├── files.py # send_file, send_album │ │ ├── download.py # download_media, get_media_info │ │ ├── attachments.py # send_location, send_contact, send_dice │ │ └── stickers.py # все sticker-операции │ ├── content/ # контент-фичи │ │ ├── polls.py # send/vote/results │ │ ├── stories.py # all stories operations │ │ └── forums.py # forum-topics │ └── advanced/ │ └── raw.py # invoke_raw — ANY MTProto method ├── pyproject.toml + uv.lock # uv-проект ├── .env.example # для standalone-режима ├── .gitignore # игнорит .env, *.session, .venv, кеши └── README.md ``` ## Стек - Python 3.14, [uv](https://docs.astral.sh/uv/) - [Telethon](https://docs.telethon.dev/) 1.43+ — MTProto-клиент - [`mcp[cli]`](https://github.com/modelcontextprotocol/python-sdk) 1.x — официальный SDK MCP ## Установка ### 1. Получить API-креденшелы 1. Открой <https://my.telegram.org> → **API development tools**. 2. Создай приложение (любые `App title` / `Short name`). 3. Скопируй `api_id` и `api_hash`. ### 2. Установить зависимости (uv создаст `.venv/`) ```bash cd ~/Desktop/Claudegram uv sync ``` ### 3. Подключить плагин в Claude Code Самый быстрый способ для разработки — `--plugin-dir` (грузит как сессионный плагин, без установки): ```bash claude --plugin-dir ~/Desktop/Claudegram ``` Постоянная установка через локальный marketplace (`marketplace.json` уже включён в `.claude-plugin/`): ``` /plugin marketplace add ~/Desktop/Claudegram /plugin install claudegram@claudegram-local ``` `claudegram-local` — имя локального marketplace из `.claude-plugin/marketplace.json`. При первом включении Claude Code откроет промпт и попросит ввести `tg_api_id`, `tg_api_hash`, `tg_phone` (поля `userConfig` из манифеста). Сенситивные значения уйдут в системный keychain, не в `settings.json`. ### 4. Авторизоваться (один раз) ⚠️ Важно: `bin/claudegram-auth` попадает в PATH **только Bash tool внутри Claude Code**, не в обычный shell хоста (это ограничение Claude Code, см. [plugins-reference](https://code.claude.com/docs/en/plugins-reference#file-locations-reference)). Вариант **A** (рекомендуемый, из активной Claude-сессии): ``` ! claudegram-auth ``` Префикс `!` запускает команду в shell сессии, и тогда `bin/claudegram-auth` из плагина уже в PATH. Вариант **B** (из обычного терминала, standalone): ```bash cd ~/Desktop/Claudegram uv run python -m server.auth # или uv run claudegram-auth # после `uv sync` появляется console-script ``` В обоих случаях — введи код из Telegram. Файл сессии создастся: - **Plugin-mode**: `~/.claude/plugins/data/claudegram-claudegram-local/claudegram.session` (переменная `${CLAUDE_PLUGIN_DATA}`) — не теряется при апдейте плагина. - **Standalone**: в корне проекта `~/Desktop/Claudegram/claudegram.session`. ### 5. Проверить ``` /mcp # должен появиться сервер "claudegram" /reload-plugins # после правок без рестарта /hooks # увидишь SessionStart + PreToolUse гейт ``` ## Использование ### Slash-skills (тип `/claudegram:<skill>`) - `/claudegram:tg-digest [N]` — сводка непрочитанных по N чатам. - `/claudegram:tg-search <запрос> [@chat]` — поиск. - `/claudegram:tg-history <@chat> [N]` — последние N сообщений чата. - `/claudegram:tg-send <@chat> <текст>` — отправка с подтверждением. Только пользователь вызывает (`disable-model-invocation: true`). - `/claudegram:tg-reply <@chat> <id> <текст>` — ответ на конкретное сообщение. Только пользователь. ### Авто-активация Skill `telegram-workflow` (`user-invocable: false`) подгружается, когда ты пишешь "что у меня в Telegram?", "найди в чатах", "напиши Пете". Claude по описанию выбирает правильный MCP-tool и следует safety-правилам из этого skill. ### Прямые MCP-инструменты (58 шт) Полный namespace: `mcp__plugin_claudegram_claudegram__<tool>`. Wildcard для permission-rule: `mcp__plugin_claudegram_claudegram__*`. Полный каталог с описаниями и сигнатурами — в skill'е [`telegram-workflow/SKILL.md`](skills/telegram-workflow/SKILL.md). Краткая сводка по категориям: - **Account** (5): `get_me`, `get_authorizations`, `terminate_authorization`, `update_profile`, `set_online` - **Messages** (11): `send_message`, `edit_message`, `delete_message`, `forward_message`, `get_history`, `search_messages`, `mark_read`, `pin_message`, `unpin_message`, `react_message`, `send_dice` - **Dialogs** (7): `list_chats`, `get_drafts`, `archive_dialog`, `unarchive_dialog`, `delete_dialog`, `mute_dialog`, `unmute_dialog` - **Users** (7): `get_chat_info`, `resolve_username`, `get_participants`, `get_profile_photos`, `block_user`, `unblock_user`, `get_common_chats` - **Chats** (12): `create_group`, `create_channel`, `edit_chat_title`, `edit_chat_about`, `join_chat`, `leave_chat`, `kick_participant`, `ban_participant`, `unban_participant`, `promote_admin`, `demote_admin`, `get_admin_log`, `get_stats` - **Media** (7): `download_media`, `download_profile_photo`, `send_file`, `send_album`, `send_location`, `send_contact`, `get_media_info` - **Contacts** (4): `get_contacts`, `add_contact`, `delete_contact`, `search_global` - **Polls** (2): `send_poll`, `vote_poll` - **Raw API** (2): `invoke_raw`, `get_input_peer` — escape hatch для **любого** MTProto-метода через `telethon.tl.functions.<module>.<MethodNameRequest>`. Покрывает Stories, Payments, Stickers, Channels admin, Folders, Themes — всё, что не обёрнуто high-level API. ## Как работает безопасность - `.env` и `*.session` в `.gitignore`. - Sensitive userConfig (api_hash, phone, 2FA) уходят в системный keychain (или `~/.claude/.credentials.json`), не в `settings.json`. - `*.session` лежит в `${CLAUDE_PLUGIN_DATA}` — не утекает с апдейтом, но даёт полный доступ к аккаунту, храни как пароль. - `PreToolUse`-хук на `delete_message` принудительно спрашивает, если `revoke=true`. - Skill `telegram-workflow` обязывает Claude получать явное подтверждение перед `send_message`/`mark_read`/`delete_message`. - Telegram может посчитать активность подозрительной → возможна блокировка. Для экспериментов используй **отдельный** аккаунт. ## Standalone-режим (без плагина) Можно запустить MCP-сервер вне Claude Code: ```bash cp .env.example .env $EDITOR .env # заполни TG_API_ID/HASH/PHONE uv run python -m server.auth # логин, .session ляжет в корень uv run python -m server.main # MCP stdio-сервер ``` `server/config.py` сначала читает `TG_*` (или `.env`), затем — `CLAUDE_PLUGIN_OPTION_TG_*`, которые экспортируются плагином. Один и тот же код работает в обоих режимах. ## Расширение - **Новый MCP-tool** → функция в `server/main.py` с `@mcp.tool()`. FastMCP сам сгенерирует JSON-схему по type-hints + docstring. - **Новый skill** → каталог `skills/<name>/` с `SKILL.md`. Frontmatter: `name`, `description`, опционально `argument-hint`, `arguments`, `allowed-tools`, `disable-model-invocation`, `paths`, `model`, `effort`. - **Новый hook** → редактируй `hooks/hooks.json`. Доступные события см. [hooks reference](https://code.claude.com/docs/en/hooks). - **Бинарь** → положи в `bin/<name>` + chmod +x. Автоматически попадёт в PATH. После любых изменений: `/reload-plugins` в Claude Code (рестарт не нужен). ## Channel-режим [Channels](https://code.claude.com/docs/en/channels) (research preview Claude Code v2.1.80+) — двусторонний bridge: входящие Telegram-сообщения **сами** появляются в активной Claude-сессии как XML-теги, Claude отвечает обратно через `send_message`. ### Что под капотом - В `.mcp.json` плагин выставляет `CLAUDEGRAM_CHANNEL_MODE=1` → `server/main.py` объявляет experimental capabilities `claude/channel` и `claude/channel/permission` через кастомный stdio-runner (FastMCP сам не умеет — обходим через `_mcp_server.create_initialization_options(experimental_capabilities=...)`). - `server/channel.py` подписывается на Telethon `@client.on(events.NewMessage(incoming=True))`. - Каждое входящее от ID из allowlist (`tg_allowed_sender_ids`) пушится как raw `JSONRPCNotification(method='notifications/claude/channel', ...)` напрямую через write_stream stdio-сессии. - Тег у Claude выглядит так: ```xml <channel source="claudegram" chat_id="-1001234567890" message_id="42" sender_id="111222333" user="Pete"> привет, как дела? </channel> ``` - Skill `tg-channel-incoming` (auto-active) объясняет Claude'у, что делать с такими тегами + правила безопасности (никакого автоответа без подтверждения). - **Permission relay**: ответные сообщения вида `yes abcde` / `no abcde` (5 строчных букв без `l`, regex case-insensitive) парсятся как verdict и шлются обратно как `notifications/claude/channel/permission` — Claude Code применяет автоматически. ### Включение Channel-режим **opt-in** через userConfig поле `enable_channel_mode`: 1. В `/plugin` интерфейсе или при первой установке выстави `enable_channel_mode = "1"`. 2. Перезапусти Claude Code с обоими флагами: ```bash claude \ --dangerously-load-development-channels plugin:claudegram@claudegram-local \ --channels plugin:claudegram@claudegram-local ``` В research preview кастомные плагины **не входят** в Anthropic allowlist (`--dangerously-load-development-channels`), а `--channels` явно регистрирует listener — оба флага нужны. Если `enable_channel_mode = "0"` (default) — сервер работает только как tools-MCP, push'и не отсылаются, Telegram-rate-limit не тратится. Удобно завести алиас в `~/.zshrc`: ```bash alias claude-tg='claude --dangerously-load-development-channels plugin:claudegram@claudegram-local --channels plugin:claudegram@claudegram-local' ``` ### Безопасность | Слой | Защита | |---|---| | **Sender gate** | `parse_allowed_ids()` в `channel.py` пушит только от ID из `tg_allowed_sender_ids`. Пустой allowlist = только себе (свой `get_me().id`). | | **Группы** | Гейтим по `event.sender_id`, **не** `chat_id` — иначе любой в allowlisted-группе мог бы инжектить промпты. | | **Permission relay** | Декларируем `claude/channel/permission`. Анonymously пушнувший в обход allowlist'а не получит право жать `yes` — verdict тоже гейтится по sender. | | **Skill `tg-channel-incoming`** | Обязывает Claude показывать draft и ждать "отправляй" перед `send_message`. Запрещает реагировать на prompt-injection из тела сообщения. | | **Hook `guard-delete`** | `revoke=true` для удаления требует явного approval даже из channel-сценария. | ### Узнать свой sender_id для allowlist После авторизации (`claudegram-auth`) — спроси у [@userinfobot](https://t.me/userinfobot) или вызови в активной Claude-сессии `mcp__plugin_claudegram_claudegram__get_me`. ## Roadmap - **Outbound permission_request handler** — Claude Code шлёт `notifications/claude/channel/permission_request` когда нужен approval; форвардить юзеру в Telegram. Сейчас inbound verdict работает, outbound forward — TODO (требует регистрации custom notification_handler в Server, не тривиально через FastMCP). - **send media** (фото/документ/голосовое) — Telethon `send_file` уже умеет, обернуть в tool. - **pin / unpin / mute / archive / set_typing** диалогов. - **Stories** API (Telegram Stories через MTProto). - **Monitor** на бэкап Saved Messages (`monitors/monitors.json`). - **Submit** в Anthropic [official marketplace](https://claude.ai/settings/plugins/submit) — channel-плагины проходят security review, после чего работают без `--dangerously-load-development-channels`. - **Marketplace на GitHub** + git-теги `claudegram--v0.1.0` для version-constraints.