Telegram Managed Bot Factory

Telegram Managed Bot Factory

セルフホスト可能な MCP コントロールプレーンです。ユーザーが所有する Telegram 管理ボットを、分離された便利な子ボットに変換します。Hermes に対応するボットを依頼し、Telegram でその作成を承認すると、永続的な Factory ワーカーが子ボットの認証情報を取得して隔離し、モデルや MCP に公開しません。

バージョン 0.2.3 はターミナルのみで動作し、デスクトップでの初期設定には対応していません。 PyPI の各バージョンは変更されません。以下の固定バージョンをインストールしてください。

重要な理由

ボットを手動で作成すると、価値のある認証情報を扱い、実際の外部操作を実行することになります。Factory はこのワークフローを明確にします。エージェントは範囲を限定したリクエストを準備できますが、作成は所有者が Telegram で承認し、その結果得られる認証情報はエージェントのコンテキスト外で永続ワーカーが受け取ります。

開発したもの

MCP とコントロールプレーンの境界、永続的なワーカーのライフサイクル、認証情報の分離、リクエストの状態と調整ルールを設計し、セルフホストで使えるようにツールをパッケージ化してリリースしました。外部操作の「厳密に一度だけ」の実行を意図的に保証していません。クラッシュによって結果が不明な場合は、むやみに再試行せず、調整が必要な状態として提示します。

インストール

systemd --user を備えた Linux、Python 3.11–3.14、uv、 Hermes 0.18、および Bot Management Mode を有効にした別の Telegram ボットが必要です。

uvx --refresh --from telegram-managed-bot-factory==0.2.3 bot-factory install-hermes

ローカルインストーラーは、まず systemd --user を確認し、検証済みのユーザーリンギングを有効にして、SSH ログアウト後もワーカーが稼働するようにします。次に、管理者認証情報を一度だけ安全に入力するよう求め、所有者を登録し、永続的なユーザーサービスと新しいワーカーハートビートをインストールして検証します。その後、9 つのツールを備えた stdio サーバーを Hermes に登録し、検出できることを確認します。子ボットは作成しません。

ターミナルのみでの初回起動

ワーカーを実行する Linux ホストと同じマシン上で、対話型の SSH またはコンソールターミナルからインストールコマンドを実行してください。このターミナルでセットアップ全体を行います。

1. 正確な Factory バージョンを永続的な uv tool としてインストールします（ワーカーユニットが削除可能な uvx キャッシュを参照することはありません）。
2. systemd --user を確認し、認証情報を求める前に検証済みのユーザーリンギングを有効にします。
3. 管理者トークンは、入力内容が表示されないターミナル入力でのみ受け付けます。
4. 所有者を登録し、サービスをインストールして、稼働中であることを確認し、新しいワーカーハートビートを確認します。
5. 9 つのツールを備えた stdio サーバーを Hermes に登録して検証します。Hermes の確認操作が必要な場合、その内容はこのターミナルに表示されます。

GUI ランチャーも、未設定の MCP 初期設定ツールもありません。このコマンドが完了するまで、Factory MCP は意図的に起動を拒否します。トークンを Hermes のチャット、MCP の引数、シェルコマンド、環境変数に貼り付けてはいけません。

仕組み

You → Hermes → Factory MCP ──durable request──▶ persistent worker
                  ▲                                │
                  │ safe status                    │ Bot API
                  │                                ▼
                  └──── Telegram confirmation ◀─ manager bot
                                                   │ child credential
                                                   ▼
                                         isolated child runtime

Hermes と MCP は、秘密情報を扱わないコントロールプレーンです。管理ボットをポーリングして認証情報を取得するのは、永続ワーカーだけです。各子ボットには専用の認証情報のみが渡され、インスタンスごとに分離された状態を使用します。

便利なプロファイル

