xonta-max-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MAX_CA_FILE | No | Path to the Russian trusted root CA certificate PEM file. | |
| MAX_BOT_TOKEN | No | Bot token that enables the local operator tools. Without it, the server still runs but without those tools. | |
| XONTA_MAX_LANG | No | Default response language. Defaults to Russian; set to "en" for English. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Tools for building bots and mini-apps for the MAX messenger (max.ru, dev.max.ru). Every tool takes lang='en' or lang='ru' — answer in the user's language. Knowledge: max_api_reference, max_endpoint_info, max_limits, max_changelog — current Bot API facts with sources. Code: max_lint_code finds outdated hosts, TLS mistakes, removed methods and Telegram leftovers; max_migrate_from_telegram plans a port from Telegram Bot API; max_scaffold_bot generates a working project. Messages: max_build_message, max_validate_message, max_split_text, max_convert_formatting. Links: max_deeplink (bot start, mini-app startapp, share-to-MAX without a bot, user mention). Testing: max_mock_update (webhook payloads + curl), max_mock_init_data and max_bridge_mock (window.WebApp emulator). Ads: max_api_reference topic='ads' (where to buy, channel monetization, marking), max_tracking_links (a link per placement), max_ad_report (cost per order, ROAS, ROMI with confidence intervals), max_check_ad_post (marking check). When the server runs locally with MAX_BOT_TOKEN, operator tools (max_send_message etc.) act as that bot. Always use platform-api2.max.ru and never suggest disabling TLS verification.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| max_api_referenceA | Look up current facts about the MAX Bot API and Mini Apps (MAX Bridge) with links to dev.max.ru. Covers base URL and auth, the Russian Trusted Root CA, advertising in MAX (topic 'ads'), webhooks vs long polling, sending messages, inline keyboards and callbacks, formatting, uploads, chat tracking without GET /chats, mini-apps, initData validation, deep links, who may create bots, official libraries. Language models usually know an outdated API (platform-api.max.ru, token in query, GET /chats) — use this before writing MAX code. With no arguments returns the list of topics. |
| max_endpoint_infoA | Details of one MAX Bot API method (query params, body, limits, gotchas, docs link) or the full method list. Also tells when a method was removed or restricted (GET /chats, POST /chats/{chatId}/members). |
| max_limitsA | All MAX platform limits in one table: text length, rate limits, keyboard size, attachments, file sizes, deep link payloads, webhook rules, bots per profile — each with a source link. Also update types, button types, errors. |
| max_changelogB | Dated MAX platform changes in 2026 that break old code: host move to platform-api2, removed GET /chats, restricted member adding, HTTPS-only webhooks, comments API, self-employed access. |
| max_lint_codeA | Check MAX bot or mini-app code for known mistakes, with line numbers and fixes. Finds: old host platform-api.max.ru, token in query string, 'Bearer' prefix, disabled TLS verification, removed GET /chats, restricted member adding, type=photo uploads, wrong webhook setup (port, HTTP, /webhook), disable_link_preview in body, plain == comparison of the webhook secret, initData signed directly with the token, trusting initDataUnsafe, hardcoded upload hosts, Telegram leftovers. Static, never runs the code. |
| max_migrate_from_telegramA | Plan a port of a Telegram bot or Web App to MAX. With code: every Telegram API usage with line number and the MAX replacement, features with no MAX equivalent, effort estimate and a step-by-step plan. Without code: the full Telegram → MAX method map. |
| max_scaffold_botA | Generate a ready MAX bot project: polling for dev, webhook for prod, the Russian Trusted Root CA in the Dockerfile, chat tracking without GET /chats, callback answers, constant-time secret check, rate limits and text splitting (Python). lang sets the language of comments, README and the bot's replies. Returns a map of file name → content. Write the files as they are. Creating the bot itself and getting a token requires a verified profile on business.max.ru. |
| max_validate_messageA | Validate a message body before sending to MAX: 4000-char text, format, keyboard limits (210/30/7, 3 per row with link/open_app/request_*), button fields and lengths, attachment combinations (≤12 media, file only with a keyboard, audio/sticker/contact alone), comment restrictions, Telegram fields left in the body. |
| max_build_messageA | Build a correct POST /messages request for MAX: JSON body with inline keyboard and images, validation result and a ready curl command. Use it instead of hand-writing keyboard JSON. |
| max_split_textB | Split text into MAX messages of at most 4000 characters, cutting at paragraphs, lines or sentences. |
| max_convert_formattingA | Convert formatted text to MAX markup: Telegram MarkdownV2 (underline x → ++x++, unescape), Telegram HTML (tg://user → max://user, spoilers dropped) or ordinary Markdown from an LLM (lists → bullets, rules removed). Reports what MAX cannot show (spoilers, tables, lists, inline images). Use the returned format value in the body. |
| max_deeplinkA | Build and validate MAX deep links. 'share' gives a link, an HTML button and a JS helper that open MAX's chat picker with prefilled text — works on any website or AI agent output without owning a bot. Payload limits are checked, because MAX silently drops payloads that are too long or have bad characters. |
| max_mock_updateA | Generate a realistic MAX webhook Update for tests, shaped like the official schema, plus a curl command to send it to your local webhook. Lets you test a bot before it passes moderation or without a token. |
| max_mock_init_dataA | Produce a correctly signed MAX mini-app initData string (two-step HMAC with 'WebAppData') for backend tests, with the token used, so you can check your validator end to end. |
| max_bridge_mockA | Generate max-bridge-mock.js: a window.WebApp emulator to develop MAX mini-apps in a normal browser on localhost. Emulates initData/initDataUnsafe (signed if a test token is given), BackButton (Esc), DeviceStorage and SecureStorage (localStorage, 10-key cap), BiometricManager, HapticFeedback, NfcManager, ScreenCapture, requestContact with a valid hash, openLink/downloadFile/shareMaxContent click requirements and per-platform restrictions. Logs every call. Use only on localhost. |
| max_check_webhook_secretA | Check a MAX webhook secret against the rules (5-256 chars, A-Z a-z 0-9 _ -) or generate a strong one. |
| server_statusB | Server version, facts date, mode (hosted or local), languages and whether operator tools are active. |
| max_tracking_linksA | Make a separate tracking link (and promo code) for every channel where an ad is placed in MAX, so you can see which placement brought users and sales. Bot links use ?start=: the id arrives in bot_started.payload, which works even for clicks that never leave the messenger. Returns a media plan as CSV. Then feed the counts to max_ad_report. |
| max_ad_reportA | Compare ad placements in MAX by real results: CPM, cost per click or bot start, cost per lead and per order, ROAS, profit after ads and ROMI (with margin), conversion with a 95% confidence interval. Says when a difference between channels may be chance and when there is too little data. A calculator only: it does not touch ad accounts or move money. |
| max_check_ad_postA | Check an ad post for MAX against Russian ad marking rules: the 'Реклама' label at the top, advertiser details (name and INN/OGRN or a site), an erid token in the link or text, the A+ mark for channels over 10,000 subscribers, and the 4000-character limit. A hint, not legal advice; ORD registration is not checked. |
| max_verify_signatureA | Verify a MAX signature locally: mini-app initData (two-step HMAC), requestContact phone hash, or the hash of a contact shared through a request_contact button. Explains why a check failed (wrong formula, double decoding, stale auth_date). Available only when the server runs on your machine. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 21 tools
Tools cluster into clearly recognizable roles: reference lookups (max_api_reference, max_endpoint_info, max_limits, max_changelog), code assistance (max_lint_code, max_migrate_from_telegram, max_convert_formatting), message composition (max_validate_message, max_build_message), test fixtures (max_mock_update, max_mock_init_data, max_bridge_mock) and ads tooling. The main fuzziness is validate vs. build (build also returns a validation result) and the four reference tools, whose boundaries an agent must read carefully to pick correctly. Overall still well-separated.
Nearly all names follow a snake_case max_<topic> pattern with a consistent, predictable prefix, which makes the set easy to scan. Minor deviations exist: several names are noun phrases (max_api_reference, max_limits, max_changelog) while others are verb_noun (max_lint_code, max_convert_formatting), max_bridge_mock reverses to noun_verb, and server_status drops the max_ prefix entirely.
21 tools is on the heavy side, but the server genuinely spans several sub-domains (API reference, scaffolding, linting, migration, message building, mocking, ads analytics), and almost every tool maps to a distinct job. There is little obvious redundancy, so the count is justified rather than padded, though a few reference tools could plausibly be merged.
The surface covers the full 'write correct MAX bot/mini-app code' lifecycle: look up facts, scaffold a project, build/validate messages, convert formatting, migrate from Telegram, mock updates and Bridge objects, and verify signatures, plus an ads/reporting branch. The notable gap is that nothing actually calls the live Bot API (no send-message or get-updates tool) and payments/upload execution are uncovered, so agents must hand-roll those steps.