Umd Mcp

umd-mcp

An MCP server exposing University of Maryland data: courses and grades (PlanetTerp, the Schedule of Classes, the Testudo student portal, ELMS), dining menus and news, Shuttle-UM routes and timetables, athletics, the campus calendar, TerpLink organizations and events, RecWell facilities, the University Senate, and the campus directory.

Development

pnpm installpnpm dev        # run the server on stdio with hot reloadpnpm inspect    # open the MCP Inspector against the dev serverpnpm test       # run testspnpm check      # typecheck + lint + format check + knip (dead code) + testspnpm build      # emit dist/

Using with a client

Add to your MCP client config (e.g. Claude Desktop, Claude Code):

{  "mcpServers": {    "umd": {      "command": "node",      "args": ["/path/to/umd-mcp/dist/index.js"]    }  }}

Signing in

Some UMD services need a signed-in user. The login tool opens a browser window that umd-mcp controls (Chrome or Edge, on its own profile under ~/.umd-mcp/browser-profile) at the UMD Shibboleth IdP, with a CAS service URL pointing at a one-shot listener on 127.0.0.1. Once the user finishes signing in (including Duo) the IdP redirects back with a service ticket, which the server validates against serviceValidate to learn who signed in.

While that single sign-on session is fresh, login then visits every connected service (see below) in the same window so each app can set its own session cookie, and copies those cookies into a per-service Session. The window closes by itself. The profile persists, so later logins are usually silent. logout forgets everything and clears the profile's cookies.

Why a browser: CAS only issues a ticket for the service named in the login URL, and each app turns its ticket into a cookie for its own origin. The only way for the server to hold those cookies is to be the browser that receives them.

The callback host is localtest.dev.umd.edu, a public DNS name UMD IT publishes that resolves to 127.0.0.1. It is used instead of localhost because the IdP sits behind an AWS WAF that rejects any service URL containing localhost with a 403.

Environment variables:

• UMD_MCP_BROWSER: path to a Chromium executable, if Chrome or Edge are not installed.
• UMD_MCP_PROFILE_DIR: where to keep the browser profile.
• CANVAS_TOKEN: a Canvas personal access token (from ELMS profile settings). When set, the ELMS tools use it as a bearer token and need no browser sign-in.

Tools

Tool names are <integration>_<method>, except the sign-in tools. Integrations marked "(login)" need the login tool first; the rest work anonymously.

shibboleth

planetterp

nutrition

testudo-soc

testudo (login)

athletics

calendar

dining

directory (login)

elms (login)

recwell

senate

terplink

transportation

Adding an integration

An integration is a folder under src/integrations/ that wraps one upstream and declares the tools it contributes:

src/integrations/example/  index.ts      # the Integration subclass, and nothing else  schemas.ts    # input schemas, exported output schemas, and their inferred types  mappers.ts    # Raw* types for the upstream payloads and the to*() functions (parsers.ts when scraping HTML)  NOTES.md      # what was learned crawling the upstream: endpoints, shapes, quirks, dead ends

Subclass Integration from src/integrations/base.ts, declare name and baseUrl, and mark each tool method with @tool(). The MCP tool name is <name>_<method> (pass name in the spec to override). Then add the class to createIntegrations() in src/integrations/index.ts.

import { z } from 'zod';import { Integration, tool } from '../base.js';import { type Building, buildingSchema } from './schemas.js';
export class Example extends Integration {  readonly name = 'example';  readonly baseUrl = 'https://example.umd.edu/api';
  @tool({    title: 'Get campus building',    description: 'Look up a campus building by its code. No login needed.',    input: { code: z.string().describe('Building code, e.g. "IRB"') },    output: buildingSchema.shape,  })  async get_building({ code }: { code: string }): Promise<Building> {    return this.get<Building>(`buildings/${code}`);  }}

Everything in the spec is advertised to the client so the model knows what a tool does, what it takes, and what it returns before calling it:

• description and title are passed through; annotations are merged over the defaults (read-only, open-world).
• input becomes the tool's inputSchema. The decorator checks at compile time that the method's parameter type accepts the parsed shape.
• output (optional) becomes the tool's outputSchema. The decorator checks at compile time that the method returns a matching object. At runtime the value is validated against the shape and returned both as structuredContent and as a JSON text block for clients that only read text. Fields not in the shape are dropped.

Conventions the existing integrations follow:

• .describe() every input and output field; the text ends up in the JSON Schema the model reads. End descriptions with "No login needed." or "Requires login.".
• Use z.enum wherever the upstream's value set is known, via a CODE: 'value' table and decode() from src/common.ts, so an unexpected upstream value surfaces as a tool error.
• Reuse the shared schemas in src/common.ts (term, courseId, sectionId, weekday, isoDate, pagination, ...) and the helpers in src/lib/: text.ts (blank-to-null trimming, joining), html.ts (HTML to plain text), scrape.ts (cheerio text, links and tables). Reach for an npm package before writing a parser by hand.
• this.get(path, query) fetches JSON and this.getText() HTML relative to baseUrl; this.request() is the general form for POSTs. HTTP errors and output-schema mismatches become tool error results automatically; override handleError() to customise that.

Integrations behind single sign-on

If the upstream needs a UMD login, declare a service on the integration. login then signs in to it along with everything else, and this.get() / this.getText() / this.request() carry the app's cookies. Before the user signs in, or after the app rejects the session, they throw AuthRequiredError, which becomes a tool error telling the model to call login.

export class StudentPortal extends Integration {  readonly name = 'testudo';  readonly baseUrl = 'https://app.testudo.umd.edu/services';  override readonly service = {    name: 'testudo',    // Page that sends an anonymous browser through single sign-on and back into the app.    loginUrl: 'https://app.testudo.umd.edu/main/',    // Optional: when the browser counts as signed in. Default is "same origin as loginUrl".    signedIn: (url: URL) => url.hash.startsWith('#/main'),    // Optional: fields to POST to loginUrl for apps whose sign-in is a button, not a redirect.    // loginForm: { login: 'Log in' },  };}

Project layout

src/  index.ts             # stdio entrypoint  server.ts            # createServer(): registers every integration  common.ts            # shared zod schemas and small helpers (terms, course ids, weekdays, enums)  lib/                 # HTTP helper, sign-in hub (auth.ts), per-service Session, browser driver,                       # text/HTML/scraping helpers  integrations/    base.ts            # Integration base class, @tool decorator, result helpers    index.ts           # createIntegrations(): instantiate integrations here    <name>/            # one folder per integration (see above)    testudo/soc/       # public Schedule of Classes    testudo/portal/    # student portal (login)    grouper/NOTES.md   # research only; Grouper is VPN-only and not implemented