# ru-companies-mcp

MCP-сервер для Claude, который ищет российские компании **без браузера**: каталог Saby (СБИС),
открытая отчётность ФНС и вакансии hh.ru. Возвращает компактный JSON вместо скриншотов
и разбора страниц, поэтому тратит заметно меньше лимитов, чем Claude in Chrome.

Сделан для поиска работы: «найди компании по обращению с отходами в Татарстане с выручкой
от 100 млн, проверь их отчётность и вакансии, добавь лучшие в список».

> Неофициальный проект, не связан с ООО «Тензор» (Saby/СБИС), ФНС или hh.ru.
> Использует публичные страницы и открытые данные; запросы к saby.ru идут не чаще раза
> в 2 секунды, как просит их `robots.txt`. Для личного использования, не для массового сбора.

## Что умеет

| Инструмент | Что делает | Источник |
|---|---|---|
| `find_categories` | Отраслевые категории (378 шт.): «отход», «эколог», «очистк»… | saby.ru |
| `find_regions` | Регионы: «Татарстан», `16`, «мск», «спб», «мо» | встроенный справочник |
| `search_companies` | Компании по категории, региону, словам, порогу выручки; по убыванию выручки | saby.ru |
| `company_card` | Карточка по ИНН: адрес, директор, ОКВЭД, выручка, дата регистрации | saby.ru |
| `company_financials` | Выручка, чистая прибыль, активы по годам | ФНС ГИР БО |
| `company_vacancies` | Открытые вакансии компании | hh.ru (нужен токен) |
| `shortlist_add` / `_show` / `_remove` / `_export` | Свой список компаний с заметками, экспорт в CSV (Excel) или Markdown | локальный файл |
| `sbis_account_status` | Проверка входа в платный аккаунт СБИС | online.sbis.ru |

Экологические категории каталога, например: «Защита окружающей среды» (~14 800 компаний),
«Экология, охрана природы, уборка территорий», «Вывоз, утилизация и переработка мусора»,
«Оборудование и системы очистки», «Услуги по геологическим и геофизическим изысканиям».

## Установка

Нужен Python 3.10+ и [uv](https://docs.astral.sh/uv/) (или pip).

```bash
uvx --from git+https://github.com/glalker/ru-companies-mcp ru-companies-mcp
```

### Claude Desktop

`claude_desktop_config.json` (Настройки → Разработчик → Изменить конфиг):

```json
{
  "mcpServers": {
    "ru-companies": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/glalker/ru-companies-mcp", "ru-companies-mcp"],
      "env": {
        "HH_APP_TOKEN": "",
        "SBIS_LOGIN": "",
        "SBIS_PASSWORD": ""
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add ru-companies -- uvx --from git+https://github.com/glalker/ru-companies-mcp ru-companies-mcp
```

Все переменные необязательны: без них работает поиск, карточки, отчётность и шорт-лист.

| Переменная | Зачем |
|---|---|
| `HH_APP_TOKEN` | Вакансии с hh.ru. API hh.ru не отвечает анонимно — получите токен приложения на [dev.hh.ru](https://dev.hh.ru) (бесплатно). Без него инструмент вернёт ссылку на поиск. |
| `SBIS_LOGIN`, `SBIS_PASSWORD` | Вход в платный аккаунт СБИС (экспериментально, см. ниже). Пароль хранится только в вашем конфиге и уходит только на `online.sbis.ru`. |
| `SBIS_SESSION_ID` | Вместо логина/пароля — готовый идентификатор сессии. |
| `RU_COMPANIES_HOME` | Папка для шорт-листа (по умолчанию `~/.ru-companies-mcp`). |

## Примеры запросов к Claude

- «Какие есть категории про отходы и экологию?»
- «Найди компании из категории "Защита окружающей среды" в Татарстане с выручкой от 50 млн»
- «Покажи отчётность ИНН 7734690939 за последние годы — растёт или падает?»
- «Есть ли у них вакансии эколога?»
- «Добавь их в шорт-лист с заметкой "написать HR", потом выгрузи в CSV»

## Платный аккаунт СБИС

В публичных карточках телефоны и email замаскированы (`(495) 21 ** 16`). Если задать
`SBIS_LOGIN` и `SBIS_PASSWORD` от платного аккаунта, `company_card` получает их полностью
(проверено на одном платном тарифе). Численность сотрудников при этом может остаться скрытой —
это зависит от тарифа. Чтобы проверить, что даёт ваш тариф:

```bash
SBIS_LOGIN=... SBIS_PASSWORD=... uvx --from git+https://github.com/glalker/ru-companies-mcp ru-companies-mcp probe
```

Команда сравнит публичную и авторизованную выдачу и сохранит `~/.ru-companies-mcp/probe-report.json`.
В отчёте только **названия полей и счётчики** — без пароля, сессии и данных компаний.
Приложите его к issue, чтобы помочь добавить контакты.

## Разработка

```bash
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest --cov=ru_companies_mcp     # офлайн-тесты
.venv/bin/pytest -m live                    # проверка живых сервисов
```

Как устроен поиск по saby.ru: страница каталога вызывает JSON-RPC метод
`Contractor.FindByRequisitesPromo` на `https://saby.ru/profile/service/`; сервер делает тот же
вызов (см. `src/ru_companies_mcp/saby.py`). Если Saby поменяет вёрстку или метод, первыми упадут
live-тесты.

## Лицензия

MIT