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