Skip to main content
Glama
telegram-bot-framework-mcp

telegram-bot-framework-mcp

by Severnbli

telegram-bot-framework-mcp

Give your AI assistant the real source, docs and a curated how-to guide for the TelegramBotBase .NET framework.

Docker pulls License: MIT MCP Framework

Quick start · Tools · Examples · Self-hosting · Upgrading · CI


An MCP server that lets an AI assistant answer questions about MajMcCloud/TelegramBotFramework (NuGet: TelegramBotBase) from the actual source code, not from memory. It ships as a Docker image with the framework source baked in, pinned to 8.0.0-preview.2 (development branch, commit 6780abf), together with a curated how-to guide.

Feature

Ask in plain English

ask ranks guide sections, known pitfalls and matching types in one call

Exact answers

read real signatures, doc comments and example bots straight from the pinned source

Pitfall finder

describe a symptom ("button spins forever") and get the known cause and fix

Upgrade helper

public API diff between any two tags or commits

Use it your way

free public endpoint, local Docker (stdio), or your own VPS

WARNING

8.0.0-preview.2 is apreview; its API can still change before 8.0.0. The builder in this version has an extra request dispatcher stage that does not exist in 7.x, so code from the guide will not compile against 7.2.0. To serve 7.2.0 instead, build with --build-arg TGBOTBASE_REF=13fff09c2736e4616f1d3c5dffe40401b92c81b0 --build-arg TGBOTBASE_NUGET_VERSION=7.2.0 and expect the guide's dispatcher parts to be wrong.

Quick start

Pick one way to connect. Both give the assistant the same tools.

Option

Best for

Command

Hosted (HTTP)

zero setup

claude mcp add --transport http tgbotbase https://tbf-mcp.severnbli.dev/mcp

Local (stdio)

reliability, offline

claude mcp add tgbotbase -- docker run -i --rm severnbli/telegram-bot-framework-mcp:8.0.0-preview.2

WARNING

Keep the-i flag in the local command. Without it the container's stdin closes and the connection fails immediately.

NOTE

The public instance is a free, read-only, best-effort service: rate limited, no uptime guarantee, no token needed. If the server owner enabled a token, add--header "Authorization: Bearer <token>". For reliability, run the local image or host your own.

Use the URL above (plus the Authorization header if a token is enabled), or this stdio config:

{ "mcpServers": { "tgbotbase": { "command": "docker",
  "args": ["run", "-i", "--rm", "severnbli/telegram-bot-framework-mcp:8.0.0-preview.2"] } } }

Check it works: run /mcp in Claude Code, or ask "What framework version does tgbotbase serve?" The answer should mention 8.0.0-preview.2 and commit 6780abf.

TIP

Pin the image tag (:8.0.0-preview.2) in your client config. Prereleases never get the latest tag.

Related MCP server: Atlas Docs MCP Server

Tools

The server also sends usage instructions to the client, so assistants start with ask for any how-to question.

Tool

Use it to

ask

Start here. One call searches the guide, pitfalls, types and README and says what to read next

list_guide_sections, get_guide_section, search_guide

Read the curated guide: decision tables (message loop / dispatcher / serializer), patterns, ship checklist. search_guide takes a plain-English question and returns ranked sections with snippets

get_gotchas

Describe a problem or error name and get the known cause and fix

framework_version

See the TelegramBotBase version, commit and dependencies (e.g. Telegram.Bot) the answers are based on

list_symbols, get_symbol

Find C# types by name; see doc comment, base types and public members (typos get "did you mean")

find_subclasses

Everything deriving from or implementing a type (FormBase, ControlBase, IStateMachine)

search_code

Case-insensitive substring search of the source (path_prefix and extension narrow it)

get_file, list_files

Read any file (optionally a line range) or list files under a path

list_examples

List example and test-bot source files

list_doc_sections, get_doc_section

Browse and read the framework README (Quick start, ButtonGrid, State Machines, ...)

get_changes, list_refs

Public API diff between two tags/commits, for example before an upgrade

Resources: tgbotbase://readme (the framework README) and tgbotbase://guide (the full guide).

NOTE

The symbol index is built with regular expressions, not a C# compiler. It is good for finding types and comparing public APIs, but can miss unusual declarations, andget_changes may list a few false positives (for example a word inside a comment reported as a type). For exact behavior, read the file with get_file.

