---

getting started

what is this?

LLMs hallucinate API specifics. When you ask about TeleBot Studio, they guess from stale training data — wrong function signatures, invented parameters, outdated patterns. This is documentation drift: the gap between what the AI says and what the docs actually specify.

TeleBot Studio MCP closes that gap two ways:

• documentation tools ground your AI in official docs. If the answer isn't in the corpus, the server returns nothing — no phantom functions, no invented APIs.
• API tools let your AI do things — create bots, write commands, start and stop them — through the official TeleBot Studio REST API v2.

The result: an AI assistant that both knows the platform and can act on it.

who should use it?

• TeleBot Studio users who want an AI assistant that actually knows the platform instead of making things up
• Developers building Telegram bots with TeleBot Studio who want to create and manage bots from their AI editor
• Teams who want a shared, always-correct reference for TeleBot Studio inside their AI workflow
• Anyone tired of AI responses that invent functions or describe APIs that don't exist

You don't need to be an MCP expert. If you can install a Python package and edit a JSON config file, you can set this up.

what the documentation engine does

The documentation engine takes every page of official TeleBot Studio documentation, breaks it into sections, and builds a search index using BM25 — a well-established ranking algorithm. When your AI asks a question, the server searches this index and returns the most relevant sections with their scores.

• Works offline — no internet connection needed for documentation queries
• Uses BM25 ranking, not embeddings — results are deterministic and exact
• Supports scoped searches — code examples, API references, function definitions, library info, or error messages
• If the answer isn't in the docs, it returns nothing — your AI won't invent answers

what the api engine does

The API engine wraps the TeleBot Studio REST API v2 and exposes it as MCP tools. Your AI can:

• Create and delete bots
• Update bot tokens
• Create, read, update, and delete bot commands
• Start, stop, and restart bots
• Deploy a complete bot in one operation (create → add commands → start)

Every API call goes through the official REST API over HTTPS. The server never stores your credentials on disk — they live in memory for the duration of the session and are lost on restart.

what the ai agent does

For multi-step operations like deploying a complete bot, the server includes an agent pipeline that breaks the task into ordered steps:

1. Planner — decomposes the goal into discrete actions (create bot, add command, start bot)
2. Validator — checks that credentials are set and parameters are valid before anything runs
3. Preview — shows you what will happen, with sensitive values masked, and waits for your confirmation
4. Executor — runs the steps one by one, continuing even if some fail, and reports per-step results

This pipeline is what powers tbs_deploy_bot, tbs_setup_commands, and the batch tools.

---

features

	what you get
documentation	BM25 full-text search, heading-aware chunking, unigram + bigram tokenization, 5 scoped search modes, LRU caching, 100% offline
bot management	create / delete / update bots, create / update / delete / list commands, start / stop / restart bots
agent pipeline	Planner → Validator → Preview → Executor for multi-step operations like full bot deployment
batch operations	bulk create or delete commands with per-step success/failure reporting
safety	preview-before-execute for destructive ops, session-scoped credentials (never persisted), token masking
server	FastMCP, STDIO + HTTP/streamable-http transports, /health endpoint, thread-safe sessions, retry with backoff

---

supported clients

Works with any MCP-compatible client. Tested with:

Claude Desktop · Cursor · Windsurf · VS Code · ChatGPT · Continue · Cline

If your client supports the Model Context Protocol, it should work out of the box.

---

quick start

If you already know your way around MCP and just want the essentials:

git clone https://github.com/harshi79/telebotstudio-mcp.git
cd telebotstudio-mcp
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python build_index.py --validate
python server.py

For detailed per-OS instructions, see local installation. For client-specific setup, see connecting to ai clients.

---

local installation

linux

1. Clone the repository

   git clone https://github.com/harshi79/telebotstudio-mcp.git
   

2. Enter the project directory

   cd telebotstudio-mcp
   

3. Create a virtual environment

   python3 -m venv venv
   

   This creates an isolated Python environment so dependencies don't conflict with your system packages. You need Python 3.11 or newer.

4. Activate the virtual environment

   source venv/bin/activate
   

   You'll see (venv) appear in your shell prompt. Run this every time you open a new terminal.

5. Install dependencies

   pip install -r requirements.txt
   

6. Validate the documentation index

   python build_index.py --validate
   

   You should see:

   ✓ All 918 chunks validated successfully.
   

7. Run the server

   STDIO mode (for local AI clients like Claude Desktop and Cursor):

   python server.py
   

   HTTP mode (for remote clients or deployment):

   python server.py --transport http
   

macos

1. Clone the repository

   git clone https://github.com/harshi79/telebotstudio-mcp.git
   

2. Enter the project directory

   cd telebotstudio-mcp
   

3. Create a virtual environment

   python3 -m venv venv
   

   If python3 isn't found, install Python from python.org or via Homebrew: brew install python3.

