From 2dc490aa77acb7f9daa139f388bfed02a0369cf4 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 26 Sep 2026 02:13:58 +0000 Subject: [PATCH] Publish to PyPI as telegram-channel-scraper The name tgscraper is taken on PyPI. The import name and the tgscraper / tgscraper-mcp commands stay the same. Adds a Trusted Publishing workflow triggered by v* tags, and makes README links absolute so they work on PyPI. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Koo8a1vU5D6JttUkzjxE6H --- .claude/skills/telegram-scraper/SKILL.md | 2 +- .github/workflows/publish.yml | 39 ++++++++++++++++++++++++ README.md | 27 ++++++++-------- llms.txt | 4 +-- pyproject.toml | 6 ++-- tgscraper/cli.py | 4 +-- tgscraper/dashboard.py | 2 +- tgscraper/exporters.py | 2 +- tgscraper/mcp_server.py | 2 +- 9 files changed, 64 insertions(+), 24 deletions(-) create mode 100644 .github/workflows/publish.yml diff --git a/.claude/skills/telegram-scraper/SKILL.md b/.claude/skills/telegram-scraper/SKILL.md index f7e786c..2e776b8 100644 --- a/.claude/skills/telegram-scraper/SKILL.md +++ b/.claude/skills/telegram-scraper/SKILL.md @@ -12,7 +12,7 @@ groups, chats or bots. ## 0. Setup (once) ```bash -tgscraper --version || pip install "tgscraper[all] @ git+https://github.com/specialteam/TelegramScraper" +tgscraper --version || pip install "telegram-channel-scraper[all]" ``` If the `telegram-scraper` MCP tools (`get_messages`, `search_messages`, `get_channel_info`, diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..d92989c --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,39 @@ +name: Publish to PyPI + +# Push a tag like v2.0.0 (or run manually) to build and upload to https://pypi.org/p/telegram-channel-scraper. +# Uses PyPI Trusted Publishing — no API token stored in GitHub. +on: + push: + tags: ["v*"] + workflow_dispatch: + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + - run: pip install build twine + - run: python -m build + - run: twine check dist/* + - uses: actions/upload-artifact@v4 + with: + name: dist + path: dist/ + + publish: + needs: build + runs-on: ubuntu-latest + environment: + name: pypi + url: https://pypi.org/p/telegram-channel-scraper + permissions: + id-token: write + steps: + - uses: actions/download-artifact@v4 + with: + name: dist + path: dist/ + - uses: pypa/gh-action-pypi-publish@release/v1 diff --git a/README.md b/README.md index 9227765..c8bcfe6 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ Python library · CLI · MCP server for AI agents · Claude Skill · Web dashboard · Docker [![Tests](https://github.com/specialteam/TelegramScraper/actions/workflows/python-package.yml/badge.svg)](https://github.com/specialteam/TelegramScraper/actions) +[![PyPI](https://img.shields.io/pypi/v/telegram-channel-scraper)](https://pypi.org/project/telegram-channel-scraper/) ![Python](https://img.shields.io/badge/python-3.9%2B-blue) ![MCP](https://img.shields.io/badge/MCP-server-8A2BE2) ![License](https://img.shields.io/badge/license-MIT-green) @@ -16,7 +17,7 @@ Python library · CLI · MCP server for AI agents · Claude Skill · Web dashboa ```bash -pip install "tgscraper[all] @ git+https://github.com/specialteam/TelegramScraper" +pip install "telegram-channel-scraper[all]" tgscraper durov ``` @@ -49,10 +50,10 @@ That's it — the latest posts of `t.me/durov`, in your terminal. ```bash # everything (CLI + Excel + MCP server + dashboard) -pip install "tgscraper[all] @ git+https://github.com/specialteam/TelegramScraper" +pip install "telegram-channel-scraper[all]" # or minimal (CLI + library only: httpx + beautifulsoup4) -pip install "git+https://github.com/specialteam/TelegramScraper" +pip install telegram-channel-scraper # or from a clone git clone https://github.com/specialteam/TelegramScraper && cd TelegramScraper && pip install -e ".[all]" @@ -239,16 +240,16 @@ Plus prompts `summarize_channel` and `track_topic`, and the resource `telegram:/ ### Connect it The only requirement is [uv](https://docs.astral.sh/uv/) (`pip install uv`) — `uvx` downloads and runs the server -on demand. Or `pip install "tgscraper[mcp] @ git+…"` and use `"command": "tgscraper-mcp"` with no args. +on demand. Or `pip install "telegram-channel-scraper[mcp]"` and use `"command": "tgscraper-mcp"` with no args.
Claude Code ```bash -claude mcp add telegram-scraper -- uvx --from "tgscraper[mcp] @ git+https://github.com/specialteam/TelegramScraper" tgscraper-mcp +claude mcp add telegram-scraper -- uvx --from "telegram-channel-scraper[mcp]" tgscraper-mcp ``` -Inside this repository it is automatic: [`.mcp.json`](.mcp.json) registers the server and -[`.claude/skills/telegram-scraper`](.claude/skills/telegram-scraper/SKILL.md) loads the skill. +Inside this repository it is automatic: [`.mcp.json`](https://github.com/specialteam/TelegramScraper/blob/main/.mcp.json) registers the server and +[`.claude/skills/telegram-scraper`](https://github.com/specialteam/TelegramScraper/blob/main/.claude/skills/telegram-scraper/SKILL.md) loads the skill.
@@ -262,7 +263,7 @@ or `~/.codeium/windsurf/mcp_config.json`: "mcpServers": { "telegram-scraper": { "command": "uvx", - "args": ["--from", "tgscraper[mcp] @ git+https://github.com/specialteam/TelegramScraper", "tgscraper-mcp"], + "args": ["--from", "telegram-channel-scraper[mcp]", "tgscraper-mcp"], "env": { "TGSCRAPER_PROXY": "" } } } @@ -280,7 +281,7 @@ or `~/.codeium/windsurf/mcp_config.json`: "telegram-scraper": { "type": "stdio", "command": "uvx", - "args": ["--from", "tgscraper[mcp] @ git+https://github.com/specialteam/TelegramScraper", "tgscraper-mcp"] + "args": ["--from", "telegram-channel-scraper[mcp]", "tgscraper-mcp"] } } } @@ -299,7 +300,7 @@ Environment variables: `TGSCRAPER_PROXY` (proxy URL for all requests), `TGSCRAPE ### Claude Skill -[`.claude/skills/telegram-scraper/SKILL.md`](.claude/skills/telegram-scraper/SKILL.md) teaches an agent when and how +[`.claude/skills/telegram-scraper/SKILL.md`](https://github.com/specialteam/TelegramScraper/blob/main/.claude/skills/telegram-scraper/SKILL.md) teaches an agent when and how to use the CLI (commands, JSON schema, how to cite results). Install it for all your projects: ```bash @@ -314,14 +315,14 @@ For claude.ai, zip the `telegram-scraper` folder and upload it under **Settings - *"Search @xyz for 'airdrop' and give me the dates and links."* - *"Export the last 1000 posts of t.me/abc to Excel."* -Other agents: [`AGENTS.md`](AGENTS.md) and [`llms.txt`](llms.txt) describe the project for LLMs. +Other agents: [`AGENTS.md`](https://github.com/specialteam/TelegramScraper/blob/main/AGENTS.md) and [`llms.txt`](https://github.com/specialteam/TelegramScraper/blob/main/llms.txt) describe the project for LLMs. --- ## 🖥 Web dashboard ```bash -pip install "tgscraper[dashboard] @ git+https://github.com/specialteam/TelegramScraper" +pip install "telegram-channel-scraper[dashboard]" tgscraper dashboard # → http://localhost:8501 ``` @@ -400,7 +401,7 @@ rates reasonable. This project is not affiliated with Telegram. ```bash -pip install "tgscraper[all] @ git+https://github.com/specialteam/TelegramScraper" +pip install "telegram-channel-scraper[all]" ```
diff --git a/llms.txt b/llms.txt index 645362b..f002fd7 100644 --- a/llms.txt +++ b/llms.txt @@ -5,8 +5,8 @@ > reactions, media, hashtags, links), supports search, date/keyword filters, JSON/CSV/Excel/SQLite export, > incremental scraping, monitoring with webhooks, media download and analytics. -Install: `pip install "tgscraper[all] @ git+https://github.com/specialteam/TelegramScraper"` -MCP server: `uvx --from "tgscraper[mcp] @ git+https://github.com/specialteam/TelegramScraper" tgscraper-mcp` +Install: `pip install "telegram-channel-scraper[all]"` +MCP server: `uvx --from "telegram-channel-scraper[mcp]" tgscraper-mcp` ## Docs - [README](README.md): features, CLI, Python API, MCP setup for Claude/Cursor/VS Code, Docker, FAQ diff --git a/pyproject.toml b/pyproject.toml index 8bae4c0..bbaf8ba 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,7 @@ requires = ["setuptools>=64"] build-backend = "setuptools.build_meta" [project] -name = "tgscraper" +name = "telegram-channel-scraper" version = "2.0.0" description = "Scrape public Telegram channels without API keys or login — Python library, CLI, MCP server for AI agents, and dashboard." readme = "README.md" @@ -29,8 +29,8 @@ dependencies = ["httpx[socks]>=0.27", "beautifulsoup4>=4.11"] excel = ["openpyxl>=3.1"] mcp = ["mcp>=1.2; python_version>='3.10'"] dashboard = ["streamlit>=1.35"] -all = ["tgscraper[excel,mcp,dashboard]"] -dev = ["tgscraper[excel,mcp]", "pytest>=7", "pytest-asyncio>=0.23", "respx>=0.21", "flake8"] +all = ["telegram-channel-scraper[excel,mcp,dashboard]"] +dev = ["telegram-channel-scraper[excel,mcp]", "pytest>=7", "pytest-asyncio>=0.23", "respx>=0.21", "flake8"] [project.scripts] tgscraper = "tgscraper.cli:main" diff --git a/tgscraper/cli.py b/tgscraper/cli.py index c463e8d..906ec3f 100644 --- a/tgscraper/cli.py +++ b/tgscraper/cli.py @@ -108,7 +108,7 @@ def build_parser() -> argparse.ArgumentParser: p = sub.add_parser("mcp", help="run the MCP server (stdio) so AI assistants can use tgscraper") p.add_argument("--transport", default="stdio", choices=["stdio", "sse", "streamable-http"]) - sub.add_parser("dashboard", help="open the web dashboard (needs tgscraper[dashboard])") + sub.add_parser("dashboard", help="open the web dashboard (needs telegram-channel-scraper[dashboard])") return parser @@ -255,7 +255,7 @@ def _dashboard() -> None: try: import streamlit # noqa: F401 except ImportError: - print("Dashboard needs streamlit: pip install 'tgscraper[dashboard]'", file=sys.stderr) + print("Dashboard needs streamlit: pip install 'telegram-channel-scraper[dashboard]'", file=sys.stderr) raise SystemExit(1) app = Path(__file__).with_name("dashboard.py") raise SystemExit(subprocess.call([sys.executable, "-m", "streamlit", "run", str(app)])) diff --git a/tgscraper/dashboard.py b/tgscraper/dashboard.py index 0381556..7671b4f 100644 --- a/tgscraper/dashboard.py +++ b/tgscraper/dashboard.py @@ -1,4 +1,4 @@ -"""Web dashboard. Run with ``tgscraper dashboard`` (needs ``pip install 'tgscraper[dashboard]'``).""" +"""Web dashboard. Run with ``tgscraper dashboard`` (needs ``pip install 'telegram-channel-scraper[dashboard]'``).""" from __future__ import annotations import datetime as dt diff --git a/tgscraper/exporters.py b/tgscraper/exporters.py index 45200e5..4a13687 100644 --- a/tgscraper/exporters.py +++ b/tgscraper/exporters.py @@ -104,7 +104,7 @@ def export(messages: Iterable[Message], path: Union[str, Path], format: Optional try: from openpyxl import Workbook except ImportError as exc: # pragma: no cover - raise ImportError("Excel export needs openpyxl: pip install 'tgscraper[excel]'") from exc + raise ImportError("Excel export needs openpyxl: pip install 'telegram-channel-scraper[excel]'") from exc wb = Workbook() ws = wb.active ws.title = "messages" diff --git a/tgscraper/mcp_server.py b/tgscraper/mcp_server.py index 6089e17..756c6bc 100644 --- a/tgscraper/mcp_server.py +++ b/tgscraper/mcp_server.py @@ -13,7 +13,7 @@ try: # mcp 1.x from mcp.server.fastmcp import FastMCP except ImportError as exc: # pragma: no cover - raise ImportError("The MCP server needs the 'mcp' package: pip install 'tgscraper[mcp]'") from exc + raise ImportError("The MCP server needs the 'mcp' package: pip install 'telegram-channel-scraper[mcp]'") from exc from .analytics import summarize from .client import AsyncScraper, ScraperError