Example prompts

  • "Using tgbotbase, write a form with a paged ButtonGrid. Check the real ButtonGrid source for the API."

  • "Which controls exist and how do they differ? Use find_subclasses on ControlBase."

  • "How do I persist user sessions across restarts? Look at the state machine classes."

  • "How do I show a calendar and read the chosen date?" (uses ask)

  • "My button spins forever. Why?" (uses get_gotchas)

  • "Which message loop and request dispatcher should I use for a bot with broadcasts?" (uses the guide's decision tables)

  • "What changed in the public API between v7.1.0 and the current version?"

TIP

tell the assistant toverify against the source (get_symbol, get_file) instead of answering from memory, and give it your bot's framework version so it can compare with framework_version.

Hosting on a VPS

Runs the container on 127.0.0.1:8000 and puts host nginx in front of it with TLS and per-IP rate limiting. The server is public by default; a bearer token is optional (see below).

Requirements: Docker, nginx and certbot on the VPS; a DNS A record for tbf-mcp.severnbli.dev pointing at it; ports 80 and 443 open.

1. Start the container

cd deploy && cp .env.example .env
docker compose up -d

The compose file runs the container read-only with a 512 MB memory and 1 CPU limit.

NOTE

the image tag8.0.0-preview.2 exists on Docker Hub only after the first publish from main (see CI and publishing). Before that, docker compose up fails with "not found".

2. Configure nginx

sudo cp nginx.conf /etc/nginx/sites-available/tgbotbase-mcp
sudo ln -s /etc/nginx/sites-available/tgbotbase-mcp /etc/nginx/sites-enabled/
sudo certbot certonly --nginx -d tbf-mcp.severnbli.dev
sudo nginx -t && sudo systemctl reload nginx
WARNING

on a fresh VPS the certificate does not exist yet, songinx -t fails on the 443 block. Comment that block out, run certbot, then restore it. http2 on; needs nginx 1.25.1 or newer; on older versions remove it and write listen 443 ssl http2;.

NOTE

the config assumes the domain is proxied through Cloudflare (orange cloud). It trustsCF-Connecting-IP only from Cloudflare's published ranges, so rate limits apply per real visitor. If you are not behind Cloudflare, delete the set_real_ip_from / real_ip_header lines. Set Cloudflare SSL/TLS mode to Full (strict).

3. Verify

curl -i https://tbf-mcp.severnbli.dev/mcp   # public mode: any response from the MCP server except 401/404/502

Optional: require a bearer token

A bearer token is a secret string the client sends as Authorization: Bearer <token>. To enable it, edit the copy in /etc/nginx/sites-available/tgbotbase-mcp:

  1. Generate a token: openssl rand -hex 32.

  2. In the map block change default 1; to default 0; and uncomment the "Bearer ..." line with your token.

  3. sudo nginx -t && sudo systemctl reload nginx, then connect clients with --header "Authorization: Bearer <token>". Requests without it get 401.

WARNING

put the token only in the copy under/etc/nginx, never in the repo file. Do not commit a real token. Anyone who has it can use the server. Use HTTPS only, since the token travels in a header.

Updating

cd deploy && docker compose pull && docker compose up -d
TIP

the port is bound to127.0.0.1 on purpose. Do not change it to 0.0.0.0: that would bypass nginx's rate limits (and the token, if enabled).

Upgrading the framework version

  1. Build with the new ref (a tag or commit SHA) and version:

    docker build \
      --build-arg TGBOTBASE_REF=<tag|sha> \
      --build-arg TGBOTBASE_NUGET_VERSION=<x.y.z> \
      -t tgbotbase-mcp:<x.y.z> .
  2. Update the defaults in the Dockerfile and the pinned version in this README, then merge to main to publish.

  3. Before changing your bot, ask the assistant for get_changes between the old and new ref to see what to adapt.

TIP

the repo does not tag NuGet releases (there is nov7.2.0 or v8.0.0-preview.2). Match the NuGet publish date to a commit on master and pin that commit SHA.

CI and publishing

  • ci.yml runs on every pull request: builds the image, runs tests/smoke.py and tests/test_search.py (search quality) inside it, and runs tests/check_guide.py, which fails if the guide mentions a source file that no longer exists in the pinned source (so a version bump can't silently leave the guide stale).

  • publish.yml runs only on a push to main or a manual dispatch on main. It re-runs CI, then pushes severnbli/telegram-bot-framework-mcp:<framework version> (read from the Dockerfile; plus :latest for stable, non-prerelease versions) to Docker Hub for linux/amd64 and linux/arm64.

WARNING

publishing needs the repository secretsDOCKERHUB_USERNAME and DOCKERHUB_TOKEN. Without them the publish job fails at login.


MIT licensed · Not affiliated with the TelegramBotBase authors · Built on the Model Context Protocol

Available Tools

17 tools
askA

Best first call for any how-to question about building a bot with TelegramBotBase. Searches the guide, the known pitfalls, the type index and the README at once, and tells you which tool to call next.

Inputs: question (required). Returns: result

find_subclassesB

Find types that inherit from / implement base (e.g. FormBase, ControlBase, IStateMachine).

Inputs: base (required). Returns: result

framework_versionA

Which framework version this server's source corresponds to (NuGet version, git commit, date).

Inputs: no named parameters. Returns: result

get_changesA

Public API diff of the TelegramBotBase library between two git refs (tags, branches, SHAs): added/removed types and added/removed public members, plus commit list. Only refs present in the clone work.

Inputs: from_ref (required), to_ref, max_items. Returns: result

get_doc_sectionA

Get README section(s) by case-insensitive partial title, e.g. 'ButtonGrid'.

Inputs: title (required). Returns: result

get_fileC

Read a repository file (optionally a line range).

Inputs: path (required), end_line, start_line. Returns: result

get_gotchasA

Known pitfalls as 'symptom -> cause & fix'. Pass words of your problem or error (e.g. 'spins forever', 'CallbackDataTooLongException'), or nothing for all.

Inputs: symptom. Returns: result

get_guide_sectionA

Read guide section(s) by number or partial title, e.g. '3.4', 'Navigation', 'Checklist'.

Inputs: query (required). Returns: result

get_symbolA

Show a type: doc comment, bases, public/protected members and file path. Use get_file for full source.

Inputs: name (required). Returns: result

list_doc_sectionsC

List README sections.

Inputs: no named parameters. Returns: result

list_examplesB

List C# example and test-bot files.

Inputs: no named parameters. Returns: result

list_filesB

List repository files filtered by path prefix and extension.

Inputs: prefix, extension. Returns: result

list_guide_sectionsA

List sections of the curated how-to guide (decision tables, patterns, gotchas, checklist).

Inputs: no named parameters. Returns: result

list_refsA

List tags and branches available for get_changes.

Inputs: no named parameters. Returns: result

list_symbolsB

List C# types (class/interface/enum/struct/record) by name substring and optional kind.

Inputs: kind, query, max_results. Returns: result

search_codeB

Case-insensitive substring search of the source; returns path:line: text.

Inputs: query (required), extension, max_results, path_prefix. Returns: result

search_guideA

Search the how-to guide with a plain-English question or keywords (e.g. 'handle a button click', 'dispatcher'). Returns the best-matching sections, most relevant first, each with the key matching lines. Read a whole section with get_guide_section.

Inputs: query (required), max_results. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools target clearly distinct facets (git refs, symbols, files, code search, README, examples, guide, gotchas), so an agent can usually pick correctly. The overlap is mild: `ask` deliberately subsumes `search_guide`, `get_gotchas`, `list_symbols` and README lookup, and `list_doc_sections`/`list_guide_sections` are two similar-looking pairs, but the docs explicitly frame `ask` as an orchestrator so the boundaries are explained.

    Naming Consistency4/5

    Names follow a clear verb_noun convention (list_refs, get_symbol, find_subclasses, search_code, get_guide_section) across the whole set. Only two deviations stand out: the noun-only `framework_version` and the verb-only `ask`, which are minor and readable.

    Tool Count3/5

    17 tools is on the heavy side for what is essentially a read-only repo/docs browser, and several doc-navigation tools (list_doc_sections/get_doc_section, list_guide_sections/get_guide_section, search_guide) could arguably be consolidated. Each still maps to a real facet of the repo, so it is heavy rather than bloated.

    Completeness4/5

    The surface covers versioning, API diffs, refs, symbol/subclass lookup, file listing and reading, code search, README, examples, the curated guide and pitfalls, and even an orchestrator entry point — a solid lifecycle for a documentation/reference server. Minor gaps remain: no full-text README search, no example-file search, and no way to enumerate all symbols in one call.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides AI assistants with up-to-date documentation for popular libraries and frameworks, enabling them to generate more accurate code using less common or newly released libraries.
      5
      36
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables clients to retrieve real-time framework documentation for any npm package, returning TypeScript types, prose, and code examples with intent-aware formatting, plus version migration guidance, error diagnosis, package comparison, and dependency scanning.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to search pinned robotics code and reusable task findings across frameworks, inspect provenance and requirements, and prepare supported upstream sources via recipes without executing robot code.
      Apache 2.0