4. Activate the virtual environment

   source venv/bin/activate
   

5. Install dependencies

   pip install -r requirements.txt
   

6. Validate the documentation index

   python build_index.py --validate
   

7. Run the server

   STDIO mode:

   python server.py
   

   HTTP mode:

   python server.py --transport http
   

windows

1. Clone the repository

   git clone https://github.com/harshi79/telebotstudio-mcp.git
   

   If you don't have git, install it from git-scm.com.

2. Enter the project directory

   cd telebotstudio-mcp
   

3. Create a virtual environment

   python -m venv venv
   

   If python isn't recognized, try py instead, or install Python from python.org. Make sure to check "Add Python to PATH" during installation.

4. Activate the virtual environment

   PowerShell:

   .\venv\Scripts\Activate.ps1
   

   Command Prompt:

   .\venv\Scripts\activate.bat
   

   If PowerShell says running scripts is disabled, run this first:

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

5. Install dependencies

   pip install -r requirements.txt
   

6. Validate the documentation index

   python build_index.py --validate
   

7. Run the server

   STDIO mode:

   python server.py
   

   HTTP mode:

   python server.py --transport http
   

---

getting your telebotstudio api credentials

The bot management tools require two pieces of information: an API Key and a Bot ID. Here's how to get both.

1. create a telebotstudio account

If you don't have one yet, sign up at:

telebotstudio.com

An account is required because the API tools communicate with the TeleBot Studio REST API on your behalf. Your API key authenticates every request.

2. get your api key

After logging in:

1. Open the top-left menu (☰)
2. Go to Settings
3. Scroll to API Access
4. Copy your API Key

• Your API key is a secret. Never commit it to git, never share it publicly, never hardcode it in your source.
• It is only needed at runtime. This MCP server stores it in memory only — never written to disk, never logged in cleartext, and lost when the server restarts.
• If your key is compromised, you can regenerate it from the same Settings page.

3. create your bot

If you don't already have a bot on TeleBot Studio:

1. Create a Telegram bot using @BotFather on Telegram
2. Copy the Bot Token that BotFather gives you
3. Open TeleBot Studio and create a new bot using that token

Alternatively, you can create a bot directly through the MCP tool tbs_create_bot by passing the Bot Token.

4. get your bot id

After creating the bot:

1. Open the top-left menu (☰)
2. Go to My Bots
3. Select your bot
4. Open Bot Settings
5. Copy the Bot ID

The Bot ID is required for almost every REST API operation — listing commands, creating commands, starting and stopping the bot, etc. Once you have it, pass it to tbs_set_bot_id so the server remembers it for the rest of your session.

---

connecting to ai clients

Once the server is installed, you need to tell your AI client how to reach it. The exact steps depend on which client you're using.

Every client needs to know two things: the command to start the server (for STDIO mode) or the URL where the server is running (for HTTP mode). If you're running the server locally, use STDIO. If you've deployed it to Render, use HTTP.

claude desktop

1. Open Claude Desktop

2. Go to Settings → Developer

3. Click Edit Config

4. This opens a claude_desktop_config.json file. Add the server:

   Local server (STDIO):

   {
     "mcpServers": {
       "telebotstudio": {
         "command": "python",
         "args": ["/absolute/path/to/telebotstudio-mcp/server.py"]
       }
     }
   }
   

   Replace /absolute/path/to/ with the actual path to where you cloned the repository. On Windows, use the full path like C:/Users/you/telebotstudio-mcp/server.py.

   Render server (HTTP):

   {
     "mcpServers": {
       "telebotstudio": {
         "url": "https://your-app.onrender.com/mcp"
       }
     }
   }
   

5. Save the file and restart Claude Desktop

6. Start a new conversation and look for the tools icon (🔧) — it should show the 26 TeleBot Studio tools

Common mistakes:

• Using a relative path instead of an absolute one — Claude Desktop needs the full path
• Forgetting to restart Claude Desktop after editing the config
• On Windows, using backslashes in the JSON — use forward slashes instead

cursor

1. Open Cursor

2. Go to Settings → Features → MCP

3. Click Add new MCP server

4. Fill in the details:

   Local server (STDIO):

   • Name: telebotstudio
   • Type: stdio
   • Command: python
   • Args: /absolute/path/to/telebotstudio-mcp/server.py

   Render server (HTTP):

   • Name: telebotstudio
   • Type: sse or streamable-http
   • URL: https://your-app.onrender.com/mcp

5. Save and wait for the tools to appear in the MCP panel

windsurf

1. Open Windsurf

2. Go to Settings → MCP Servers

3. Click Add Server

