agh-skos-mcp
# agh-skos-mcp
MCP server for [SkOs](https://skos.agh.edu.pl) — the AGH University staff directory.
No API key, no login.
## Tools
| Tool | Arguments | Returns |
|---|---|---|
| `search_people` | `nazwisko`, `imie`, `email`, `pokoj`, `telefon` (prefix, case-insensitive) · `tytul`, `id_status`, `grupa`, `stanowisko`, `funkcja`, `jednostka`, `pawilon`, `cialo` (id or Polish label) · `limit` | `total`, `results[]` (name, title, url, units), `person` — full profile, set only when exactly one person matched |
| `get_person` | `person` — slug or url, e.g. `krzysztof-bzowski-7674` | id, name, title, emails, phones, www, workplaces (unit, job, group, function, room), collegial bodies |
| `list_filter_options` | `field`, `contains` | `[{value, label}]` |
An ambiguous label raises an error listing the candidates. A query with no filters is rejected.
## Add to Claude Code
Requires [uv](https://docs.astral.sh/uv/).
`.mcp.json` in the project root:
```json
{
"mcpServers": {
"agh-skos": {
"command": "uvx",
"args": ["--from", "git+https://github.com/kbzowski/agh-skos-mcp", "agh-skos-mcp"]
}
}
}
```
Or via CLI:
```bash
claude mcp add agh-skos --scope user -- uvx --from git+https://github.com/kbzowski/agh-skos-mcp agh-skos-mcp
```
Check with `claude mcp list` or `/mcp`.
## Run over HTTP
The server speaks stdio by default. For a remote setup use the streamable HTTP transport:
```bash
agh-skos-mcp --transport streamable-http --host 0.0.0.0 --port 8000
```
or with Docker, which binds to `127.0.0.1:8000`:
```bash
docker compose up -d --build
claude mcp add agh-skos --transport http http://127.0.0.1:8000/mcp
```
There is no authentication. To reach it from outside, put a reverse proxy with TLS in front of it and accept its public name with `--allowed-host mcp.example.org` (repeatable; see the commented `command` in `compose.yaml`). Requests with any other `Host` header are rejected.
## Development
```bash
git clone https://github.com/kbzowski/agh-skos-mcp && cd agh-skos-mcp
uv sync
uv run ruff check . && uv run ruff format .
uv run mypy
uv run pytest # offline
uv run pytest -m network # against the live directory
```
`uvx` caches its build. To run your working copy:
```bash
claude mcp add agh-skos --scope user -- uv run --directory /path/to/agh-skos-mcp agh-skos-mcp
```
## Implementation notes
- Data comes from the `__NEXT_DATA__` JSON embedded in each rendered page, not from HTML scraping.
- Filter dictionaries come from the site's `/a/select?id=…` endpoint.
- E-mails are stored obfuscated (reversed `<a>` tag, `#` for `@`) and decoded on the way out.
- A search matching exactly one person redirects `/search/` → profile page; `search_people` follows it and returns the full record in `person`.
## License
MIT
TDQS
Scored across 3 tools
Each tool has a clearly separate role: list_filter_options is a helper for enumerating dictionary values, search_people queries the directory, and get_person retrieves a single full profile. The descriptions even explain the intended workflow (use filter options before searching, pass the returned url to get_person), so an agent cannot easily confuse them.
All three names follow a strict verb_noun snake_case pattern (list_filter_options, search_people, get_person) with verbs that match the action performed. No mixed casing or inconsistent verb styles.
Three tools is a tight, purpose-built surface for a read-only directory lookup service: browse vocabularies, search, then fetch details. No redundant or filler tools, and nothing appears artificially split.
The read-only lifecycle (browse filters -> search -> full profile) is fully covered, and the single-match shortcut in search_people avoids a dead end. Minor gaps remain, such as no pagination or batch/export option for large result sets, but agents can work around these by narrowing search filters.