GhostPaw Telegram

@ghostpaw/telegram

エージェント向けTelegramボット：ハンドラーが実行される前に、すべての更新をSQLiteにミラーリングします。

npm install @ghostpaw/telegram

Telegramボット向けのチャネルエンジンです。実行時依存関係のないfetchトランスポート、FTS5全文検索対応のSQLiteメッセージミラー、ファイルの即時BLOB保存、Markdownレンダリング、構造化されたLLMツールファサードを備えています。

受信した更新はすべて、ハンドラーが実行される前にローカルSQLiteデータベースへミラーリングされるため、ボットが認識した内容すべてを永続的に記録し、検索できます。写真、ドキュメント、ボイスメッセージ、動画の生バイトデータも含まれます。これらは更新の保存後にバックグラウンドでダウンロードされ、SHA-256ハッシュごとに1つだけ保持されます。ダウンロードに失敗すると、チェックサムのないファイル行が残るため、write.downloadFileで再試行できます。人間の開発者がコードでボットのバックエンドを構築する場合と、LLMエージェントが構造化されたツールファサードを介して操作する場合の両方を想定した、単一の事前バンドル済みファイルとして提供されます。

MCP サーバー

以下の各クライアントは、同じstdioサーバーを起動します：npx -y @ghostpaw/telegram mcp。 GHOSTPAW_TELEGRAM_DB環境変数（絶対パス）または--db <path>で別の場所を指定しない限り、 メッセージは~/.ghostpaw/telegram.dbに保存されます。

Claude Code

claude mcp add ghostpaw-telegram -- npx -y @ghostpaw/telegram mcp

または、スキルもインストールされるプラグインとして使用できます：

/plugin marketplace add GhostPawJS/telegram
/plugin install ghostpaw-telegram@ghostpaw-telegram

Codex CLI（~/.telegram/config.toml）

[mcp_servers.ghostpaw-telegram]
command = "npx"
args = ["-y", "@ghostpaw/telegram", "mcp"]

Cursor（.cursor/mcp.json）、Claude Desktop（claude_desktop_config.json） またはプロジェクトの.mcp.json：

{
  "mcpServers": {
    "ghostpaw-telegram": {
      "command": "npx",
      "args": ["-y", "@ghostpaw/telegram", "mcp"]
    }
  }
}

Claude Desktopのユーザーは、最新のGitHubリリースから server.mcpbをインストールすることもできます。 コンテナホスト向けにDockerfileも含まれています： docker build -t ghostpaw-telegram . && docker run -i --rm -v telegram:/data ghostpaw-telegram。

サーバーはMCP 2026-07-28（ステートレス、server/discover）と、 initializeベースのリビジョン2025-11-25、2025-06-18、2025-03-26、2024-11-05に対応しています。

送信およびモデレーション操作を実行するには、サーバー環境にTELEGRAM_BOT_TOKENを設定してください。 トークンがない場合、これらのツールは実行計画を返します。ローカルでの読み取りとツールの検出はオフラインでも機能します。 .mcp.jsonのトークンのプレースホルダーには、クライアント環境から値を指定する必要があります。 サーバーはライブラリのトランスポートによってデータが追加されたミラーを読み取ります。更新をポーリングすることはありません。

CLI

npx -y @ghostpaw/telegram tools
npx -y @ghostpaw/telegram call tg_read '{"subcommand":"list_chats"}'
npx -y @ghostpaw/telegram --db :memory: call tg_send '{"subcommand":"send_message","chatId":123,"text":"Hello"}'

送信の例は、TELEGRAM_BOT_TOKENが設定されていない場合、実行計画を返します。

エージェントスキル

SKILL.mdとskills/telegram/はパッケージに含まれています。npx -y @ghostpaw/telegram skillで スキルを表示するか、skills/telegram/をスキルフォルダーにコピーしてください。

インストール

npm install @ghostpaw/telegram

**Node.js 24+**が必要です（組み込みのnode:sqliteモジュールを使用します）。

クイックスタート

import { DatabaseSync } from 'node:sqlite';
import { createBot, initTelegramTables } from '@ghostpaw/telegram';

const db = new DatabaseSync('bot.db');
initTelegramTables(db);

const bot = createBot({
  token: process.env.TELEGRAM_TOKEN!,
  db,
  onMessage: async ({ message, user }) => {
    console.log(user?.firstName, message.text);
  },
});

await bot.start(); // long-polling

