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

{telegram_dev-0.6.0 → 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.0"},
+  "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.0",
+      "version": "0.7.0",
       "homepage": "https://github.com/Kay0k1/telegram-dev",
       "repository": "https://github.com/Kay0k1/telegram-dev",
       "license": "MIT",

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

@@ -1,6 +1,6 @@
 {
   "name": "telegram-dev",
-  "version": "0.6.0",
+  "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.0 → telegram_dev-0.7.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "telegram-dev",
-  "version": "0.6.0",
+  "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.0 → telegram_dev-0.7.0}/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "telegram-dev",
-  "version": "0.6.0",
+  "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.0 → telegram_dev-0.7.0}/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 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
+
+- MCP tool definitions: every tool has a short title and a description of when to use it and what it returns; every parameter has a description, examples and limits (`limit` 1–20, `length` 100–40000, `offset` ≥ 0); `area` is a list of allowed values instead of free text.
+- `glama.json` pins the Glama build spec (Python 3.14 until dependencies support 3.15).
+
 ## [0.6.0] - 2026-11-10
 
 ### Added
@@ -62,6 +80,8 @@ 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
 [0.5.0]: https://github.com/Kay0k1/telegram-dev/compare/v0.4.0...v0.5.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telegram-dev
-Version: 0.6.0
+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.0 → 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.0 → 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.0 → 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.7.0/glama.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": ["Kay0k1"],
+  "transport": "stdio",
+  "buildSteps": ["uv sync --frozen --python 3.14"],
+  "cmdArguments": ["mcp-proxy", "--", "uv", "run", "--frozen", "telegram-dev", "serve"],
+  "placeholderArguments": {}
+}

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "telegram-dev"
-version = "0.6.0"
+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.0 → 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.0 → telegram_dev-0.7.0}/server.json

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

{telegram_dev-0.6.0 → 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.0 → 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.0
+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.0 → telegram_dev-0.7.0}/telegram_knowledge.py

@@ -14,12 +14,14 @@ import sys
 import threading
 import time
 from datetime import datetime, timezone
+from typing import Annotated, Literal
 from urllib.parse import urljoin, urlsplit, urlunsplit
 
 import httpx
 from bs4 import BeautifulSoup
 from markdownify import markdownify
 from platformdirs import user_cache_path
+from pydantic import Field
 
 ROOT = Path(__file__).resolve().parent
 DB = Path(os.environ.get("TELEGRAM_KNOWLEDGE_DB", str(user_cache_path("telegram-dev") / "corpus.sqlite3")))
@@ -669,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"))
@@ -794,6 +808,10 @@ def document(url, offset=0, length=16000, refresh=False):
     return result
 
 
+Area = Literal["", "bot-api", "mini-apps", "telegram-api", "tdlib", "releases", "product-releases", "gateway",
+               "web-integrations", "media-design", "ton", "ton-releases", "aiogram", "python-telegram-bot", "grammy"]
+
+
 def create_server(transport="stdio", host="127.0.0.1", port=8000):
     from mcp.server.fastmcp import FastMCP
     from mcp.server.transport_security import TransportSecuritySettings
@@ -832,27 +850,53 @@ def create_server(transport="stdio", host="127.0.0.1", port=8000):
         return JSONResponse({"status": "ok", "pages": status["pages"],
                              "stale_pages": status["stale_pages"], "source_errors": len(status["errors"])})
 
