Telegram Dev

Telegram Dev

Telegram ボットと AI コーディングエージェントを、最新の Bot API に対応させましょう。

Telegram は1、2か月ごとに Bot API を更新するため、コードもモデルも遅れがちです。Telegram Dev は次の3つの要素で構成されています。

• telegram-dev check は Python ボット（aiogram、python-telegram-bot、pyTelegramBotAPI、または生の HTTP 呼び出し）を読み取り、廃止されたパラメーターや無効な値を含む Bot API 呼び出しを一覧表示します。ターミナル、GitHub Action としての CI、またはエージェントツールとして実行できます。
• エージェント向けの Bot API ツール：公式ページをもとに作成された、メソッドと型の定義、リクエストチェッカー、バージョン別の変更履歴です。
• Claude Code、Codex、Cursor 向けのドキュメントサーバーとスキル：Telegram と TON の公式ドキュメント（Bot API、Mini Apps、MTProto、TDLib、ボットライブラリ、TON Connect、Tolk）を検索でき、自動的に更新されます。

Telegram アカウント、ボットトークン、API キーは不要です。すべて公開ドキュメントを読み取ります。

ロシア語版

ボットプロジェクトをチェックする

telegram-dev check は、Python ボット（aiogram、python-telegram-bot、pyTelegramBotAPI、または api.telegram.org への生の HTTP リクエスト）内のすべての Bot API 呼び出しを一度にチェックし、検出結果だけを出力します。

uvx telegram-dev check ./my-bot

$ uvx telegram-dev check ./tutorial        # a popular open-source aiogram 3 tutorial
code/03_buttons/bot.py:79: warning: types.KeyboardButton: `request_user` was retired in Bot API 7.0: Renamed the field request_user in the class KeyboardButton to request_users. The old name will still work for backward compatibility. ...
code/08_inline_mode/handlers/inline_mode.py:48: warning: inline_query.answer: `switch_pm_text` was retired in Bot API 6.7: ... replacing the parameters switch_pm_text and switch_pm_parameter of the method answerInlineQuery with the parameter button of type InlineQueryResultsButton. ...
Bot API 10.4; 95 files with bot code; libraries: aiogram ==3.14.0 ==3.7.0 >=3.24.0 ...; 0 errors, 5 warnings

誤った値はエラーとして扱われます。たとえば、InlineKeyboardButton(text="Delete", style="red") は style: must be one of danger, success, primary というエラーになります。

エラーには、ドキュメントに記載されたリストにない値、生の API リクエストに含まれる不明なメソッドやパラメーターがあります。警告には、Telegram が廃止したパラメーター（置き換えたバージョンと変更履歴の項目を含む）、Bot API パラメーターでも既知のライブラリオプションでもないキーワード引数、Bot API に対応するメソッドがないボットメソッドがあります。コードは実行せずに読み取るため、変数を追跡したり、必須パラメーターをチェックしたりはしません。オプション：--json、--exclude 'tests/*'、--strict（警告がある場合は失敗）、--format github。エージェントのセッションでは、同じチェックを check_telegram_project ツールとして利用できます（ファイルを読み取るため、ローカルの stdio サーバーでのみ使用できます）。

GitHub リポジトリでは、すべてのプルリクエストで実行できます。検出結果は変更された行の注釈として表示されます。

# .github/workflows/telegram.yml
on: [pull_request]
jobs:
  bot-api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Kay0k1/[email protected]
        with:
          path: .
          exclude: "tests/*"

インストール

uv が必要です。ボットトークン、Telegram アカウント、API キーは不要です。サーバーは公開ドキュメントのみを読み取ります。

MCP サーバーとスキルを1つのコマンドでインストールする

プロジェクトディレクトリで次を実行します。

uvx telegram-dev install --agent claude    # or: codex, cursor

--agent	MCP サーバーの追加先	スキルのコピー先
claude	.mcp.json	.claude/skills/telegram-dev
codex	.codex/config.toml	.agents/skills/telegram-dev
cursor	.cursor/mcp.json	.cursor/skills/telegram-dev

インストーラーは他の設定を保持し、変更するファイルのバックアップを作成します。また、既存の Telegram Dev のセットアップを上書きすることはありません。サーバーはインストール済みのバージョンに固定されるため、ディスク上に残しておく必要があるのは uv キャッシュだけです。その後、新しいエージェントセッションを開き、確認を求められたらプロジェクトの MCP サーバーを承認してください。Codex がプロジェクト設定を読み込むのは、プロジェクトディレクトリを信頼してからです。

