MCP-сервер для 1С на Python SDK 2.x: проверка ответа по контракту

Я проверила прототип MCP-сервера, который получает журнал регистрации через HTTP и отдаёт записи агенту. В хорошем ответе есть время UTC, замаскированный пользователь и навигационная ссылка. Если сервис добавляет полное ФИО, присылает время без зоны или меняет формат ссылки, сервер возвращает ошибку. Агент получает признак isError и причину отказа, а для ошибок после входа в инструмент - ещё и TraceID.

Ниже - контракт, фрагменты его реализации и результаты восьми проверок отказа. Все записи в этом опыте синтетические. Вместо платформы работает HTTP-заглушка, поэтому вы можете проверить Python-часть до публикации сервиса 1С. Саму публикацию и права пользователя базы этот опыт не подтверждает.

🔬 Что именно я проверила

Сервер предоставляет инструмент event_log. Входные параметры - metadata, since_utc, events. Выход - модель EventLogAnswer, внутри которой находится список EventLogRecord. Я разделила проверку аргументов и проверку ответа: корректный вызов инструмента ещё не означает, что HTTP-сервис вернул допустимые данные.

Версии сохранённого прогона:

Последний прогон я сделала 05.10.2026 на Windows 11 на текущем коде сервера. Если повторяете у себя, начните с фиксации своих версий: строка mcp 2.2.0, pydantic 2.13.5 печатается первой.

В начале проверки клиент запросил список инструментов. Существенная строка вывода выглядит так:

mcp 2.2.0, pydantic 2.13.5
1 инструмент event_log: readOnlyHint=True, вход=['events', 'metadata', 'since_utc'], outputSchema=есть

Наличие outputSchema подтверждено для этого инструмента. Публичная схема помогает клиенту понять форму результата; дополнительные правила Python проверяются при построении модели на сервере. Например, собственный валидатор UTC нельзя заменить одной лишь проверкой наличия схемы в списке инструментов.

Аннотация readOnlyHint=True описывает намерение автора инструмента. Она не выдаёт и не отбирает права пользователя 1С. В редакции спецификации MCP 2025-11-25 прямо сказано, что клиент обязан считать аннотации недоверенными, если сервер не входит в число доверенных. Ограничения на запись задаются правами пользователя базы, под которым работает HTTP-сервис.

🧱 Какие поля допускает контракт

Я начала с полей, которые агент использует для разбора события. Для записи обязательны time_utc, user, event, metadata, link; comment допускает строку или None. Дополнительные поля запрещены. Такой запрет распространяется и на оболочку ответа, где находятся trace_id, records и truncated.

Основные объявления из прототипа:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

from datetime import datetime, timedelta
from pydantic import (
    AwareDatetime, BaseModel, ConfigDict, Field,
    field_validator, model_validator,
)

LINK_PATTERN = r"^e1cib/(data/[^?\s]+\?ref=[0-9a-f]{32}|list/[^?\s]+)$"
MASK_PATTERN = r"^[^*]{0,3}\*\*\*$"

class EventLogRecord(BaseModel):
    model_config = ConfigDict(extra="forbid")
    time_utc: AwareDatetime
    user: str = Field(pattern=MASK_PATTERN)
    event: str
    metadata: str
    link: str = Field(pattern=LINK_PATTERN)
    comment: str | None = None

    @field_validator("time_utc")
    @classmethod
    def only_utc(cls, v: datetime) -> datetime:
        if v.utcoffset() != timedelta(0):
            raise ValueError("время не в UTC")
        return v

class EventLogAnswer(BaseModel):
    model_config = ConfigDict(extra="forbid")
    trace_id: str
    records: list[EventLogRecord]
    truncated: bool = False

AwareDatetime требует информацию о часовом поясе. Проверка utcoffset() добавляет требование нулевого смещения. Строка с +03:00 содержит зону, но этот контракт её отклоняет. Автоматического перевода времени в UTC в показанном валидаторе нет. Если ваш сервис возвращает местное время, согласуйте преобразование на стороне сервиса или осознанно измените контракт.

Регулярное выражение для пользователя допускает до трёх символов перед тремя звёздочками. Оно проверяет наличие согласованной маски. Маскирование выполняет источник данных: Python-сервер не превращает полное ФИО в сокращение. В частности, строка Тестов Т. Т. до агента как успешная запись не доходит.

Ссылка может вести на объект через e1cib/data/...?... либо на список через e1cib/list/.... Для ссылки на объект требуется ref из 32 строчных шестнадцатеричных знаков без дефисов. Это узкий формат нашего контракта. Из него нельзя вывести, что любые другие навигационные ссылки платформы неправильны.

