# Личный ассистент в Telegram на Claude

Пишешь боту в Telegram → Claude раз в 15 минут разбирает входящие, отвечает и запоминает.

Ставится **из браузера за 30 минут**. Терминал, Node и Git не нужны.

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvladyslavhumeniuk-oss%2Ftg-assistant&project-name=my-assistant&repository-name=my-assistant&env=TELEGRAM_BOT_TOKEN,APP_SECRET,SUPABASE_URL,SUPABASE_SERVICE_ROLE_KEY&envDescription=4%20%D0%BA%D0%BB%D1%8E%D1%87%D0%B0%3A%20%D1%82%D0%BE%D0%BA%D0%B5%D0%BD%20%D0%B1%D0%BE%D1%82%D0%B0%2C%20%D0%BB%D1%8E%D0%B1%D0%B0%D1%8F%20%D1%81%D0%BB%D1%83%D1%87%D0%B0%D0%B9%D0%BD%D0%B0%D1%8F%20%D1%81%D1%82%D1%80%D0%BE%D0%BA%D0%B0%2C%20%D0%B8%202%20%D0%B8%D0%B7%20Supabase&envLink=https%3A%2F%2Fgithub.com%2Fvladyslavhumeniuk-oss%2Ftg-assistant%23%D0%BF%D0%B5%D1%80%D0%B5%D0%BC%D0%B5%D0%BD%D0%BD%D1%8B%D0%B5-%D0%BE%D0%BA%D1%80%D1%83%D0%B6%D0%B5%D0%BD%D0%B8%D1%8F)

---

## Как это работает

```
  Telegram  ──POST──▶  /api/telegram   ──▶  Supabase.inbox  (status = new)
                                                   │
                                        каждые 15 мин, по расписанию
                                                   ▼
                                          Claude (Cowork)
                                                   │  через MCP-коннектор
                                                   ▼
                                      /api/mcp/<секрет>  ──▶  Supabase.items
                                                   │              (память)
                                                   ▼
                                        sendMessage ──▶ Telegram
```

Сервер **не думает**. Он только принимает сообщения, хранит их и умеет писать в Telegram.
Всё мышление — на стороне Claude, по расписанию. Поэтому нет ни одного платного API-ключа модели.

---

## Что нужно

| Сервис | План | Зачем |
|---|---|---|
| [Telegram](https://t.me/BotFather) | бесплатно | сам бот |
| [Supabase](https://supabase.com) | Free | база: входящие + память |
| [GitHub](https://github.com) | Free | копия этого репозитория |
| [Vercel](https://vercel.com) | Hobby | хостинг вебхука и MCP |
| Claude Pro или Max | платно | Cowork + расписание + коннекторы |

---

## Установка

### 1. Бот в Telegram

Открой [@BotFather](https://t.me/BotFather) → `/newbot` → имя → username (обязан кончаться на `bot`).
Скопируй токен вида `8123456789:AAH...` — это `TELEGRAM_BOT_TOKEN`.

### 2. База в Supabase

[supabase.com](https://supabase.com) → New project (регион — Frankfurt) → придумай пароль, **запиши его**.
Пока проект поднимается (~2 мин), возьми ключи в **Project Settings → API**:

- `Project URL` → это `SUPABASE_URL`
- `service_role` (нажми Reveal) → это `SUPABASE_SERVICE_ROLE_KEY`

Затем **SQL Editor → New query** → вставь целиком файл [`schema.sql`](./schema.sql) → **Run**.

> `service_role` обходит все ограничения доступа. Он живёт только в переменных Vercel. В браузер, в чат и в скриншоты — никогда.

### 3. Деплой на Vercel

Нажми кнопку **Deploy** выше. Vercel попросит:

1. подключить GitHub (Create Git Repository) — репозиторий скопируется тебе;
2. заполнить 4 переменные (см. таблицу ниже).

Через ~40 секунд получишь адрес вида `https://my-assistant-xxxx.vercel.app`.

### 4. Самонастройка

Открой в браузере:

```
https://ТВОЙ-АДРЕС.vercel.app/api/setup?secret=ТВОЙ_APP_SECRET
```

Страница сама проверит ключи, проверит базу, зарегистрирует webhook в Telegram
и выдаст готовый **MCP-адрес** для Claude.

### 5. Коннектор в Claude

Claude → **Settings → Connectors → Add custom connector**.
Имя: `assistant`. URL: тот, что выдала страница настройки.

Проверь в чате: *«покажи мои новые сообщения»* — Claude должен дёрнуть `get_new_messages`.

### 6. Расписание

В Cowork напиши `/schedule` и вставь промт из [`PROMPTS.md`](./PROMPTS.md).
Раз в 15 минут — `*/15 * * * *`.

---

## Переменные окружения

| Переменная | Откуда |
|---|---|
| `TELEGRAM_BOT_TOKEN` | @BotFather, шаг 1 |
| `APP_SECRET` | придумай сам: 20+ случайных символов, латиница и цифры |
| `SUPABASE_URL` | Supabase → Project Settings → API → Project URL |
| `SUPABASE_SERVICE_ROLE_KEY` | там же → service_role → Reveal |

`APP_SECRET` служит двум целям сразу: им подписан webhook Telegram и им закрыт MCP-эндпоинт.
Кто знает секрет — управляет ботом. Меняется в Vercel → Settings → Environment Variables → Redeploy,
после чего надо заново открыть `/api/setup` и обновить URL коннектора.

---

## Что умеет ассистент

Инструменты, которые видит Claude:

| Инструмент | Что делает |
|---|---|
| `get_new_messages` | забрать необработанные сообщения |
| `mark_message_done` | закрыть сообщение (иначе обработает повторно) |
| `send_telegram` | написать в Telegram |
| `save_item` | сохранить task / reminder / idea / note |
| `list_items` | найти в памяти по типу, статусу, подстроке |
| `complete_item` | закрыть задачу |

---

## Если что-то не работает

| Симптом | Причина |
|---|---|
| `/api/setup` — красное про Supabase | не прогнал `schema.sql`, либо неверный URL/ключ |
| `/api/setup` — красное про Telegram | опечатка в токене бота |
| Бот молчит на сообщение | не открыл `/api/setup`, webhook не зарегистрирован |
| Claude не видит инструменты | опечатка в MCP-URL; секрет в адресе должен совпадать с `APP_SECRET` |
| Claude отвечает дважды | пропущен `mark_message_done` — поправь промт расписания |
| Всё умерло через неделю | Supabase Free ставит проект на паузу после 7 дней тишины. Разбуди в дашборде |

Диагностический промт — в [`PROMPTS.md`](./PROMPTS.md), раздел «Спасатель».

---

## Куда расти

- **Голос.** Ловить `msg.voice` в webhook, гнать file_id в распознавание, класть текст в тот же `inbox`.
- **Проактивность.** Отдельное расписание в 8:00: `list_items(kind=reminder, status=open)` → сводка дня.
- **Кто угодно не напишет.** Проверять `msg.from.id` против своего Telegram ID в `api/telegram.ts`.
- **Векторный поиск.** `pgvector` в Supabase поверх `items` — семантический поиск вместо `ilike`.

## Лицензия

MIT. Форкай, ломай, переделывай под себя.