後でアップグレードするには、uvx telegram-dev@latest install --agent claude --update を実行します。

Claude Code プラグイン

/plugin marketplace add Kay0k1/telegram-dev
/plugin install telegram-dev@telegram-dev-tools

これにより、すべてのプロジェクトにスキルと MCP サーバーが追加されます。プラグインとインストーラーは併用せず、どちらか一方を使用してください。

MCP サーバーのみ

claude mcp add --scope user telegram-knowledge -- uvx telegram-dev serve

codex mcp add telegram-knowledge -- uvx telegram-dev serve

Cursor：

その他の MCP クライアント：

{
  "mcpServers": {
    "telegram-knowledge": { "command": "uvx", "args": ["telegram-dev", "serve"] }
  }
}

ツールはスキルがなくても動作しますが、エージェントが一貫して使うようにするのがスキルの役割です。

エージェント向けの最新ドキュメント

Telegram では、1、2か月ごとに新しい Bot API バージョンがリリースされます。モデルが持つ知識は学習のカットオフ時点で止まるため、エージェントは変更済み、または存在したことのないフィールドを使ったコードを自信を持って書いてしまいます。また、機能が大きく異なる Bot API、MTProto、TDLib を混同することもあります。

TON も同じように速いペースで進化しています。現在の TON ドキュメントでは、コインを Gram と呼び、Telegram に組み込まれたウォレットである Telegram Money について説明し、Tolk を主要なコントラクト言語、FunC をレガシーとして扱っています。さらに、Telegram 独自のルールもあります。Mini Apps のブロックチェーン機能では TON と TON Connect を使用する必要があり、デジタル商品は Stars で販売されます。

Telegram Dev を使うと、エージェントはコードを書く前に最新のページを読み込みます。新しいプロジェクトで uvx telegram-dev install --agent codex を実行した、実際の Codex CLI の実行例です（ツール呼び出しは一部省略）。

> Use the telegram-dev skill. In a python-telegram-bot project, I want the inline
  'Delete' button to be red and show a custom emoji. Which Bot API fields do this,
  what are the requirements, and what does the request JSON look like?

  get_telegram_corpus_status {}
  search_telegram_docs {"query": "style icon_custom_emoji_id", "area": "releases"}
  search_telegram_docs {"query": "InlineKeyboardButton icon_custom_emoji_id style", "area": "bot-api"}
  get_telegram_document {"url": "https://core.telegram.org/bots/api", "offset": 167594, "length": 10500}
  get_telegram_document {"url": "https://core.telegram.org/bots/api-changelog", "offset": 39089, "length": 6000}

Use these InlineKeyboardButton fields:
- style: "danger" makes the button red.
- icon_custom_emoji_id is a custom emoji ID shown before "Delete".
- callback_data is your action identifier, 1-64 bytes.

The custom emoji requires either a bot that bought additional usernames on Fragment,
or a Premium bot owner with the message sent by the bot to a private chat, group or
supergroup. PTB 22.7+ supports both fields. Older Telegram clients show the button
unstyled. Source: https://core.telegram.org/bots/api#inlinekeyboardbutton

{"chat_id": 123456789, "text": "Choose an action:",
 "reply_markup": {"inline_keyboard": [[{"text": "Delete", "callback_data": "delete:42",
   "style": "danger", "icon_custom_emoji_id": "YOUR_CUSTOM_EMOJI_ID"}]]}}

このスキルは、ブロックチェーンを使うべきでない場合も判断できます。こちらも実際の Codex の実行例です。

> Use the telegram-dev skill. Our Telegram Mini App sells a premium in-game skin
  for 2 TON. I want a Buy button that connects the user's wallet and charges them.

  get_telegram_document {"url": "https://core.telegram.org/bots/payments-stars", "refresh": true}
  search_telegram_docs {"query": "createInvoiceLink answerPreCheckoutQuery successful_payment XTR", "area": "bot-api"}
  get_telegram_document {"url": "https://docs.ton.org/applications/ton-connect/overview", "refresh": true}
  get_telegram_document {"url": "https://core.telegram.org/bots/webapps", "offset": 40310}

Use Telegram Stars (XTR) through the Bot API. The skin is a digital good, so
Telegram requires Stars and prohibits cryptocurrency payment for this purchase.
For permitted wallet features, use the TON Connect SDK.
1. Validate initData on the backend and bind the order to the user.
2. createInvoiceLink with currency "XTR", open it with Telegram.WebApp.openInvoice.
3. Answer pre_checkout_query, grant the skin once on successful_payment,
   store telegram_payment_charge_id for refunds.