4. Fill in the details:

   Local server (STDIO):

   • Name: telebotstudio
   • Command: python
   • Args: /absolute/path/to/telebotstudio-mcp/server.py

   Render server (HTTP):

   • Name: telebotstudio
   • URL: https://your-app.onrender.com/mcp

5. Save and restart Windsurf if the tools don't appear immediately

chatgpt

1. Open ChatGPT

2. Go to Settings → Connectors or MCP Servers

3. Click Add connector

4. Enter the server URL:

   Render server (HTTP):

   • URL: https://your-app.onrender.com/mcp

   ChatGPT currently supports HTTP-based MCP connections. If you're running locally, you'll need to deploy the server to Render or another host first.

5. Save and start a new conversation to verify the tools are available

Common mistake:

• Trying to use a localhost URL — ChatGPT can't reach your local machine. Use a publicly deployed server instead.

visual studio code

1. Install an MCP extension for VS Code (such as the official MCP extension or a community one)

2. Open VS Code settings

3. Find the MCP configuration section

4. Add the server:

   Local server (STDIO):

   {
     "mcp": {
       "servers": {
         "telebotstudio": {
           "command": "python",
           "args": ["/absolute/path/to/telebotstudio-mcp/server.py"]
         }
       }
     }
   }
   

   Render server (HTTP):

   {
     "mcp": {
       "servers": {
         "telebotstudio": {
           "url": "https://your-app.onrender.com/mcp"
         }
       }
     }
   }
   

5. Reload VS Code to apply the changes

continue

1. Open Continue settings — click the gear icon in the Continue panel

2. Find the MCP Servers section

3. Add a new server:

   Local server (STDIO):

   {
     "mcpServers": {
       "telebotstudio": {
         "command": "python",
         "args": ["/absolute/path/to/telebotstudio-mcp/server.py"]
       }
     }
   }
   

   Render server (HTTP):

   {
     "mcpServers": {
       "telebotstudio": {
         "url": "https://your-app.onrender.com/mcp"
       }
     }
   }
   

4. Save and restart Continue

cline

1. Open the Cline panel in your editor

2. Click the MCP Servers icon

3. Click Add server

4. Fill in the details:

   Local server (STDIO):

   • Name: telebotstudio
   • Command: python
   • Args: /absolute/path/to/telebotstudio-mcp/server.py

   Render server (HTTP):

   • Name: telebotstudio
   • URL: https://your-app.onrender.com/mcp

5. Save and verify the tools appear

verifying the connection

After adding the server to your client, check that it's working:

1. Start a new conversation
2. Ask something like "search for broadcast in the TeleBot Studio docs"
3. If the AI can call search_docs, the connection is working
4. You can also ask "list all available documentation pages" — it should call list_pages and return the page names

If the AI doesn't use the MCP tools, check the troubleshooting section below.

---

first chat

After connecting the MCP, start every new conversation with a prompt like this:

You are connected to the TeleBot Studio MCP.

Always prefer the connected MCP instead of web search whenever the requested information exists inside the TeleBot Studio documentation.

Before answering:
1. search the documentation using the MCP.
2. use the relevant documentation pages.
3. if bot management is required, use the API tools.
4. never invent undocumented functions.
5. if something is not documented, explicitly say so.
6. only use web search when the MCP cannot answer.

Why this helps: by default, many AI clients prefer web search over MCP tools, or they answer from training data without checking the connected tools at all. A prompt like this tells the AI to check the documentation first, use the API tools when needed, and be honest when something isn't covered. It dramatically reduces hallucinated functions and outdated information.

You don't need to paste this every time if your client supports custom instructions or system prompts — add it there once and it applies to every conversation.

---

example conversations

These examples show how the AI uses the MCP tools in a real conversation.

example 1: documentation query

you: how do broadcasts work?

↓ AI calls search_docs("broadcast")

↓ AI receives the relevant documentation chunks

↓ AI reads the chunks and answers using the official docs

ai: Broadcasts in TeleBot Studio let you send messages to all your bot subscribers at once. Here's how it works based on the documentation: [answer drawn from the actual docs, not guessed]

example 2: creating a command

you: create a /start command that sends a welcome message

↓ AI calls tbs_set_api_key (if not already set)

↓ AI calls tbs_set_bot_id (if not already set)

↓ AI calls tbs_create_command(command="/start", code="...")

↓ API returns success

ai: The /start command has been created on your bot. It will send a welcome message when users start the bot.

example 3: restarting a bot

you: restart my bot

↓ AI calls tbs_restart_bot(bot_id="...")

↓ API returns success

ai: Your bot has been restarted. The webhook has been removed and re-set.

example 4: searching documentation broadly

you: find every page mentioning variables

↓ AI calls search_docs("variables")

↓ AI receives matching chunks across multiple pages

ai: Here are the documentation pages that mention variables: [lists the pages with relevant sections]

---

ai in action

Screenshots from actual MCP usage — no mock data, no staging.

