Merge pull request chigwell#255 from markov12/feat/mcpb-desktop-extension

feat: add MCPB manifest for one-click Claude Desktop install

Author: chigwell

.mcpbignore

@@ -0,0 +1,32 @@
+# Secrets and local state must never end up in the bundle
+.env
+.env.*
+*.session
+*.session-journal
+*.log
+data/
+
+# Environments and caches
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+*.egg-info/
+build/
+dist/
+
+# Not needed at runtime
+.git/
+.github/
+tests/
+screenshots/
+skills/
+Dockerfile
+docker-compose.yml
+poetry.lock
+requirements.txt
+.pre-commit-config.yaml
+*.mcpb

README.md

@@ -336,6 +336,26 @@ uv run main.py
 
 ## MCP Client Configuration
 
+### Claude Desktop extension (.mcpb)
+
+The repository ships a `manifest.json`, so it can be packed into a
+[Claude Desktop extension](https://github.com/modelcontextprotocol/mcpb) and
+installed without editing any JSON:
+
+```bash
+npx @anthropic-ai/mcpb pack . telegram-mcp.mcpb
+```
+
+Open the resulting `telegram-mcp.mcpb` with Claude Desktop (or drag it onto
+Settings → Extensions) and fill in the API ID, API hash and session string
+(see [Quick Start](#quick-start) for generating one). Claude Desktop installs
+Python and the dependencies itself via `uv`, and masks the API hash and
+session string as sensitive fields. The allowed-chats and files-directory fields map to
+`TELEGRAM_ALLOWED_CHAT_IDS` and `TELEGRAM_ALLOWED_ROOTS`. `.mcpbignore` keeps
+`.env`, session files and logs out of the bundle.
+
+### Manual configuration
+
 For Claude Desktop or Cursor, point the MCP server at a cloned checkout of
 this project:
 

manifest.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://raw.githubusercontent.com/modelcontextprotocol/mcpb/main/dist/mcpb-manifest.schema.json",
+  "manifest_version": "0.4",
+  "name": "telegram-mcp",
+  "display_name": "Telegram",
+  "version": "2.0.1",
+  "description": "Read, search and send Telegram messages from your own account via Telethon",
+  "author": {
+    "name": "chigwell"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chigwell/telegram-mcp"
+  },
+  "homepage": "https://github.com/chigwell/telegram-mcp",
+  "documentation": "https://github.com/chigwell/telegram-mcp#readme",
+  "support": "https://github.com/chigwell/telegram-mcp/issues",
+  "server": {
+    "type": "uv",
+    "entry_point": "main.py",
+    "mcp_config": {
+      "command": "uv",
+      "args": ["run", "--directory", "${__dirname}", "main.py"],
+      "env": {
+        "TELEGRAM_API_ID": "${user_config.api_id}",
+        "TELEGRAM_API_HASH": "${user_config.api_hash}",
+        "TELEGRAM_SESSION_STRING": "${user_config.session_string}",
+        "TELEGRAM_ALLOWED_CHAT_IDS": "${user_config.allowed_chat_ids}",
+        "TELEGRAM_ALLOWED_ROOTS": "${user_config.allowed_root}"
+      }
+    }
+  },
+  "user_config": {
+    "api_id": {
+      "type": "string",
+      "title": "API ID",
+      "description": "From https://my.telegram.org/apps",
+      "required": true
+    },
+    "api_hash": {
+      "type": "string",
+      "title": "API hash",
+      "description": "From https://my.telegram.org/apps",
+      "required": true,
+      "sensitive": true
+    },
+    "session_string": {
+      "type": "string",
+      "title": "Session string",
+      "description": "Generate it with session_string_generator.py (see the README). Anyone holding it has full access to your account.",
+      "required": true,
+      "sensitive": true
+    },
+    "allowed_chat_ids": {
+      "type": "string",
+      "title": "Allowed chats",
+      "description": "Optional comma-separated chat IDs or @usernames. When set, every other chat is hidden from Claude.",
+      "required": false,
+      "default": ""
+    },
+    "allowed_root": {
+      "type": "directory",
+      "title": "Files directory",
+      "description": "Optional directory that file tools (send_file, download_media, ...) may read from and write to.",
+      "required": false,
+      "default": ""
+    }
+  },
+  "compatibility": {
+    "platforms": ["darwin", "linux", "win32"],
+    "runtimes": {
+      "python": ">=3.10"
+    }
+  },
+  "keywords": ["telegram", "telethon", "messaging", "chat"],
+  "license": "Apache-2.0"
+}