diff --git a/src/pages/ai/index.md b/src/pages/ai/index.md index b9d5b64..5b9ac96 100644 --- a/src/pages/ai/index.md +++ b/src/pages/ai/index.md @@ -1298,18 +1298,40 @@ blast radius. У каждого этапа должны быть понятны **Короткий ответ** -MCP, или Model Context Protocol, - это открытый стандарт, который позволяет AI-приложениям подключаться к внешним -системам: файлам, базам данных, браузеру, Figma, GitHub, календарю, документации и внутренним сервисам. +MCP, или Model Context Protocol, - это открытый протокол, который стандартизирует подключение AI-приложений к внешнему +контексту и действиям: файлам, документации, GitHub, Figma, браузеру, базам данных и внутренним сервисам. **Полный ответ** -MCP, или Model Context Protocol, - это открытый стандарт, который позволяет AI-приложениям подключаться к внешним -системам: файлам, базам данных, браузеру, Figma, GitHub, календарю, документации и внутренним сервисам. +MCP решает интеграционную задачу: вместо отдельного нестандартного адаптера для каждого AI-клиента внешний сервис +предоставляет возможности через единый протокол, а host подключает их к модели. Сам MCP не является моделью, агентом или +plugin - это контракт между приложением и сервером. -Простая аналогия: модель сама по себе умеет рассуждать по тексту, но не знает приватные данные проекта и не может -безопасно выполнить действие. MCP дает ей стандартный способ получить контекст или вызвать инструмент через MCP server. +На высоком уровне взаимодействуют три стороны: -См. официальное описание: [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro). +- **host** управляет пользователем, моделью, permissions и жизненным циклом подключений; +- **client** внутри host поддерживает соединение с конкретным MCP server; +- **server** публикует capabilities, которые host может предоставить модели. + +Основные server primitives: + +- **tools** - действия, которые можно вызвать, например создать issue или выполнить поиск; +- **resources** - данные и контекст, которые можно прочитать; +- **prompts** - переиспользуемые шаблоны взаимодействия. + +Протокол использует JSON-RPC 2.0, включает initialization и согласование capabilities. Для локальных серверов обычно +используют STDIO, для удаленных - Streamable HTTP. + +Например, GitHub MCP server может дать агенту tools для работы с Pull Request и resources с данными репозитория. Модель +выбирает, какой capability нужен, но реальные permissions, подтверждения и выполнение контролируются host и server. + +Важно: MCP стандартизирует интерфейс, но сам по себе не делает интеграцию безопасной. Узкие права, validation, approvals +и защита от prompt injection остаются обязанностью приложения и сервера. + +На интервью полезно формулировать MCP как протокол интеграции между AI-host и внешними capabilities, а не как «способ +дать модели полный доступ к системе». + +См. [MCP architecture](https://modelcontextprotocol.io/docs/learn/architecture). @@ -1321,18 +1343,40 @@ MCP, или Model Context Protocol, - это открытый стандарт, **Короткий ответ** -Обычно есть три роли: +MCP-интеграция состоит из host, MCP client и MCP server. Они договариваются о capabilities через initialization, а +сообщения передаются по транспортному слою - обычно STDIO или Streamable HTTP. **Полный ответ** -Обычно есть три роли: +Архитектуру удобно разделить на роли и два слоя протокола. + +**Роли:** + +- **Host** - приложение, в котором работает пользователь и модель. Оно управляет permissions, consent и несколькими + MCP-подключениями. +- **Client** - компонент host, который поддерживает отдельное соединение с одним server и обменивается с ним + MCP-сообщениями. +- **Server** - локальный процесс или удаленный сервис, который предоставляет capabilities. + +При установке соединения стороны проходят initialization и объявляют поддерживаемые capabilities. Поэтому клиент не +должен предполагать, что любой server обязательно поддерживает все возможности протокола. + +**Data layer** описывает JSON-RPC сообщения, lifecycle и primitives. Server может предоставлять tools, resources и +prompts. Протокол также предусматривает client-side возможности, например запросы к host, если они были согласованы. -- **Host** - приложение, где работает пользователь: Claude Desktop, Codex, IDE, ChatGPT или другой AI-клиент. -- **Client** - часть host-приложения, которая держит соединение с MCP server. -- **Server** - процесс или HTTP-сервис, который предоставляет модели capabilities. +**Transport layer** отвечает за доставку сообщений: -MCP server может отдавать resources, tools и prompts. Resources похожи на читаемые данные, tools - на функции, которые -можно вызвать, prompts - на заготовленные сценарии работы. +- **STDIO** удобно использовать для локального процесса: host запускает server и общается через stdin/stdout; +- **Streamable HTTP** подходит для удаленного сервиса и позволяет использовать обычную сетевую инфраструктуру и + аутентификацию. + +Например, Codex может одновременно иметь отдельные clients к GitHub server, browser server и внутренней документации. +Каждое соединение имеет собственный набор capabilities и собственную границу доверия. + +На интервью сильный ответ упоминает не только «host-client-server», но и initialization, capability negotiation и +разделение data layer от transport layer. + +См. [MCP architecture](https://modelcontextprotocol.io/docs/learn/architecture). @@ -1344,17 +1388,35 @@ MCP server может отдавать resources, tools и prompts. Resources п **Короткий ответ** -Обычная функция вызывается вашим приложением напрямую. MCP tool описывается так, чтобы AI-клиент мог показать модели, -что инструмент делает, какие параметры принимает и какой результат возвращает. +Обычная функция является внутренней частью программы. MCP tool - это capability, опубликованный через протокол: AI-host +может обнаружить его, увидеть schema аргументов, запросить вызов и получить стандартизированный результат. **Полный ответ** -Обычная функция вызывается вашим приложением напрямую. MCP tool описывается так, чтобы AI-клиент мог показать модели, -что инструмент делает, какие параметры принимает и какой результат возвращает. +Обычную функцию вызывает код, который уже знает ее API и работает внутри доверенной границы приложения. MCP tool +находится на интеграционной границе между host и server, поэтому кроме реализации ему нужны protocol metadata: понятное +имя, описание, input schema и предсказуемый результат. + +Типичный путь вызова выглядит так: + +1. Client получает от server список доступных tools. +2. Host показывает модели их имена, описания и schemas. +3. Модель предлагает конкретный tool call с аргументами. +4. Host применяет свою policy и при необходимости спрашивает approval. +5. Server повторно валидирует аргументы и authorization. +6. Результат или ошибка возвращаются модели через MCP. + +То есть модель может выбирать tool, но она не должна быть security boundary. Проверки доступа, допустимых параметров и +side effects выполняются детерминированным кодом host/server. -Главное отличие - граница ответственности. MCP tool становится частью агентного контура: модель решает, когда запросить -вызов, host может попросить подтверждение у пользователя, server выполняет действие и возвращает структурированный -результат. +Особенно важно это для write-tools. Например, `getIssue(id)` сравнительно безопасен и обратим, а `deleteDeployment(id)` +требует строгой authorization, подтверждения, audit trail и защиты от случайного повторного выполнения. + +Плохой дизайн - tool вроде `runAnyCommand(command)`: schema формально есть, но capability настолько широкий, что почти +вся безопасность переносится на вероятностное решение модели. Лучше публиковать узкие операции с понятным эффектом. + +На интервью полезно подчеркнуть: MCP tool отличается от функции не «магией AI», а тем, что функция становится +обнаруживаемым protocol API на границе доверия. @@ -1366,21 +1428,38 @@ MCP server может отдавать resources, tools и prompts. Resources п **Короткий ответ** -В Codex MCP servers настраиваются в config.toml: глобально в /.codex/config.toml или на уровне проекта в -.codex/config.toml для trusted project. CLI и IDE extension используют одну конфигурацию. +В Codex MCP servers можно настроить глобально в `~/.codex/config.toml` или для trusted project в `.codex/config.toml`. +Поддерживаются локальные STDIO servers и удаленные Streamable HTTP servers. **Полный ответ** -В Codex MCP servers настраиваются в `config.toml`: глобально в `~/.codex/config.toml` или на уровне проекта в -`.codex/config.toml` для trusted project. CLI и IDE extension используют одну конфигурацию. +Codex хранит MCP-конфигурацию в `config.toml`. Глобальные подключения задаются в `~/.codex/config.toml`, а +project-specific конфигурацию можно положить в `.codex/config.toml` внутри trusted project. + +Есть два основных способа настройки: + +- CLI: `codex mcp add`, `codex mcp list`, `codex mcp login ` и `codex mcp --help`; +- вручную через секции `[mcp_servers.]` в `config.toml`. + +Для локального STDIO server обычно задают `command` и `args`, при необходимости `env`, `env_vars` и `cwd`. Например, +host запускает Node.js или Python процесс и общается с ним через стандартные потоки. -Есть два распространенных способа: +Для удаленного Streamable HTTP server задают `url`; аутентификация может использовать OAuth, bearer token или +настраиваемые headers в зависимости от сервера. -- через CLI-команды `codex mcp add`, `codex mcp login`, `codex mcp --help`; -- вручную через секции `[mcp_servers.]` в `config.toml`. +В конфигурации также можно ограничивать поверхность доступа: включать или отключать отдельные tools, задавать approval +mode и timeouts. Это полезнее, чем подключать мощный server и надеяться только на инструкцию «не вызывай опасные tools». -Локальный server обычно запускается как STDIO-процесс через `command` и `args`. Удаленный server обычно подключается по -Streamable HTTP через `url`, bearer token или OAuth. В Codex TUI активные servers можно посмотреть через `/mcp`. +Активные MCP connections и tools в Codex TUI можно посмотреть через `/mcp`. Codex также может учитывать `instructions`, +которые MCP server возвращает во время initialization, поэтому содержимое и доверие к server имеют значение. + +Пример принципа настройки: GitHub server может быть доступен для чтения без подтверждения, а write-tools для создания +или изменения данных - требовать approval. Конкретную policy выбирают по blast radius операции. + +На интервью лучше не запоминать один большой `config.toml`, а объяснить четыре вещи: scope конфигурации, transport, +authentication и tool approval policy. + +См. [Codex MCP documentation](https://developers.openai.com/codex/mcp). @@ -1392,20 +1471,33 @@ Streamable HTTP через `url`, bearer token или OAuth. В Codex TUI акт **Короткий ответ** -MCP нужен, когда контекст должен быть живым, приватным, большим или действующим: +MCP нужен, когда контекст живой, приватный, повторно используемый или требует действий во внешней системе. Короткий +статичный контекст для одной задачи обычно проще передать в prompt. **Полный ответ** -MCP нужен, когда контекст должен быть живым, приватным, большим или действующим: +Prompt и MCP решают разные задачи. Prompt передает уже известный текст модели. MCP дает стандартный способ получить +актуальные данные или выполнить действие во время agent workflow. + +MCP особенно полезен, когда нужно: + +- читать состояние, которое меняется: Pull Request, тикеты, календарь, логи или базу данных; +- работать с приватной системой через нормальную authentication, а не копировать данные вручную; +- выполнять действия: создать issue, обновить документ, открыть браузер или вызвать внутренний API; +- переиспользовать одну интеграцию в разных задачах; +- получать только нужный фрагмент большого источника вместо постоянной загрузки всего контента в context window. + +Но MCP не стоит добавлять автоматически. Server увеличивает operational complexity и attack surface: появляются +credentials, permissions, network failures, prompt injection через внешние данные и необходимость поддерживать API. -- прочитать актуальные данные из системы; -- выполнить действие во внешнем сервисе; -- авторизоваться от имени пользователя; -- открыть браузер, Figma, GitHub, Sentry или внутренний API; -- не копировать секреты и большие документы в промпт вручную. +Если правило статично и относится к репозиторию, лучше положить его в `AGENTS.md`. Если нужна повторяемая методика +работы, подходит Skill. Если пользователь один раз дал небольшой фрагмент текста, достаточно prompt. -Если контекст короткий, статичный и нужен один раз, проще вставить его в prompt или документировать правило в -`AGENTS.md`. +Например, инструкция «после изменений запускай unit-тесты» не требует MCP. А задача «найди последние ошибки в Sentry и +создай GitHub issue по подтвержденной регрессии» уже естественно использует live integrations и tools. + +На интервью полезно выбирать механизм по вопросу: нужны ли freshness, authentication и side effects. Если нет, MCP может +быть лишней инфраструктурой. @@ -1417,21 +1509,38 @@ MCP нужен, когда контекст должен быть живым, п **Короткий ответ** -Минимальный путь: +Начните с узкого use case: выберите STDIO или Streamable HTTP, возьмите официальный SDK, опишите +tools/resources/prompts, добавьте schemas и validation, а затем проверьте server в реальном client и ограничьте его +права. **Полный ответ** -Минимальный путь: +Хороший MCP server начинается не с вопроса «что можно подключить», а с конкретной capability и границы доверия. +Например: read-only поиск по внутренней документации или создание issue с заранее определенными полями. + +Практичный порядок: + +1. **Определить use case и права.** Что server читает, что меняет и какими credentials располагает. +2. **Выбрать transport.** STDIO обычно проще для локального инструмента, Streamable HTTP - для удаленного сервиса. +3. **Взять SDK.** Официальные TypeScript и Python SDK реализуют lifecycle, transport и protocol plumbing. +4. **Спроектировать primitives.** Tools должны быть узкими, resources - адресуемыми, descriptions - понятными модели. +5. **Задать schemas и validation.** Не доверять аргументам только потому, что их сформировала модель. +6. **Вернуть полезный результат.** Не отправлять модели мегабайты логов, если можно вернуть компактные структурированные + данные и ссылку на источник. +7. **Проверить ошибки и side effects.** Нужны timeouts, понятные error responses, idempotency там, где возможен retry. +8. **Протестировать интеграцию.** Проверить discovery, вызовы и ошибки через MCP Inspector или реальный host. +9. **Усилить security.** Least privilege, authentication для удаленного server, audit и approvals для опасных действий. + +Для STDIO есть отдельное практическое правило: protocol messages идут через `stdout`, поэтому обычные debug-логи нужно +писать в `stderr` или файл. Иначе server может повредить JSON-RPC поток. -1. Выбрать транспорт: STDIO для локального инструмента или HTTP для удаленного сервиса. -2. Создать server на SDK, например TypeScript SDK `@modelcontextprotocol/sdk` или Python SDK. -3. Описать tools, resources или prompts. -4. Для каждого tool задать понятное имя, описание и schema входных параметров. -5. Вернуть результат в формате, который клиент сможет показать модели. -6. Подключить server в host-приложении и проверить через MCP Inspector или клиент. +После запуска стоит тестировать не только happy path, но и неизвестный tool, неверные параметры, timeout, потерю +соединения, повторный вызов и недостаточные права. -Для TypeScript официальный quickstart показывает `McpServer`, `StdioServerTransport`, `zod` для схем и регистрацию tool -через `server.registerTool(...)`: [Build an MCP server](https://modelcontextprotocol.io/docs/develop/build-server). +На интервью сильный ответ показывает, что MCP server - это внешний API для агента: его нужно проектировать с той же +дисциплиной, что и обычный production API. + +См. [Build an MCP server](https://modelcontextprotocol.io/docs/develop/build-server). @@ -1443,21 +1552,48 @@ MCP нужен, когда контекст должен быть живым, п **Короткий ответ** -Частые ошибки: +Частые ошибки: слишком широкие tools, слабые schemas и descriptions, отсутствие authorization, огромные ответы, +смешивание read/write операций, неправильное логирование STDIO и отсутствие timeout, idempotency и approvals. **Полный ответ** -Частые ошибки: +Ошибки удобно группировать по нескольким уровням. + +**Дизайн API:** + +- универсальный `runAnyCommand` вместо нескольких узких capabilities; +- название и description не позволяют модели понять, когда tool можно использовать; +- input schema слишком широкая, а ошибки не объясняют, что исправить; +- один tool одновременно читает, изменяет и публикует данные. + +**Protocol и transport:** + +- обычные логи пишутся в `stdout` STDIO server и ломают protocol stream; +- server предполагает capabilities клиента без initialization/negotiation; +- удаленное соединение не обрабатывает timeout, reconnect или частичный сбой. + +**Security:** + +- server доверяет аргументам модели вместо собственной validation и authorization; +- используются слишком широкие credentials; +- destructive action выполняется без approval или дополнительной проверки; +- внешние данные и server instructions считаются доверенными автоматически. + +**Context efficiency:** + +- tool возвращает огромный HTML, лог или JSON вместо минимально полезных данных; +- response неструктурирован и заставляет модель заново извлекать поля из текста; +- десятки похожих tools имеют неразличимые descriptions и ухудшают tool selection. + +**Надежность:** -- писать логи в `stdout` у STDIO server, ломая JSON-RPC поток; -- делать слишком широкие tools вроде `runAnyCommand`; -- не валидировать входные параметры; -- возвращать слишком большой или неструктурированный ответ; -- смешивать чтение данных и destructive actions без подтверждения; -- прятать важные ограничения только в README, а не в описаниях tools и server instructions. +- write-operation не учитывает retry и повторяет side effect; +- нет стабильных error codes и audit trail; +- сервер сложно тестировать независимо от модели. -Для STDIO server логи нужно писать в `stderr` или файл. Для опасных действий стоит требовать явное подтверждение на -уровне host или tool policy. +Хороший MCP server предсказуем: узкие capabilities, строгие schemas, минимальные permissions, компактные результаты и +понятные failure modes. На интервью лучше привести конкретный анти-паттерн и объяснить его blast radius, чем просто +перечислить «validation и security».