chatgpt

Connection established — all 26 MCP tools available

Grounded response — answer sourced from the docs, not training data

claude desktop

Tool call — Claude queries the TeleBot Studio documentation engine

Grounded response — accurate answer from the documentation

---

MCP tools (26)

documentation search (8)

tool	what it does
search_docs(query, top_k)	Primary search. Full-text BM25 across all chunks.
get_page(name)	Retrieve an entire documentation page by filename.
list_pages()	List all available documentation pages.
search_examples(query, top_k)	Scoped search for code examples and snippets.
search_api(query, top_k)	Scoped search for API references and endpoints.
search_library(query, top_k)	Scoped search for library and dependency info.
search_functions(query, top_k)	Scoped search for function definitions and signatures.
search_errors(query, top_k)	Scoped search for errors and troubleshooting.

credentials (3)

tool	what it does
tbs_set_api_key(api_key)	Set your API key (memory-only, never persisted).
tbs_set_bot_id(bot_id)	Set the active Bot ID for the session.
tbs_credential_status()	Check if credentials are set (key is masked).

bot management (3)

tool	what it does
tbs_create_bot(bot_token)	Create a new bot with a Telegram bot token. Auto-sets the Bot ID.
tbs_delete_bot(bot_id, confirm)	Soft-delete a bot. Set confirm=true to execute; defaults to preview-only.
tbs_update_bot_token(bot_id, new_token, confirm)	Update a bot's token (triggers a restart). Preview-supported.

command management (5)

tool	what it does
tbs_create_command(command, code, bot_id)	Create a new command on a bot.
tbs_get_command(command_name, bot_id)	Get command details by name.
tbs_update_command(command_name, code, bot_id, confirm)	Update a command's code. Preview-supported.
tbs_delete_command(command_name, bot_id, confirm)	Delete a command. Preview-supported.
tbs_list_commands(bot_id)	List all commands for a bot.

bot control (3)

tool	what it does
tbs_start_bot(bot_id)	Start a bot (set webhook).
tbs_stop_bot(bot_id)	Stop a bot (remove webhook).
tbs_restart_bot(bot_id)	Restart a bot (stop + start).

agent tools (2)

tool	what it does
tbs_deploy_bot(bot_token, commands_json, confirm)	Complete deployment: create bot → add commands → start.
tbs_setup_commands(commands_json, bot_id, confirm)	Bulk create commands on an existing bot.

batch tools (2)

tool	what it does
tbs_batch_create_commands(commands_json, bot_id, confirm)	Create multiple commands in sequence.
tbs_batch_delete_commands(command_names_json, bot_id, confirm)	Delete multiple commands in sequence. Preview-supported.

---

architecture

two-engine design

The server runs two independent engines side by side, connected through the FastMCP framework:

┌─────────────────────────────────────────────────────┐
│                   FastMCP Server                     │
│                                                      │
│  ┌──────────────────┐   ┌──────────────────────────┐ │
│  │  documentation    │   │  bot management          │ │
│  │  engine (BM25)    │   │  engine (REST API v2)    │ │
│  │                   │   │                          │ │
│  │  8 search tools   │   │  Planner → Validator     │ │
│  │  100% offline     │   │  → Preview → Executor    │ │
│  │  in-memory index  │   │  18 API tools            │ │
│  └──────────────────┘   └──────────────────────────┘ │
│                                                      │
│  ┌────────────────────────────────────────────────┐   │
│  │  session manager (thread-safe, memory-only)    │   │
│  └────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
        │                              │
   STDIO / HTTP              HTTPS → api.telebotstudio.com

agent pipeline

Agent tools (tbs_deploy_bot, tbs_setup_commands, batch operations) decompose complex goals into executable plans:

user goal  →  Planner (decompose into steps)
            →  Validator (check credentials, params)
            →  Preview (show what will happen, mask secrets)
            →  [confirm=true]  →  Executor (run steps sequentially)
                              →  BatchResult (per-step success/failure)

• Planner takes a high-level goal and breaks it into ordered steps.
• Validator checks that credentials are set and parameters are valid. If the API key is missing, it stops here.
• Preview generates a human-readable description of every step, masks sensitive values, and tells you whether confirmation is required. Nothing executes at this stage.
• Executor runs the steps one by one. If a step fails, it records the failure and continues. The final result reports per-step success and failure.

preview & confirmation

Destructive operations — deleting a bot, deleting a command, updating a bot token — require confirm=true. When confirm is false or omitted, the tool returns a preview: a description of what will happen, without executing anything.

This two-step pattern exists because AI assistants can misinterpret intent. "Remove the test bot" shouldn't accidentally delete a production bot. The preview gives you a chance to verify before anything irreversible happens.

documentation engine internals

