Free lesson

Catalog and argument schema

Catalog and argument schema — Build a minimal read-only MCP server. Start with a pure lookup; Make the schema executable; Avoid arbitrary path APIs. Practical assignment: Practice: Catalog and argument schema.

Demo edition. The materials are undergoing editorial review.

Topics covered

  • Start with a pure lookup
  • Make the schema executable
  • Avoid arbitrary path APIs

Start with a pure lookup

Save catalog.mjs. Lookup returns a new object from an explicit map, preventing callers from mutating the catalog through a returned reference. Only safety and backup exist. Other identifiers produce note_not_found rather than triggering a filesystem search. These educational records explain rules, not verified facts about your VPS. Never add credential-bearing configuration. When introducing a database later, preserve the narrow lookup contract instead of replacing it with arbitrary SQL or shell access requested by a model.

// 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 };
}

Make the schema executable

Use a Zod enum for noteId and a strict object to reject extra path or command fields. Descriptions explain purpose but cannot replace validation. The output schema defines id and text for structuredContent checks. Resolve schema-handler disagreements before involving a model. Test noteId:safety positively, and reject ../../secret, missing identifiers and extra commands. Also test the pure function independently: SDK validation should not be the only barrier against unsupported identifiers if another caller later reuses your code.

Avoid arbitrary path APIs

Even a read_file tool can expose SSH keys or .env contents. A first MCP server needs no arbitrary path argument. Future file access should map approved IDs to explicit paths, resolve real paths and symlinks, enforce root containment and bound reads. A raw string prefix check is insufficient. Operating-system permissions should independently prevent secret access. This implementation uses no filesystem access, so a traversal-shaped identifier must fail validation without attempting to open any file at all.

Practical assignment

Practice: Catalog and argument schema

Continue to learning

Course outline

  1. Read-only MCP contract
  2. Catalog and argument schema
  3. Register a real tool and resource
  4. Stdio, HTTP and version negotiation
  5. Protocol tests without a model
  6. Client connection and acceptance