同じ 4 つの組み込みプロファイルが、厳格な Hermes 関数カタログとして公開されます。Telegram で子ボットの作成が確認され、プロビジョニングされた後、factory_list_functions を使い、続けて既存の子ボットのスラッグと confirm=true を指定して factory_attach_function を使います。同じアタッチを繰り返しても何も起きません。再バインドしても、ボットのユーザー名と Telegram の ID は維持されます。一時停止と再開には、引き続き既存の停止／起動ツールを使用します。

プロファイル	用途
quick_faq	3～8 件のローカルなプレーンテキスト回答と連絡先を掲載する公開メニューです。
lead_inbox	プライバシー通知付きのメッセージフォームで、所有者への通知と確認済みのエクスポート／消去に対応します。
link_inbox	所有者専用の URL とメモを /list と /done で管理します。URL を取得することはありません。

所有者専用の分離とヘルスチェック用スモークテストとして、owner_echo も含まれています。プロファイルでは、任意のコード、実行ファイル、ファイルシステムパス、HTML、エージェントツール、リモート取得を指定できません。

60～90 秒のデモ

インストール後、Hermes に次のように依頼します。

「Studio FAQ」という名前で、ユーザー名 studio_faq_bot の簡単な FAQ ボットを作成してください。 ウェルカムメッセージ：「質問を選んでください。」料金、納期、連絡先に関する FAQ を追加してください。

Hermes から Telegram の作成リンクが返されます。リンクを開いて一度承認し、新しい子ボットを開いて /start、/faq 1、/health を送信します。プロビジョニングがまだ進行中の場合は、リクエストのステータスを Hermes に確認してください。その他のプロファイルでは、テスト用のリードを 1 件送信し、所有者専用の /export confirm、続けて /purge confirm を試すか、link_inbox に URL を保存して /list を確認し、/done 1 を使用してください。

プラットフォームと制限事項

• 対応ランタイム：systemd --user を使用する Linux。Ubuntu と WSL2 でテスト済みです。
• 対応クライアント：Hermes 0.18 のレガシー stdio と、テスト済みの MCP 2026-07-28 パスです。
• 非対応：Windows/macOS へのインストール、ホスト型マルチテナント、任意の子コード、自動ボットアカウント削除、Telegram 承認の回避。
• 管理ボットはユーザーが所有するもので、Hermes ゲートウェイボットとは別です。
• 子ボットの作成には毎回 Telegram での確認が必要です。「ワンクリック」ではありません。
• Official MCP Registry への掲載はメタデータであり、セキュリティ認証ではありません。

セキュリティの要点

• トークンが MCP の引数／結果、チャット、CLI 引数、YAML、SQLite、マニフェスト、ログ、トレース、フィクスチャ、Git に入ることはありません。
• シークレットディレクトリの権限は 0700、ファイルの権限は 0600 です。子ボットの認証情報は argv や環境変数ではなく、継承された匿名ファイルディスクリプターを通じて渡されます。
• 子ボットの受信更新 ID とオフセットは永続化されます。完了済みの重複は何も行いません。副作用が発生したか判然としないクラッシュの場合は、黙って再試行せず、調整のために隔離されます。外部の副作用が厳密に 1 回だけ発生するとは保証しません。
• 入力には上限が設けられ、検証されます。プロファイルが、指定されたコンテンツを実行したり取得したりすることはありません。

境界モデルの詳細については、セキュリティポリシー とアーキテクチャを参照してください。

ドキュメントとソース

• ソースと課題
• 仕様 · 受け入れ基準 · ステータス · 公開の証拠
• 変更履歴 · コントリビューション · セキュリティ
• Telegram Managed Bots · Official MCP Registry の掲載情報

トラブルシューティングと削除

未確認のジャーナル出力を共有せずに、ワーカーと Hermes の登録状況を確認します。

systemctl --user status bot-factory-manager.service
hermes mcp test bot-factory

WSL2 では、PID 1 が systemd である必要があり、ディストリビューションを実行状態に保つ必要があります。サービス／パッケージをアンインストールしても Factory のデータは削除されず、Telegram ボットも取り消されません。ローカルの XDG bot-factory ディレクトリと BotFather の設定は、それぞれ個別に確認してください。