# osiris-mcp-server

An MCP server exposing Dutch university Osiris course catalogs as tools. It
reads from the public, read-only Osiris Student API that universities publish
at `https://<host>.osiris-student.nl/` (e.g. TU/e, TU Delft, Radboud,
Twente, Wageningen).

## Quick start

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).

```bash
uv sync
uv run osiris          # run the MCP server over stdio
```

The server targets TU/e (`tue`) by default and accepts an `institution` code
per call, e.g. `tue`, `tudelft`, `rug`, `ut`:

```text
search_courses("4DM00", institution="tudelft")
get_course("4DM00", institution="tue")
```

## Usage with MCP clients

Add the server to your MCP client configuration.

```json
{
  "mcpServers": {
    "osiris": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/osiris-mcp-server", "osiris"]
    }
  }
}
```

For clients that support environment variables (e.g. `OSIRIS_LANGUAGE`,
`OSIRIS_TIMEOUT`), pass them via the `env` key.

## Tools

| Tool | Description |
| --- | --- |
| `list_faculties()` | Faculties/departments, code + name |
| `list_course_types()` | Course types (Bachelor College, Graduate School, ...) |
| `get_available_years()` | Academic years in the catalog |
| `get_categories()` | Course categories/levels |
| `get_blocks()` | Period/block tokens (e.g. `1`, `GS1`, `JAAR`) |
| `get_timeslots()` | Timeslots (e.g. `A`, `B1`) |
| `get_units()` | Coordinating units (capaciteitsgroep/sectie) |
| `get_lecturers()` | Lecturer names |
| `get_languages()` | Instruction languages |
| `get_education_types()` | Education types (e.g. `Challenge based`) |
| `get_course_structure()` | Sections/fields a course contains |
| `list_courses(faculty, course_type, ...)` | `{code, id, name, year}` list for a faculty + type |
| `get_course(code, year)` | Course header (id, code, name, ECTS, course_type, owner, level, year, blocks) |
| `get_course_details(code)` | Full detail: content, exams, lecturers, materials, deep link, ... |
| `get_course_details_by_id(id)` | Full detail by internal course id |
| `search_courses(keyword, ...)` | Full-text search with filters |
| `search_minors(keyword, ...)` | Search minors (coherent packages, certificates) |
| `get_minor_details(code)` | Full minor detail: study programme, entrance requirements, ... |
| `get_minor_details_by_id(id)` | Full minor detail by internal minor id |

The `list_courses` and `search_courses` tools accept the same filters; every
one is optional except `faculty` for `list_courses`:

| Filter | Description |
| --- | --- |
| `faculty` | Faculty code (e.g. `EE`) or full name |
| `course_type` | Course-type code or full name (default `BC`) |
| `category` | Category/level (e.g. `Introductory`, `Advanced`) |
| `year` | Start year (`2025`) or range (`2025-2026`) |
| `period` | Block token (e.g. `1` for bachelor Q1, `GS1` for graduate Q1) |
| `timeslot` | Timeslot code, prefix match (e.g. `A` matches `A1`, `A2`, ...) |
| `unit` | Coordinating unit (capaciteitsgroep/sectie) |
| `lecturer` | Lecturer name |
| `language` | Instruction language (name or 2-letter code) |
| `education_type` | Education type (e.g. `Challenge based`) |
| `available` | Only courses with places available (`true`) or not (`false`) |

Search results include a `blocks` list per course with the offering periods:
block token, dates, timeslots, location and availability — plus `lecturers`,
`education_type`, faculty and coordinating unit.

`search_minors` accepts the same `year`, `faculty` and `education_type` filters;
results include `startmoments` (academic year + block the minor can be started)
and `study_programs` (degree programmes the minor serves).

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `OSIRIS_RELEASE_VERSION` | *(unset)* | Optional search-index header |
| `OSIRIS_MANIFEST` | *(unset)* | Optional search-index header |
| `OSIRIS_LANGUAGE` | `EN` | Content language (`NL` or `EN`) |
| `OSIRIS_TIMEOUT` | `30` | HTTP timeout in seconds |

Most institutions serve a sensible default index without `OSIRIS_RELEASE_VERSION`
or `OSIRIS_MANIFEST`. Only set them to pin a specific Elasticsearch index
version (e.g. one extracted from a university's Osiris app bundle).

## Development

```bash
uv run pytest           # unit tests (offline)
uv run pytest -m e2e    # live tests against the configured catalog (default TU/e)
uv run ruff check .
uv run ruff format --check .
uv run mypy src
```

## License

The code is MIT licensed; see [LICENSE](LICENSE).

The course data comes from the relevant university's Osiris API and is owned
by that institution. This project is not affiliated with or endorsed by any
university, and the MIT license does not cover the underlying course data.