ツール

ツール	機能
search_telegram_docs	インデックス化されたセクションを全文検索します。必要に応じて、bot-api、mini-apps、telegram-api、tdlib、ton、releases、ton-releases、aiogram、python-telegram-bot、grammy などの領域に絞り込めます。クエリでライブラリが指定されていない場合は、Telegram の主要ドキュメントを優先して表示します
get_telegram_document	公式ページを最大40,000文字ずつ読み込みます。ページが存在しない場合、または6時間以上前のものである場合は取得します
get_telegram_corpus_status	インデックス化されている内容、その鮮度、取得に失敗したソースを確認します
list_telegram_document_revisions	このインストールで取得したページの改訂履歴を表示します
list_telegram_sources	公式のエントリーポイント61件を API 領域ごとにまとめて表示します
list_telegram_cached_pages	ローカルキャッシュに保存済みのページを、領域別に鮮度とともに表示します
get_bot_api_definition	Bot API のメソッドまたは型を構造化データで表示します。パラメーターまたはフィールド、型、必須フラグ、許容値、長さ制限、および該当項目に言及している変更履歴が含まれます
check_bot_api_call	コードから送信するリクエストを現在の Bot API スキーマに照らして確認します。不明なメソッドやパラメーター（候補付き）、不足している必須項目、型の不一致、ドキュメントに記載されたリスト外の値、置き換えられたバージョンとともに表示される廃止済みパラメーターを検出します
list_bot_api_changes	バージョン（since_version="9.0"）またはメソッド、型、フィールド名で絞り込んだ、公式 Bot API 変更履歴を構造化されたリリース情報として表示します
check_telegram_project	ローカルの Python ボットプロジェクトに含まれるすべての Bot API 呼び出しを一度に確認します（ボットプロジェクトの確認を参照）。ローカル stdio サーバー専用です

Bot API 呼び出しの確認

Bot API ツールは、キャッシュ内の公式 API ページと変更履歴から構築されるため、手書きのスキーマを使わずに Telegram の最新バージョン（執筆時点では Bot API 10.4）に追従します。たとえば、次の内容に対して check_bot_api_call を実行すると、

{"method": "sendMessage", "params": {"chat_id": 1, "text": "Delete?", "reply_to_message_id": 42,
  "reply_markup": {"inline_keyboard": [[{"text": "Delete", "callback_data": "del", "style": "red"}]]}}}

reply_markup.inline_keyboard[0][0].style に対するエラー（danger、success、primary のいずれかである必要があります）と、Bot API 7.0 で reply_to_message_id が reply_parameters に置き換えられたという警告が返されます。Telegram への呼び出しは行わないため、権限、チャットの状態、ファイルの内容については、実際にテストする必要があります。

キャッシュは空の状態から始まります。エージェントが初めてページを読むと、そのページは取得され、すぐにインデックス化されます。設定済みのソースから到達できるすべてのページを事前に取得するには、次のコマンドを実行します。

uvx telegram-dev sync --max-pages 0
uvx telegram-dev search "sendVideoNote"
uvx telegram-dev status

スキルの対象範囲

領域	エージェントが確認する内容
Bot API	メッセージ、キーボード、アップデート、Webhook、ファイル、権限
書式設定と絵文字	エンティティ、UTF-16 オフセット、カスタム絵文字と使用できるユーザー
メディアとスタンプ	音声メッセージ、動画メッセージ、スタンプセット、ファイルの上限
Mini Apps	JS ブリッジ、起動パラメーター、テーマ、サーバー側での initData の検証
MTProto と TDLib	ユーザーとボットの認証、スキーマとレイヤー、TDLib のバージョン
ビジネスと決済	ビジネス接続、Stars、サブスクリプション、ギフト、有料メディア
グループとチャンネル	管理者権限、フォーラムとトピック、モデレーション
TON	Mini Apps に関する Telegram のブロックチェーンルール、Stars と暗号資産の違い、TON Connect と ton_proof、決済処理、jetton と NFT（TEP）、Tolk コントラクト、まずテストネットを使用すること、鍵の安全性
ボットライブラリ	aiogram、python-telegram-bot、grammY：インストール済みバージョンに対応するライブラリのドキュメントを Bot API のページと比較し、インデックス済みのドキュメントが別のバージョンを説明している場合はその旨を伝えます
リリース	Bot API の変更履歴、API レイヤー、TDLib の変更履歴、TON ノードと Tolk の変更履歴、公式発表

このスキルは skills/telegram-dev にあり、領域ごとに 1 つのリファレンスファイルが用意されています。

