# mcp-1c-its — MCP-сервер доступа к 1С:ИТС, релизам, ошибкам типовых и Бухэксперт8

Даёт ИИ-агенту (ZCode, Claude, Cursor и любому клиенту с поддержкой Model
Context Protocol) доступ к трём ресурсам фирмы «1С» **по одной учётной
записи** (тем же логином и паролем, что и на ИТС): материалы ИТС и релизы
открываются в рамках подписки ИТС, доске ошибок достаточно самой учётной
записи. Отдельно — справочная система **Бухэксперт8** (подписка 1С не
нужна: без учётной записи доступны открытые материалы, с учётной записью
подписчика — и платные).

- **1С:ИТС** ([its.1c.ru](https://its.1c.ru)) — поиск по 36 разделам портала
  (`its_search`) и материалы в Markdown (`its_get`): стандарты разработки,
  руководство разработчика платформы, документация платформы по версиям,
  описание БСП и стандартных библиотек, практическое пособие по 1C:EDT,
  глоссарий терминов, «Отвечает специалист 1С»;
- **релизы** ([releases.1c.ru](https://releases.1c.ru)) — типовые конфигурации
  с короткими кодами и версиями (`releases_products`, например
  `Accounting30` — «Бухгалтерия предприятия, редакция 3.0») и списки
  исправлений любой версии с номерами `EF_...` и описаниями
  (`releases_patches`);
- **доска ошибок** ([bugboard.1c.ru](https://bugboard.1c.ru),
  «1С:Публикация ошибок») — поиск по симптомам: текст в заголовках и
  описаниях всех ошибок версии (`bugboard_search`); карточка ошибки по номеру
  `EF_...` со статусом, планом исправления и способом обхода
  (`bugboard_card`); списки исправленных и открытых ошибок версии
  (`bugboard_version_errors`); последние версии проекта
  (`bugboard_versions`);
- **Бухэксперт8** ([buhexpert8.ru](https://buhexpert8.ru), подписка 1С не
  нужна) — справочная система по 1С:Бухгалтерии и 1С:ЗУП: поиск по статьям,
  вопросам-ответам и новостям (`buhexpert_search`) и материалы в Markdown
  (`buhexpert_get`). Анонимно читаются открытые материалы; если задан логин
  и пароль подписки — и платные.

Типовой сценарий «это баг типовой или наш?»: `bugboard_search` (симптомы) →
`bugboard_card` (статус, обход) → `releases_patches` (в какой версии вышло).

Сервер сам хранит вход по подписке (логин и пароль лежат в локальном файле и
никак не отдаются агенту), бережно ходит на порталы (не чаще запроса в секунду,
кэширует: материалы — на неделю, поиск — на сутки) и отдаёт материалы в
Markdown со ссылкой на источник.

## Инструменты

| Инструмент | Назначение |
|---|---|
| `its_search(query, section)` | Поиск по ИТС; по умолчанию по всем разделам (`morphmerged`) |
| `its_get(path)` | Материал в Markdown по адресу из результата поиска |
| `its_sections()` | Каталог разделов для поиска (36 разделов по группам) |
| `releases_products(query)` | Типовые конфигурации с releases.1c.ru: название, код, версии |
| `releases_history(nick)` | История релизов конфигурации: версия, дата выхода, с каких версий обновление, минимальная платформа |
| `releases_patches(nick, ver)` | Список исправлений (баг-фиксов `EF_...`) версии конфигурации |
| `releases_changes(nick, ver, details, since)` | Что нового в релизе: минимальная и рекомендованная платформа из предупреждения на странице релиза + изменения из отчёта «Новое в версии»; `since` — установленная версия: накопительный итог всех релизов новее неё и перечень непокрытых |
| `releases_where_fixed(nick, number)` | В каком релизе исправление вошло в состав конфигурации, а в каких доступно только багфиксом |
| `bugboard_card(number, project)` | Карточка ошибки с bugboard.1c.ru по номеру `EF_...` |
| `bugboard_search(project, ver, query)` | Поиск ошибок по симптомам: текст в заголовках/описаниях всех ошибок версии |
| `bugboard_version_errors(project, ver)` | Ошибки версии конфигурации: исправленные и открытые |
| `bugboard_versions(project)` | Последние версии проекта на bugboard |
| `buhexpert_search(query, limit)` | Поиск по справочной системе Бухэксперт8: статьи, вопросы-ответы, новости по 1С:Бухгалтерии и 1С:ЗУП |
| `buhexpert_get(url_or_id)` | Материал Бухэксперт8 в Markdown по адресу или id из результата поиска; платные — при заданной учётной записи подписчика |
| `its_status()` | Самопроверка: источник учётных данных, состояние сессии |

Все три ресурса 1С — [ИТС](https://its.1c.ru), [releases.1c.ru](https://releases.1c.ru)
и [bugboard.1c.ru](https://bugboard.1c.ru) (1С:Публикация ошибок) — открываются
одной учётной записью: сервер входит один раз и переиспользует сессию единого
входа. Бухэксперт8 — отдельная учётная запись подписки (необязательная,
без неё доступны открытые материалы). Типовая связка для анализа ошибок
типовых: `releases_products` → `releases_patches` (номер `EF_...`) → `bugboard_card`.

Внутренний протокол bugboard (вход и вызовы) разобран и описан в
[docs/bugboard-protocol.md](docs/bugboard-protocol.md); при изменении
протокола на стороне 1С инструменты вернут понятную ошибку — чинить по
этому документу. Устройство доступа к Бухэксперт8 (REST API WordPress,
заглушка платных материалов, вход подписчика) — в
[docs/buhexpert-api.md](docs/buhexpert-api.md).

## Установка

### Вариант 1 — uv (Python не нужен)

Установите [uv](https://docs.astral.sh/uv/getting-started/installation/)
(один исполняемый файл, без прав администратора):

```bash
# Windows
winget install astral-sh.uv
# или PowerShell: irm https://astral.sh/uv/install.ps1 | iex
```

uv сам скачает изолированный Python и зависимости. Проще всего — запуск
напрямую из этого репозитория, без клонирования:

```bash
uvx --from git+https://github.com/VoskresenskiyAU/mcp-1c-its mcp-1c-its
```

(команда запустит сервер и будет молча ждать — это норма для stdio;
Ctrl+C для выхода). Для клиента в конфигурации:

```json
"1c-its": { "command": "uvx",
            "args": ["--from", "git+https://github.com/VoskresenskiyAU/mcp-1c-its", "mcp-1c-its"] }
```

Для разработки или без сети — из локальной копии:

```bash
git clone https://github.com/VoskresenskiyAU/mcp-1c-its
cd mcp-1c-its
uv sync
uv run mcp-1c-its
```

После публикации пакета на PyPI запуск упростится до `uvx mcp-1c-its`.

### Вариант 2 — системный Python (3.10+)

```bash
git clone https://github.com/VoskresenskiyAU/mcp-1c-its
cd mcp-1c-its
python -m pip install .
```

Либо на Windows просто запустите `install.bat` из папки репозитория.

## Учётные данные

Создайте файл `its_credentials.txt` (пример — `its_credentials.example.txt`):

```
ITS_USER=ваш_логин
ITS_PASS=ваш_пароль
```

И положите его в **`%USERPROFILE%\.1c-its\`** (Linux/macOS: `~/.1c-its/`).
Альтернативы — переменная окружения `ITS_CRED_FILE` с полным путём к файлу
или файл в текущей папке (приоритет: окружение → домашняя папка → текущая
папка).

Файл добавлен в `.gitignore` — не коммитите его и не передавайте вместе с
репозиторием. Значения не попадают ни в аргументы инструментов, ни в ответы,
ни в тексты ошибок.

### Бухэксперт8 (необязательно)

Для чтения платных материалов Бухэксперт8 создайте рядом файл
`buhexpert_credentials.txt` (пример — `buhexpert_credentials.example.txt`):

```
BUHEXPERT_USER=логин_подписки
BUHEXPERT_PASS=пароль
```

Без файла сервер работает анонимно: поиск и все открытые материалы.
Файл ищется так же (переменная окружения `BUHEXPERT_CRED_FILE` → домашняя
папка → текущая); неудачный вход не мешает работе — сервер сообщит об этом
в `its_status` и продолжит анонимно.

## Подключение к клиенту

Общая запись (stdio):

```json
"1c-its": {
  "command": "<запуск сервера>",
  "args": []
}
```

Конкретные значения `command`/`args`:

- **uvx из GitHub (без клонирования)**: `uvx`, `["--from", "git+https://github.com/VoskresenskiyAU/mcp-1c-its", "mcp-1c-its"]`
- **uv из локальной копии**: `uv`, `["--directory", "<путь к репозиторию>", "run", "mcp-1c-its"]`
- **pip-установка**: `python`, `["-m", "mcp_1c_its.server"]`
- **ZCode**: раздел `mcp.servers` файла `~/.zcode/cli/config.json`
- **Claude Desktop / Cursor**: раздел `mcpServers` их конфигурации

После подключения перезапустите клиент.

## Проверка

```bash
python -m mcp_1c_its.check     # или: uv run python -m mcp_1c_its.check
```

Проверяет все четыре ресурса: вход в ИТС с пробным поиском и материалом,
список конфигураций на releases, вход с версиями проекта на bugboard и
поиск с материалом на buhexpert8.ru (анонимно или по учётной записи
подписки — о чём сообщает). Код возврата 1 — если что-то не работает.
Через агента — попросить «проверь its_status».

## Ограничения и заметки

- Не чаще одного запроса к порталу в секунду; массовая автоматическая выкачка
  — серая зона правил портала, не используйте сервер для неё.
- Кэш материалов — 7 дней, выдачи поиска — сутки (`~/.1c-its/cache/`).
- Если 1С изменит форму входа на login.1c.ru — править функцию `_login()`
  в `src/mcp_1c_its/server.py`; если Бухэксперт8 уйдёт со стандартного
  входа WordPress или REST API — функции `_be_ensure_session()` и
  `be_get_raw()` там же (см. docs/buhexpert-api.md).

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

```bash
python -m pip install -e .          # редактируемая установка
python -m mcp_1c_its.check          # проверка
uv build                            # сборка пакета (dist/); pip-путь: pip install build && python -m build
```

Структура: `src/mcp_1c_its/server.py` — сервер, `src/mcp_1c_its/check.py` —
проверка, `pyproject.toml` — пакет и точка входа `mcp-1c-its`.

## Лицензия

MIT — см. [LICENSE](LICENSE).