Bedolaga MCP Server

MCP サーバーは、Bedolaga Bot から Telegram ID または内部 user_id でユーザーファクトを取得します。

サーバーは read-only です。Bedolaga MCP を介して、残高の変更、サブスクリプションの作成や延長、プロモコードの適用、返金の処理、紹介資金の引き出し、その他ユーザーに代わっての操作はできません。

破壊的移行 (1.0.0)

バージョン 1.0.0 以降、ツールの公開コントラクトが変更され、古い名前は削除されました。クライアントの設定を更新してください:

また、1.0.0 では非推奨の HTTP パス /mcp が削除されました。sessionful Streamable HTTP は、mcp-remnawave と同様にルートエンドポイント / で提供されるようになりました。イメージの各公開には、:latest、:{version}、:{sha} の3つのタグが付与されます。

バージョン 1.0.0 は、正しい API ルート、構造化された結果、Remnawave との明確な責任境界を備えた最初のコントラクトです。

Related MCP server: Monobank MCP Server

ツール

サーバーは、MCP プロトコルを介して利用できるちょうど8つのツールを提供します。すべてのツールは readonly であり、データは変更されません。

アイデンティティのコントラクト

各ツールは、次の2つのフィールドのうちちょうど1つを受け取ります:

• telegram_id — 整数、ユーザーの Telegram ID（正の値）;

• user_id — 整数、Bedolaga 内のユーザー内部 ID（正の値）。メール専用のキャビネットチケットに使用されます。

フィールドが1つも渡されない場合、または両方が渡された場合、ツールは invalid_input エラーを返します。アイデンティティはモデルから取得されることはありません。supportBot は常に実際の送信者を特定します。認証された Telegram update からの正の telegram_id、または email-only チケットの場合はキャビネットの内部 user_id です。

bedolaga_user_get

現在の Bedolaga ユーザーのアカウントと残高を取得します。

パラメータ:

レスポンスの JSON フィールド（data）:

promo_group フィールドには、name、server_discount_percent、traffic_discount_percent、device_discount_percent のみが含まれます。

解釈の例（合成データ）: balance_kopeks: 350000 と balance_rubles: 3500.0 は、残高 3,500 ルーブルを意味します。has_had_paid_subscription: false は、有料購入がまだないことを意味します。

bedolaga_billing_get

1回の呼び出しで、残高、最近の金融イベント、Bedolaga の内部購入記録を表示し、入金と購入を区別します。

パラメータ:

レスポンスの JSON フィールド（data）:

transactions 内の各操作:

bot_subscriptions 内の各レコードには、id、bot_record_status、bot_record_effective_status、is_trial、tariff_id、tariff_name、start_date、end_date、autopay_enabled、autopay_days_before、および固定の note が含まれます。サーバーは完全なアップストリームリスト subscriptions を優先し、id で重複レコードを削除し、単一のレガシーフィールド subscription へのフォールバックを保持します。このフィールドが bot_record_status という名前なのは意図的です。これは Bedolaga の内部レコードであり、VPN パネルのステータスではありません。bot_record_effective_status もボット側の実効ステータス（status と end_date からボットが計算したもの）であり、パネルの状態ではありません。

解釈の例（合成データ）: latest_completed_deposit: {amount_kopeks: 350000} と purchased_after_latest_deposit: false は、入金が残高に計上されたが、入金後の個別の購入は完了していないことを意味します。

bedolaga_referrals_get

現在のユーザーの紹介サマリーを取得します。

パラメータ:

レスポンスの JSON フィールド（data）:

返されるのはアカウント所有者のみの統計です。招待されたユーザーの Telegram ID、内部 ID、username、名前、残高、アクティビティは決して返されません。

bedolaga_subscription_get

Bot 側のサブスクリプション記録とライフサイクル日付（created_at、start_date、end_date、is_trial、autopay_enabled）を取得します。

パラメータ: telegram_id または user_id（いずれか1つのみ）。

has_subscription_records、active_record_count、subscriptions リスト、固定の meta を返します。bot_record_status フィールドは Bot の内部記録であり、VPN パネルのステータスではありません（実際の状態は Remnawave MCP で確認します）。

