MCP server project (TypeScript) · Chapter 3 of 12
Tools with schemas
By the end of this chapter Parda's server offers five tools: find_showtimes, see_seats, hold_seats, book_seats and list_my_bookings. Each argument has a type, a description and limits that the assistant reads in tools/list and that the SDK checks before your code runs, and each result has a shape of its own. An assistant can find Saturday's Ghar Wapsi Express, see the free Middle seats, hold E1 and E2 and book them for Neha (booking 2, ₹400), and cannot hold 9 seats at once. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: What the server offers
- 3 tasks
- TypeScript
- In the all labs plan
The first 2 chapters of MCP server project (TypeScript) are free. This one comes with the all labs plan.
Why you need this
The October integrations went wrong in small ways that cost real time. One sent the date as "7 Nov", and the booking API refused it. One wanted "E1 and E2" for a member and sent the seat ids 1 and 2, because the API holds seats by id; ids 1 and 2 are A1 and A2, in the front row, and the member's evening started with a call to Datta. And when the film club asked for "seats for all of us", an integration tried 9 seats in one hold, got the API's refusal, and tried again with 9 different ones.
Chapter 2's server cannot prevent any of that. Look at what an assistant reads about find_showtimes' date today: {"type":"string","description": "The day, YYYY-MM-DD (Pune)"}. Any string at all. And there is only one tool: an assistant can find a showtime but cannot see a seat or book one. Sayali wants the server to say the rules, so a model can follow them, and to keep them, so a model that does not follow them is stopped before anything is held or booked.
What you build: 3 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
schemas.ts: the arguments' and results' shapes
Write the zod shapes in src/mcp/schemas.ts. Arguments, each with a .describe(): Day is z.iso.date(), Title a string of at most 60 characters, PartOfDay z.enum of morning, afternoon, evening and night, ShowtimeId, MaxPrice and BookingId ints greater than 0, SeatClass a string of at most 20 characters, SeatLabels an array of 1 to 6 strings each matching /^[A-Z]{1,2}[0-9]{1,2}$/. Results, as z.object with keys in this order: Showtime (showtime_id, starts_at, venue, prices, name), SeatRow (row, seat_class, price, free, seats), Seats (showtime_id, free, rows), Hold (showtime_id, seats, held_until) and Booking (booking_id, status, seats, total, showtime_id, name).
The Check reads the input schemas the SDK writes from your shapes in tools/list (find_showtimes' date has the date format and a description; part_of_day is an enum of four; hold_seats' seats has at most 6 items), checks values against each shape, and reads the result shapes' keys and see_seats' output schema.
- Task 2
tools/seats.ts: see_seats
Write seeSeats({ showtime_id, seat_class, max_price }, member) in src/mcp/tools/seats.ts. As the member (apiAs), it gets GET /showtimes/<id>/seats and returns { showtime_id, free, rows }: for each row with at least one free seat (status 'free'), of seat_class and at max_price or less when they are given, { row, seat_class, price, free: how many, seats: ranges(their labels) }; free is the sum.
The Check holds E1 and E2 of showtime 18 as Pranav, then calls see_seats through an MCP client as Neha: every row (410 free seats, row E is E3-E24), at max_price 180 (no Balcony), the Balcony only (rows P to S), and showtime 999 (a tool error).
- Task 3 · interview question
Interview: tools/bookings.ts, hold, book, list
Write holdSeats, bookSeats and listMyBookings in src/mcp/tools/bookings.ts. holdSeats looks the labels up in the seat map, throws ToolError "Showtime <id> has no seat <labels>. Its rows are <rows>; see_seats lists the free seats." for labels the showtime does not have, then POST /holds { showtimeId, seatIds } and returns { showtime_id, seats, held_until: puneTime(expiresAt) }. bookSeats does POST /bookings { showtimeId } and returns bookingRow(booking, showtimeNames). listMyBookings returns { bookings: bookingRow of each of GET /bookings/me }.
The Check holds F1 and F2 of showtime 18 through an MCP client as Neha, asks for a seat Z9, sends 9 seats (refused before your code runs), books (booking 2, ₹400), books again (the API's no_holds), and lists Neha's and Pranav's bookings.
Nikhil will ask: an assistant asked to hold 9 seats. Which code stopped it, and what did the assistant read back?
What you will learn
- JSON schema: the part of tools/list that describes a tool's arguments, and what a model learns from it.
- zod shapes as schemas: z.enum, z.iso.date(), .int(), .positive(), .max(), arrays with limits, .describe() and .optional(), and the JSON schema the SDK writes from each.
- What the SDK checks before a tool runs: every call's arguments against the same shape; a bad one never reaches your code.
- Output schemas: a result shape, the schema clients see, and the SDK checking your own result too.
- Tools that change something: holding seats by label when the API wants ids, booking, and letting the API's refusals through.
More in What the server offers
Build "Tools with schemas" yourself
Parda wants AI assistants like Claude Desktop to book seats for its members, safely. You build the MCP server that lets them, and only as the member who allowed it. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
The first 2 chapters of MCP server project (TypeScript) are free. This one comes with the all labs plan.