В текущем коде есть дополнительная зависимость между полями: изменение ссылочного объекта должно сопровождаться ссылкой на сам объект. Фрагмент проверки:

1
2
3
4
5
6
7
8
9
10
11
12
13

REF_KINDS = (
    "Справочник.", "Документ.", "ПланВидовХарактеристик.",
    "ПланСчетов.", "ПланВидовРасчета.", "ПланОбмена.",
    "БизнесПроцесс.", "Задача.",
)

@model_validator(mode="after")
def object_change_needs_object_link(self):
    if (self.event.startswith("_$Data$_.")
            and self.metadata.startswith(REF_KINDS)
            and not self.link.startswith("e1cib/data/")):
        raise ValueError("изменение ссылочного объекта без ссылки e1cib/data")
    return self

Этот метод находится внутри EventLogRecord. В восьми основных сценариях отдельного опыта с подменой объектной ссылки на ссылку списка нет. Я показываю правило как часть текущей реализации, не включаю его в число проверенных отказов.

🔌 Где ответ HTTP становится ответом MCP

Для SDK 2.2.0 в прототипе используются следующие импорты:

1
2
3

from mcp.server.mcpserver import MCPServer
from mcp.server.mcpserver.exceptions import ToolError
from mcp_types import ToolAnnotations

Инструмент объявлен с возвращаемым типом EventLogAnswer. Ниже приведён фрагмент регистрации и главная строка преобразования. AuditedServer - наш наследник MCPServer, который добавляет журналирование отказов; его поведение разберу дальше.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

server = AuditedServer("nopik-archive-door")

@server.tool(
    annotations=ToolAnnotations(
        read_only_hint=True,
        open_world_hint=False,
    )
)
def event_log(
    metadata: str,
    since_utc: AwareDatetime,
    events: list[str] | None = None,
) -> EventLogAnswer:
    # Здесь создаются trace_id и started, проверяются аргументы.
    raw = call_1c(
        "event_log",
        {
            "metadata": metadata,
            "since": since_utc.isoformat(),
            "event": ",".join(events or []),
        },
        trace_id,
    )
    answer = EventLogAnswer.model_validate({**raw, "trace_id": trace_id})
    # Здесь результат и длительность записываются в журнал.
    return answer

Это фрагмент функции, с опущенными ветвями ошибок. Он показывает место, где пришедший JSON проверяется моделью. До model_validate() данные HTTP-сервиса считаются сырым ответом. Возврат из инструмента происходит после успешной валидации.

TraceID создаётся в Python-сервере. В ответе поле trace_id устанавливается после распаковки raw, поэтому одноимённое значение источника будет заменено локальным идентификатором. При HTTP-вызове тот же идентификатор передаётся в заголовке X-Trace-ID.

Параметры запроса собираются через urlencode, список событий соединяется запятыми. В коде прототипа это связано с тем, что HTTP-обработчик 1С принимает параметры как соответствие. Произвольный текст запроса к базе инструмент не принимает: в его схеме такого параметра нет.

При HTTP 4xx или 5xx сервер формирует сообщение по коду ответа. Тело ошибки не читается. Так содержимое диагностического ответа веб-сервера не становится частью сообщения агенту через эту ветвь. При проблеме транспорта обрабатываются TimeoutError и URLError.

1
2
3
4
5
6
7

except error.HTTPError as e:
    raise DoorError(
        f"1С ответила HTTP {e.code}",
        "denied" if 400 <= e.code < 500 else "unavailable",
    ) from None
except (TimeoutError, error.URLError) as e:
    raise DoorError(f"1С недоступна: {e}") from None

В этом прогоне проверены HTTP 502 и таймаут. Поведение для остальных кодов видно из ветвления, но отдельными строками результата здесь не подтверждено.

🧪 Что агент видит при каждом отказе

Для эталона я использовала одну синтетическую запись. Время внутри неё - тестовое значение, оно не обозначает дату запуска проверки.

1
2
3
4
5
6
7

GOOD = {
    "time_utc": "2026-10-06T06:02:11Z",
    "user": "Те***",
    "event": "_$Data$_.Update",
    "metadata": "Справочник.ТЕСТ",
    "link": "e1cib/data/Справочник.ТЕСТ?ref=" + "0" * 31 + "1",
}

Заглушка возвращает {"records": [GOOD]}. Для каждого сценария изменяется одно поле либо режим HTTP-ответа. Клиент вызывает тот же event_log, а имя сценария передаётся через metadata. Такое использование параметра принадлежит тестовой заглушке; в рабочем сервисе это имя объекта метаданных.

Итого восемь отрицательных сценариев: шесть ответов вне контракта и два сбоя получения ответа. Успешный сценарий в эти восемь не входит. Фрагмент сохранённого вывода:

2 ok          isError=False записей=1
2 extra_fio   isError=True  Error executing tool event_log: ответ 1С вне контракта, TraceID 9e430c99-1bac-42a3-afbd-cbe2bab6fc36: records.0.user_full_name: Extra inputs are not permitted
2 naive_time  isError=True  Error executing tool event_log: ответ 1С вне контракта, TraceID 9faa7938-668b-4520-86b1-d0798f03788d: records.0.time_utc: Input should have timezone info
2 msk_time    isError=True  Error executing tool event_log: ответ 1С вне контракта, TraceID a69db99e-2562-4a81-ad44-8eb476bfd199: records.0.time_utc: Value error, время не в UTC
2 empty_link  isError=True  Error executing tool event_log: ответ 1С вне контракта, TraceID e59cc6f3-f26f-413f-977c-79171073b6ab: records.0.link: String should match pattern '^e1cib/(data/
2 guid_dashes isError=True  Error executing tool event_log: ответ 1С вне контракта, TraceID 8faf5551-d701-4178-955b-5e4a4a25f154: records.0.link: String should match pattern '^e1cib/(data/
2 unmasked    isError=True  Error executing tool event_log: ответ 1С вне контракта, TraceID 43ada938-6ec2-4462-a79e-763568f9af1d: records.0.user: String should match pattern '^[^*]{0,3}\*\
2 502         isError=True  Error executing tool event_log: 1С ответила HTTP 502, TraceID 1371eee7-99ed-4241-bc81-b9e8695c30fb
2 slow        isError=True  Error executing tool event_log: 1С недоступна: timed out, TraceID 17f443c3-7fd0-4cde-8ce9-a32302060c24

Строки ошибок шаблона обрезаны самим проверочным скриптом: он печатает первые 160 символов результата. Полный шаблон виден в объявлении поля выше.

Путь records.0.time_utc означает поле первой записи списка. При лишнем поле ошибка указывает records.0.user_full_name. Такой путь помогает разработчику сервиса найти нарушенный участок ответа без публикации всей записи в журнале MCP.

Сборка описания ошибки в прототипе использует расположение и сообщение валидатора:

1
2
3
4
5
6
7
8
9

except ValidationError as e:
    problems = "; ".join(
        f"{'.'.join(map(str, x['loc']))}: {x['msg']}"
        for x in e.errors()
    )
    log_call(trace_id, "event_log", args, "rejected", started, problems)
    raise DoorError(
        f"ответ 1С вне контракта, TraceID {trace_id}: {problems}"
    ) from None

Поле input из структуры ошибки здесь не включается в problems. Это имеет значение для лишних данных: полное значение отвергнутого поля не требуется для объяснения причины. Однако свободные строки допустимых полей требуют отдельной проверки, о чём говорится в ограничениях.

📒 Почему отказ оформлен через ToolError

DoorError в нашем коде наследует ToolError. В проверенном SDK ожидаемая ошибка инструмента доходит до клиента с текстом. Для сравнения я создала отдельный инструмент boom, который выбрасывает обычный RuntimeError с сообщением о HTTP 502.

1
2
3
4
5

crash = MCPServer("crash-demo")

@crash.tool()
def boom() -> str:
    raise RuntimeError("1С ответила HTTP 502")

Результат сравнения:

5 обычное исключение вместо ToolError: агент видит «Error executing tool boom»

Поэтому ожидаемые отказы источника оформлены через ToolError. Иначе клиент в этом опыте видит лишь общее сообщение. Выбор исключения влияет на диагностику, но не отменяет необходимость фильтрации текста перед его отправкой.

Кроме восьми отказов ответа, проверка содержит два отказа до вызова HTTP-сервиса: since_utc без зоны и запрос неизвестного инструмента run_query. Их результат:

