Бесплатный урок

Каталог и схема аргументов

Каталог и схема аргументов — Минимальный read-only MCP server. Начните с чистой функции; Schema является исполняемым контрактом; Не превращайте ID в файловый API. Практическое задание: Практика: Каталог и схема аргументов.

Демо-версия. Материалы проходят редакторскую проверку.

Что рассмотрим

  • Начните с чистой функции
  • Schema является исполняемым контрактом
  • Не превращайте ID в файловый API

Начните с чистой функции

Сохраните catalog.mjs. Функция получает ID и возвращает новый объект из разрешённой map, поэтому вызов не меняет каталог через полученную ссылку. Известны только safety и backup. Другой рядок даёт note_not_found, не запускает поиск файла. Учебные записи не являются проверенным состоянием вашего VPS: они объясняют правила. Не добавляйте config с паролями. При будущем подключении базы сохраните узкую функциональную границу вместо инструмента для произвольного SQL или shell-команд по желанию модели.

// catalog.mjs
const notes = new Map([
  ['safety', { id: 'safety', text: 'Educational rule: keep model services private.' }],
  ['backup', { id: 'backup', text: 'Educational rule: test recovery on a separate copy.' }]
]);
export function lookupNote(id) {
  const note = notes.get(id);
  if (!note) throw new Error('note_not_found');
  return { ...note };
}

Schema является исполняемым контрактом

Входная Zod schema ограничит noteId enum-значениями, strict object отклонит лишний path или command. Description объясняет назначение, но не заменяет schema. Выходная schema задаёт id и text для проверки structuredContent клиентом. Если schema и handler расходятся, исправьте контракт до подключения модели. Позитивный пример — noteId:safety; негативные — ../../secret, пустой объект и лишний command. Отдельно проверьте чистую функцию: SDK-защита не должна быть единственной преградой для неправильного ID во всей системе.

Не превращайте ID в файловый API

Даже read_file tool может раскрыть SSH-ключ либо .env. Первому MCP server не нужен произвольный path. Если позже нужны файлы, сопоставляйте известные ID с разрешёнными путями, проверяйте realpath и выход symlink за корень, ограничивайте объём чтения. Строковый startsWith без реальной нормализации недостаточен. Нужны и OS-права, запрещающие процессу читать чужие секреты. В примере файлового доступа нет, поэтому отрицательный path-case заканчивается schema-error, а не попыткой открыть указанный пользователем файл.

Практическое задание

Практика: Каталог и схема аргументов

Перейти к обучению

Программа курса

  1. Контракт read-only MCP
  2. Каталог и схема аргументов
  3. Tool и resource в настоящем server
  4. Stdio, HTTP и version negotiation
  5. Протокольные тесты без модели
  6. Подключение клиента и приёмка