MCP-сервер на TypeScript: как дать AI-инструменту ровно нужные данные

MCP-сервер может публиковать tools, resources и prompts. Tool — действие, которое клиент вызывает с параметрами; resource — доступный для чтения контекст; prompt — подготовленный шаблон взаимодействия. Для первого проекта достаточно одного сценария, например получения списка открытых задач. Так проще понять, какую информацию реально использует агент и какие права ему необходимы.

TypeScript SDK задаёт структуру сервера и описание инструментов, но не заменяет проектирование границы доверия. Если назвать инструмент run_any_query, модель получит огромную поверхность действий, даже когда интерфейс выглядит аккуратно. Узкое имя, строгая схема параметров и ограниченный ответ делают поведение понятнее для клиента и безопаснее для владельца данных.

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

Для удалённого HTTP-сервера документация SDK описывает bearer-авторизацию на входе к MCP-маршруту. Локальный stdio-процесс имеет другую границу: его права определяются запустившим процессом и доступными ему секретами. В обоих случаях минимальные права важнее удобства. Ключ только для чтения и отдельный тестовый ресурс лучше универсального административного токена.

Результат инструмента должен быть небольшим и структурированным: идентификатор, заголовок, статус, ссылка. Не нужно отдавать весь объект базы с внутренними заметками и персональными полями, если агенту нужна только сводка. Ограничьте число записей, размер текста и время выполнения. Это уменьшает стоимость контекста и риск утечки лишних данных через ответ модели.

Обрабатывайте ошибки как часть контракта. Отсутствующий проект, отказ в доступе, недоступный backend и превышение лимита — разные ситуации. Логи должны позволять сопоставить вызов с пользователем, инструментом и временем, но не превращаться в копию чувствительных аргументов и ответов. Хороший журнал помогает расследовать проблему, не создавая новую.

Сначала запустите сервер локально с тестовыми данными и вызовите инструмент вручную. Проверьте обычный запрос, неверную схему, чужой проект и пустой результат. Затем подключите один AI-клиент и посмотрите, выбирает ли он инструмент тогда, когда это нужно, и правильно ли объясняет отказ. Лишь после этого добавляйте второй инструмент или удалённый транспорт.

Полезный критерий готовности — другой разработчик может прочитать описание инструмента, увидеть вход и выход, воспроизвести тест и понять требуемые права. Если для работы нужно выдать агенту полный доступ к базе или shell, граница выбрана слишком широко. MCP ценен как чёткий интерфейс между AI и системой, а не как повод обойти обычную инженерную дисциплину.

В центре решения — MCP-сервера на TypeScript для AI-инструментов: его стоит оценивать в границах «один read-only инструмент с жёсткой схемой входа и ограниченным доступом», а не на абстрактном демо.

Тема MCP-сервера на TypeScript для AI-инструментов легко превращается в спор о вкусах. Чтобы принять инженерное решение, нужно сначала зафиксировать исходное состояние, ожидаемый результат и стоимость ошибки. Полезно сузить пилот до области «один read-only инструмент с жёсткой схемой входа и ограниченным доступом»: так легче сравнить поведение до и после, а также откатить изменение без потери данных.

• Ограничить пилот контуром: один read-only инструмент с жёсткой схемой входа и ограниченным доступом.
• Заранее описать доказательство готовности: контракт инструмента, журнал вызовов и тесты отказа.
• Выбрать один репрезентативный сценарий: получение списка задач проекта без права менять или удалять записи.
• Зафиксировать версии, настройки, права и бюджет, чтобы опыт можно было повторить.
• Назначить человека, который может остановить пилот и оценить качество без авторитета инструмента.

Критерии нужно согласовать до начала: если формулировать их после результата, любой исход можно объявить успехом.

Репрезентативный сценарий для пилота — получение списка задач проекта без права менять или удалять записи; он достаточно реален, но остаётся управляемым.