Webhook モードでは、代わりに webhook 設定を渡します。

const bot = createBot({
  token: process.env.TELEGRAM_TOKEN!,
  db,
  webhook: { path: '/webhook', port: 8443, secretToken: process.env.TG_SECRET },
  onMessage: async ({ message, user }) => { /* ... */ },
});

await bot.start(); // listens on port 8443

保存されるデータ

ハンドラーの実行前に、すべての更新が SQLite にミラーリングされます。

• メッセージ — テキスト、メディア、編集、返信関係、アルバム、スレッド（Unicode のダイアクリティカルマークを折りたたむ FTS5 全文インデックス）
• ユーザー — 名、姓、ユーザー名、言語コード
• チャット — タイトル、種類、メンバー数、フォーラムフラグ
• メンバー — チャットごとのステータス、権限、管理者タイトル
• リアクション — メッセージごとのユーザー別絵文字、絵文字ごとの件数とイベントログ
• ファイル — メタデータと BLOB として保存される生バイト列。SHA-256 で重複排除され、受信したすべてのファイルがバックグラウンドでダウンロードされます（DEFAULTS.autoDownload は非推奨で、使用されません。この動作は変わりません）
• コールバック — データと回答済み状態を含むインラインボタンの押下
• ボットの状態 — 任意のキー／値ストアと実行統計

8 つすべてのテーブルは、1 回の呼び出しで作成されます：initTelegramTables(db)。

2 つの利用者層

人間の開発者

read、write、network 名前空間を使用すると、あらゆるドメイン操作にコードから直接アクセスできます。

import { read, write, network } from '@ghostpaw/telegram';

// query the local mirror — no network calls
const chat = read.getChat(db, chatId);
const messages = read.listMessages(db, { chatId, limit: 50 });
const results = read.searchMessages(db, chatId, 'invoice');
const chain = read.replyChain(db, chatId, messageId);

// retrieve a stored file blob
const bytes = write.getFileBlob(db, fileId); // Buffer | null

// send text and media
await write.sendMessage(bot.client, chatId, 'Hello');
await write.sendPhoto(bot.client, chatId, fileId);
await write.sendDocument(bot.client, chatId, buffer, { caption: 'Report' });
await write.broadcast(bot.client, chatIds, 'Announcement');

// streaming — progressive in-place edits
const stream = write.createStream(bot.client, { chatId });
await stream.append('Thinking...');
await stream.replace('Done.');

実例を含む開発者向けガイドの全編は、docs/HUMAN.md をご覧ください。

LLM エージェント

構造化されたランタイムインターフェースとして、tools、skills、soul 名前空間を使用します。

import { tools, skills, soul } from '@ghostpaw/telegram';

// 4 JSON-schema tools with structured ToolResult responses
const allTools = tools.telegramTools;
const readTool = tools.getTelegramToolByName('tg_read');
const result = readTool?.handler(db, { subcommand: 'search_messages', chatId, query: 'invoice' });

// 6 workflow playbooks for common multi-step scenarios
const allSkills = skills.telegramSkills;

// Herald persona for system prompts
const prompt = soul.renderTelegramSoulPromptFoundation();

すべてのツールは、outcome: 'success' | 'no_op' | 'error'、構造化データ、次のステップのヒントを含む判別可能な結果を返します。解析が必要な例外はスローされません。

soul、ツール、スキルを網羅した AI 向けガイドの全編は、docs/LLM.md をご覧ください。

パッケージのインターフェース

エクスポート	役割
initTelegramTables(db)	1 回で完了する DDL。起動時に 1 回呼び出します
createBot(config)	組み込みの fetch トランスポートを備えたボット全体の構成。ポーリングまたは Webhook に対応
adaptBot(grammy)	生の grammy Bot を MockBot エグゼキューターインターフェースに接続
read	ローカルの SQLite ミラーをクエリ（ネットワーク通信なし）
write	メッセージ、メディア、アクションの送信と、ファイル BLOB の管理
keyboards	インラインキーボードとコールバックボタンを構築
network	ポーリングと更新のディスパッチを管理
render	純粋な Markdown とテキストの変換
tools	LLM エージェント向けの JSON スキーマツール 4 種
skills	LLM エージェント向けのワークフロープレイブック 6 種
soul	システムプロンプト用の Herald ペルソナ
DEFAULTS	調整可能なランタイム定数

ツール