bedolaga_tickets_get

自分のサポートチケットの概要（id、title、status、priority、作成/更新/クローズ日時）を、メッセージ本文やメディアなしで取得します。

パラメータ: telegram_id または user_id（いずれか1つのみ）、limit（デフォルト10、最大50）。

bedolaga_payment_status_get

Bot の会計システムにおける金融取引履歴と完了ステータス（completed / not_completed / unknown）を取得します。

パラメータ: telegram_id または user_id（いずれか1つのみ）、limit（デフォルト5、最大20）。

not_completed ステータスは、Bot の課金処理で取引が完了していないことを意味するだけで、支払いゲートウェイ側の障害や待機を意味するものではありません。

bedolaga_promocode_check

プロモコードのグローバル定義、有効期限、アクティブ状態、ボーナス、残り利用回数を確認します。

パラメータ: code（必須）、telegram_id または user_id（いずれか1つのみ、ID 固定用）。

マスクされたコード（code_masked）、globally_valid フラグ、reason_code（not_found、inactive、not_yet_valid、expired_or_exhausted、lookup_incomplete）、および user_eligibility: "unknown" を返します。

bedolaga_gifts_get

アカウント所有者のギフト購入履歴を取得します。

パラメータ: telegram_id または user_id（いずれか1つのみ）、limit（デフォルト20、最大50）。

ギフトの購入事実（会計）のみを表示します。ギフトトークン、受取人、アクティベーションステータスは開示されません。

判定テーブル

LLM（supportBot）がシナリオに応じて Bedolaga と Remnawave のデータをどう使うか:

結果の形式

各ツールは、共通ラッパー付きのテキスト MCP content 内の JSON を返します:

• 成功: ok: true、source: "bedolaga-mcp"、tool、data、meta;

• エラー: ok: false、source、tool、error.code、安全な error.message、error.retryable。

Bedolaga API の生のレスポンスボディや Python モデルの例外は返されません。ツールは email、サブスクリプションリンク、crypto link、キー、外部決済 ID、receipt 識別子、Remnawave 識別子、紹介者の個人データを返しません。

エラーコード

ユーザー向けメッセージは安全な error.message のみから構築され、HTTP ボディや内部 URL を決して開示しません。

トランスポート

サーバーは、単一の server factory と単一のツールレジストリ上で2つのトランスポートをサポートします:

エンドポイント / は1つだけですが、2つのプロトコルエラを同時に処理します。SDK v2 は各リクエストがどのエラに属するかを MCP-Protocol-Version ヘッダーで自動判定します:

• 最新プロトコル 2026-07-28 — stateless/sessionless。/ への各 POST は自己完結型で、サーバーは Mcp-Session-Id を発行せず、リクエスト間で状態を保持しません。公式 MCP SDK v2 クライアント（下記「公式 SDK v2 クライアント」参照）はこのモードを自動的に使用します。

• initialize-handshake を使用する legacy クライアント（2024-11-05 を含む 2025-11-25 までのプロトコル）は、initialize への応答で Mcp-Session-Id ヘッダーを受け取り、以降のすべてのリクエストでそれを渡す必要があります。このヘッダー付きの DELETE / はそのセッションのみを終了します。他のセッションや最新クライアントには影響しません。

GET /health はプロセスの liveness とサーバーバージョンを返し、設定やシークレットは開示しません。

バージョン互換性

ツール契約は、指定された upstream コミットおよび mcp-remnawave v3.2.1 のリファレンスに対して検証済みです。

要件

• Python 3.11+

• Docker（オプション）

• Web API 付きの Bedolaga Bot がデプロイされていること

• Bedolaga の API キー（Bot の管理パネルで発行）

クイックスタート

1. クローン

git clone https://github.com/mitetenov/bedolaga-mcp.git
cd bedolaga-mcp

2. 設定

cp .env.example .env
# Заполнить BEDOLAGA_API_URL и BEDOLAGA_API_KEY

3. 起動

Streamable HTTP（推奨）:

# Установить зависимости
pip install -r requirements.txt

# Запустить HTTP-сервер
BEDOLAGA_API_URL=https://your-bot.example.com \
BEDOLAGA_API_KEY=your-key \
python3 http_server.py

