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.