# 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.

```bash
npm install
npm run build
```

The stdio server entry point is:

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

For Codex CLI, register that command:

```bash
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.

## Authentication

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

```bash
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

| Tool | Purpose |
|---|---|
| `ais_auth_status` | Show redacted session status |
| `ais_auth_set_session` | Set username and AccessToken in memory |
| `ais_auth_login` | Login with username/password |
| `ais_auth_verify_otp` | Finish email/SMS OTP login |
| `ais_auth_send_sms_otp` | Request the login OTP by SMS with confirmation |
| `ais_auth_logout` | Clear the in-memory session |
| `ais_password_reset_request` | Send reset email, behind a feature flag and confirmation |
| `ais_password_reset_verify` | Verify a reset token |
| `ais_password_reset_complete` | Complete reset, behind a feature flag and confirmation |
| `ais_password_change` | Change the authenticated account password using the portal cipher |
| `ais_crypto_transform` | Encrypt/decrypt AES, DES, TripleDES, or Rabbit portal payloads |
| `ais_list_features` | Search endpoints/screens by query, domain, role, or risk |
| `ais_get_feature` | Inspect one endpoint or route |
| `ais_get_portal_route` | Return a shareable dashboard screen URL |
| `ais_list_external_portals` | Return the academic services linked by AIS |
| `ais_call` | Invoke any cataloged or API-relative operation |
| `ais_batch_read` | Execute up to 20 non-mutating operations |
| `ais_upload` | Multipart upload with confirmation, path boundary, and size limit |
| `ais_student_profile` | Read and decrypt student profile data |
| `ais_student_fee_status` | Read current-semester fee status |
| `ais_student_fee_details` | Read and decrypt fee details and total |
| `ais_student_semester_records` | Read and decrypt semester history |
| `ais_student_gradesheet` | Prepare the portal request and decrypt gradesheet data |
| `ais_student_transcript` | Read and decrypt the authenticated student's transcript |

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:

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

Example route lookup:

```json
{
  "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](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.

| Variable | Default | Meaning |
|---|---|---|
| `IITR_AIS_USERNAME` | unset | Enrollment/employee/portal username |
| `IITR_AIS_ACCESS_TOKEN` | unset | Existing AIS AccessToken |
| `IITR_AIS_API_BASE_URL` | official `/api/` URL | API base |
| `IITR_AIS_PORTAL_URL` | official portal URL | Dashboard URL base |
| `IITR_AIS_TIMEOUT_MS` | `30000` | Request timeout |
| `IITR_AIS_MAX_RESPONSE_BYTES` | `10485760` | Maximum response size |
| `IITR_AIS_UPLOAD_ROOT` | process working directory | Only local tree allowed for multipart files |
| `IITR_AIS_MAX_UPLOAD_BYTES` | `26214400` | Maximum total bytes per multipart call |
| `IITR_AIS_ALLOW_UNSAFE_URLS` | `0` | Permit calls outside the official API boundary |
| `IITR_AIS_ENABLE_PASSWORD_TOOLS` | `0` | Enable password-reset mutations |
| `IITR_AIS_DEBUG` | `0` | Write startup diagnostics to stderr |

## Verification

```bash
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](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.