IIT Roorkee Academics MCP

A local, role-aware Model Context Protocol server for the official IIT Roorkee Academics/AIS portal at https://academics.iitr.ac.in.

The server was built from a production-bundle audit rather than a short student-only menu scrape. Its checked-in catalog contains:

• 577 backend operations across 23 API domains

• 192 dashboard screens across student, faculty, advisor, DAPC, AAO, DoSW, department, HOD, library, and shared roles

• Login, email/SMS OTP, in-memory session setup, forgot-password, reset-token verification, and password-reset support

• Explicit fee, profile, semester-record, gradesheet, and transcript helpers

• A safe generic caller covering every recovered endpoint, including operations added to the portal later

• Catalog, route, coverage, and session resources plus reusable workflow prompts

Portal authorization is not bypassed. The signed-in IITR account can only use the roles and operations allowed by the portal backend.

Install and build

Requirements: Node.js 20 or newer.

npm install
npm run build

The stdio server entry point is:

node /absolute/path/to/iitr-academics-mcp/dist/index.js

For Codex CLI, register that command:

codex mcp add iitr-academics -- node /absolute/path/to/iitr-academics-mcp/dist/index.js

The server is also compatible with MCP hosts that accept a stdio command. Use node as the command and the absolute dist/index.js path as its argument.

Related MCP server: Nettskjema MCP Server

Authentication

The safest setup is to inject an existing portal session through the launch environment:

export IITR_AIS_USERNAME='your-enrollment-or-employee-id'
export IITR_AIS_ACCESS_TOKEN='your-current-AIS-AccessToken'
node dist/index.js

Do not commit these values or place them in a shared MCP configuration. They are intentionally absent from this repository.

Alternatively, call ais_auth_login, then ais_auth_verify_otp when the portal requires the 5-digit email/SMS OTP. The password and OTP are used only for their individual requests; the resulting token is held only in process memory.

Use ais_auth_status to check the session. It returns authentication source and token-expiry metadata, but never returns the token or decoded account claims.

MCP surface

Resources:

• iitr://catalog/endpoints

• iitr://catalog/routes

• iitr://catalog/coverage

• iitr://session/status

• iitr://catalog/external-portals

Prompts:

• ais-safe-operation

• ais-fee-workflow

Calling an operation safely

1. Call ais_list_features with a focused query.

2. Inspect the selected operation with ais_get_feature.

3. For a read, call ais_call with the required query or JSON body.

4. For a mutation, review the exact endpoint and payload, obtain user confirmation, then set confirmWrite: true.

AIS often uses POST even for reads. The catalog records methods observed in the production client and separately classifies whether an operation mutates state. Seven unused environment constants have an explicit assumed-post method-evidence marker instead of being presented as observed calls.

Example read:

{
  "identifier": "DIRECT_FEE_BASE_URL_GETSTUDENTCURRENTSEMFEES",
  "body": {
    "EnrollmentNo": "YOUR_ENROLLMENT",
    "StSession": "2026-27",
    "Semester": "Autumn"
  }
}

Example route lookup:

{
  "route": "student-acad-fees-page"
}

Security controls

• Requests are restricted to the configured Academics API origin and /api/ prefix by default.

• Authentication follows the portal client exactly: username plus authorization: Bearer <AccessToken>.

• Passwords, OTPs, tokens, cookies, authorization headers, and JWT-looking strings are recursively redacted from tool output.

• Token storage is memory-only.

• Mutating and uncataloged non-GET calls require confirmWrite: true.

• Password mutation tools are disabled unless IITR_AIS_ENABLE_PASSWORD_TOOLS=1.

• Response size and timeout limits are enforced.

• Multipart files must stay under IITR_AIS_UPLOAD_ROOT and the total size limit.

• Multipart symlinks are resolved before the upload-root check.

• Authenticated requests and uploads reject redirects so credentials and files cannot be forwarded to another origin.

• Custom headers are allowlisted; callers cannot replace authorization or cookie headers.

See SECURITY.md for the trust model and configuration controls.

Configuration

Copy .env.example only as a reference; this project does not automatically read .env files.

Verification

npm run typecheck
npm test
npm run build
npm audit

The completion audit asserts that every recovered endpoint resolves through ais_call, every recovered screen resolves through ais_get_portal_route, all URLs remain under the official API origin, method evidence is explicit (observed or assumed-post), and all catalog identifiers are unique.

For the domain-by-domain breakdown, see COVERAGE.md.

Scope and portal changes

The catalog is a snapshot of the production Angular client audited on 10 July 2026. ais_call accepts a safe API-relative path as an escape hatch for new backend operations before the catalog is refreshed. The production portal remains the source of truth for accepted payload fields and account permissions.