1. Loading — MarkdownLoader reads every .md file in docs/ recursively (including subdirectories like docs/patterns/) and splits each file into chunks at heading boundaries (H1, H2, H3). It never splits mid-paragraph or mid-code-block.
2. Tokenization — each chunk is tokenized into lowercase unigrams and bigrams. send_message becomes send, message, and send_message, which helps match multi-word API names.
3. Indexing — tokens are fed into BM25Okapi, which computes term frequencies and document lengths for ranking.
4. Searching — queries are tokenized the same way, and BM25 scores every chunk. The top-k results are returned with their scores.
5. Caching — results are cached in an LRU cache (256 entries) so repeated queries return instantly.

api engine internals

1. Authentication — your API key is stored in the session manager. Every outgoing request gets an Authorization: Bearer <key> header.
2. Request — TeleBotStudioClient sends the request using httpx with a 30-second timeout.
3. Retry — on 5xx or timeout, the client retries up to 3 times with exponential backoff (1s, 2s, 4s). It does not retry 4xx errors.
4. Error mapping — HTTP status codes are mapped to typed exceptions: 401 → AuthenticationError, 404 → ResourceNotFoundError, 400 → ValidationError, 429 → RateLimitError, 5xx → ServerError.
5. Response — parsed into an ApiResponse object with the result, status code, and rate-limit headers.

---

project structure

telebotstudio-mcp/
├── server.py              entry point — FastMCP server, doc tools, /health
├── loader.py              markdown loader & heading-aware chunking
├── search.py              BM25 index builder & search engine
├── build_index.py         CLI diagnostic tool
├── crawler.py             documentation crawler
├── download_docs.py       documentation downloader
├── api/
│   ├── __init__.py        public API exports
│   ├── auth.py            input validation (API key, bot token, command names)
│   ├── client.py          HTTP client with retry, timeout, error mapping
│   ├── errors.py          typed exception hierarchy
│   ├── models.py          request/response dataclasses
│   ├── session.py         thread-safe credential manager
│   ├── bots.py            bot management wrapper
│   ├── commands.py        command management wrapper
│   ├── bot_control.py     start / stop / restart wrapper
│   └── utils.py           shared utilities (token masking)
├── agent/
│   ├── __init__.py        agent layer exports
│   ├── planner.py         decompose goals into execution plans
│   ├── validator.py       validate plans against session state
│   ├── preview.py         generate human-readable plan previews
│   └── executor.py        execute plans with rate-limit awareness
├── tools/
│   ├── __init__.py
│   ├── api_tools.py       core API MCP tools
│   ├── agent_tools.py     deploy & setup MCP tools
│   ├── batch_tools.py     batch operation MCP tools
│   ├── bot_tools.py       bot management MCP tools
│   ├── command_tools.py   command management MCP tools
│   ├── control_tools.py   bot control MCP tools
│   ├── credential_tools.py credential MCP tools
│   └── helpers.py         shared tool utilities
├── tests/                 pytest suite (244 tests)
<<<<<<< HEAD
├── docs/                  official TeleBot Studio documentation (.md)
=======
├── docs/
│   ├── *.md               official TeleBot Studio documentation
│   └── patterns/           implementation pattern knowledge base
│       ├── README.md       pattern index and standards
│       ├── TEMPLATE.md     standard pattern template
│       ├── ui/             user-facing interaction patterns
│       ├── admin/          bot owner tool patterns
│       ├── systems/        core infrastructure patterns
│       ├── commerce/       payment & referral patterns
│       ├── storage/        data persistence patterns
│       ├── integrations/   external service patterns
│       └── utilities/      reusable helper patterns
>>>>>>> c15d897 (docs: synchronize README and project metadata)
├── Dockerfile             container definition
├── .dockerignore          Docker build exclusions
├── requirements.txt       Python dependencies
├── LICENSE                MIT License
└── README.md              this file

---

configuration

transport modes

STDIO — default, for local AI clients:

python server.py

The server communicates with the AI client through standard input and output. This is the mode you use with Claude Desktop, Cursor, and other local editors.

HTTP / streamable-http — for remote clients and deployment:

python server.py --transport http --host 0.0.0.0 --port 9000

The server listens for HTTP requests and speaks the MCP protocol over streamable-http. This is the mode you use for Render deployment or any remote client.

environment variables

variable	default	purpose
TBS_DOCS_DIR	docs	override the documentation directory
HOST	0.0.0.0	default host for HTTP mode
PORT	8000	default port for HTTP mode (Render sets this automatically)

---

deployment

local deployment

Running the server on your own machine is the simplest option. It works well for personal use with local AI clients.

STDIO mode (recommended for local use):

python server.py

No port or host configuration needed. The AI client starts and stops the server automatically through the MCP protocol.

HTTP mode (for local testing or LAN access):

python server.py --transport http --host 127.0.0.1 --port 8000

