Metadata-Version: 2.4
Name: eth-library-mcp
Version: 0.3.3
Summary: MCP Server for ETH Library Zurich — Access 30M+ resources (books, maps, images, archives) via Discovery & Persons API
Project-URL: Homepage, https://github.com/malkreide/eth-library-mcp
Project-URL: Repository, https://github.com/malkreide/eth-library-mcp
Project-URL: Issues, https://github.com/malkreide/eth-library-mcp/issues
License: MIT License
        
        Copyright (c) 2026 Hayal Oezkan
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: archives,discovery,eth-library,mcp,model-context-protocol,research,swiss-open-data
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: mcp[cli]<2.0.0,>=1.0.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: structlog<26.0.0,>=24.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio<2.0.0,>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov<7.0.0,>=5.0.0; extra == 'dev'
Requires-Dist: pytest<9.0.0,>=8.0.0; extra == 'dev'
Requires-Dist: respx<1.0.0,>=0.21.0; extra == 'dev'
Requires-Dist: ruff<1.0.0,>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

> 🇨🇭 **Part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide)**

# 🏛️ eth-library-mcp

![Version](https://img.shields.io/badge/version-0.3.0-blue)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple)](https://modelcontextprotocol.io/)
[![Data Source](https://img.shields.io/badge/Data-ETH%20Library%20Zurich-red)](https://developer.library.ethz.ch)
[![CI](https://github.com/malkreide/eth-library-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/malkreide/eth-library-mcp/actions/workflows/ci.yml)

🌐 **English** | **[Deutsch](README.de.md)**

> MCP server giving AI models direct access to 30M+ resources at ETH Library Zurich – books, maps, images, archival material, and linked-data person records.

### Demo

![Demo: Claude using eth_search_archive to find historical school documents](docs/assets/demo.svg)

---

## Overview

**eth-library-mcp** connects AI assistants like Claude to the largest natural-science library in Switzerland. It exposes full-text search, archive-level queries, resource-type filtering, and person lookups via the ETH Library's Discovery and Persons APIs – all through a single, standardised MCP interface.

**7 Tools · 3 APIs · 2 Resources · 2 Prompts**

**MCP Protocol Version:** [`2025-06-18`](https://modelcontextprotocol.io/specification/) (via `mcp[cli]>=1.0.0,<2.0.0`).

> ⚠️ **Known issue (BUG-02):** The tool `eth_search_persons` is currently non-functional because the Persons API endpoint returns HTTP 404. The correct URL needs to be verified at [developer.library.ethz.ch](https://developer.library.ethz.ch). All other 6 tools work correctly.

**Anchor demo query:** *"Find historical documents about Zurich school history in the ETH Library archives."*

---

## Features

- 🔍 **Full-text search** over 30M+ resources with fields, operators, and facets
- 📖 **Resource details** – full metadata via MMS-ID
- 🗂️ **Archive search** – ETH University Archives, Max Frisch, Thomas Mann, Graphische Sammlung, Bildarchiv
- 🏷️ **Resource type filter** – books, maps, images, archival material and more
- 🎓 **Education search** – curated workflow optimised for pedagogy and school history
- 👤 **Person search** with linked-data enrichment (Wikidata, GND, Metagrid) *(BUG-02: currently unavailable)*
- 📋 **Server overview** – all resource types and archives at a glance
- 🗣️ **Built-in prompts** – structured research and education-research workflows
- ☁️ **Dual transport** – stdio for Claude Desktop, Streamable HTTP/SSE for cloud deployment

---

## Prerequisites

- Python 3.11+
- A free API key from [developer.library.ethz.ch](https://developer.library.ethz.ch)

---

## Installation

```bash
# Clone the repository
git clone https://github.com/malkreide/eth-library-mcp.git
cd eth-library-mcp

# Install
pip install -e .

# Or with uv (recommended)
uv pip install -e .
```

---

## Quickstart

```bash
# Set the API key
export ETH_LIBRARY_API_KEY=your_key_here   # macOS / Linux
# $env:ETH_LIBRARY_API_KEY = "your_key_here"  # Windows (PowerShell)

# Start the server (stdio mode for Claude Desktop)
python -m eth_library_mcp.server
```

> Without an API key the server returns a helpful error message with the registration link – no crashes.

Try it immediately in Claude Desktop:

> *"Find books about Swiss education history in the ETH Library."*
> *"Search the Max Frisch archive for manuscripts about Zurich."*

[→ More use cases by audience →](EXAMPLES.md)

---

## Configuration

### Environment Variables

| Variable | Description | Required |
|---|---|---|
| `ETH_LIBRARY_API_KEY` | API key for Discovery & Persons API | ✅ |

### Claude Desktop Configuration

```json
{
  "mcpServers": {
    "eth-library": {
      "command": "python",
      "args": ["-m", "eth_library_mcp.server"],
      "env": {
        "ETH_LIBRARY_API_KEY": "your_key_here"
      }
    }
  }
}
```

**Config file locations:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

### Cloud Deployment (SSE for browser access)

For use via **claude.ai in the browser** (e.g. on managed workstations without local software):

```bash
python -m eth_library_mcp.server --http --port 8000
```

The HTTP transport binds to `127.0.0.1` by default. To expose it on another
interface, pass `--host` explicitly:

```bash
# Only behind a reverse-proxy / firewall that terminates TLS and enforces auth.
python -m eth_library_mcp.server --http --host 0.0.0.0 --port 8000
```

> ⚠️ **Do not bind to `0.0.0.0` without a reverse proxy.** The server has no
> built-in auth, rate-limiting or TLS — any LAN neighbour could call your tools.

> 💡 *"stdio for the developer laptop, HTTP for the browser — behind a proxy."*

---

## Available Tools

### Discovery API (api.library.ethz.ch)

| Tool | Description |
|---|---|
| `eth_search_resources` | Full-text search over 30M+ resources with fields, operators, facets |
| `eth_get_resource` | Full metadata for a specific resource via MMS-ID |
| `eth_search_archive` | Search within a specific archive (University Archives, Max Frisch, Thomas Mann, etc.) |
| `eth_search_by_type` | Filter by resource type (books, maps, images, archival material, etc.) |
| `eth_search_education` | Curated search for education topics (pedagogy, school history, etc.) |

### Persons API

| Tool | Description |
|---|---|
| `eth_search_persons` | Person search with linked-data enrichment (Wikidata, GND, Metagrid) — ⚠️ BUG-02 |

### Utilities

| Tool | Description |
|---|---|
| `eth_library_info` | Server overview: all types and archives at a glance |

### Resources & Prompts

| Item | Type | Description |
|---|---|---|
| `eth://resource-types` | Resource | All available resource types |
| `eth://archives` | Resource | All available archives and collections |
| `research-workflow` | Prompt | Structured research workflow |
| `education-research` | Prompt | Education topics workflow (Schulamt-optimised) |

### Query Syntax

The Discovery API uses structured queries:

```
field,operator,value
```

| Field | Meaning |
|---|---|
| `any` | All fields (recommended for starters) |
| `title` | Title only |
| `creator` | Author / creator |
| `sub` | Subject headings / topics |

| Operator | Meaning |
|---|---|
| `contains` | Term is present |
| `exact` | Exact match |
| `begins_with` | Starts with |

**Examples:**

```
any,contains,Volksschule Zürich
title,contains,Pädagogik
creator,exact,Einstein Albert
sub,contains,Bildungsforschung
title,contains,Schule;sub,contains,Geschichte
```

### Available Archives

| Identifier | Description |
|---|---|
| `ETH_Hochschularchiv` | Institutional memory of ETH Zurich |
| `ETH_MaxFrischArchiv` | Estate of Swiss author Max Frisch |
| `ETH_ThomasMannArchiv` | Letters and documents of Thomas Mann |
| `ETH_GraphischeSammlung` | Prints, drawings, graphic works |
| `ETH_Bildarchiv` | Science/technology history, Swissair (E-Pics) |

### Example Use Cases

| Query | Tool |
|---|---|
| *"Find books about Zurich school history"* | `eth_search_education` |
| *"What's in the Max Frisch archive?"* | `eth_search_archive` |
| *"Find historical maps of Switzerland"* | `eth_search_by_type` |
| *"Get full metadata for resource ID 991170525863705501"* | `eth_get_resource` |
| *"Which archives does the ETH Library hold?"* | `eth_library_info` |

---

## Project Structure

```
eth-library-mcp/
├── src/
│   └── eth_library_mcp/
│       ├── __init__.py        # Package init, version
│       └── server.py          # FastMCP server, all tools
├── tests/
│   └── test_server.py         # Unit tests
├── CHANGELOG.md
├── CONTRIBUTING.md             # Contribution guide (English)
├── CONTRIBUTING.de.md          # Contribution guide (German)
├── SECURITY.md                 # Security posture (English)
├── SECURITY.de.md              # Security posture (German)
├── LICENSE
├── README.md                  # This file (English)
├── README.de.md               # German version
├── claude_desktop_config.json # Example Claude Desktop configuration
└── pyproject.toml             # Build configuration
```

---

## Testing

```bash
# Unit tests (no API key required)
PYTHONPATH=src pytest tests/ -m "not live"

# Integration tests (API key required)
ETH_LIBRARY_API_KEY=xxx pytest tests/ -m "live"
```

---

## Safety & Limits

- **Read-only:** All tools perform HTTP GET requests only — no data is written, modified, or deleted.
- **No personal data:** The APIs return bibliographic metadata (titles, authors, subjects, identifiers). No personally identifiable information (PII) is processed or stored by this server.
- **Authentication:** A free API key from [developer.library.ethz.ch](https://developer.library.ethz.ch) is required. The key is read from the `ETH_LIBRARY_API_KEY` environment variable and never logged or transmitted to third parties.
- **Rate limits:** The ETH Library API enforces rate limits per API key. The server enforces a 30-second timeout per request. Use `limit` and `offset` parameters conservatively.
- **Data freshness:** Results reflect the ETH Library catalogue at query time. No caching is performed by this server.
- **Terms of service:** Bibliographic metadata is published as **Public Domain** — free for all uses. API access is subject to the [ETH Library Developer Portal](https://developer.library.ethz.ch) terms.
- **Known issue (BUG-02):** `eth_search_persons` returns HTTP 404 — the Persons API endpoint URL needs verification. All other 6 tools work correctly.
- **No guarantees:** This is a community project, not affiliated with the ETH Library or ETH Zurich. Availability depends on upstream APIs.

---

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) ([Deutsch](CONTRIBUTING.de.md)) for guidelines.

---

## Security

Read-only, no PII, a single upstream API key, and a fixed egress allow-list of
ETH Library endpoints. See [SECURITY.md](SECURITY.md) ([Deutsch](SECURITY.de.md))
for the full security posture and accepted-risk decisions.

---

## Changelog

See [CHANGELOG.md](CHANGELOG.md)

---

## License

- **Server code:** MIT License — see [LICENSE](LICENSE)
- **Bibliographic metadata:** Public Domain (no restrictions)
- **API documentation:** [developer.library.ethz.ch](https://developer.library.ethz.ch)

---

*Powered by [Model Context Protocol](https://modelcontextprotocol.io/) • 2 APIs • 7 Tools • 2 Resources • 2 Prompts*

<!-- mcp-name: io.github.malkreide/eth-library-mcp -->
