# 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)

## Установка

```powershell
# Создание виртуального окружения
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)

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

Или через батник:
```powershell
.\run_server.bat
```

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

### Stdio

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

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

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

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

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

### Конфиг для STDIO

```json
{
  "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

```json
{
  "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`

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

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

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