3 since_utc без зоны: isError=True Error executing tool event_log: 1 validation error for event_logArguments
since_utc
  Input should have timezone info [t
4 чужой инструмент run_query: isError=True Unknown tool: run_query
6 журнал вызовов: 11 строк, статусы {'ok': 1, 'unavailable': 2, 'refused': 2, 'rejected': 6}

Сообщение проверки времени также обрезано скриптом. Для этих двух ранних отказов идентификатор создан в журнале обёрткой AuditedServer; приведённые ответы клиенту TraceID не содержат. Обещание «в каждой ошибке агент получает TraceID» было бы шире результата опыта.

Журнал содержит один успешный вызов, шесть отказов контракта, два сбоя доступности и два отказа входа. Это даёт 11 строк. Отдельный инструмент boom принадлежит другому серверу и в этот журнал не входит.

Я сохраняю в строке журнала trace_id, имя инструмента, аргументы, статус, длительность и краткое описание. Тексты проходят redact(), строки внутри аргументов - рекурсивную обработку redact_all(). В текущем коде описание ограничено 300 символами, длительность округляется до двух знаков после запятой.

Обёртка проверяет само исключение и его __cause__. Это нужно, чтобы уже записанный инструментом DoorError не появился второй строкой как ранний отказ. Для постороннего внутреннего сбоя предусмотрен статус crashed. В данном прогоне такого статуса нет; наличие ветви видно в реализации.

Если вы повторяете опыт, сначала проверьте число строк по статусам, затем сопоставьте конкретный TraceID ответа с журналом. Идентификаторы нового запуска будут другими. Само совпадение текстов ошибок со снимком не подтверждает, что журналирование сохранилось после изменения сервера.

🧭 Ограничения

Прогон сделан на mcp 2.2.0, Pydantic 2.13.5 и Python 3.12.10 с HTTP-заглушкой вместо опубликованной базы. Права пользователя базы, авторизацию веб-сервера и запрет записи этот опыт не проверяет: их проверяют на публикации HTTP-сервиса 1С.

Схема проверяет форму и несколько согласованных правил. Она не подтверждает достоверность события, существование объекта по ссылке или правильность имени метаданных. Синтетическая ссылка с ref, оканчивающимся на 1, проходит наш шаблон; переход в клиенте 1С в этом опыте не выполнялся.

Допустимые строки event, metadata, comment в текущем сервере дополнительно проверяются на признаки секрета. Я прочитала отдельную проверку утечек: она рассматривает аргументы, лишнее поле, комментарий и значение в форме UUID. Универсального распознавания секретов здесь нет. Произвольное значение в форме UUID без поясняющего имени по виду неотличимо от обычного идентификатора. Значения тестовых маркеров в статью не включены.

Принимается весь HTTP-ответ через resp.read(), затем разбирается JSON. Лимит размера HTTP-тела в этой функции не задан. Ошибки разбора JSON и все возможные внутренние сбои не входят в восемь рассмотренных сценариев. Политики повтора запроса в показанном вызове тоже нет.

Проверка журнала при запуске подтверждает возможность открыть файл в тот момент. Последующую потерю доступа к диску, заполнение тома и ротацию журнала я не проверяла. Для эксплуатации нужны отдельные решения по хранению и доступу к журналу: аргументы содержат имена объектов и интервалы запросов даже после удаления похожих на секреты строк.

Имена импортов сверены со страницей миграции SDK: MCPServer вместо FastMCP, ToolError в mcp.server.mcpserver.exceptions. Соответствие версии 2.2.0 всем требованиям спецификации MCP я не проверяла.

📚 Источники

• Миграция Python SDK MCP с 1.x на 2.x - MCPServer, ToolError, отказ от mcp.server.fastmcp.
• Инструменты MCP, спецификация 2025-06-18 - outputSchema, isError, результаты инструментов.
• Инструменты MCP, спецификация 2025-11-25 - аннотации инструментов считаются недоверенными.
• Рекомендации MCP по безопасности.

Практическая основа - проверка check_door.py и сервер archive_door.py; объявления и вывод прогона приведены в статье.

Предшественники на Infostart:

• Синтакс-помощник 1С как MCP-инструмент: индекс из справки платформы и сервер на Python SDK (Ninel_S, 01.10.2026) - та же библиотека, другая задача: индекс справки.
• MCP-сервер для проверки ИИ-кода 1С на соответствие API платформы (Sorm, 26.05.2026).
• MCP-сервер внутри 1C:EDT: даём AI-агентам «руки», не открывая ни одного порта наружу (galich, 08.07.2026).
• Бесплатный MCP-сервер для 1С: ИИ читает данные базы и структуру метаданных (MCP:RSV Data) (Prepod2003, 22.06.2026).

Здесь разобран контракт ответа 1С, причины отказа и сверка журнала вызовов.

📎 Файл к статье

В архиве к статье - 13.1-companion.zip: сервер archive_door.py, проверка check_door.py с HTTP-заглушкой вместо 1С, вывод прогона 05.10.2026 output-2026-10-05.txt и README. Установите mcp==2.2.0, запустите python check_door.py и сравните восемь отказов и счётчики журнала с этим выводом. Перед подключением своего сервиса согласуйте поля ответа, формат времени, маску пользователя и правила ссылок.

 

Нинель Адольевна Щербакова (Ninel_S)

Архитектор • SRE & DevOps инженер • HighLoad 1С

Автор 48 технических публикаций на Infostart. Разработчик NOPik, SRE-Suite-for-1C и мультиагентных ассистентов для экосистемы 1С:Предприятие.

Каталог статей и открытых репозиториев Ninel_S