BREAKING: все 55 инструментов переименованы с плоского snake_case
(get_debtors) на трёхсегментный dot-notation <read|write>.<категория>.<имя>
(read.analytics.get_debtors). Причина — критерий Naming в оценке качества
листинга Smithery: плоский список инструментов без иерархии получает 0 баллов
(«Tool and trigger names should form a navigable tree via dot-notation … Flat
lists and over-nested paths both reduce the score»). Алиасов на старые имена
нет — сервер опубликован на Smithery только сегодня, внешних пользователей
листинга ещё нет, лучший момент для чистого переименования. Категории:
system/schema/counterparty/document/analytics/organization (чтение),
counterparty/entity/catalog/document/sales/purchase/warehouse/
money (запись) — полная таблица соответствий в
README «Инструменты». Заодно упростилась
annotationsFor() в src/mcp/server.ts: вместо regex-подбора по префиксу имени
теперь просто name.startsWith("read.")/"write.".
Добавлено
outputSchemaу всех 55 инструментов — MCP-клиенты теперь могут типизировать
ответы (structuredContent), не только парсить текстовый JSON. Ещё один
критерий quality score Smithery: «Tools should declare an outputSchema so
callers can type-check responses». Схемы — в новомsrc/schemas/output.ts;
большинство write-инструментов сводится к 4 переиспользуемым формам
(createResultSchema/patchResultSchema/mark_for_deletion/post_document—
почти всеcreate_*/update_*идут через общие хелперыcreateOrPreview()/
patchOrPreview()вwrite.ts), у read-инструментов — своя схема на каждый.
src/tools/_shared.ts:ok(data)теперь кладётstructuredContentцентрализованно
для всех инструментов разом.src/types/domain.ts:Counterparty/DocumentSummary
выводятся из Zod-схем (z.infer) вместо дублирования вручную — один источник
правды; заодно убраны 4 неиспользуемых нигде типа (BalanceRow/DebtRow/
SalesSummary/CashflowSummary), не совпадавших с реальной формой ответа.
Важная находка при разработке:outputSchemaне может бытьz.union([...])
или голымz.record()на верхнем уровне — MCP SDK падает сCannot read properties of undefined (reading '_zod')(протокол требуетtype:"object"
на верхнем уровне, а обе формы конвертируются иначе). Все схемы поэтому —
плоскийz.object({...}).passthrough()с необязательными полями (разные
ветки dry-run/confirmed — просто разные подмножества одних и тех же полей).
Проверено вживую на реальной базе: все 55 инструментов (21 чтение реальными
вызовами, 34 записи черезconfirm:falsedry-run — ничего не пишет) прошли
без единой ошибки валидацииstructuredContent.
Исправлено
- Пять параметров без описания (
limitвsearch_documents/
get_customer_history/get_supplier_history;entitySet/ref/lineв
add_document_line/remove_document_line) — найдено проверкой Smithery
quality score («Parameter descriptions»). Манифест Smithery (manifest.json)
также получилtitle/annotationsпо каждому инструменту — раньше терялись
при выгрузке (закрывает критерии Naming/Annotations).