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 and the ActiveTerp recreation portal, the University Senate, and the campus directory.

Development

pnpm install
pnpm dev        # run the server on stdio with hot reload
pnpm inspect    # open the MCP Inspector against the dev server
pnpm test       # run tests
pnpm check      # typecheck + lint + format check + knip (dead code) + tests
pnpm 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)

activeterp

activeterp-member (login)

athletics

calendar

dining

directory (login)

elms (login)

go (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)

An upstream with a public side and a signed-in side becomes two classes in sibling folders (testudo/soc and testudo/portal, activeterp/catalog and activeterp/member), with anything they share in a common.ts beside them.

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), dates.ts (printed dates to YYYY-MM-DD). 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.postForm() and this.postJson() send what the site's own forms and scripts send, and this.request() is the general form. A query value may be an array (the key repeats), and every request times out after a minute. HTTP errors (with the server's own message when it gives one), network failures and output-schema mismatches become tool error results automatically; override handleError() to customise that.
• An anonymous flow that still needs a server session (a search kept in the session, a token tied to a cookie) overrides fetcher with cookieFetcher() from src/lib/http.ts. A value read once per signed-in session (a CSRF token, an account id) goes through perSession() from src/lib/session.ts.

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' },
    // Optional: a button to click on loginUrl when its form carries a per-page token the
    // browser must send (an anti-forgery token, a provider field).
    // loginClick: 'button.btn-sso-shibboleth',
    // Optional: when a response means the session is gone. Default: 401, or a redirect off
    // the app's origin or to signInPage.
    // expired: (response, requested, landed) => response.status === 403 || landed.pathname === '/expired',
    // Optional: the app's own sign-in page, for apps that bounce an expired session there
    // (same origin, HTTP 200) instead of answering 401 or redirecting to the IdP.
    // signInPage: (url: URL) => url.pathname === '/shortener/signin',
  };
}

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