{"_id":"@imenam/mcp-telegram","_rev":"5-2a721e38d479521255119253bc98c433","name":"@imenam/mcp-telegram","dist-tags":{"latest":"1.0.6"},"versions":{"1.0.1":{"name":"@imenam/mcp-telegram","version":"1.0.1","keywords":["mcp","model-context-protocol","telegram","telegram-bot","channel"],"author":{"name":"Matthieu Pesnot-Pin","email":"matthieupin@gmail.com"},"license":"ISC","_id":"@imenam/mcp-telegram@1.0.1","maintainers":[{"name":"imenam","email":"matthieupin@gmail.com"}],"bin":{"mcp-telegram":"dist/src/index.js"},"dist":{"shasum":"631eb6727918610928f2094cc148c72a245575ff","tarball":"https://registry.npmjs.org/@imenam/mcp-telegram/-/mcp-telegram-1.0.1.tgz","fileCount":33,"integrity":"sha512-3w9Itx3E3L/s5ICdC5mY/XpD+BpU8siHNaI9Q0UdQWGqVdMuaAxHHvfNMXptUXASX0hh10PPbxAvNsDvFHlLJQ==","signatures":[{"sig":"MEUCIAtSyNROBHhlFqV9B/Elst0GZxOTsmZBC5uAtpy1PxkmAiEA9JMVpP2kB9X/qj11BvySrJx8PDUr2CONX+VWQOEBZT8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":103108},"main":"dist/src/index.js","type":"module","types":"./dist/src/index.d.ts","engines":{"node":">=20"},"gitHead":"c5f3fd75f40ff18725909f64358d5ba070d5bd59","scripts":{"test":"npm run build && vitest run","build":"npm run clean && node scripts/generate-version.js && tsc","clean":"node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"","start":"node dist/src/index.js","release":"npm version patch && npm publish && git push --follow-tags","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"imenam","email":"matthieupin@gmail.com"},"_npmVersion":"12.0.2","description":"MCP server that connects an AI agent to one Telegram channel through a bot: read incoming posts, publish, edit, delete, pin, react and exchange files.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"zod":"^4.6.5","@modelcontextprotocol/sdk":"^1.30.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^5.0.2","typescript":"^7.0.2","@types/node":"^26.6.3"},"_npmOperationalInternal":{"tmp":"tmp/mcp-telegram_1.0.1_1790663036113_0.029797077044623643","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@imenam/mcp-telegram","version":"1.0.2","keywords":["mcp","model-context-protocol","telegram","telegram-bot","channel"],"author":{"name":"Matthieu Pesnot-Pin","email":"matthieupin@gmail.com"},"license":"ISC","_id":"@imenam/mcp-telegram@1.0.2","maintainers":[{"name":"imenam","email":"matthieupin@gmail.com"}],"bin":{"mcp-telegram":"dist/src/index.js"},"dist":{"shasum":"740204d657a6570fb110a83e649108cfe3b50e6c","tarball":"https://registry.npmjs.org/@imenam/mcp-telegram/-/mcp-telegram-1.0.2.tgz","fileCount":33,"integrity":"sha512-mrr7buVsu3a1KQ3RFQcN8RiyPcexaCHnBdXqRDyR43SkXEI01jTLdFMV6oS920MTt70VqAJDIBRDYzjcy9wBwg==","signatures":[{"sig":"MEUCIQCZbf/8ZllIeOjBZmuhMfTOJLhn8S7tRepjiUrJhPKLfgIgQ55PnNxk2ED/aeHMC++V/Tu4jN/b2sHQn/CvNSTgjpg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQC9tM/OFv/0f7WaWyWh274TTU//+58LmZWVjSHumrlLmAIhAKtwKwjzjYAXlNpzilF5CHJWwr3fe/b4s2KtT/DhsFLT","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":103108},"main":"dist/src/index.js","type":"module","types":"./dist/src/index.d.ts","engines":{"node":">=20"},"gitHead":"fc546256d1621a8be4da20b6d666044a97608710","scripts":{"test":"npm run build && vitest run","build":"npm run clean && node scripts/generate-version.js && tsc","clean":"node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"","start":"node dist/src/index.js","release":"npm version patch && npm publish && git push --follow-tags","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"imenam","email":"matthieupin@gmail.com"},"_npmVersion":"12.0.2","description":"MCP server that connects an AI agent to one Telegram channel through a bot: read incoming posts, publish, edit, delete, pin, react and exchange files.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"zod":"^4.6.5","@modelcontextprotocol/sdk":"^1.30.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^5.0.2","typescript":"^7.0.2","@types/node":"^26.6.3"},"_npmOperationalInternal":{"tmp":"tmp/mcp-telegram_1.0.2_1790663287326_0.5377858894026424","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@imenam/mcp-telegram","version":"1.0.3","keywords":["mcp","model-context-protocol","telegram","telegram-bot","channel"],"author":{"name":"Matthieu Pesnot-Pin","email":"matthieupin@gmail.com"},"license":"ISC","_id":"@imenam/mcp-telegram@1.0.3","maintainers":[{"name":"imenam","email":"matthieupin@gmail.com"}],"bin":{"mcp-telegram":"dist/src/index.js"},"dist":{"shasum":"12968019698a17b639bc8d9107c90559fb830373","tarball":"https://registry.npmjs.org/@imenam/mcp-telegram/-/mcp-telegram-1.0.3.tgz","fileCount":41,"integrity":"sha512-hx133LKjey//jCSl23shqLHsfOMzx4DyAVUzxQStbP4segvgYoVoFogbOlepXLQ3dep94UncNYNjjnB7yGvzLA==","signatures":[{"sig":"MEYCIQCrqHQav1bkdW3NKCzWhWOehiW/czHBiEEr0LHCMqyaxQIhAIyExP3qX9ou6W3jVQDSbxm2Rvic7KaOCS6LUrmKQCv5","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIHSYFakZjPuZrQ9d1TA8UszfCWH0mgKeE/tldgrOlNrkAiEA00ielOi8PiMYi9DdZV8IvSPp0EbF+7w9gJ9l9NLJQO4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":131338},"main":"dist/src/index.js","type":"module","types":"./dist/src/index.d.ts","engines":{"node":">=20"},"gitHead":"859a9911ca560c940061fcca65d43a7f39a7aa64","scripts":{"test":"npm run build && vitest run","build":"npm run clean && node scripts/generate-version.js && tsc","clean":"node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"","start":"node dist/src/index.js","release":"npm version patch && npm publish && git push --follow-tags","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"imenam","email":"matthieupin@gmail.com"},"_npmVersion":"12.0.2","description":"MCP server that connects an AI agent to one Telegram channel through a bot: read incoming posts, publish, edit, delete, pin, react and exchange files.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"zod":"^4.6.5","@modelcontextprotocol/sdk":"^1.30.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^5.0.2","typescript":"^7.0.2","@types/node":"^26.6.3"},"_npmOperationalInternal":{"tmp":"tmp/mcp-telegram_1.0.3_1790671920195_0.006012114585121742","host":"s3://npm-registry-packages-npm-production"}},"1.0.5":{"name":"@imenam/mcp-telegram","version":"1.0.5","keywords":["mcp","model-context-protocol","telegram","telegram-bot","channel"],"author":{"name":"Matthieu Pesnot-Pin","email":"matthieupin@gmail.com"},"license":"ISC","_id":"@imenam/mcp-telegram@1.0.5","maintainers":[{"name":"imenam","email":"matthieupin@gmail.com"}],"bin":{"mcp-telegram":"dist/src/index.js"},"dist":{"shasum":"59e67cf5b4a3b41afed4a52fb67648a031268d09","tarball":"https://registry.npmjs.org/@imenam/mcp-telegram/-/mcp-telegram-1.0.5.tgz","fileCount":41,"integrity":"sha512-u2MXZIRJTrFBgdlgX+0UMfJIax9Y1B2Ow6e524oQ2pIfxEpFO/GatViyf9VAcbliDpSDjqoUXaKEafMDRWgPgg==","signatures":[{"sig":"MEYCIQCSel8WS5uzuWHeiw4tQt+rNwQUHBUD8PUcZq6O2Jn/UQIhAMvrgPR9ZINjceSmuYSpJqkz7nbxDnSyUmoNbOox1t7g","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQCH0MlMjTsEKP656nFIw3eVo5LYMVQ5L5UejoNlPvXwBwIgQyHwHr0Aa8ptQnU7Qvv1WZyZYSKdvS4w0L4Wuh8jN0Y=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":131822},"main":"dist/src/index.js","type":"module","types":"./dist/src/index.d.ts","engines":{"node":">=20"},"gitHead":"5652a9371cf3077fdce5d887b68da9afd484c11f","scripts":{"test":"npm run build && vitest run","build":"npm run clean && tsc","clean":"node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"","start":"node dist/src/index.js","release":"npm version patch && npm publish && git push --follow-tags","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"imenam","email":"matthieupin@gmail.com"},"_npmVersion":"12.0.2","description":"MCP server that connects an AI agent to one Telegram channel through a bot: read incoming posts, publish, edit, delete, pin, react and exchange files.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"zod":"^4.6.5","@modelcontextprotocol/sdk":"^1.30.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^5.0.2","typescript":"^7.0.2","@types/node":"^26.6.3"},"_npmOperationalInternal":{"tmp":"tmp/mcp-telegram_1.0.5_1793013266232_0.8342798392739073","host":"s3://npm-registry-packages-npm-production"}},"1.0.6":{"_id":"@imenam/mcp-telegram@1.0.6","bin":{"mcp-telegram":"dist/src/index.js"},"bugs":{"url":"https://github.com/Matthieu-Pesnot-Pin/mcp-telegram/issues"},"dist":{"shasum":"e091908f62fb92937364e94a6c5a042b02eb7d1e","tarball":"https://registry.npmjs.org/@imenam/mcp-telegram/-/mcp-telegram-1.0.6.tgz","fileCount":41,"integrity":"sha512-+e5K+s2oPUiyYM2G8tQ8hm39ZUldmXzpGXa6zooaI8Jd6lALq8AQANp31xwYXRhXjYl5jJ2Prm4qFP6AjDTPQQ==","signatures":[{"sig":"MEUCIQCznZ6KW6xEo5r40SMtxbXiEC6DVU6wEuG7ageg5eiBcAIgGoeuF4Umn8YhMd6nWl7wXAkJN1HrweAy9nwEtoDZhLA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBb5/kj3tsx8EUwcMp7nhA0kIfy7ZQgnFQQHSXLP9cFsAiADzO5lYcCCF1Y4THl67GuYgf1T+dSAuW9xXDuy1vC+AA=="}],"unpackedSize":132712},"main":"dist/src/index.js","name":"@imenam/mcp-telegram","type":"module","types":"./dist/src/index.d.ts","author":{"name":"Matthieu Pesnot-Pin","email":"matthieupin@gmail.com"},"engines":{"node":">=20"},"gitHead":"716a3b90c2a4ddb354cfee9e8560994cc439c3da","license":"ISC","scripts":{"test":"npm run build && vitest run","build":"npm run clean && tsc","clean":"node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"","start":"node dist/src/index.js","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"version":"1.0.6","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"848389be-75d4-45f3-a7d3-a60fa41113e8"}},"homepage":"https://github.com/Matthieu-Pesnot-Pin/mcp-telegram#readme","keywords":["mcp","model-context-protocol","telegram","telegram-bot","channel"],"repository":{"url":"git+https://github.com/Matthieu-Pesnot-Pin/mcp-telegram.git","type":"git"},"_npmVersion":"11.19.1","description":"MCP server that connects an AI agent to one Telegram channel through a bot: read incoming posts, publish, edit, delete, pin, react and exchange files.","directories":{},"maintainers":[{"name":"imenam","email":"matthieupin@gmail.com"}],"_nodeVersion":"24.22.2","dependencies":{"zod":"^4.6.5","@modelcontextprotocol/sdk":"^1.30.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^5.0.2","typescript":"^7.0.2","@types/node":"^26.6.3"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-telegram_1.0.6_1793974277039_0.6814562294575832"}}},"time":{"created":"2026-09-29T06:23:55.854Z","modified":"2026-11-06T14:11:17.417Z","1.0.1":"2026-09-29T06:23:56.318Z","1.0.2":"2026-09-29T06:28:07.403Z","1.0.3":"2026-09-29T08:52:00.276Z","1.0.5":"2026-10-26T11:14:26.317Z","1.0.6":"2026-11-06T14:11:17.165Z"},"author":{"name":"Matthieu Pesnot-Pin","email":"matthieupin@gmail.com"},"license":"ISC","keywords":["mcp","model-context-protocol","telegram","telegram-bot","channel"],"description":"MCP server that connects an AI agent to one Telegram channel through a bot: read incoming posts, publish, edit, delete, pin, react and exchange files.","maintainers":[{"name":"imenam","email":"matthieupin@gmail.com"}],"readme":"# mcp-telegram\n\nServeur MCP qui relie un agent IA à **un seul channel Telegram**, par l'intermédiaire d'un\nbot administrateur de ce channel. L'agent lit les posts qui arrivent, publie, modifie,\nsupprime, épingle, réagit, envoie et télécharge des fichiers — toujours dans ce channel-là,\nqu'aucun outil ne permet de changer.\n\n```mermaid\nflowchart LR\n    A[\"Agent IA\"] -->|stdio MCP| B[\"mcp-telegram\"]\n    B -->|\"HTTPS Bot API\\n(token du bot)\"| C[\"api.telegram.org\"]\n    C --> D[\"Channel\\n(bot administrateur)\"]\n    B -->|posts reçus| E[(\"MCP_DATA_DIR\\nchannels/*.json\")]\n```\n\n## Ce qu'il faut côté Telegram\n\nLe serveur utilise la **Bot API** : il n'a besoin que du token d'un bot, jamais de votre\ncompte personnel ni de votre numéro de téléphone.\n\n| Élément | Où l'obtenir | Rôle |\n|---|---|---|\n| **Token du bot** | [@BotFather](https://t.me/BotFather), commande `/newbot` | Authentifie toutes les requêtes. Format `123456789:AAH…`. C'est un secret : qui le détient contrôle le bot. |\n| **Statut d'administrateur** | Réglages du channel > Administrateurs | Un bot ne peut entrer dans un channel **que** comme administrateur. |\n| **Droits d'administrateur** | Même écran, au moment de l'ajout | Voir le tableau ci-dessous. |\n| **Identifiant du channel** | `@username` pour un channel public ; `--find-channel` donne l'identifiant `-100…` de tout channel | Désigne le channel ciblé. |\n\nDroits à accorder au bot, selon ce que l'agent doit pouvoir faire :\n\n| Droit (Bot API) | Libellé dans l'application | Outils concernés |\n|---|---|---|\n| `can_post_messages` | Publier des messages | `send_post`, `send_media` |\n| `can_edit_messages` | Modifier les messages des autres | `edit_post`, `pin_post`, `unpin_post` |\n| `can_delete_messages` | Supprimer les messages des autres | `delete_posts` |\n\nLa lecture ne demande aucun droit particulier : un bot administrateur reçoit tous les posts\ndu channel. `get_channel_info` et `--find-channel` affichent les droits effectivement accordés.\n\n### Procédure\n\n1. Dans Telegram, ouvrir [@BotFather](https://t.me/BotFather), envoyer `/newbot`, choisir un\n   nom puis un identifiant se terminant par `bot`. Copier le token.\n2. Ouvrir le channel > Administrateurs > Ajouter un administrateur > chercher le bot par son\n   identifiant, puis accorder les droits voulus.\n3. Lancer `npx -y @imenam/mcp-telegram --find-channel` et coller le token : la commande affiche\n   l'identifiant du channel (voir ci-dessous).\n\nUn bot doit être **dédié** à ce serveur : si un autre programme lit ses mises à jour\n(`getUpdates` ou webhook), l'un des deux ne reçoit plus rien. `--find-channel` détecte un webhook\net propose de le supprimer.\n\n### Limites de la Bot API\n\n- **Pas d'historique.** Aucune méthode ne permet à un bot de relire les posts d'un channel.\n  Le serveur conserve ce que Telegram lui pousse — posts publiés ou modifiés depuis que le bot\n  est administrateur — et les posts qu'il envoie lui-même.\n- **Rétention de 24 h.** Telegram garde les mises à jour non lues au plus 24 heures. Un post\n  publié pendant une période de plus de 24 h sans aucun appel d'outil de lecture est perdu\n  pour le serveur.\n- **Suppressions invisibles.** Telegram ne signale pas aux bots les posts supprimés par un\n  humain : ils restent dans `list_posts`.\n- **Fichiers.** Envoi : 10 Mo pour une photo, 50 Mo pour les autres fichiers. Téléchargement :\n  20 Mo au plus.\n- **Textes.** 4096 caractères par post, 1024 par légende.\n- **Débit.** Au-delà d'environ un message par seconde dans un même chat, Telegram répond\n  `429` avec un délai d'attente, que l'outil rapporte tel quel.\n\n## Démarrage rapide\n\nLe token et le channel sont propres à chaque projet : ils vivent dans le bloc `env` de\nl'entrée `mcp-telegram` de son `.mcp.json`, et nulle part ailleurs.\n\n```bash\n# 1. Trouver l'identifiant du channel à partir du token\nnpx -y @imenam/mcp-telegram --find-channel\n\n# 2. Dans le dossier du projet, déclarer le serveur dans .mcp.json\nnpx -y @imenam/mcp-telegram --claude-setup-mcp\n```\n\n`--find-channel` demande le token (saisie masquée), le vérifie auprès de Telegram et affiche,\npour chaque channel où le bot a été ajouté, la ligne `TELEGRAM_CHANNEL=-100…` à recopier et les\ndroits du bot. La commande n'écrit rien. Un channel n'y apparaît que si Telegram a signalé au\nbot son ajout, ou un post, dans les dernières 24 h : sinon, publier un message dans le channel\net relancer. Un serveur mcp-telegram qui tourne avec le même bot consomme ces événements :\nl'arrêter le temps de la commande.\n\n`--claude-setup-mcp` ajoute l'entrée au `.mcp.json` du dossier courant, sans toucher aux\nautres serveurs ; il reste à remplir les deux variables :\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-telegram\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@imenam/mcp-telegram\"],\n      \"env\": {\n        \"TELEGRAM_BOT_TOKEN\": \"123456789:AAH…\",\n        \"TELEGRAM_CHANNEL\": \"-1001234567890\",\n        \"TELEGRAM_UPLOAD_ROOTS\": \"C:/Users/moi/Documents/telegram\",\n        \"TELEGRAM_DOWNLOAD_ROOTS\": \"C:/Users/moi/Downloads/telegram\"\n      }\n    }\n  }\n}\n```\n\nPour une copie locale non publiée, remplacer `command` et `args` par\n`\"command\": \"node\", \"args\": [\"<chemin>/mcp-telegram/dist/src/index.js\"]`.\n\n## Outils MCP\n\n| Outil | Rôle |\n|---|---|\n| `get_channel_info` | Titre, lien, description, abonnés, post épinglé, droits du bot et droits manquants. |\n| `list_posts` | Posts connus, du plus récent au plus ancien, après lecture des mises à jour en attente. Pagination par `before_message_id` / `after_message_id`. |\n| `get_post` | Un post par son `message_id` : texte ou légende, média, réactions, lien. |\n| `enable_notifications` | Active les notifications entrantes : renvoie l'appel `Monitor` qui arme le veilleur (voir ci-dessous). |\n| `wait_for_posts` | Attend jusqu'à 300 s l'arrivée d'un post nouveau ou modifié. Renvoie un `cursor` : passé à l'appel suivant, il rend exactement ce qui est arrivé depuis, modifications comprises. |\n| `send_post` | Publie un texte, brut ou formaté (`HTML`, `MarkdownV2`), avec ou sans notification sonore. |\n| `send_media` | Publie une photo, vidéo, animation, audio, note vocale ou document, depuis un fichier local, une URL ou un `file_id`. |\n| `edit_post` | Modifie le texte d'un post texte, ou la légende d'un post média. |\n| `delete_posts` | Supprime jusqu'à 100 posts. |\n| `pin_post` / `unpin_post` | Épingle ou désépingle un post. |\n| `react_to_post` | Pose ou retire la réaction du bot. |\n| `download_media` | Télécharge le fichier d'un post dans un dossier de la machine de l'agent. |\n\nChaque post est rendu sous la forme :\n\n```json\n{\n  \"message_id\": 42,\n  \"date\": \"2026-09-28T09:15:00.000Z\",\n  \"kind\": \"photo\",\n  \"text\": \"Légende de la photo\",\n  \"media\": { \"file_id\": \"AgAC…\", \"file_unique_id\": \"AQAD…\", \"width\": 1280, \"height\": 720 },\n  \"reactions\": [{ \"emoji\": \"🔥\", \"count\": 3 }],\n  \"link\": \"https://t.me/monchannel/42\"\n}\n```\n\nSi `TELEGRAM_AGENT_NAME` est défini, chaque texte publié par `send_post`, chaque légende de\n`send_media` et chaque texte ou légende modifié par `edit_post` commence par\n`Message de <nom>`, suivi d'une ligne vide. L'en-tête est échappé selon le `parse_mode` ; un\nmédia sans légende reçoit l'en-tête seule comme légende. L'en-tête compte dans les limites de\n4096 et 1024 caractères.\n\n## Notifications entrantes\n\nMême mécanisme que mcp-messenger : l'agent n'a pas à interroger le channel, chaque post nouveau\nou modifié le réveille, y compris à l'arrêt.\n\n1. En début de session, l'agent appelle `enable_notifications`. Le serveur dépose un relais\n   (token, channel, dossier de données) dans `MCP_DATA_DIR/watch/`, en droits 600, et renvoie\n   l'appel `Monitor` à faire, par exemple :\n   ```text\n   command:     \"C:/nvm4w/nodejs/node.exe\" \"…/mcp-telegram/dist/src/index.js\" --watch \"…/watch/<id>.json\"\n   timeout_ms:  1800000\n   ```\n   La commande reprend le Node et le script du serveur : elle fonctionne aussi bien avec le\n   paquet publié qu'avec une copie locale.\n2. L'agent arme ce `Monitor`. Le veilleur (`--watch`) lit les mises à jour avec le même stockage\n   et le même verrou que le serveur. Chaque post reçu ou modifié y porte un numéro d'ordre de\n   réception : le veilleur annonce tout post dont le numéro dépasse le dernier annoncé, même si\n   c'est un appel d'outil de l'agent (`list_posts`, `get_post`…) qui a lu la mise à jour. Une\n   ligne par post :\n   ```text\n   [telegram] new post 42 (photo): Légende de la photo — read it with get_post\n   ```\n3. L'hôte arrête tout `Monitor` au bout de 30 minutes au plus : l'agent le réarme avec le même\n   appel. Un second `enable_notifications` pendant qu'un veilleur tourne le signale au lieu d'en\n   demander un deuxième.\n\nLe relais est propre au processus serveur qui l'écrit. Il est supprimé à l'arrêt du serveur, ou,\nsi le serveur a été tué, par le prochain serveur qui démarre. Le token ne passe jamais dans la\ncommande du veilleur, donc jamais dans la conversation.\n\nDerrière mcp-http-gateway, le fonctionnement est décrit ci-dessous, dans\n[Notifications derrière le gateway](#notifications-derrière-le-gateway).\n\n## Configuration\n\nLa configuration est lue dans l'environnement du serveur, c'est-à-dire le bloc `env` de son\nentrée. Si une variable manque, le serveur démarre quand même et chaque outil renvoie une erreur\nqui la nomme.\n\n| Variable | Défaut | Rôle |\n|---|---|---|\n| `TELEGRAM_BOT_TOKEN` | requis | Token du bot. |\n| `TELEGRAM_CHANNEL` | requis | `@username` public ou identifiant `-100…` du channel. |\n| `TELEGRAM_UPLOAD_ROOTS` | aucun | Dossiers dont `send_media` peut publier un fichier local, séparés par `;` sous Windows et `:` ailleurs. Vide : aucun fichier local ne peut être publié ; `url` et `file_id` restent utilisables. |\n| `TELEGRAM_DOWNLOAD_ROOTS` | aucun | Dossiers où `download_media` peut écrire, même séparateur. Vide : aucun téléchargement local. |\n| `TELEGRAM_AGENT_NAME` | aucun | Nom placé en tête de chaque publication de l'agent : `Message de <nom>`. Vide : aucune en-tête. |\n| `MCP_DATA_DIR` | `~/.mcp-telegram` | Dossier des posts conservés, accessible au seul utilisateur courant. |\n| `TELEGRAM_LOG_LEVEL` | `info` | `debug`, `info`, `warn` ou `error`. Les journaux vont sur stderr, token masqué. |\n\nContenu de `MCP_DATA_DIR` :\n\n```text\nbots/<id du bot>/         offset de lecture des mises à jour et verrou\nchannels/<id>.json        posts conservés, 5000 au plus par channel\nwatch/                    relais des notifications et présence des veilleurs\n```\n\nPlusieurs sessions peuvent utiliser le même bot sur la même machine : un verrou sérialise la\nlecture des mises à jour. Les posts de chaque channel du bot sont conservés, si bien que deux\nconfigurations visant deux channels différents avec le même bot ne se volent rien.\n\n## Derrière mcp-http-gateway\n\nQuand le serveur tourne sur la machine du gateway, les fichiers voyagent par les conventions\ndu relais `--mcp` :\n\n- `send_media` déclare la paire `file_path` / `file_content` (+ `file_name`) : le relais lit\n  le fichier chez l'agent et en transmet le contenu. Renseigner `GATEWAY_INLINE_ROOTS` dans la\n  configuration du relais ; `TELEGRAM_UPLOAD_ROOTS` ne s'applique qu'aux fichiers lus par le\n  serveur lui-même.\n- `download_media` déclare la paire `destination_path` / `destination_relay` : le relais écrit\n  le fichier chez l'agent. Renseigner `GATEWAY_INLINE_WRITE_ROOTS` ; `TELEGRAM_DOWNLOAD_ROOTS`\n  ne s'applique qu'aux fichiers écrits par le serveur lui-même.\n\nLe token et le channel se passent alors dans le bloc `env` de `mcp-servers.json` (ou chiffrés\ndans mcp-gateway-manager), avec un `MCP_DATA_DIR` propre à ce serveur.\n\n### Notifications derrière le gateway\n\nLe serveur tourne sur la machine du gateway, l'agent sur la sienne : le veilleur ne peut plus\nlire Telegram lui-même. Il tourne toujours sur la machine de l'agent, mais c'est le relais\n`--mcp` de mcp-http-gateway qui le fournit, et il interroge le serveur à travers le gateway\n(convention `_gateway_watch`, décrite dans le README de mcp-http-gateway) :\n\n1. `enable_notifications` déclare la propriété réservée `_gateway_watch`, que le relais remplit\n   et cache à l'agent. Le serveur répond alors par une spécification de veille : l'outil\n   `wait_for_posts` et le numéro d'ordre actuel.\n2. Le relais dépose chez l'agent un fichier de veille (adresse et jeton du gateway, route,\n   point de reprise) et rend l'appel `Monitor` à faire, qui lance `mcp-http-gateway --watch`.\n3. Ce veilleur appelle `wait_for_posts` en boucle avec le point de reprise, chaque appel\n   restant ouvert jusqu'à 50 s. Le serveur renvoie les lignes à afficher et le point suivant\n   dans `_meta[\"gateway/events\"]`.\n\nLe serveur reste le seul lecteur Telegram et le token Telegram ne quitte jamais la machine du\ngateway. Il faut un relais mcp-http-gateway qui connaît la convention `_gateway_watch`.\n\n## Sécurité\n\n- Le token donne le contrôle total du bot. Il ne figure dans aucun journal ni message d'erreur.\n  S'il fuit, le révoquer dans @BotFather (`/mybots` > API Token > Revoke) et mettre le nouveau\n  dans `TELEGRAM_BOT_TOKEN`.\n- Le `.mcp.json` qui porte le token ne doit pas être versionné. Le token y figure en clair, et\n  finit aussi dans les transcripts de l'agent (`~/.claude/projects/*.jsonl`).\n- Le serveur ne lit et n'écrit de fichiers que dans les dossiers de `TELEGRAM_UPLOAD_ROOTS` et\n  `TELEGRAM_DOWNLOAD_ROOTS`, liens symboliques résolus. Un contenu qui pousserait l'agent à\n  publier `~/.ssh/id_rsa` dans le channel se heurte à un refus. Garder ces dossiers dédiés.\n- N'accorder au bot que les droits nécessaires : sans `can_delete_messages`, l'agent ne peut\n  rien supprimer.\n- Le contenu des posts vient du channel : l'agent le traite comme une donnée, jamais comme une\n  instruction (rappelé dans les instructions du serveur).\n\n## Développement\n\n```bash\nnpm install\nnpm run build        # vide dist/ puis compile\nnpm test             # build + vitest\nnpm run typecheck\n```\n\n### Structure\n\n```text\nsrc/\n  index.ts            point d'entrée : --find-channel, --watch, --claude-setup-mcp, --help, --version, mode MCP\n  config.ts           lecture et validation des variables d'environnement\n  logger.ts           journal sur stderr, token masqué\n  version.ts          version lue dans package.json\n  cli/find-channel.ts identifiants et droits des channels du bot, à partir du token\n  cli/setup-mcp.ts    écriture de l'entrée dans ./.mcp.json\n  core/channel.ts     opérations sur le channel configuré, lecture des mises à jour\n  core/store.ts       offset, verrou et posts conservés sur disque\n  core/lock.ts        verrou inter-processus\n  core/post.ts        conversion d'un message Bot API en post\n  core/header.ts      en-tête « Message de <nom> » des publications\n  notify/enable.ts    outil enable_notifications et commande du veilleur\n  notify/handoff.ts   relais entre le serveur et son veilleur, ménage des relais orphelins\n  notify/watch.ts     mode veilleur : une ligne par post\n  mcp/start.ts        serveur MCP et instructions\n  mcp/tools.ts        définitions et validation des outils\n  mcp/relay.ts        fichiers entrants et sortants, conventions du relais\n  telegram/bot-api.ts client HTTP de la Bot API\n  telegram/types.ts   types de la Bot API utilisés\n```\n\n### Tests\n\nLes tests remplacent `fetch` par un faux serveur Bot API (`test/helpers.ts`) et pilotent le\nserveur par un client MCP en mémoire : aucun appel réseau, aucun token réel.\n\n## Publication\n\nChaque push sur `master`, merge de pull request compris, publie une nouvelle version de\n`@imenam/mcp-telegram` sur npm (`.github/workflows/publish.yml`) : `npm ci`, build et tests,\npuis `npm version patch`, dont le commit et le tag sont poussés sur `master`, et `npm publish`.\nLa publication passe par le trusted publishing de npm (OIDC, sans token), avec attestation de\nprovenance. Un échec du build ou des tests arrête le workflow avant la montée de version.\n\nSur npmjs.com, le paquet déclare ce workflow comme publieur de confiance (Settings → Trusted\npublishing → GitHub Actions : `Matthieu-Pesnot-Pin`, `mcp-telegram`, `publish.yml`, avec\n`npm publish` dans les actions autorisées). Le commit de version est poussé avec\n`GITHUB_TOKEN` : si `master` est protégée, la règle doit autoriser GitHub Actions à y pousser.\n\n## Licence\n\nISC\n","readmeFilename":"README.md","homepage":"https://github.com/Matthieu-Pesnot-Pin/mcp-telegram#readme","repository":{"url":"git+https://github.com/Matthieu-Pesnot-Pin/mcp-telegram.git","type":"git"},"bugs":{"url":"https://github.com/Matthieu-Pesnot-Pin/mcp-telegram/issues"}}