ツールはデフォルトでプランを返します。既存の同期ハンドラーは外部アクションを実行しません。 送信やモデレーションのアクションを実行するには、非同期ファサードを明示的に作成します。

const facade = tools.createTelegramToolFacade({
  client: bot.client,
  execute: true,
  perChatPerSecond: 1,
  globalPerSecond: 30,
  maxRetries: 2,
});
const result = await facade.handler(db, 'tg_send', {
  subcommand: 'send_message', chatId: 123, text: 'Hello',
});

プランのみの動作を維持するには、execute を省略します。実行では外部送信エグゼキューターを再利用し、アクションデータと、該当する場合は sent メッセージ ID を含む共通の結果形式を返します。また、エラー内のボットトークンはマスクされます。容量 1 のトークンバケットにより、チャットごとおよび全体で各 API 呼び出しが制限されます。Telegram からの 429 retry_after 応答を受け取ると、再試行は一時停止されます。デフォルトでは 2 回再試行します。制限はファサードのインスタンスごとに適用されます。同じボットを共有する呼び出し元では、1 つのファサードを再利用してください。複数の呼び出しを伴うアクションが失敗した場合、実行が一部だけ完了することがあります（たとえば、kick は ban してから unban します）。

オペレーターの意図に沿って構成された 4 つのツール：

ツール	機能
tg_read	メッセージ、チャット、ユーザー、リアクション、編集履歴、返信チェーンをクエリ
tg_send	メッセージの送信、編集、削除、転送、ピン留め、リアクションの設定、一斉送信
tg_manage	ユーザーの ban、unban、制限、昇格、kick、およびメンバーステータスのクエリ
tg_connect	ボットの統計情報の取得、ボットの状態の読み取り、アクティブなチャットの一覧表示

各ツールは、名前、説明、JSON Schema、副作用レベル、readOnly フラグなどのランタイムメタデータをエクスポートするため、エージェントのハーネスはドキュメントを読まずにツールを組み込めます。

スキル

ワークフローのプレイブックを Markdown 文字列で6つ用意しています。

スキル	ワークフロー
manage-telegram-conversations	コンテキストを読み取り、返信、ピン留め、スレッドとアルバムを追跡します
moderate-chat-effectively	違反を検出し、警告、制限、禁止を監査証跡とともに実施します
handle-group-administration	権限の昇格、降格、移行、設定を行います
broadcast-to-audience	メッセージを作成、送信し、エラーに対処して失敗したチャットを再試行します
search-and-retrieve-messages	全文検索、返信チェーン、編集履歴を確認します
stream-progressive-responses	オーバーフローとエラー復旧に対応したデバウンス付きストリーミングを行います

ドキュメント

ドキュメント	対象読者
docs/HUMAN.md	read／write／network API を利用する開発者
docs/LLM.md	ツール、スキル、ソウルを連携させるエージェントの構築者
docs/RECIPES.md	ストリーミング、承認フロー、ページネーションなどの高度な UI／UX パターン
docs/README.md	アーキテクチャの概要：ストレージモデル、サーフェス、不変条件
docs/entities/	正確な公開 API の一覧を含む、エンティティごとのマニュアル

このパッケージには実行時依存関係がありません。Bot API リクエストには Node 24 のグローバル fetch を、Markdown の解析にはリポジトリ内の同期パーサーを使用します。grammy と marked は、互換性テストで使用する開発依存関係です。

createBot は、fetch 実装を注入する場合やカスタム Bot API エンドポイントを指定する場合に、オプションの api: { fetch, apiRoot } 設定を受け付けます。デフォルトのエンドポイントは https://api.telegram.org です。

adaptBot は引き続き grammy の Bot インスタンスを受け付けます。アップロードを伴わない呼び出しには api.raw を使用し、ファイルのアップロードには組み込みクライアントを使用するため、アップロードには grammy の API トランスフォーマーは適用されません。2つ目の引数には、オプションで { fetch, apiRoot } を指定できます。

開発

npm install
npm test            # node:test runner
npm run typecheck   # tsc --noEmit
npm run lint        # biome check
npm run build       # ESM + CJS + declarations via tsup
npm run test:dist   # built artifact checks (after build)
npm run check:deps  # verify zero runtime dependencies

このリポジトリでは、Volta を使って Node 24.14.0 に固定しています。お好みのバージョンマネージャーを使用してください。

サポート

このパッケージがプロジェクトに役立つ場合は、メンテナンスへのスポンサーをご検討ください。

---

Anonyfox • MIT ライセンス