The MCP endpoint is at http://127.0.0.1:8000/mcp and the health check is at http://127.0.0.1:8000/health.

Use 0.0.0.0 as the host if you want other machines on your network to reach the server.

render deployment

Deploying to Render lets you use the server from any HTTP-based client without running anything locally.

1. Create a Render account at render.com

2. Create a new Web Service

   • Click New + → Web Service
   • Connect your GitHub repository (or fork this one)

3. Configure the build

   • Build Command: pip install -r requirements.txt
   • Start Command: python server.py --transport http
   • Environment: Python 3

4. Set environment variables (optional)

   • No custom env vars are required — Render provides PORT automatically

5. Deploy

   • Click Create Web Service
   • Render builds and starts the server
   • Once live, your MCP endpoint is at https://your-app.onrender.com/mcp
   • The health check is at https://your-app.onrender.com/health

6. Configure your AI client

   • Use the Render URL as the server address in your client's MCP settings
   • Select sse or streamable-http as the transport

Notes on Render:

• Free-tier services spin down after 15 minutes of inactivity. The first request after a cold start takes a few seconds.
• You can use UptimeRobot to ping /health periodically and keep the service awake.
• Credentials are lost when the service restarts — this is by design.

docker

docker build -t telebotstudio-mcp .
docker run -p 8000:8000 telebotstudio-mcp

The MCP endpoint is at http://localhost:8000/mcp and the health check is at http://localhost:8000/health.

The Dockerfile does not hardcode a port — it reads the PORT environment variable, so you can override it:

docker run -p 9000:9000 -e PORT=9000 telebotstudio-mcp

health check

GET /health returns {"status": "ok"}. This endpoint lives outside the MCP protocol and requires no authentication. Suitable for UptimeRobot, Render health checks, or any uptime monitor.

---

live api validation

Every REST API endpoint in this project was verified against the live TeleBot Studio API. Where the official documentation diverged from actual API behavior, the implementation follows the live API — not the docs.

Known discrepancies that were identified and handled:

• The documented GET method for /command/by-name returns 405 — the live API accepts POST with a JSON body
• The documented GET /bots/{botid}/commands endpoint is used for creating commands — the actual list endpoint is GET /bots/{botid}/commands/list

These are reflected in the code and tested against production.

---

security & privacy

how credentials are stored

When you call tbs_set_api_key or tbs_set_bot_id, the values are stored in a Python class called CredentialManager. This class holds credentials in regular Python variables — nothing is written to the filesystem, nothing goes into a database, nothing appears in log files.

• STDIO mode (single user): credentials are stored as class-level variables. There's only one session, so one set of credentials.
• HTTP mode (potentially multi-user): credentials are stored in a per-session dictionary, keyed by a session ID stored in thread-local storage. Each thread (each HTTP request) can have its own session with its own credentials.

All access to the credential store is protected by a threading.Lock, so concurrent requests can't corrupt each other's data.

session-based storage

Credentials are tied to the lifetime of the server process. As long as the server is running, your API key and Bot ID remain available. When the server stops — whether you kill it, it crashes, or the hosting platform restarts it — the credentials are gone. Python variables exist in the process's memory, and the operating system reclaims that memory on exit. There is no mechanism to persist credentials across restarts, and that's by design — it prevents secrets from lingering on disk or in swap space.

If you need credentials to survive restarts, that's the responsibility of your AI client, not the MCP server. Some clients can be configured to re-send credentials automatically at the start of each session.

other security details

• no telemetry — zero analytics, tracking, or phone-home
• token masking — bot tokens and API keys are masked in all log messages and preview responses (e.g. tbs_1...xyz)
• preview before destructive — delete and update operations require explicit confirm=true. Default is preview-only
• input validation — all inputs are validated before API calls (token format, bot ID format, command name length, code length)
• thread-safe sessions — credential manager uses thread-local storage and locks for HTTP transport safety
• offline docs — documentation search works without any network connection. API tools require internet to reach api.telebotstudio.com

---

troubleshooting

mcp not being used

The AI answers from its training data instead of calling the MCP tools.

Why it happens: Most AI clients default to answering from training data. They don't automatically prefer MCP tools unless you tell them to.

How to fix:

• Add the recommended system prompt from the first chat section
• Explicitly ask the AI to use the MCP: "search the TeleBot Studio docs for..."
• Check that the server is connected in your client's MCP settings

ai prefers web search

The AI does a web search instead of using the MCP documentation tools.

Why it happens: Some clients prioritize web search results over MCP tool calls, especially for informational queries.

How to fix:

• Use the system prompt from first chat — it explicitly tells the AI to prefer MCP over web search
• Rephrase your question to be more specific: "use the MCP to search the TeleBot Studio documentation for..."

invalid api key

