Каталог и схема аргументов
Каталог и схема аргументов — Минимальный 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, а не попыткой открыть указанный пользователем файл.
Практическое задание
Практика: Каталог и схема аргументов
Перейти к обучению