Асинхронный Python-клиент Tehzor Public API

Все 73 метода Tehzor Public API и MCP-сервер для LLM-агентов.

pip install -U tehzor            # библиотека
pip install -U "tehzor[mcp]"     # + MCP-сервер tehzor-mcp

0.2.0 несовместима с 0.1.x (TehzorAPI.create) — см. docs/MIGRATION.md и CHANGELOG.md. Примеры — в examples/.

Принципы

• Факт важнее спецификации. docs/openapi.json — заявление разработчика API о доступных методах. Модели строятся по фактическим ответам, которые проверяют контрактные тесты (pytest -m contract). Найденные расхождения собраны в docs/API_FACTS.md.
• Бережно к серверу. Ограничение частоты и параллельности, повторы только для безопасных операций в пределах бюджета времени, circuit breaker. Тяжёлые запросы (502 после ~30 с) не повторяются.
• Запись под контролем. Режим read_only=True блокирует изменяющие операции до отправки. Создание, изменение и удаление проверяются только на заглушках.

Быстрый старт

import asyncio
from tehzor import TehzorClient
from tehzor.models.problems import ProblemFilters
from tehzor.models.spaces import SpaceEdit


async def main() -> None:
    async with TehzorClient(api_key="...") as thz:   # или переменная окружения TEHZOR_API_KEY
        print(await thz.objects.stages())
        async for p in thz.problems.iter(ProblemFilters(objects=["<id объекта>"])):
            print(p.number, p.status.name if p.status else None)

        # изменения: сначала посмотреть запрос, ничего не отправляя
        req = await thz.spaces.edit("<id помещения>", SpaceEdit(area_bti=55.1), dry_run=True)
        print(req.describe(), req.json)


asyncio.run(main())

MCP-сервер для LLM-агентов

tehzor-mcp публикует все 73 операции API как инструменты MCP, плюс problems_search (поиск нарушений с автопагинацией), space_overview (сводка по помещению) и справочники как ресурсы tehzor://….

Запуск

uvx (без установки):

uvx --from "tehzor[mcp]" tehzor-mcp

Из git (например, ветка до релиза): uvx --from "tehzor[mcp] @ git+https://github.com/gritsyuk/tehzor@<ветка>" tehzor-mcp.

Docker:

docker build -t tehzor-mcp .

docker run -i --rm -e TEHZOR_API_KEY tehzor-mcp

За корпоративным прокси с собственным CA сертификат передаётся только на время сборки: docker build --build-arg HTTPS_PROXY --secret id=pip_ca,src=/path/to/ca.pem -t tehzor-mcp .

HTTP (streamable-http) — для удалённого подключения, только с токеном:

TEHZOR_API_KEY=… TEHZOR_MCP_HTTP_TOKEN=$(openssl rand -hex 32) docker compose up -d

Клиент подключается к http://<host>:8000/mcp с заголовком Authorization: Bearer <TEHZOR_MCP_HTTP_TOKEN>. Наружу публикуйте только за reverse-proxy с TLS.

Подключение

Claude Code:

claude mcp add tehzor --env TEHZOR_API_KEY=… -- uvx --from "tehzor[mcp]" tehzor-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "tehzor": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "TEHZOR_API_KEY", "tehzor-mcp"],
      "env": {"TEHZOR_API_KEY": "…"}
    }
  }
}

Запись данных и подтверждение человеком

• По умолчанию запись выключена: изменяющие инструменты видны агенту, но отказывают и ничего не отправляют. Включается TEHZOR_MCP_ALLOW_WRITE=1; TEHZOR_MCP_WRITE_TOOLS=problems_create,comments_create сужает список. TEHZOR_MCP_HIDE_WRITE=1 убирает изменяющие инструменты совсем.
• Даже при включённой записи каждая изменяющая операция сначала возвращает превью (метод, путь, тело) и одноразовый confirmation_id (живёт 10 минут). Выполнение — только после подтверждения человеком: через диалог клиента (MCP elicitation) или инструмент confirm_operation. Отправляется ровно показанный запрос.
• Создание никогда не повторяется автоматически (дублей не будет). Для большинства сущностей удаления в API нет.
• Журнал аудита — TEHZOR_MCP_AUDIT_LOG (по умолчанию ~/.tehzor-mcp/audit.jsonl, в Docker — том /data); ФИО, телефоны и email маскируются, ключ не пишется.
• Важно: при создании нарушения сервер Tehzor сам назначает исполнителей и наблюдателей по настройкам объекта — они получают уведомления (см. docs/API_FACTS.md).

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

Разработка

python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/ruff check . && .venv/bin/mypy
.venv/bin/pytest                  # unit-тесты, без сети
.venv/bin/pytest -m contract      # живое API, только чтение (нужны ключ и TEHZOR_SEED_OBJECT_ID)

Статус