The AI returns an AuthenticationError when trying to use API tools.

Why it happens: The API key is missing, incorrect, or has been regenerated on the TeleBot Studio dashboard.

How to fix:

• Call tbs_credential_status to check if an API key is set
• Call tbs_set_api_key with the correct key from your TeleBot Studio Settings → API Access page
• If you recently regenerated your key, make sure you're using the new one

invalid bot id

The AI returns a ValidationError or ResourceNotFoundError mentioning the bot ID.

Why it happens: The bot ID doesn't exist, doesn't belong to your account, or isn't a number.

How to fix:

• Verify the bot ID in TeleBot Studio: ☰ → My Bots → select bot → Bot Settings
• Call tbs_set_bot_id with the correct numeric ID
• Make sure you're using the Bot ID (a number), not the bot username

render sleeping

Your Render-hosted server takes a long time to respond on the first request.

Why it happens: Render's free tier puts services to sleep after 15 minutes of inactivity. The first request after a cold start needs to wait for the service to boot.

How to fix:

• Use UptimeRobot to ping https://your-app.onrender.com/health every 5 minutes
• This keeps the service awake and avoids cold starts
• Alternatively, upgrade to a paid Render plan that doesn't spin down

connection refused

The AI client can't connect to the server.

Why it happens: The server isn't running, or it's running on a different host/port than the client expects.

How to fix:

• Make sure the server is running: python server.py for STDIO, python server.py --transport http for HTTP
• For HTTP mode, verify the host and port match your client's configuration
• Check that no firewall is blocking the connection
• If using Render, make sure the service is deployed and the URL is correct

http 401

API calls return a 401 Unauthorized error.

Why it happens: The API key is invalid, expired, or not set.

How to fix:

• Call tbs_set_api_key with a valid key
• If the key was working before, it may have been regenerated — check the TeleBot Studio dashboard

http 404

API calls return a 404 Not Found error.

Why it happens: The bot ID doesn't exist or doesn't belong to your account.

How to fix:

• Verify the bot ID in the TeleBot Studio dashboard
• Make sure you're using the correct bot ID — it's a numeric string, not the bot username

timeout

API calls take too long and time out.

Why it happens: The TeleBot Studio API is slow to respond, or your internet connection is unstable. The default timeout is 30 seconds.

How to fix:

• Retry the request — transient timeouts can happen
• If the problem persists, check your internet connection
• Check the TeleBot Studio status page for any ongoing incidents

server offline

The server isn't responding at all.

Why it happens: The process crashed or was never started.

How to fix:

• For local deployment: check that python server.py is still running
• For Render: check the Render dashboard for deployment status and logs
• Use the /health endpoint to verify: curl https://your-app.onrender.com/health

documentation not found

Search queries return "No matching documentation found" for topics that should exist.

Why it happens: The search query doesn't match the way the documentation is written, or the docs/ directory is empty.

How to fix:

• Try different search terms — use the exact function name or keyword from the docs
• Call list_pages to see what documentation pages are available
• Call get_page with a specific page name to retrieve it directly
• If no pages are listed, check that the docs/ directory contains .md files

---

best practices

• keep api keys private. Never commit them to git, never paste them in chat, never hardcode them. Use tbs_set_api_key at runtime.
• never commit secrets. Add any config files containing keys to .gitignore. This server stores nothing on disk, but your AI client might.
• use preview before destructive actions. When the AI wants to delete a bot or update a token, let it run with confirm=false first. Read the preview, then confirm.
• validate generated code. When the AI creates a command using tbs_create_command, review the code before deploying. AI-generated code can have bugs.
• keep documentation updated. If TeleBot Studio adds new features, pull the latest docs into the docs/ directory and restart the server. The index rebuilds automatically.
• regenerate compromised api keys. If you suspect your key was leaked, regenerate it immediately in TeleBot Studio Settings → API Access. The old key stops working right away.

---

design decisions

why BM25 instead of vector embeddings?

For a technical documentation corpus, users search for exact function names, error codes, and class properties. BM25 mathematically outperforms semantic embeddings for exact-lexicon matching at this scale — with zero cost, zero latency, and zero external dependencies.

why session-scoped credentials instead of persistent config?

Storing API keys in config files is a security risk — they could be committed to git, leaked in logs, or accessed by other processes. Session-scoped memory-only credentials are lost on restart, which is intentional: it forces re-authentication and prevents stale credentials from persisting.

why preview & confirmation for destructive ops?

AI assistants can misinterpret user intent. A user saying "remove the test bot" shouldn't accidentally delete a production bot. The two-step preview → confirm pattern gives the user a chance to verify before irreversible actions.

why sync HTTP client instead of async?

FastMCP tool handlers can be sync or async. We use sync httpx.Client for simplicity and reliability. The retry sleep logic is async-aware (uses run_in_executor) to avoid blocking the event loop under HTTP transport.

