umich-dining-mcp
[npm]
[CI]
[Live site]
An MCP server for the dining halls of the University of Michigan in Ann Arbor. It answers
what is being served, which dishes are vegan or halal, what a dish contains, how many
calories it has, and when each hall is open.
Every answer is read live from dining.umich.edu. Pages are kept
in memory for a few minutes so that ten questions cost one visit, but nothing is written to
disk and no menu is mirrored.
Install
or run it without installing anything:
Claude Code
Cursor
~/.cursor/mcp.json:
VS Code
.vscode/mcp.json:
Any other client that starts MCP servers over stdio takes the same mcpServers entry as
Cursor, with npx -y umich-dining-mcp as the command.
Tools
Resources
Example questions
The response contract
The rows of search_dishes and filter_dishes carry small integers instead of names, and a
key block at the top of the response maps every code back to its slug. The key lists only
what that response uses. The codes are frozen for the life of the contract.
A row is an array; its fixed positions are named in each tool description and the
variable nutrient tail is carried once per response as nutrients. The member names of a
named row are two and a half times the data of the row, repeated on every row: a named row
cost 216 bytes, an array row costs 72.
- The halls are 1..10 in the order of the registry below, the meals are 1 (Breakfast),
2 (Brunch), 3 (Lunch) and 4 (Dinner), the allergens are 1..15 and the six boolean traits
are 1..6 (glutenfree, halal, kosher, spicy, vegan, vegetarian). A meal label the site
invents takes the next free code, from 5. The stations have a frozen vocabulary too: the
same station carries the same code in every response, so a code can be remembered.
mhealthyTier is 1 (Nutrient Dense Low) to 5 (Nutrient Dense High). The scale is fixed
and described in the tool descriptions and in umich://taxonomy.
- A row carries the carbon tier (
carbonFootprint) only when the call constrains it with
max_carbon or sorts by carbonFootprint; otherwise it is left out to keep the row small.
- The
traits array carries the six boolean traits only; the density tier is lifted into
its own numeric field.
- The
units map gives the unit of every nutrient the response returns. A micronutrient
is an amount like every other nutrient: the site publishes the percent of the Daily
Value, and the row carries the amount that percent stands for — 15 %DV of an 18 mg
Daily Value of iron is 2.7 in mg. The percent is still available under its own name,
%DV, in a threshold.
- A search or a filter takes the halls it covers: one hall, several halls, or no hall at
all for every one of them. The rows come back in the order that was asked for, and
limit takes the first of them: the default is 50 rows, and the answer says how many
matched and how to see the rest.
- The row always carries the calories and the serving size. Every other nutrient, the
sodium included, is asked for by name with
include_nutrients — the sodium has nothing
that makes it more interesting than the protein. A nutrient a filter constrained is
always returned, whether or not it was asked for.
- A single-day response carries
date; a range response carries dateRange and each row
carries the dates it appeared on.
- A dish without a published value is reported as
null, never as zero. A trace or a
< value is not a value at all.
get_menu and the sweep tools return the same compact row, so a row means the same thing
wherever it is read. get_item_nutrition is the tool that returns the raw nutrition panel,
of one dish.
A whole menu is far smaller this way: the menu of South Quad went from 60,266 bytes to
8,817, and the menu of Bursley from 42,141 to 6,573. The panel of a single dish is one
call to get_item_nutrition.
The halls
The id is what get_menu, get_hours and search_dishes expect. The code of a hall is
its position in this list, counted from one.
Dates
The site publishes menus from three days ago to fourteen days ahead. Outside that range
the site does not answer with an error, it answers with a different day's menu, so a date
outside the range is refused before anything is fetched, with a message that names the range
the site offers. When the page states which day it rendered, that day is compared with the
one you asked for and a mismatch is an error rather than a wrong answer.
A range is asked for with from and to; to omitted means the last published day. The
two cannot be combined with date. A range that does not fit in one call is read in
windows with offset; the coverage block of the answer names the offset of the next
window.
Time
Every time the server reports is campus time: the time zone of Ann Arbor,
America/Detroit, which is Eastern Standard Time and Eastern Daylight Time in the summer.
The day the site publishes, the mealtimes, and the "today" of a cache entry are all read in
that zone.
The zone of the machine the server runs on does not matter. A server in Chicago and a server
in UTC answer the same question the same way, and the test suite checks that by running the
meal selection under several host zones. Set UMICH_DINING_TIMEZONE only to point the
server at a mirror of the site in another zone.
Filters
A constraint on a nutrient excludes the dishes that publish no value for it: an unknown
value is never a zero.
The cost of a range
A range query reads one page per hall per day, and the site is fetched at most two pages a
second. A query that needs more upstream pages than UMICH_DINING_MAX_RANGE_FETCHES
(default 12) returns the rows it could serve and a coverage block that says how much was
served:
The numbers add up: every page the query asked for was cached, fetched, left pending or
failed. nextOffset is where the rest of the range begins, so a wide range is read in
windows: ask again with offset set to that number.
The persistent cache exists for this: the pages of the published window are kept on disk and
warmed in the background, so a range query is usually served without touching the site.
Allergens
Allergen data is only as good as the site. The menu page flags the allergens the kitchen
reported for a dish, but it does not distinguish "contains" from "may contain", there are
no ingredient lists, and a missing flag is not an absence of the allergen. The site's own
guidance is: "Look for the signs posted near each food serving area for a list of menu
options with allergens highlighted in red." "Gluten Free" means the dish is made without
gluten, not that it is safe for someone with coeliac disease. Dedicated gluten-free
pantries exist at South Quad, East Quad, Mosher-Jordan and Bursley.
The caveat is in the description of every tool that returns allergen data and in
umich://taxonomy. A response that carries allergens repeats one line reminding the reader
to resolve the codes; the long caveat is not repeated in every body. No tool ever claims
that a dish is safe.
Two further points about the traits, because the site is careful about them: a vegan dish is
reported as vegetarian as well, since the site keeps the two apart, and no other trait
implies another (halal does not imply vegetarian, and neither does kosher).
Configuration
How it treats the site
dining.umich.edu is somebody else's website, so the server stays gentle with it:
- Two requests in flight, 500 ms apart at most. The limit is global to the process.
- A cache with in-flight de-duplication. Ten questions about the same hall cost one
request. Today's menu is cached for 15 minutes, a future menu for 6 hours, a past menu for
24 hours and the weekly hours for 24 hours.
- Stale on error. If the site cannot be reached and a cached copy exists, the copy is
served and marked as stale instead of failing the question.
- One User-Agent. The site answers HTTP 200 to a small set of clients only;
python-requests/2.32.3 is the one that has been measured to work, while a generic fetch
agent and a headless browser both get 403. It is not the server's real identity, which is
why it is configurable.
Occupancy
get_dining_occupancy reports real-time fullness for the halls that carry
sensors (Bursley, East Quad, South Quad, Mosher-Jordan, Twigs at Oxford):
It returns the current count, daily patron flow, total capacity, percent full,
and the time of the reading. A hall with no sensor is simply omitted.
Short forms
Hall names, nutrients, and traits accept short, case-insensitive aliases:
- Halls:
mojo, south, east, lawyers, cook, twigs, wovlerine, ...
- Nutrients:
cals, kcals, carbs, fiber, protein/prot, na/salt, ...
- Traits:
gf, veg.
Descriptions are unchanged; the server resolves the alias before validating.
Data source
Menus, hours, locations, nutrition, and occupancy are read from the U-M dining
mobile API, with the public site scraper retained as a fallback. Answers are
still read live and cached for a few minutes.
Contributing
Pull requests are welcome. The test suite, the fixtures and the release process are
described in CONTRIBUTING.md.
License
MIT, see LICENSE.