Хороший пилот начинается не с миграции всего проекта, а с одного повторяемого сценария. Для этой темы подойдёт «получение списка задач проекта без права менять или удалять записи». Важно записать не только итог, но и путь: какой контекст потребовался, где возникли неясности, сколько было повторов и какие ручные решения остались за разработчиком.

1. Снять базовые замеры и сохранить чистую точку отката до начала работы.
2. Разбить сценарий на исследование, минимальную реализацию, проверку и независимое ревью.
3. Запустить проверки, соответствующие риску: валидацию параметров, авторизацию, негативные случаи и аудит доступа.
4. Собрать артефакты: контракт инструмента, журнал вызовов и тесты отказа, не ограничиваясь текстом финального отчёта.
5. Попросить ревьюера оценить результат по критериям, не зная, какой инструмент или подход использовался.

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

Особого внимания требует расширение прав агента через слишком общий инструмент или небезопасный транспорт: эту зону нужно проверять отдельно и не скрывать за общим успехом.

Главный риск здесь — расширение прав агента через слишком общий инструмент или небезопасный транспорт. Его нельзя снять одним промптом, настройкой или проходящим unit-тестом. Нужна сетка защиты: минимальные права, маленький diff, изолированная среда, автоматические проверки и ручная оценка там, где ошибка влияет на пользователя, данные или производство.

• Отдельно проверить главную зону риска: расширение прав агента через слишком общий инструмент или небезопасный транспорт.
• Не расширять permissions и доступ к данным только ради более гладкого демо-сценария.
• Не смешивать миграцию, рефакторинг и новую функцию в одном diff: такой патч сложно проверить и откатить.
• Считать непроходящую или неопределённую проверку блокером, а не поводом изменить ожидание.
• Для данных, авторизации, платежей и публичных API оставлять обязательную ручную проверку и явное одобрение.

Защита не должна зависеть от того, что исполнитель «помнит» все инструкции. Критические ограничения лучше выразить правами, CI, валидаторами и средой, которую нельзя обойти обычным текстом.

Для итогового решения нужны артефакты «контракт инструмента, журнал вызовов и тесты отказа» и динамика метрик, а не субъективное впечатление от первого запуска.

Пилот стоит признавать успешным только тогда, когда он улучшает измеримую часть работы. Для MCP-сервера на TypeScript для AI-инструментов полезно наблюдать долю успешных вызовов, отказы и время на проверку результатов. Сначала нужна базовая линия без нового подхода, затем две-три недели наблюдения и только после этого — решение о расширении. Единичный удачный пример не заменяет серию повторяемых задач.

• Измерять долю успешных вызовов, отказы и время на проверку результатов на серии задач, а не на лучшем единичном примере.
• Сравнивать медиану и неудачные выбросы: среднее значение часто скрывает дорогие провалы.
• Записывать время человека на постановку, перехваты, ревью и исправления, а не только машинное время.
• Отдельно считать регрессии, откаты, инциденты и доработки, появившиеся уже после слияния.
• По итогам пилота обновить командные инструкции, проверки и ограничения, даже если сам инструмент не будет внедрён.

После первого цикла стоит пересмотреть не только выбор инструмента, но и сам процесс: какие инструкции оказались неясными, каких проверок не хватило и где ревью началось слишком поздно.

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

• Какой минимальный контур «один read-only инструмент с жёсткой схемой входа и ограниченным доступом» даст полезный ответ без большой миграции?
• Как будет собрано доказательство: контракт инструмента, журнал вызовов и тесты отказа?
• Нужно ли включить в обязательный набор валидацию параметров, авторизацию, негативные случаи и аудит доступа?
• По какому сигналу пилот будет остановлен, даже если первые результаты выглядят многообещающе?

Если на эти вопросы нет коротких и проверяемых ответов, то разворачивать новый подход ещё рано. Лучше потратить час на ясные границы, чем неделю на разбор неуправляемого эксперимента.