サーバーは http://0.0.0.0:3100 で待ち受け、MCP endpoint はルート / です。

Stdio:

BEDOLAGA_API_URL=https://your-bot.example.com \
BEDOLAGA_API_KEY=your-key \
python3 bedolaga_server.py

Docker 経由:

docker compose up -d

Docker イメージはデフォルトでポート3100の Streamable HTTP サーバーを起動します。

MCP サーバーとしての接続

Streamable HTTP

サーバーは HTTP ポート3100で利用可能で、endpoint はルート /（http://localhost:3100）です。

Hermes Agent

# ~/.hermes/config.yaml
mcp_servers:
  bedolaga:
    transport: streamable-http
    url: "http://localhost:3100"
    env:
      BEDOLAGA_API_URL: "https://your-bot.example.com"
      BEDOLAGA_API_KEY: "your-api-key"

Claude Desktop

{
  "mcpServers": {
    "bedolaga": {
      "type": "streamableHttp",
      "url": "http://localhost:3100"
    }
  }
}

Cursor / VS Code

{
  "mcpServers": {
    "bedolaga": {
      "transport": "streamable-http",
      "url": "http://localhost:3100"
    }
  }
}

curl での確認（legacy compatibility check）

curl による生の JSON-RPC は legacy initialize-handshake（プロトコル 2024-11-05）を使用します。これは手動の後方互換性チェックであり、最新クライアントの通信方法ではありません。最新の MCP SDK v2 クライアントはプロトコル 2026-07-28 を自動的にネゴシエーションし、Mcp-Session-Id を受け取りません（下記「公式 SDK v2 クライアント（最新プロトコル）」参照）。

# Liveness
curl -s http://localhost:3100/health

# Legacy initialize handshake (получить session ID; работает для протоколов вплоть до 2025-11-25)
curl -s -X POST http://localhost:3100/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}},"id":1}' \
  -D - | grep -i mcp-session-id

# Список инструментов (с session ID)
curl -s -X POST http://localhost:3100/ \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <SESSION_ID>" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}'

# Вызов инструментов
# Пользователь и баланс
curl -s -X POST http://localhost:3100/ \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <SESSION_ID>" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"bedolaga_user_get","arguments":{"telegram_id":123456789}},"id":3}'

# Биллинг (операции и внутренние записи покупок)
curl -s -X POST http://localhost:3100/ \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <SESSION_ID>" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"bedolaga_billing_get","arguments":{"telegram_id":123456789,"limit":20}},"id":4}'

# Реферальная сводка
curl -s -X POST http://localhost:3100/ \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <SESSION_ID>" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"bedolaga_referrals_get","arguments":{"telegram_id":123456789}},"id":5}'

# Завершение legacy-сессии (для современного протокола 2026-07-28 не требуется и не применяется)
curl -s -X DELETE http://localhost:3100/ \
  -H "Mcp-Session-Id: <SESSION_ID>"

公式 SDK v2 クライアント（最新プロトコル）

Python MCP SDK v2（mcp==2.0.0）の公式クライアントは、サーバーがサポートしていれば 2026-07-28、そうでなければ legacy-handshake を、_meta やヘッダーの手動構築なしで自動的にネゴシエーションします:

import asyncio

from mcp.client.client import Client


async def main() -> None:
    async with Client("http://localhost:3100/", mode="auto") as client:
        print("negotiated protocol:", client.protocol_version)  # "2026-07-28" against this server

        tools = await client.list_tools()
        print([tool.name for tool in tools.tools])

        result = await client.call_tool(
            "bedolaga_user_get", {"telegram_id": 123456789}
        )
        print(result.content)


asyncio.run(main())

mode="auto" は supportBot が使用するのと同じネゴシエーションです。クライアント自身が、目の前のサーバーが最新版かレガシーかを判断し、呼び出し側のコードが事前にプロトコル時代を知っている必要はありません。

Stdio トランスポート

Hermes Agent