---

faq

does the documentation search work offline?

Yes. Once installed, the BM25 index and documentation are entirely local. The API tools require internet to reach api.telebotstudio.com, but the documentation tools work without any network connection.

can i deploy this on render / railway?

Yes. Run python server.py --transport http and the server reads the PORT environment variable automatically. See the deployment section for step-by-step Render instructions.

is my api key safe?

Your API key is stored in server memory only — never written to disk, never logged in cleartext. It is transmitted over HTTPS to api.telebotstudio.com and is lost when the server restarts.

For multi-user HTTP deployments, note that FastMCP's streamable-http transport does not currently expose a per-client session identifier. All HTTP clients share a global credential store. This is fine for single-user deployments but not for multi-tenant environments.

what happens if a batch operation partially fails?

The executor runs each step independently. If step 3 of 5 fails, steps 4 and 5 still execute. The BatchResult reports per-step success/failure so you can see exactly what happened and which steps need retrying.

which API endpoints are supported?

All 11 endpoints from the TeleBot Studio REST API v2:

method	endpoint	purpose
POST	/v2/create-bot	Create a new bot
DELETE	/v2/bots/{botid}	Delete a bot
POST	/v2/bots/{botid}/update-bot-token	Update a bot's token
POST	/v2/bots/{botid}/commands	Create a command
POST	/v2/bots/{botid}/command/by-name	Get a command by name
POST	/v2/bots/{botid}/command/by-name/update	Update a command
POST	/v2/bots/{botid}/command/by-name/delete	Delete a command
GET	/v2/bots/{botid}/commands/list	List all commands
POST	/v2/bots/{botid}/start	Start a bot
POST	/v2/bots/{botid}/stop	Stop a bot
POST	/v2/bots/{botid}/restart	Restart a bot

---

development

adding a new API endpoint

The architecture is designed for extensibility:

1. Add request/response models in api/models.py
2. Add a method to the appropriate manager (api/bots.py, api/commands.py, or api/bot_control.py)
3. Add a tool function in the appropriate tools/ module with the @mcp.tool decorator
4. If it's destructive, add a confirm parameter with preview support
5. If it's a multi-step operation, add a planner method in agent/planner.py

adding documentation

1. Drop .md files into the docs/ directory (subdirectories are scanned recursively)
2. Restart the server — the BM25 index rebuilds automatically

coding style

PEP 8 with type hints. from __future__ import annotations in every file. Keep functions pure where possible.

---

roadmap

current (v2.1.0)

• 8 documentation search tools (BM25)
• 18 bot management API tools
• Session-scoped credential manager
• Agent pipeline (Planner → Validator → Preview → Executor)
• Preview & confirmation for destructive operations
• Batch operations with per-step error reporting
• Thread-safe credential storage
• Async-aware retry logic
• Docker + Render deployment
• /health endpoint
• Live API validation against production
• GitHub Actions CI/CD pipeline
• Pytest test suite (244 tests)
• Ruff + mypy linting (zero issues)

next

• Connection pooling for API calls
• FastMCP session middleware for per-client credential isolation
• Exact phrase match boosting for search
• Heading hierarchy boosting (H1 > H3)

future

• Abstract into a generic documentation MCP framework

---

changelog

v2.1.0

• Split tools/api_tools.py into modular files (agent_tools, batch_tools, bot_tools, command_tools, control_tools, credential_tools, helpers)
• GitHub Actions CI/CD pipeline
• Pytest test suite (244 tests)
• Ruff + mypy compliance (zero issues)
• Thread-safe LRUCache counters and session copy semantics
• Async-aware rate-limit pause in executor
• Bot token regex widened for test environments
• .dockerignore rewritten for correct Docker builds
• Open source maturity files (SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, issue/PR templates, Dependabot)

v2.0.0

• 18 TeleBot Studio API management tools
• Session-scoped, thread-safe credential manager
• Agent pipeline with Planner → Validator → Preview → Executor
• Preview & confirmation for destructive operations
• Batch command create/delete
• Async-aware retry with exponential backoff
• Token masking in logs and responses
• Live API validation against production endpoints

v0.1.0

• 8 documentation search tools
• BM25 ranking with unigram + bigram tokenization
• LRU caching, input validation, path traversal prevention
• STDIO and HTTP/streamable-http transports
• Docker support, /health endpoint

---

community

Meet us on Telegram Made by solo dev yori

---

contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make sure your code passes basic linting
4. Write a clear, descriptive commit message
5. Open a Pull Request against main

---

credits

• FastMCP — Python framework for building MCP servers
• rank-bm25 — Pure Python BM25 implementation
• TeleBot Studio — The platform and documentation
• Model Context Protocol — Anthropic's standard for AI tool integration

---