-    @server.tool(annotations=annotations)
-    def search_telegram_docs(query: str, area: str = "", limit: int = 6) -> dict:
-        """Search public Telegram docs, preferring exact English API symbols. Areas: bot-api, mini-apps, telegram-api, tdlib, releases, product-releases, gateway, web-integrations, media-design, ton (docs.ton.org, TON Connect, Tolk, TVM, TEPs), ton-releases, aiogram, python-telegram-bot (docs and wiki), grammy. Core Telegram docs rank first unless the query names a library (aiogram, PTB/python-telegram-bot/telegram.ext, grammY). Russian feature aliases supported for common media topics."""
+    @server.tool(title="Search Telegram and TON docs", annotations=annotations)
+    def search_telegram_docs(
+        query: Annotated[str, Field(min_length=1, description=(
+            "Exact API names or short English keywords work best, e.g. 'InlineKeyboardButton style', "
+            "'sendVideoNote', 'ton_proof', 'jetton transfer', 'aiogram Router callback_query'. "
+            "Common Russian feature words (кнопка, кружок, кошелек) are expanded automatically."))],
+        area: Annotated[Area, Field(description=(
+            "Limit results to one documentation area; empty searches all areas. Core Telegram docs rank above "
+            "library docs unless the query names a library."))] = "",
+        limit: Annotated[int, Field(ge=1, le=20, description="Maximum number of matching sections to return.")] = 6,
+    ) -> dict:
+        """Find the official documentation sections that answer a Telegram or TON development question.
+
+        Use it before writing or reviewing code that calls the Bot API, Mini Apps JS, Telegram API/MTProto, TDLib, TON Connect, Tolk contracts or the aiogram, python-telegram-bot and grammY libraries. Returns up to `limit` sections with page URL, heading, excerpt, `document_offset` and freshness. Excerpts are partial: open the page with `get_telegram_document` at `document_offset` before relying on details. Stale matching pages are re-fetched first. An empty result is not proof that a feature does not exist; if the cache is empty, the response suggests pages to fetch."""
         result = search(query, area, limit, refresh_results=True)
         if not result['results'] and coverage()['pages'] == 0:
             result['note'] = 'The cache is empty. Fetch a relevant official URL with get_telegram_document first, then search again. Suggested starts: https://core.telegram.org/bots/api ; https://core.telegram.org/api ; https://core.telegram.org/bots/webapps ; TON: https://docs.ton.org/llms.txt (index of all TON pages) ; libraries: https://docs.aiogram.dev/en/latest/ ; https://docs.python-telegram-bot.org/en/stable/ ; https://grammy.dev/sitemap.xml.'
         return result
 
-    @server.tool(annotations=annotations)
-    def get_telegram_document(url: str, offset: int = 0, length: int = 16000, refresh: bool = False) -> dict:
-        """Read paginated official documentation. Missing/stale pages refresh automatically; refresh=True forces a live check. Failures preserve cached content with freshness.stale and refresh_error. Includes hash and observation date, not release date. URL fragments do not change pagination."""
+    @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 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,
+        refresh: Annotated[bool, Field(description="Force a live check of the source even if the cached copy is fresh.")] = False,
+    ) -> 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_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(annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False))
-    def telegram_corpus_status() -> dict:
-        """Report indexed scope, coverage gaps, source errors, and last successful check. Never equate indexed pages with all Telegram knowledge."""
+    @server.tool(title="Cache coverage and freshness", annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False))
+    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 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(annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False))
-    def telegram_document_history(url: str) -> dict:
-        """List locally observed revisions of a source. Does not reconstruct versions predating this corpus."""
+    @server.tool(title="Observed revisions of a page", annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False))
+    def list_telegram_document_revisions(
+        url: Annotated[str, Field(description="Official page URL, the same form accepted by get_telegram_document.")],
+    ) -> dict:
+        """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. 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:
@@ -860,12 +904,25 @@ def create_server(transport="stdio", host="127.0.0.1", port=8000):
             target = conn.execute("SELECT target FROM aliases WHERE url=?", (base,)).fetchone()
             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(annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False))
-    def telegram_sources() -> dict:
-        """List configured official entrypoints by API family; use the relevant index to discover current feature pages. This is source configuration, not proof of complete cached coverage."""
+    @server.tool(title="Official documentation entry points", annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False))
+    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`. 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.0 → 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.0 → 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)
@@ -121,3 +121,46 @@ class CliTests(unittest.TestCase):
         with patch("builtins.print") as printed:
             k.main(["--version"])
         self.assertRegex(printed.call_args.args[0], r"^\d+\.\d+\.\d+")
+
+
+class ToolDefinitionTests(unittest.TestCase):
+    def test_every_tool_has_a_title_and_documented_parameters(self):
+        async def tools():
+            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), 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.0 → telegram_dev-0.7.0}/uv.lock

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

telegram_dev-0.6.0/glama.json

@@ -1,4 +0,0 @@
-{
-  "$schema": "https://glama.ai/mcp/schemas/server.json",
-  "maintainers": ["Kay0k1"]
-}