# ~/.hermes/config.yaml
mcp_servers:
  bedolaga:
    command: "python3"
    args: ["/path/to/bedolaga-mcp/bedolaga_server.py"]
    env:
      BEDOLAGA_API_URL: "https://your-bot.example.com"
      BEDOLAGA_API_KEY: "your-api-key"

Claude Desktop

{
  "mcpServers": {
    "bedolaga": {
      "command": "python3",
      "args": ["/path/to/bedolaga-mcp/bedolaga_server.py"],
      "env": {
        "BEDOLAGA_API_URL": "https://your-bot.example.com",
        "BEDOLAGA_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor / VS Code

.cursor/mcp.json または settings.json に追加します:

{
  "mcpServers": {
    "bedolaga": {
      "command": "python3",
      "args": ["/path/to/bedolaga-mcp/bedolaga_server.py"],
      "env": {
        "BEDOLAGA_API_URL": "https://your-bot.example.com",
        "BEDOLAGA_API_KEY": "your-api-key"
      }
    }
  }
}

セッション管理

Streamable HTTP トランスポートは dual-era であり、セッションは2つの時代のうちの1つにのみ適用されます:

• レガシー initialize-handshake (2025-11-25 までのプロトコル): initialize の後、サーバーは Mcp-Session-Id ヘッダーを返し、クライアントは後続のすべてのリクエストでそれを渡す必要があります。このヘッダーを使った DELETE / は指定されたセッションのみを終了します。1つのクライアントが他のクライアントのセッションを終了したり再利用したりすることはできません。

• 最新プロトコル 2026-07-28: stateless/sessionless — サーバーは Mcp-Session-Id を決して発行せず、そのようなクライアントに対して DELETE / は不要であり、適用されません。

環境変数

互換性のため、MCP_HTTP_HOST/MCP_HTTP_PORT が設定されていない場合は、レガシー変数 HOST/PORT が受け入れられます。

Upstream API

Bedolaga Web API: ヘッダーに X-API-Key を指定します。使用するルート:

• GET /users/by-telegram-id/{telegram_id} — Telegram ID によるユーザー；

• GET /users/{user_id} — 内部 ID によるユーザー（email-only チケット）；

• GET /transactions?user_id=... — フィルターとページネーション付きの取引；

• GET /partners/referrers/{user_id} — リファーラルカード。

詳細: https://docs.bedolagam.ru

初版の制限

• プロバイダー固有の支払い試行はありません。 Bedolaga は、共通の transactions テーブルのレコードになった操作のみを返します。レコードにならなかった支払いプロバイダーの生の試行は利用できません。

• ユーザーの Redis カートの読み取りはありません。 現在の Web API は、このための安全な read-only エンドポイントを提供していません。「入金したのに購入がない」という現在の問題は、deposit と subscription_payment の差によって確実に診断できます（decision table を参照）。

• Email-only ルックアップはサポートされています。 Telegram ID を持たないキャビネットのチケットの場合、サーバーは内部 user_id（正の整数）を受け入れ、GET /users/{user_id} でそれを解決します。supportBot はキャビネットの内部 user_id（負の synthetic conversation key の絶対値）をピン留めします。そのようなチケットでは Bedolaga データが利用可能ですが、Remnawave ツールは identity_unavailable を返します。これは、そのようなユーザーには Telegram アイデンティティとパネル内の証明されたレコードがないためです。

ロールバック (rollback)

supportBot で BEDOLAGA_MCP_ENABLED=false を無効にすると、Remnawave-only モードに戻ります。Bedolaga MCP は接続されず、そのツールは allowlist から消え、ウェブフック/poller によるチケット処理（BEDOLAGA_ENABLED）は独立したままです。ロールバックはユーザーベースと財務データに影響しません。Bedolaga MCP は read-only であり、状態を保持しません。

bedolaga-mcp イメージをタグ 1.1.0（MCP SDK v2 への移行前の最後のリリース、レガシー時代の Streamable HTTP のみ）にロールバックすることも安全です。MCP SDK v2 上の supportBot クライアントは、サーバーが最新プロトコル 2026-07-28 に応答しない場合、自動的に（auto-fallback）レガシー initialize-handshake に移行するため、Bedolaga MCP ツールは追加設定なしで引き続き利用できます。