telegram-dev 0.6.1__tar.gz → 0.7.0__tar.gz

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/.claude-plugin/marketplace.json

@@ -1,13 +1,13 @@
 {
   "name": "telegram-dev-tools",
   "owner": {"name": "Kay0k1"},
-  "metadata": {"description": "Independent Telegram development tools with official documentation", "version": "0.6.1"},
+  "metadata": {"description": "Independent Telegram development tools with official documentation", "version": "0.7.0"},
   "plugins": [
     {
       "name": "telegram-dev",
       "source": "./",
       "description": "Source-verified Telegram and TON development with official documentation search",
-      "version": "0.6.1",
+      "version": "0.7.0",
       "homepage": "https://github.com/Kay0k1/telegram-dev",
       "repository": "https://github.com/Kay0k1/telegram-dev",
       "license": "MIT",

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "telegram-dev",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "displayName": "Telegram Dev",
   "description": "Source-verified Telegram and TON development across Bot API, Mini Apps, MTProto, TDLib, TON Connect, Tolk and public releases. Independent project by Kay0k1.",
   "author": {

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "telegram-dev",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Source-verified Telegram and TON development across Bot API, Mini Apps, MTProto, TDLib, TON Connect, Tolk and public release history",
   "author": {
     "name": "Kay0k1",

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "telegram-dev",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Source-verified Telegram and TON development: Bot API, Mini Apps, MTProto, TDLib, TON Connect, Tolk and public releases",
   "author": {"name": "Kay0k1"},
   "license": "MIT",

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project. Versions follow [Semantic Versioning](https://semver.org/).
 
+## [0.7.0] - 2026-11-10
+
+### Changed
+
+- MCP tools follow one verb-noun naming scheme. Renamed: `telegram_corpus_status` → `get_telegram_corpus_status`, `telegram_document_history` → `list_telegram_document_revisions`, `telegram_sources` → `list_telegram_sources`. `search_telegram_docs` and `get_telegram_document` are unchanged. The skill uses the new names; update a project install with `uvx telegram-dev@latest install --agent <agent> --update`.
+- Every tool description names its neighbouring tools and says when to use them instead.
+
+### Added
+
+- `list_telegram_cached_pages`: pages already stored in the local cache, filtered by area, with freshness and paging.
+
 ## [0.6.1] - 2026-11-10
 
 ### Changed
@@ -69,6 +80,7 @@ All notable changes to this project. Versions follow [Semantic Versioning](https
 
 - First public release: documentation MCP server with an on-demand local cache, agent skill, project installer for Codex, Claude Code and Cursor, and a Claude Code plugin catalog.
 
+[0.7.0]: https://github.com/Kay0k1/telegram-dev/compare/v0.6.1...v0.7.0
 [0.6.1]: https://github.com/Kay0k1/telegram-dev/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/Kay0k1/telegram-dev/compare/v0.5.1...v0.6.0
 [0.5.1]: https://github.com/Kay0k1/telegram-dev/compare/v0.5.0...v0.5.1

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telegram-dev
-Version: 0.6.1
+Version: 0.7.0
 Summary: Source-grounded Telegram development skills and documentation MCP
 License-Expression: MIT
 Requires-Python: <3.15,>=3.10
@@ -45,7 +45,7 @@ With Telegram Dev the agent reads the current page before it writes code. A real
   'Delete' button to be red and show a custom emoji. Which Bot API fields do this,
   what are the requirements, and what does the request JSON look like?
 
-  telegram_corpus_status {}
+  get_telegram_corpus_status {}
   search_telegram_docs {"query": "style icon_custom_emoji_id", "area": "releases"}
   search_telegram_docs {"query": "InlineKeyboardButton icon_custom_emoji_id style", "area": "bot-api"}
   get_telegram_document {"url": "https://core.telegram.org/bots/api", "offset": 167594, "length": 10500}
@@ -147,9 +147,10 @@ The tools work without the skill, but the skill is what makes an agent use them
 | --- | --- |
 | `search_telegram_docs` | Full-text search over indexed sections, optionally limited to one area: `bot-api`, `mini-apps`, `telegram-api`, `tdlib`, `ton`, `releases`, `ton-releases`, `aiogram`, `python-telegram-bot`, `grammy` and others. Core Telegram docs rank first unless the query names a library |
 | `get_telegram_document` | Reads an official page in pages of up to 40,000 characters; fetches it if it is missing or older than 6 hours |
-| `telegram_corpus_status` | What is indexed, how fresh it is and which sources failed |
-| `telegram_document_history` | Revisions of a page captured by this installation |
-| `telegram_sources` | The 61 official entry points, grouped by API area |
+| `get_telegram_corpus_status` | What is indexed, how fresh it is and which sources failed |
+| `list_telegram_document_revisions` | Revisions of a page captured by this installation |
+| `list_telegram_sources` | The 61 official entry points, grouped by API area |
+| `list_telegram_cached_pages` | Pages already stored in the local cache, by area, with freshness |
 
 The cache starts empty. Pages are fetched the first time the agent reads them and indexed right away. To pre-fetch everything reachable from the configured sources:
 

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/README.md

@@ -28,7 +28,7 @@ With Telegram Dev the agent reads the current page before it writes code. A real
   'Delete' button to be red and show a custom emoji. Which Bot API fields do this,
   what are the requirements, and what does the request JSON look like?
 
-  telegram_corpus_status {}
+  get_telegram_corpus_status {}
   search_telegram_docs {"query": "style icon_custom_emoji_id", "area": "releases"}
   search_telegram_docs {"query": "InlineKeyboardButton icon_custom_emoji_id style", "area": "bot-api"}
   get_telegram_document {"url": "https://core.telegram.org/bots/api", "offset": 167594, "length": 10500}
@@ -130,9 +130,10 @@ The tools work without the skill, but the skill is what makes an agent use them
 | --- | --- |
 | `search_telegram_docs` | Full-text search over indexed sections, optionally limited to one area: `bot-api`, `mini-apps`, `telegram-api`, `tdlib`, `ton`, `releases`, `ton-releases`, `aiogram`, `python-telegram-bot`, `grammy` and others. Core Telegram docs rank first unless the query names a library |
 | `get_telegram_document` | Reads an official page in pages of up to 40,000 characters; fetches it if it is missing or older than 6 hours |
-| `telegram_corpus_status` | What is indexed, how fresh it is and which sources failed |
-| `telegram_document_history` | Revisions of a page captured by this installation |
-| `telegram_sources` | The 61 official entry points, grouped by API area |
+| `get_telegram_corpus_status` | What is indexed, how fresh it is and which sources failed |
+| `list_telegram_document_revisions` | Revisions of a page captured by this installation |
+| `list_telegram_sources` | The 61 official entry points, grouped by API area |
+| `list_telegram_cached_pages` | Pages already stored in the local cache, by area, with freshness |
 
 The cache starts empty. Pages are fetched the first time the agent reads them and indexed right away. To pre-fetch everything reachable from the configured sources:
 

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/README.ru.md

@@ -26,7 +26,7 @@ TON меняется так же быстро. В текущей докумен
   'Delete' button to be red and show a custom emoji. Which Bot API fields do this,
   what are the requirements, and what does the request JSON look like?
 
-  telegram_corpus_status {}
+  get_telegram_corpus_status {}
   search_telegram_docs {"query": "style icon_custom_emoji_id", "area": "releases"}
   search_telegram_docs {"query": "InlineKeyboardButton icon_custom_emoji_id style", "area": "bot-api"}
   get_telegram_document {"url": "https://core.telegram.org/bots/api", "offset": 167594, "length": 10500}
@@ -124,9 +124,10 @@ Cursor: [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](htt
 | --- | --- |
 | `search_telegram_docs` | Полнотекстовый поиск по разделам, можно ограничить областью: `bot-api`, `mini-apps`, `telegram-api`, `tdlib`, `ton`, `releases`, `ton-releases`, `aiogram`, `python-telegram-bot`, `grammy` и другими. Документация Telegram идёт первой, если в запросе не названа библиотека |
 | `get_telegram_document` | Читает официальную страницу частями до 40 000 символов; загружает её, если страницы нет или она старше 6 часов |
-| `telegram_corpus_status` | Что проиндексировано, насколько свежее и какие источники не загрузились |
-| `telegram_document_history` | Версии страницы, которые видела эта установка |
-| `telegram_sources` | 61 официальная точка входа по областям API |
+| `get_telegram_corpus_status` | Что проиндексировано, насколько свежее и какие источники не загрузились |
+| `list_telegram_document_revisions` | Версии страницы, которые видела эта установка |
+| `list_telegram_sources` | 61 официальная точка входа по областям API |
+| `list_telegram_cached_pages` | Страницы, которые уже лежат в локальном кэше, по областям, со свежестью |
 
 Кэш сначала пустой. Страница загружается, когда агент впервые её читает, и сразу индексируется. Загрузить заранее всё, что достижимо из настроенных источников:
 

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/docs/runtime.md

@@ -8,7 +8,7 @@
 
 Пока MCP запущен, фоновая задача каждые 6 часов обрабатывает до **120 страниц**. Она проверяет входные источники, расширяет обнаруженный набор документов и возвращается к старым страницам. Расписание хранится в общей SQLite-базе, поэтому несколько проектов, использующих один кеш, не начинают отдельный обход при каждом запуске. Первое подключение запускает проверку в фоне и не ждёт загрузки всей базы.
 
-Это постепенное заполнение кеша. Для полного первоначального обхода используйте `uv run --frozen telegram-dev sync --max-pages 0`. Его завершение и недоступные источники проверяйте через `telegram-dev status`; количество страниц само по себе не доказывает полноту знаний Telegram. `telegram_sources` перечисляет настроенные точки входа; живые API indexes и schema позволяют находить дополнительные функции.
+Это постепенное заполнение кеша. Для полного первоначального обхода используйте `uv run --frozen telegram-dev sync --max-pages 0`. Его завершение и недоступные источники проверяйте через `telegram-dev status`; количество страниц само по себе не доказывает полноту знаний Telegram. `list_telegram_sources` перечисляет настроенные точки входа; живые API indexes и schema позволяют находить дополнительные функции.
 
 Настройки задаются в окружении MCP-сервера:
 
@@ -54,7 +54,7 @@ From 0.3.0, reading a document automatically refreshes pages older than **6 hour
 
 Source failures preserve previously cached text and explicitly mark it stale; they never advance the successful check date. Automatic retries wait 15 minutes by default; forced refresh bypasses that backoff.
 
-While the MCP process runs, a background cycle every 6 hours checks up to **120 pages**, covering entrypoints, new discovered links and older documents. Its SQLite schedule is shared between projects using the same cache. Startup does not wait for a full corpus. Coverage expands gradually; use `uv run --frozen telegram-dev sync --max-pages 0` for a complete initial crawl of the discovered scope and inspect `telegram-dev status` for gaps. `telegram_sources` lists configured entrypoints; follow the live API indexes and schema for further features.
+While the MCP process runs, a background cycle every 6 hours checks up to **120 pages**, covering entrypoints, new discovered links and older documents. Its SQLite schedule is shared between projects using the same cache. Startup does not wait for a full corpus. Coverage expands gradually; use `uv run --frozen telegram-dev sync --max-pages 0` for a complete initial crawl of the discovered scope and inspect `telegram-dev status` for gaps. `list_telegram_sources` lists configured entrypoints; follow the live API indexes and schema for further features.
 
 The environment settings in the table above control the database, age threshold, background enablement, interval, page budget and retry backoff. Run `uv run --frozen telegram-dev maintain --max-pages 120` for one bounded cycle. Background work requires a running server; a permanently hosted MCP continues refreshing between user sessions.
 

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "telegram-dev"
-version = "0.6.1"
+version = "0.7.0"
 description = "Source-grounded Telegram development skills and documentation MCP"
 readme = "README.md"
 requires-python = ">=3.10,<3.15"

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/scripts/package_openai.py

@@ -83,7 +83,7 @@ def review_cases() -> dict:
              "expected_behavior": "Select the client API/TDLib surface, read the relevant public pages and cite them."},
             {"description": "Check published release history",
              "prompt": "Inspect the Bot API changelog and report the cache freshness before summarizing a documented change.",
-             "tools_triggered": "get_telegram_document, telegram_corpus_status",
+             "tools_triggered": "get_telegram_document, get_telegram_corpus_status",
              "expected_behavior": "Read the changelog and separate source observation timestamps from Telegram release dates."},
         ],
         "negative": [

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/server.json

@@ -8,12 +8,12 @@
     "source": "github"
   },
   "websiteUrl": "https://github.com/Kay0k1/telegram-dev",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "telegram-dev",
-      "version": "0.6.1",
+      "version": "0.7.0",
       "runtimeHint": "uvx",
       "transport": {
         "type": "stdio"

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/skills/telegram-dev/SKILL.md

@@ -42,11 +42,11 @@ Prefer the project's existing suitable library. Do not introduce a connector, ac
 ## Retrieve evidence
 
 If available, use the telegram-knowledge MCP tools:
-1. `telegram_corpus_status` when corpus coverage/freshness is not yet known in this task. Inspect per-document observations and reported refresh errors; a recent corpus-wide check does not prove the requested page is current.
-   Use `telegram_sources` to discover the configured official entrypoints for the requested area when the right source is unclear; its source count is not proof that every page has been indexed. A new public installation can start with an empty local cache. In that case, call `get_telegram_document` on the relevant entrypoint; it fetches and indexes the page. Bot API and Mini App entrypoints include their full specifications. Do not fetch every source or require a full crawl before helping the user.
+1. `get_telegram_corpus_status` when corpus coverage/freshness is not yet known in this task. Inspect per-document observations and reported refresh errors; a recent corpus-wide check does not prove the requested page is current.
+   Use `list_telegram_sources` to discover the configured official entrypoints for the requested area when the right source is unclear; its source count is not proof that every page has been indexed. A new public installation can start with an empty local cache. In that case, call `get_telegram_document` on the relevant entrypoint; it fetches and indexes the page. Bot API and Mini App entrypoints include their full specifications. Do not fetch every source or require a full crawl before helping the user. `list_telegram_cached_pages` shows which pages of an area are already in the cache.
 2. `search_telegram_docs` with exact API names or English feature keywords and a suitable area. Translate Russian intent to API terms; built-in Russian aliases are only a convenience.
 3. `get_telegram_document` to read actual requirements; start at the search result's `document_offset` and paginate beyond a truncated excerpt. Reads/searches automatically check stale matched sources, and the runtime can also synchronize sources in the background while MCP is running. Inspect each result's freshness/error metadata rather than assuming a background task finished. Use the existing `refresh=true` parameter when a current limit, permission rule, newly released method or deprecated behavior needs an immediate source check. After a refresh changes the source hash, search again because offsets may have changed. If a source check fails, distinguish usable cached evidence from verified current evidence and use direct official browsing when available.
-4. `telegram_document_history` only for observed local revisions. Release history is in official changelog documents, not inferred from local capture timestamps.
+4. `list_telegram_document_revisions` only for observed local revisions. Release history is in official changelog documents, not inferred from local capture timestamps.
 
 Without MCP, open the official sources linked in the surface map using available browsing tools. If neither is available, explicitly identify unverified details instead of fabricating methods or restrictions.
 

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/telegram_dev.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telegram-dev
-Version: 0.6.1
+Version: 0.7.0
 Summary: Source-grounded Telegram development skills and documentation MCP
 License-Expression: MIT
 Requires-Python: <3.15,>=3.10
@@ -45,7 +45,7 @@ With Telegram Dev the agent reads the current page before it writes code. A real
   'Delete' button to be red and show a custom emoji. Which Bot API fields do this,
   what are the requirements, and what does the request JSON look like?
 
-  telegram_corpus_status {}
+  get_telegram_corpus_status {}
   search_telegram_docs {"query": "style icon_custom_emoji_id", "area": "releases"}
   search_telegram_docs {"query": "InlineKeyboardButton icon_custom_emoji_id style", "area": "bot-api"}
   get_telegram_document {"url": "https://core.telegram.org/bots/api", "offset": 167594, "length": 10500}
@@ -147,9 +147,10 @@ The tools work without the skill, but the skill is what makes an agent use them
 | --- | --- |
 | `search_telegram_docs` | Full-text search over indexed sections, optionally limited to one area: `bot-api`, `mini-apps`, `telegram-api`, `tdlib`, `ton`, `releases`, `ton-releases`, `aiogram`, `python-telegram-bot`, `grammy` and others. Core Telegram docs rank first unless the query names a library |
 | `get_telegram_document` | Reads an official page in pages of up to 40,000 characters; fetches it if it is missing or older than 6 hours |
-| `telegram_corpus_status` | What is indexed, how fresh it is and which sources failed |
-| `telegram_document_history` | Revisions of a page captured by this installation |
-| `telegram_sources` | The 61 official entry points, grouped by API area |
+| `get_telegram_corpus_status` | What is indexed, how fresh it is and which sources failed |
+| `list_telegram_document_revisions` | Revisions of a page captured by this installation |
+| `list_telegram_sources` | The 61 official entry points, grouped by API area |
+| `list_telegram_cached_pages` | Pages already stored in the local cache, by area, with freshness |
 
 The cache starts empty. Pages are fetched the first time the agent reads them and indexed right away. To pre-fetch everything reachable from the configured sources:
 

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/telegram_knowledge.py

@@ -671,6 +671,18 @@ def _maintain(stop):
         stop.wait(30)
 
 
+def cached_pages(area="", offset=0, limit=50):
+    offset, limit = max(0, offset), max(1, min(limit, 200))
+    with connect() as conn:
+        total = conn.execute("SELECT count(*) FROM pages WHERE ?='' OR family=?", (area, area)).fetchone()[0]
+        rows = conn.execute("SELECT url,title,family,checked_at,error FROM pages WHERE ?='' OR family=? ORDER BY url LIMIT ? OFFSET ?",
+                            (area, area, limit, offset)).fetchall()
+    pages = [{"url": r["url"], "title": r["title"], "area": r["family"], "checked_at": r["checked_at"],
+              "freshness": freshness(r)} for r in rows]
+    return {"pages": pages, "total": total, "offset": offset,
+            "next_offset": offset + len(pages) if offset + len(pages) < total else None}
+
+
 def coverage():
     with connect() as conn:
         states = dict(conn.execute("SELECT state,count(*) FROM frontier GROUP BY state"))
@@ -860,7 +872,7 @@ def create_server(transport="stdio", host="127.0.0.1", port=8000):
     @server.tool(title="Read an official documentation page", annotations=annotations)
     def get_telegram_document(
         url: Annotated[str, Field(description=(
-            "Official page URL from search results or telegram_sources, e.g. https://core.telegram.org/bots/api "
+            "Official page URL from search results or list_telegram_sources, e.g. https://core.telegram.org/bots/api "
             "or https://docs.ton.org/applications/ton-connect/overview. Pages outside the official sources are rejected."))],
         offset: Annotated[int, Field(ge=0, description="Character offset to start from; use a search result's document_offset or the previous next_offset.")] = 0,
         length: Annotated[int, Field(ge=100, le=40000, description="Number of characters to return.")] = 16000,
@@ -868,23 +880,23 @@ def create_server(transport="stdio", host="127.0.0.1", port=8000):
     ) -> dict:
         """Read the text of an official Telegram, TON or bot-library documentation page, one window at a time.
 
-        Use it to read requirements, parameters and limits in full after search, or to load an entry page into an empty cache. Pages missing from the cache or older than the freshness limit (6 hours by default) are fetched first. Returns title, URL, Markdown `body` for the requested window, `next_offset` (null at the end), `total_characters`, content hash and freshness. If the live source fails, the cached text is returned with `freshness.stale` and `refresh_error` set. The observation date is when this installation read the page, not when Telegram changed it."""
+        Use it to read requirements, parameters and limits in full after `search_telegram_docs` found the page, or to load an entry page from `list_telegram_sources` into an empty cache. Do not use it to find which page answers a question: search first. Pages missing from the cache or older than the freshness limit (6 hours by default) are fetched first. Returns title, URL, Markdown `body` for the requested window, `next_offset` (null at the end), `total_characters`, content hash and freshness. If the live source fails, the cached text is returned with `freshness.stale` and `refresh_error` set. The observation date is when this installation read the page, not when Telegram changed it."""
         return document(url, offset, length, refresh)
 
     @server.tool(title="Cache coverage and freshness", annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False))
-    def telegram_corpus_status() -> dict:
-        """Report what the local documentation cache contains and how current it is.
+    def get_telegram_corpus_status() -> dict:
+        """Report how complete and how current the local documentation cache is, as totals.
 
-        Use it at the start of a task or when results look incomplete. Returns page counts per area, crawl queue state, stale page count, last and oldest successful checks, refresh policy and the latest source errors. Indexed pages are not all of Telegram's knowledge: absence from the cache is not evidence that a feature does not exist."""
+        Use it at the start of a task or when search results look incomplete. For the configured entry points use `list_telegram_sources`; for the individual cached pages use `list_telegram_cached_pages`; to answer a question use `search_telegram_docs`. Refreshing is automatic (on read, on search and in a background cycle), so there is no refresh command. Returns page counts per area, crawl queue state, stale page count, last and oldest successful checks, refresh policy and the latest source errors. Indexed pages are not all of Telegram's knowledge: absence from the cache is not evidence that a feature does not exist."""
         return coverage()
 
     @server.tool(title="Observed revisions of a page", annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False))
-    def telegram_document_history(
+    def list_telegram_document_revisions(
         url: Annotated[str, Field(description="Official page URL, the same form accepted by get_telegram_document.")],
     ) -> dict:
-        """List the versions of a documentation page that this installation has observed, newest first.
+        """List the revisions of one documentation page that this installation has observed, newest first.
 
-        Use it to see whether a page changed since an earlier read. Returns content hash, capture time and length for each revision. It does not reconstruct history before the page was first fetched here; for Telegram release history read the official changelogs (area `releases` or `ton-releases`)."""
+        Use it to see whether a page changed since an earlier read. To read the current text use `get_telegram_document`. Returns content hash, capture time and length for each revision. It does not reconstruct history before the page was first fetched here; for Telegram release history read the official changelogs (area `releases` or `ton-releases`)."""
         with connect() as conn:
             base = canonical(url)
             if base is None:
@@ -893,13 +905,24 @@ def create_server(transport="stdio", host="127.0.0.1", port=8000):
             return {"revisions": [dict(r) for r in conn.execute("SELECT sha,captured_at,length(body) AS characters FROM revisions WHERE url=? ORDER BY captured_at DESC", (target[0] if target else base,))]}
 
     @server.tool(title="Official documentation entry points", annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False))
-    def telegram_sources() -> dict:
+    def list_telegram_sources() -> dict:
         """List the official entry points this server crawls, each with its documentation area.
 
-        Use it to find where to start reading for an unfamiliar area (for example the Bot API index, docs.ton.org/llms.txt or a library's docs) and pass the URL to get_telegram_document. This is the source configuration, not proof that every page below it is already cached."""
+        Use it to find where to start reading for an unfamiliar area (for example the Bot API index, docs.ton.org/llms.txt or a library's docs) and pass the URL to `get_telegram_document`. If you already know the feature or API name, use `search_telegram_docs` instead. This is the source configuration, not the cache: `list_telegram_cached_pages` shows what is already stored."""
         return {"sources": [{"url": url, "area": family(url)} for url in SEEDS],
                 "scope": "Entry points for discovery. Follow each official API index and schema for additional features."}
 
+    @server.tool(title="List cached documentation pages", annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False))
+    def list_telegram_cached_pages(
+        area: Annotated[Area, Field(description="Only pages from this documentation area; empty lists all areas.")] = "",
+        offset: Annotated[int, Field(ge=0, description="Number of pages to skip, for paging through long lists; use the previous next_offset.")] = 0,
+        limit: Annotated[int, Field(ge=1, le=200, description="Maximum number of pages to return.")] = 50,
+    ) -> dict:
+        """List the documentation pages already stored in the local cache, sorted by URL.
+
+        Use it to see which pages of an area are available offline or to pick a page to open with `get_telegram_document`. Returns URL, title, area, last check time and freshness for each page, the total count and `next_offset` (null at the end). It lists stored pages only; to find content by topic use `search_telegram_docs`, and for totals and errors use `get_telegram_corpus_status`."""
+        return cached_pages(area, offset, limit)
+
     return server
 
 

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/tests/test_http.py

@@ -58,7 +58,7 @@ class HttpTransportTests(unittest.TestCase):
                             async with ClientSession(read, write) as session:
                                 await session.initialize()
                                 listing = await session.list_tools()
-                                self.assertEqual(len(listing.tools), 5)
+                                self.assertEqual(len(listing.tools), 6)
                                 self.assertTrue(all(tool.annotations.readOnlyHint for tool in listing.tools))
                                 result = await session.call_tool("search_telegram_docs", {"query": "InlineKeyboardButton", "area": "bot-api"})
                                 self.assertFalse(result.isError)

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/tests/test_knowledge.py

@@ -95,8 +95,8 @@ class KnowledgeTests(unittest.TestCase):
                 async with ClientSession(read, write) as session:
                     await session.initialize()
                     listing = await session.list_tools()
-                    self.assertEqual(len(listing.tools), 5)
-                    result = await session.call_tool("telegram_corpus_status", {})
+                    self.assertEqual(len(listing.tools), 6)
+                    result = await session.call_tool("get_telegram_corpus_status", {})
                     self.assertFalse(result.isError)
                     payload = result.structuredContent or json.loads(result.content[0].text)
                     self.assertEqual(payload["pages"], 0)
@@ -129,13 +129,38 @@ class ToolDefinitionTests(unittest.TestCase):
             return await k.create_server().list_tools()
         with patch.dict(os.environ, {"TELEGRAM_DOC_AUTO_SYNC": "0"}):
             listing = asyncio.run(tools())
-        self.assertEqual(len(listing), 5)
+        self.assertEqual(len(listing), 6)
+        verbs = ("search_", "get_", "list_")
         for tool in listing:
             with self.subTest(tool=tool.name):
                 self.assertTrue(tool.title)
+                self.assertTrue(tool.name.startswith(verbs))
                 self.assertGreater(len(tool.description), 150)
                 for name, schema in tool.inputSchema.get("properties", {}).items():
                     self.assertTrue(schema.get("description"), name)
         search = next(tool for tool in listing if tool.name == "search_telegram_docs")
         areas = set(search.inputSchema["properties"]["area"]["enum"])
         self.assertEqual(areas - {""}, {k.family(url) for url in k.SEEDS} | {"media-design", "gateway"})
+
+
+class CachedPagesTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.old_db = k.DB
+        k.DB = Path(self.temp.name) / "pages.sqlite3"
+
+    def tearDown(self):
+        k.DB = self.old_db
+        self.temp.cleanup()
+
+    def test_lists_cached_pages_by_area_with_paging(self):
+        with k.connect() as conn:
+            for url in ("https://core.telegram.org/bots/api", "https://core.telegram.org/bots/webapps",
+                        "https://docs.ton.org/applications/ton-connect/overview"):
+                k.save(conn, url, (url, url.rsplit("/", 1)[-1], "# Title\nSome documented text for the page.", []))
+        first = k.cached_pages(limit=2)
+        self.assertEqual((first["total"], len(first["pages"]), first["next_offset"]), (3, 2, 2))
+        self.assertIsNone(k.cached_pages(offset=2, limit=2)["next_offset"])
+        ton = k.cached_pages(area="ton")
+        self.assertEqual([page["url"] for page in ton["pages"]], ["https://docs.ton.org/applications/ton-connect/overview"])
+        self.assertFalse(ton["pages"][0]["freshness"]["stale"])

{telegram_dev-0.6.1 → telegram_dev-0.7.0}/uv.lock

@@ -946,7 +946,7 @@ wheels = [
 
 [[package]]
 name = "telegram-dev"
-version = "0.6.1"
+version = "0.7.0"
 source = { editable = "." }
 dependencies = [
     { name = "beautifulsoup4" },