# librus-mcp

Local, read-only MCP server for a Librus Portal account. It uses the Portal login flow to obtain a short-lived Librus API token for a chosen Synergia account.

## Security model

- Credentials are read from `LIBRUS_EMAIL` and `LIBRUS_PASSWORD` only.
- Cookies and tokens are kept in memory and are discarded when the process exits or `librus_logout` is called.
- The server permits HTTPS requests only to `portal.librus.pl` and `api.librus.pl`.
- It exposes an allowlist of read-only API resources; it cannot send messages, mark notices read, or submit arbitrary requests.
- It deliberately writes no request, response, credential, token, or API payload to stdout/stderr. Stdout is reserved for MCP protocol traffic.

Do not put credentials in `package.json`, MCP configuration checked into git, or a tracked `.env` file.

## Install and build

```bash
cd /home/xadix0wy/librus-mcp
npm install
npm run build
```

## Configure an MCP host

Use environment variables in the host's private configuration or secret store:

```json
{
  "mcpServers": {
    "librus": {
      "command": "node",
      "args": ["/home/xadix0wy/librus-mcp/dist/index.js"],
      "env": {
        "LIBRUS_EMAIL": "your-email@example.com",
        "LIBRUS_PASSWORD": "your-password"
      }
    }
  }
}
```

`LIBRUS_CLIENT_ID` is optional. The default is the public client ID from the legacy Librus mobile flow. It is not treated as a secret.

## Tools

- `librus_profiles`: lists the Synergia accounts linked to the Portal account.
- `librus_get`: reads grades, attendance, timetable, homework, notices, school information and other supported API resources. Pass `account_login` from `librus_profiles`.
- `librus_logout`: clears all in-memory authentication material.

The Portal can require reCAPTCHA or an account action. The server stops with a clear error in that case; complete the required action directly at `https://portal.librus.pl` or in the official app, then retry.

## Compatibility

This relies on an undocumented Portal/API flow observed in the legacy Szkolny Android source. Librus can change or restrict it without notice. It is intended only for the account owner and should be used in accordance with Librus terms and school policy.