Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .env.sample
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,8 @@ UOS_MCP_PASSWORD="secret"
# If set, the server runs on HTTP transport instead of stdio.
# UOS_MCP_SERVER_PORT="8080"
# UOS_MCP_SERVER_HOST="127.0.0.1"

# Path to the pre-scraped people-directory JSON file used to answer
# uos_people_search (produced by `mcp-uos-scrape-people`). Required for
# the server to start; defaults to ./data/people.json.
# UOS_MCP_PEOPLE_DATA_PATH="./data/people.json"
79 changes: 69 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,14 +94,70 @@ The server will be available at `http://127.0.0.1:8000/mcp`.

### MCP Tools

The server exposes four tools:
The server exposes three tools:

| Tool | Description |
|-----------------------|-------------------------------------------------------------------|
| `uos_search` | Search the Osnabrück University website for content |
| `uos_fetch` | Fetch page content from a URL and return it as markdown |
| `uos_people_search` | Search for people employed at the university by name |
| `uos_person_details` | Fetch full contact details for a person using their details URL |
| `uos_people_search` | Search for people by name; returns full contact details inline |

`uos_people_search` answers from a local pre-scraped snapshot (see
[People Search](#people-search) below) rather than querying the live
website.

## Scraping the People Directory

The Personensuche only supports on-demand name search, which isn't suitable for building a full
directory. `mcp-uos-scrape-people` walks the public A-Z listing instead, fetches full contact details
for every person, and writes the result to a JSON file:

```bash
mcp-uos-scrape-people
```

The endpoints scraped here (the alphabetical listing and person detail pages) are public, so no
credentials are required. The output file has the shape:

```json
{
"scraped_at": "2026-07-14T12:00:00+00:00",
"count": 5000,
"people": [
{ "name": "...", "department": "...", "address": "...", "room": "...",
"phone": "...", "fax": "...", "email": "...", "website": "...", "source_url": "..." }
]
}
```

This script has no built-in scheduler; run it periodically via an external cron job or systemd timer,
e.g.:

```
0 3 * * * /path/to/venv/bin/mcp-uos-scrape-people >> /var/log/mcp-uos-scrape.log 2>&1
```

Note: the package currently loads the people snapshot at import time, so on a fresh
install `mcp-uos-scrape-people` itself will not start while the data file is missing.
Create an empty stub once before the first scrape:

```bash
mkdir -p data && echo '{"people": []}' > data/people.json
```

## People Search

`uos_people_search` always answers from the JSON file written by
`mcp-uos-scrape-people` (path taken from `UOS_MCP_PEOPLE_DATA_PATH`) rather
than querying the live website, and returns full contact details inline
for every match (case-insensitive substring match against the name).

The data file is loaded once at startup; a missing or unreadable file is a
fatal startup error — the server won't run without a scraped snapshot in
place. To pick up a fresh scrape without restarting the server, send it
`SIGHUP` (e.g. `kill -HUP <pid>`) — this reloads the JSON file in place. If
the reload fails (file missing or corrupt at reload time), the server logs
the error and keeps serving the previously loaded data.

## Running the Test Script

Expand All @@ -123,13 +179,15 @@ The package can be configured using environment variables. You can either set th

### Environment Variables

| Variable | Description | Default |
|------------------------|----------------------------------------------------|---------------------------|
| `UOS_MCP_USERNAME` | Username of UOS account | `None` (required) |
| `UOS_MCP_PASSWORD` | Password of UOS account | `None` (required) |
| `UOS_MCP_SKIP_LOGIN` | Skip authentication (public content only) | `false` |
| `UOS_MCP_SERVER_HOST` | Host for HTTP transport | `127.0.0.1` |
| `UOS_MCP_SERVER_PORT` | Port for HTTP transport | `None` (enables HTTP mode)|
| Variable | Description | Default |
|----------------------------------|----------------------------------------------------|----------------------------|
| `UOS_MCP_USERNAME` | Username of UOS account | `None` (required) |
| `UOS_MCP_PASSWORD` | Password of UOS account | `None` (required) |
| `UOS_MCP_SKIP_LOGIN` | Skip authentication (public content only) | `false` |
| `UOS_MCP_SERVER_HOST` | Host for HTTP transport | `127.0.0.1` |
| `UOS_MCP_SERVER_PORT` | Port for HTTP transport | `None` (enables HTTP mode) |
| `UOS_MCP_PEOPLE_DATA_PATH` | Data file for `uos_people_search` and the scraper | `./data/people.json` |
| `UOS_MCP_SCRAPE_DELAY_SECONDS` | Delay between requests in `mcp-uos-scrape-people` | `0.3` |

### Using a .env File

Expand All @@ -147,6 +205,7 @@ mcp-uos/
├── mcpuos/ # Package directory
│ ├── __init__.py # Package initializer
│ ├── website.py # Core functionality (UOSWebsiteClient)
│ ├── people_data.py # PeopleDataStore for scrape mode
│ ├── mcp_server.py # MCP server implementation
│ └── __main__.py # MCP server entry point
├── tests/ # Test scripts (outside package)
Expand Down
58 changes: 17 additions & 41 deletions mcpuos/mcp_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@
from fastmcp import FastMCP

from mcpuos import UOSWebsiteClient
from mcpuos.models import SearchResults, PersonSearchResults, PersonDetails
from mcpuos.models import SearchResults, PersonDetailsResults
from mcpuos.people_data import PeopleDataStore, install_reload_handler


# Create the FastMCP server instance
Expand All @@ -29,14 +30,19 @@
Set UOS_MCP_SKIP_LOGIN=true to skip authentication and access only public content.

Use the uos_people_search tool to search for people employed at the university.
Use the uos_person_details tool to retrieve full contact details for a person.
It answers from a local pre-scraped snapshot (UOS_MCP_PEOPLE_DATA_PATH) and
returns full contact details inline for every match; there is no separate
"person details" tool.
""",
)


# Initialize the UOSWebsiteClient
_client = UOSWebsiteClient()

_people_store = PeopleDataStore()
install_reload_handler(_people_store)


@mcp.tool(
name="uos_search",
Expand Down Expand Up @@ -84,55 +90,25 @@ def uos_fetch(
@mcp.tool(
name="uos_people_search",
description=(
"Search for people employed at the Osnabrück University. "
"Returns a list of matches with names and detail URLs. "
"Pass a details_url to uos_person_details to get full contact information."
"Search for people employed at the Osnabrück University using a locally "
"cached directory snapshot. Returns full contact details directly for "
"every match."
),
)
def uos_people_search(
query: Annotated[str, Field(description="Name or partial name to search for.")],
) -> PersonSearchResults:
) -> PersonDetailsResults:
"""
Search for people employed at the Osnabrück University.
Search the locally cached people directory.

Args:
query: Name or partial name to search for.

Returns:
A PersonSearchResults object containing:
- results: List of PersonSearchResult objects with name and details_url
A PersonDetailsResults object containing:
- results: List of PersonDetails objects with full contact details
- query: The search query that was performed
- total_count: Total number of people found
"""
return _client.people_search(query)


@mcp.tool(
name="uos_person_details",
description=(
"Fetch full contact details for a person at the Osnabrück University. "
"Pass the details_url returned by uos_people_search."
),
)
def uos_person_details(
url: Annotated[str, Field(
description=(
"The details_url from a uos_people_search result. "
"Must start with https://www.uni-osnabrueck.de/kontakt/personensuche/personendetails"
)
)],
) -> PersonDetails:
"""
Fetch full contact details for a person at the Osnabrück University.

Args:
url: The details_url from a uos_people_search result.

Returns:
A PersonDetails object with all available contact fields including
name, department, address, room, phone, fax, email, and website.

Raises:
ValueError: If the URL does not point to the person details endpoint.
"""
return _client.people_details(url)
matches = _people_store.search(query)
return PersonDetailsResults(results=matches, query=query, total_count=len(matches))
18 changes: 9 additions & 9 deletions mcpuos/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -41,16 +41,9 @@ class SearchResults(BaseModel):


class PersonSearchResult(BaseModel):
"""Represents a single result from a people search."""
"""Represents a single result from a people search (used internally while scraping)."""
name: Annotated[str, Field(description="Full name with academic title, e.g. 'Kiesow, Lars, M. Sc.'")]
details_url: Annotated[str, Field(description="URL to fetch full contact details via uos_person_details")]


class PersonSearchResults(BaseModel):
"""Container for people search results."""
results: Annotated[list[PersonSearchResult], Field(description="List of matching people")]
query: Annotated[str, Field(description="The search query that was performed")] = ""
total_count: Annotated[int, Field(description="Total number of results found")] = 0
details_url: Annotated[str, Field(description="URL of the person's full details page")]


class PersonDetails(BaseModel):
Expand All @@ -64,3 +57,10 @@ class PersonDetails(BaseModel):
email: Annotated[str | None, Field(description="Email address")] = None
website: Annotated[str | None, Field(description="Personal or group website URL")] = None
source_url: Annotated[str | None, Field(description="URL of the page these details were retrieved from")] = None


class PersonDetailsResults(BaseModel):
"""Container for people search results with full contact details inline."""
results: Annotated[list[PersonDetails], Field(description="List of matching people with full contact details")]
query: Annotated[str, Field(description="The search query that was performed")] = ""
total_count: Annotated[int, Field(description="Total number of results found")] = 0
76 changes: 76 additions & 0 deletions mcpuos/people_data.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
"""
In-memory store for the pre-scraped Personensuche directory.

Used by the MCP server to answer uos_people_search locally, without hitting
the live website, using the JSON file produced by `mcp-uos-scrape-people`
(see scrape_people.py).
"""

import json
import os
import signal

from fastmcp.utilities.logging import get_logger

from mcpuos.models import PersonDetails
from mcpuos.scrape_people import DEFAULT_DATA_PATH

logger = get_logger(__name__)


class PeopleDataStore:
"""Holds the people directory loaded from a scrape_people.py JSON file."""

def __init__(self, path: str | None = None):
if path is None:
path = os.getenv("UOS_MCP_PEOPLE_DATA_PATH", DEFAULT_DATA_PATH)
self.path = path
self._people: list[PersonDetails] = self._read(path)

@staticmethod
def _read(path: str) -> list[PersonDetails]:
with open(path, "r", encoding="utf-8") as f:
data = json.load(f)
return [PersonDetails(**p) for p in data["people"]]

def reload(self) -> bool:
"""
Reload the JSON file from disk. On failure, keeps serving the
last-known-good in-memory data and logs the error; never raises.

Returns:
True if the reload succeeded, False otherwise.
"""
try:
people = self._read(self.path)
except Exception as exc:
logger.error(
"people_data: reload of %s failed (%s); keeping %d previously loaded records",
self.path, exc, len(self._people),
)
return False
self._people = people
logger.info("people_data: reloaded %d people from %s", len(self._people), self.path)
return True

def search(self, query: str) -> list[PersonDetails]:
"""Case-insensitive substring match against `name`."""
q = query.lower()
return [p for p in self._people if q in p.name.lower()]

def __len__(self) -> int:
return len(self._people)


def install_reload_handler(store: PeopleDataStore):
"""
Register a SIGHUP handler that reloads `store`. Returns the handler
function (mainly so it can be exercised directly in unit tests without
needing a real signal delivery).
"""
def _handler(signum, frame):
store.reload()

if hasattr(signal, "SIGHUP"):
signal.signal(signal.SIGHUP, _handler)
return _handler
Loading