# fgis-mcp

### ФГИС ЦС в вашем ИИ-клиенте

Независимый MCP-сервер для работы с публичными данными [ФГИС ЦС](https://fgiscs.minstroyrf.ru/) Минстроя России.

`fgis-mcp` даёт ИИ-агенту прямой доступ к сметным нормам, ресурсам, ценам, техническим частям, методикам и открытым данным ФГИС ЦС. Сервер умеет сохранять версии нормативной базы, сравнивать редакции и показывать источник каждого полученного факта.

**fgis-mcp не выбирает расценку за пользователя. Он предоставляет данные ФГИС, первоисточники и сведения об их происхождении. Выводы делает агент или специалист.**

Работает с Codex, Claude Desktop, Gemini, Cursor, Qwen Code, VS Code, LM Studio и другими MCP-клиентами.

[Подключение](docs/CLIENTS.md) · [Работа без локальной базы](docs/ONLINE.md) · [Покрытие ФГИС](docs/COVERAGE.md) · [Источники](docs/SOURCE_INVENTORY.md) · [Проверка данных](docs/VERIFICATION.md)

---

## Что умеет fgis-mcp

- **Находить и читать сметные нормы**  
  Код, наименование, единица измерения, состав работ и ресурсы с исходными количествами. Для ведомостей
  доступны пакетный поиск и пакетное чтение до 10 позиций за вызов с сохранением `input_id`.

- **Сравнивать редакции норм**  
  Показывает добавленные и удалённые работы и ресурсы, изменения наименований и количеств.

- **Хранить историю ФСНБ-2022**  
  Официальные версии из OpenData сохраняются отдельно и не затирают друг друга. Завершённый снимок
  неизменяем, а неполные и сбойные импорты по умолчанию исключаются из запросов и экспорта.

- **Работать с ФСБЦ**  
  Читает ресурсные каталоги и позволяет просматривать изменения карточек ресурсов между редакциями.

- **Работать с ценами ФГИС ЦС**  
  Получает цены по ценовым зонам и периодам и позволяет смотреть их историю.

- **Читать технические части и методики**  
  Доступны текст документов, структура, таблицы и исходные ячейки с сохранением объединений строк и столбцов.

- **Извлекать коэффициенты из документов**  
  Возвращает значение, условие, основание и контекст. Неоднозначные строки помечаются как неразрешённые, а не интерпретируются автоматически.

- **Работать с OpenData Минстроя**  
  Получает паспорта наборов, версии и официальные дистрибутивы ФСНБ.

- **Создавать локальные наборы данных**  
  Ответы и исходные файлы сохраняются в SQLite, JSONL, Parquet и каталоге `raw/`.

- **Сохранять происхождение данных**  
  Для записей фиксируются источник, версия, документ, файл и контрольные суммы SHA-256.

- **Проверять полноту выгрузки**  
  Сервер сохраняет сведения о количестве полученных записей, пропущенных страницах, дублях, составе файлов и других признаках полноты конкретного источника.

- **Импортировать внешние файлы**  
  Можно вручную добавлять территориальные нормативы и другие материалы. Для некоторых PDF и архивов импорт ограничивается сохранением исходного файла без структурного разбора.

---

## Чего fgis-mcp не делает

- **Не выбирает сметную норму автоматически**  
  Сервер предоставляет найденные нормы и их содержание, но не решает, какая из них применима к конкретной технологии.

- **Не определяет применимость коэффициента сам по себе**  
  MCP возвращает текст нормы, таблицу и условия. Решение принимается на основании исходного документа и условий конкретного объекта.

- **Не обходит CAPTCHA и авторизацию**  
  Закрытые и защищённые разделы автоматически не вскрываются.

- **Не скачивает содержимое сторонних региональных сайтов ТЕР**  
  Реестр и доступные ссылки сохраняются, но сторонние ресурсы автоматически не обходятся.

- **Не распознаёт изображения как текст**  
  Если формула, схема или таблица существует только в виде изображения, сервер не пытается восстанавливать её содержимое через OCR.

- **Не считает отсутствие локальных данных доказательством отсутствия данных во ФГИС**  
  Неполная локальная база помечается отдельно.

---

## Как работать через ИИ

Для точных ответов агенту достаточно придерживаться простой последовательности:

1. Найти нужную норму или документ через MCP; для списка работ использовать пакетный поиск.
2. Перед описанием нормы прочитать её карточку по шифру и семейству (`ГЭСН`, `ГЭСНм` и т. п.).
3. Перед нормативным выводом открыть первоисточник.
4. Использовать сведения об источнике из результата MCP.
5. Не выдавать поисковое совпадение за подтверждённую применимость.
6. Отличать отсутствие данных во ФГИС от отсутствия данных в локальной базе.

`document_guid` в чтении нормы — строгий фильтр публикации конкретной карточки, а не указатель на
накопительный состав действующей ФСНБ. Сначала читайте норму без этого фильтра; используйте GUID,
только когда нужно подтвердить принадлежность к конкретной публикации.

Поисковая выдача различает:

- `exact` — однозначная карточка с подтверждённым официальным происхождением;
- `candidate` — найдено возможное совпадение;
- `ambiguous` — один шифр соответствует нескольким нормативным сущностям, требуется `family`;
- `not_found` — совпадение не подтверждено; `filter_reason` отличает строгий промах фильтра;
- `unverified` — локальная запись есть, но официальный provenance не подтверждён;
- `error` — ошибка отдельной позиции пакетного вызова, не прерывающая остальные позиции.

Каждый инструмент может вернуть ожидаемую операционную ошибку как обычный структурированный
результат с полями `status`, `error_code`, `error`/`message`, `http_status` и `retryable`. Например,
`NETWORK_ERROR` означает недоступность источника, а не отсутствие данных во ФГИС. Клиенту следует
повторять вызов только при `retryable: true`; `LOCAL_DATASET_INCOMPLETE` означает отсутствие нужного
среза в локальной базе и также не доказывает отсутствие данных во ФГИС.

---

## Что можно спросить у ИИ

> «Подрядчик применил ГЭСНм10-04-067-04. Что это за норма, какие работы и ресурсы в неё входят?»

> «Найди нормы для прокладки кабеля по готовому лотку и покажи, чем найденные варианты отличаются по составу работ.»

> «В техчасти указан коэффициент 1,15. Найди, при каких условиях он применяется и покажи исходный пункт документа.»

> «Что изменилось в этой норме между редакциями ФСНБ 2024 и 2026 годов?»

> «Покажи, как менялась цена этого ресурса в Санкт-Петербурге по доступным кварталам.»

> «Вот код ресурса из старой сметы. Как он назывался в разных редакциях ФСБЦ и менялись ли его характеристики?»
---

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

Нужны [uv](https://docs.astral.sh/uv/getting-started/installation/) и Git.

### Codex

```sh
codex mcp add fgis -- uvx --from git+https://github.com/proovcme/fgis-mcp.git fgis-mcp
```

### Claude Desktop, Cursor, Qwen Code, VS Code и другие MCP-клиенты

Добавьте сервер в конфигурацию клиента:

```json
{
  "mcpServers": {
    "fgis": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/proovcme/fgis-mcp.git",
        "fgis-mcp"
      ]
    }
  }
}
```

Подробные примеры для разных клиентов: [docs/CLIENTS.md](docs/CLIENTS.md).

Проверить соединение с ФГИС ЦС:

```sh
uvx --from git+https://github.com/proovcme/fgis-mcp.git fgis-mcp diagnose
```

---

## Документация

| Задача | Документ |
|---|---|
| Подключить MCP-клиент | [Клиенты и конфигурации](docs/CLIENTS.md) |
| Работать с ФГИС без локальной базы | [Онлайн-инструменты](docs/ONLINE.md) |
| Посмотреть доступные источники | [Инвентаризация источников](docs/SOURCE_INVENTORY.md) |
| Проверить покрытие данных | [Покрытие источников](docs/COVERAGE.md) |
| Скачать данные через терминал | [Команды CLI](docs/CLI.md) |
| Разобраться в локальной базе | [Формат датасета](docs/DATASET.md) |
| Разобраться в XML OpenData | [Схема ФСНБ и ФСБЦ](docs/OPENDATA_XML.md) |
| Проверить воспроизводимость и тесты | [Проверка реализации](docs/VERIFICATION.md) |
| Настроить сеть, VPN и прокси | [Сеть](docs/NETWORK.md) |
| Запустить MCP по URL | [Streamable HTTP](docs/HTTP.md) |
| Посмотреть правила использования данных | [Источники и использование](docs/DATA_USE.md) |

---

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

Обычные тесты не требуют доступа к ФГИС:

```sh
uv sync --locked --group dev
uv run pytest -q
uv run ruff check src tests scripts
uv run ruff format --check src tests scripts
uv build
```

Проверки с реальным подключением к ФГИС и подготовленной локальной базой запускаются отдельно:

```sh
uv run pytest -q -m live
```

---

Код распространяется по лицензии [MIT](LICENSE).

Данные принадлежат их первоисточникам и используются на условиях соответствующих источников.

Проект независим и не связан с Минстроем России или оператором ФГИС ЦС.