Metadata-Version: 2.5
Name: mensa-stw-vp-mcp
Version: 0.3.1
Summary: MCP server for accessing Studierendenwerk Vorderpfalz (stw-vp.de) meal plans
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: mcp<3,>=2.0.0
Requires-Dist: requests>=2.31.0
Description-Content-Type: text/markdown

# Mensa MCP Server

An MCP (Model Context Protocol) server for accessing meal plans from Studierendenwerk Vorderpfalz (stw-vp.de).

## Features

- Get meals plans for specific weeks or dates
- Fetch meal plans for all canteens from Studierendenwerk Vorderpfalz
- Structured JSON output with meal details (vegan, vegetarian, main dish flags)

## Available Canteens

| ID  | Name              |
| --- | ----------------- |
| 310 | Landau            |
| 311 | Landau Bürgerstr. |
| 320 | Germersheim       |
| 330 | Worms             |
| 340 | Ludwigshafen      |

## Installation

```bash
uv sync
```

## Transports

The server supports three transport protocols:

- **stdio** (default) — launched as a child process by the MCP client. Best for IDE/editor integration.
- **streamable-http** — runs as a long-running HTTP server. Best for remote access or multi-client deployments.
- **sse** — runs the legacy HTTP+SSE transport for clients that still require it.

### Stdio (default)

Add to your MCP client e.g., `opencode.json`:

```json
{
  "mcpServers": {
    "mensa": {
      "type": "local",
      "command": ["uv", "run", "mensa-mcp", "--canteen", "330"],
      "cwd": "/Users/boza/git/hswo/zd/mensa-stw-vp"
    }
  }
}
```

### Streamable HTTP

```bash
uv run mensa-mcp --transport streamable-http --port 8000
```

The MCP endpoint is `/mcp`.

### SSE

```bash
uv run mensa-mcp --transport sse --port 8000
```

The default SSE endpoint is `/sse`, with client messages sent to `/messages/`.

The `--canteen` argument sets the default canteen ID. Omit it if you prefer to always specify canteen_id explicitly.

## Available Tools

### list_canteens

List all available canteens with their IDs and names.

Parameters: none.

Example:

- `list_canteens()`

### get_weekly_meals

Fetch the weekly meal plan for a canteen.

Parameters:

- canteen_id (int, optional): ID of the canteen (310, 311, 320, 330, 340). Uses default from command line if not specified.
- week_number (int, optional): ISO week number (1-53). Defaults to current week.

Example:

- get_weekly_meals() # Uses default canteen, current week
- get_weekly_meals(canteen_id=330) # Current week, Worms
- get_weekly_meals(canteen_id=330, week_number=25) # Specific week

### get_daily_meals

Get meals for a specific date.

Parameters:

- date (string, optional): Date in ISO format YYYY-MM-DD (e.g., "2026-06-11"). If omitted, uses today.
- canteen_id (int, optional): Canteen ID. Uses default from command line if not specified.

Example:

- get_daily_meals() # Today's meals, default canteen
- get_daily_meals(date="2026-06-11") # Specific date, default canteen
- get_daily_meals(canteen_id=340) # Today, Ludwigshafen
- get_daily_meals(date="2026-06-11", canteen_id=340) # Both specified

## Development

```bash
# Install dependencies (including dev/test extras)
uv sync --extra dev

# Run tests
uv run pytest tests/ -v

# Run server in stdio mode (for MCP integration)
uv run mensa-mcp --canteen 330

# Run server with HTTP transport
uv run mensa-mcp --transport streamable-http --port 8000
```

## Validation

- `canteen_id` must be one of the known IDs (310, 311, 320, 330, 340).
- `week_number` must be an ISO week number between 1 and 53. Out-of-range values are rejected with a clear error at both the server and scraper layers.
- `date` must be in `YYYY-MM-DD` format.
- Dates outside the currently-served week return an empty meal list with a `note` explaining the date is out of range.

----

2026 Hochschule Worms, Zentrum für Digitalisierung.