ドキュメントの鮮度

• 6 時間以上前のページを読み込むと、再取得します。検索では、条件に一致する古いページを最大 6 件まで再取得します。
• サーバーの稼働中は、バックグラウンドのサイクルで 6 時間ごとに最大 120 ページを確認します。対象はエントリーポイント、新たに見つかったリンク、最も古いページです。
• Telegram のサイトにアクセスできない場合、キャッシュされたテキストは保持され、エラーとともに古い情報としてマークされます。そのため、エージェントは古いコピーを読んでいることがわかります。
• 毎日の GitHub Action が公式ソース 61 件すべてを確認し、ハッシュとエラーを docs-status ブランチに公開します。

キャッシュパス（TELEGRAM_KNOWLEDGE_DB）や更新間隔などの設定については、docs/runtime.md をご覧ください。

どの程度役立つか

11 件の質問と 10 件のコード作成タスクを Codex CLI で評価しました（評価結果）。

• Codex 独自のウェブアクセスを使った場合、Telegram Dev の有無にかかわらず、回答の正確さは同じでした。エージェントは自力で同じ公式ページを見つけました。
• ウェブアクセスがない場合、Telegram Dev を使うと回答の最新性が保たれました（評価基準の事実は 47 件中 45 件、Telegram Dev なしでは 47 件中 38 件。コードチェックは 26 件中 26 件、Telegram Dev なしでは 26 件中 23 件）。通常の Codex は、Bot API の最新機能や TON の現在の名称を把握していませんでした。

そのため、このドキュメントサーバーはエージェントがウェブを閲覧できない場合に最も役立ちます。プロジェクトチェックは質問ではなくコードを対象に機能するため、どちらの場合でも役立ちます。GitHub のオープンソースボットで実行すると、主に Bot API 7.0 で廃止された disable_web_page_preview と reply_to_message_id が見つかります。Telegram とライブラリは互換性のため、引き続きこれらを受け付けています。誤検知に関するレビューを含む詳細は、docs/validation.md をご覧ください。

セルフホスティング

サーバーは Streamable HTTP でも動作するため、チームで 1 つのキャッシュを共有できます。HTTPS 対応の Dockerfile と Caddy の設定も含まれています。docs/deployment.md をご覧ください。

uvx telegram-dev serve --transport streamable-http --port 8000

制限事項

• 検索はローカルの全文検索（SQLite FTS5）であり、セマンティック検索ではありません。正確なメソッド名と英語の用語が最も効果的です。ロシア語の別名も少数、組み込まれています。
• 対象範囲は、61 個の公式エントリーポイントからたどれるページです。TON のページは、docs.ton.org がエージェント向けに公開している llms.txt インデックスから取得するため、新しい TON のページも自動的に取り込まれます。
• ボットライブラリ：aiogram（latest。メインブランチからビルド）、python-telegram-bot（stable ドキュメントと公式 Wiki）、grammY（英語のガイドとプラグイン）のガイドおよびボット向けリファレンスが約 250 ページあります。Bot API を複製した型ごとの生成ページ、grammY の /ref/、翻訳版はインデックスに含まれません。リリース済みの aiogram と PTB のバージョン（/en/vX.Y.Z/）は、必要に応じて読み込めます。Telegraf、Telethon、Pyrogram はインデックスに含まれません。ページの履歴は、インストール後にそのページを初めて取得した時点から始まります。
• サーバーは Telegram にログインせず、メッセージの送信やチャットへのアクセス、ウォレットキーの保持も行いません。公開ページを読み取るだけです。
• このスキルは、エージェントの作業を改善します。正確な回答を保証するものではありません。リリース前に、Telegram の情報と照合してコードを確認してください。

開発

git clone https://github.com/Kay0k1/telegram-dev && cd telegram-dev
uv sync --frozen
uv run --frozen python -m unittest discover -s tests -v
uv run --frozen telegram-dev install --agent claude --project /path/to/test-project

CI では、Linux、macOS、Windows でテストを実行し、Docker イメージを検証します。docs/validation.md には、手作業で検証済みの項目と未検証の項目が記載されています。Issue やプルリクエストを歓迎します。tests/behavioral-cases.json には、各クライアントでの実行がまだ必要なエージェントのシナリオが含まれています。

ライセンス

コードとスキルには MIT ライセンスが適用されます。取得した Telegram および TON のドキュメントの権利は各所有者に帰属します。このパッケージには同梱されていません（NOTICE）。これは独立したプロジェクトであり、Telegram または TON Foundation とは提携していません。