TelegramMCP

Сервер с протоколом MCP — единственный инструмент: отправляет в Telegram название проекта и статус завершения. Работает в двух вариантах транспорта: StreamableHTTP (FastAPI) и stdio (stdin/stdout).

Возможности

• 🚀 MCP-сервер с инструментом notify_task_done(project_name, status)
• 📡 StreamableHTTP транспорт — FastAPI-сервер на порту 8000
• 💬 Stdio транспорт — stdin/stdout для MCP-клиентов
• 📱 Отправка уведомлений в Telegram (через python-telegram-bot)
• 🌐 Прокси SOCKS5 (по умолчанию socks5://192.168.0.250:2081)
• 🧪 Unit-тесты (mock, без сети)

Требования

• Python 3.11+
• Windows 10/11 (PowerShell 5.1)

Установка

# Создание виртуального окружения
python -m venv venv

# Установка зависимостей (используем прямой вызов python)
.\venv\Scripts\python.exe -m pip install --upgrade pip
.\venv\Scripts\python.exe -m pip install -r requirements.txt

# Настройка переменных окружения
copy .env.example .env
# Отредактируйте .env: BOT_TOKEN, TG_CHAT_ID и т.д.

Запуск

HTTP (StreamableHTTP)

# Запуск HTTP-сервера (двойной вызов, без активации venv)
.\venv\Scripts\python.exe main.py

Или через батник:

.\run_server.bat

Сервер запустится на 127.0.0.1:8000, MCP-эндпоинт доступен на /mcp.

Stdio

# Запуск MCP-сервера через stdin/stdout
.\venv\Scripts\python.exe mcp_stdio.py

Подключение MCP-клиента

Ниже примеры конфигурации для подключения MCP-клиента (Claude Desktop, opencode, VS Code и т.д.) к каждому транспорту.

Конфиг для HTTP (StreamableHTTP)

{
  "mcpServers": {
    "telegram": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Конфиг для STDIO

{
  "mcpServers": {
    "telegram": {
      "type": "stdio",
      "command": ".\\venv\\Scripts\\python.exe",
      "args": ["mcp_stdio.py"],
      "cwd": "<путь к корню проекта, например C:\\Projects\\TelegramMCP>"
    }
  }
}

cwd можно опустить — mcp_stdio.py сам добавляет свою директорию в sys.path, поэтому сервер запустится из любого рабочего каталога. Путь к python.exe должен быть абсолютным или указываться относительно cwd.

Переменные окружения (.env)

Переменная	Описание	По умолчанию
BOT_TOKEN	Токен Telegram-бота	CHANGE_ME
TG_CHAT_ID	ID чата для уведомлений	0
PROXY_URL	URL SOCKS5-прокси	socks5://192.168.0.250:2081
PROXY_LOGIN	Логин прокси (пусто = без auth)	""
PROXY_PASSWORD	Пароль прокси	""
HOST	Адрес привязки	127.0.0.1
PORT	Порт сервера	8000
LOG_LEVEL	Уровень логов	INFO

Использование MCP-инструмента

Сервер предоставляет один инструмент MCP:

notify_task_done(project_name: str, status: str, message: str?)

Проект поддерживает два транспорта — оба используют одинаковую логику (app/server.py):

Транспорт	Запуск	MCP-эндпоинт
StreamableHTTP	python main.py	POST /mcp на порту 8000
stdio	python mcp_stdio.py	stdin / stdout

Вызов инструмента через HTTP

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "notify_task_done",
    "arguments": {
      "project_name": "MyProject",
      "status": "completed",
      "message": "All green"
    }
  }
}

Вызов инструмента через stdio

MCP-клиент (например, Claude Desktop, VS Code) подключается к mcp_stdio.py напрямую через stdio. Сами JSON-RPC-сообщения передаются клиентом автоматически.

В Telegram будет отправлено сообщение: Задача "MyProject": completed

Тестирование

.\venv\Scripts\python.exe -m pytest tests/ -v

Все тесты используют mock — реальная сеть не используется. Подробности см. в tests/TEST_GUIDE.md.