Skip to main content
Glama
agh-skos-mcp

agh-skos-mcp

by kbzowski
README.md
# 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

A4.4/5.0

Scored across 3 tools

Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness4/5

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.

Maintenance

ActivityNo data
ResponsivenessOutdated data