eth-library-mcp 0.2.0__tar.gz

eth_library_mcp-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Python ${{ matrix.python-version }} einrichten
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: uv installieren
+        run: pip install uv
+
+      - name: Abhängigkeiten installieren
+        run: uv pip install -e ".[dev]" --system
+
+      - name: Linting mit ruff
+        run: python -m ruff check eth_library_mcp/
+
+      - name: Syntax-Prüfung
+        run: python -m py_compile eth_library_mcp/server.py eth_library_mcp/api_client.py
+
+      - name: Import-Test
+        run: python -c "from eth_library_mcp.server import mcp; print('Import OK')"
+
+      - name: Unit-Tests
+        run: pytest tests/ -m "not live" -v
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - run: pip install ruff
+
+      - run: python -m ruff check eth_library_mcp/
+
+      - run: python -m ruff format --check eth_library_mcp/

eth_library_mcp-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+permissions:
+  id-token: write  # Pflicht für Trusted Publisher
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Python einrichten
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build-Tools installieren
+        run: pip install build
+
+      - name: Paket bauen
+        run: python -m build
+
+      - name: Build-Artefakte hochladen
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/eth-library-mcp/
+
+    steps:
+      - name: Build-Artefakte herunterladen
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Auf PyPI publizieren
+        uses: pypa/gh-action-pypi-publish@release/v1

eth_library_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+Alle nennenswerten Änderungen an diesem Projekt werden hier dokumentiert.
+Format basiert auf [Keep a Changelog](https://keepachangelog.com/de/1.0.0/).
+
+---
+
+## [0.2.0] – 2026-03-04
+
+### Behoben
+- **BUG-01** `pyproject.toml`: Falscher Package-Pfad `src/eth_library_mcp` → `eth_library_mcp` (Installation via `pip install -e .` schlug fehl)
+- **BUG-03** `sort`-Parameter: Beliebige Strings akzeptiert → `Literal["rank","title","author","date"]` (verhindert ungültige API-Anfragen)
+- **BUG-04** `resource_type`-Parameter: Beliebige Strings akzeptiert → vollständiger `Literal`-Typ mit allen 10 gültigen Werten (verhindert stille Leerantworten)
+- **BUG-06** Persons-Response-Parsing: Nur `persons`/`results`-Keys unterstützt → robustes Parsing mit `data`, `items`, `hits` + Logging bei unbekannter Struktur
+- **BUG-07** HTTP-404-Fehlermeldung: Generische "ID prüfen"-Meldung auch bei Suchen → kontext-spezifische Meldungen (`is_search`-Parameter in `handle_api_error`)
+
+### Entfernt
+- **BUG-05** Ungenutzte Konstanten `RESEARCH_BASE_URL` und `ETHORAMA_BASE_URL` aus `api_client.py` entfernt
+
+### Bekannte Probleme
+- **BUG-02** Persons-API-Endpunkt (`/persons/v1/persons`) gibt HTTP 404 zurück. Die korrekte URL muss via [developer.library.ethz.ch](https://developer.library.ethz.ch) verifiziert werden. Das Tool `eth_search_persons` ist strukturell korrekt implementiert, aber erst nach URL-Verifikation funktionsfähig.
+
+---
+
+## [0.1.0] – 2026-03-01
+
+### Hinzugefügt
+- Initiale Implementierung mit 7 Tools, 3 APIs, 2 Resources, 2 Prompts
+- Discovery API: `eth_search_resources`, `eth_get_resource`, `eth_search_archive`, `eth_search_by_type`, `eth_search_education`
+- Persons API: `eth_search_persons`
+- Dual Transport: stdio (lokal) + SSE (Cloud/Render.com)
+- Graceful Degradation ohne API-Key (hilfreiche Fehlermeldung mit Registrierungslink)
+- Schulamt-spezifisches Tool `eth_search_education` für Bildungsthemen

eth_library_mcp-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,135 @@
+# Contributing to eth-library-mcp
+
+Thank you for your interest in contributing to **eth-library-mcp**! This server is part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide) and contributions that strengthen Swiss open-data accessibility for AI assistants are especially welcome.
+
+---
+
+## How to Contribute
+
+### Reporting Issues
+
+Use [GitHub Issues](https://github.com/malkreide/eth-library-mcp/issues) to report bugs or request features.
+
+When reporting a bug, please include:
+- Python version (`python --version`)
+- Operating system
+- Steps to reproduce the issue
+- Expected vs. actual behaviour
+- Relevant error messages or logs
+
+### Open Issues
+
+| ID | Description | Priority |
+|---|---|---|
+| **BUG-02** | `eth_search_persons` returns HTTP 404 – correct Persons API endpoint URL needs verification at [developer.library.ethz.ch](https://developer.library.ethz.ch) | High |
+
+If you have resolved BUG-02 or have a verified working endpoint URL, please open a pull request or comment on the issue directly.
+
+---
+
+## Development Setup
+
+```bash
+# Clone and install in editable mode
+git clone https://github.com/malkreide/eth-library-mcp.git
+cd eth-library-mcp
+pip install -e ".[dev]"
+
+# Or with uv
+uv pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+# Unit tests (no API key required)
+PYTHONPATH=. pytest tests/ -m "not live"
+
+# Integration tests (requires a valid API key)
+ETH_LIBRARY_API_KEY=your_key pytest tests/ -m "live"
+```
+
+Tests marked `@pytest.mark.live` call the real ETH Library API and require a valid key from [developer.library.ethz.ch](https://developer.library.ethz.ch).
+
+### Code Style
+
+This project uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting:
+
+```bash
+ruff check .
+ruff format .
+```
+
+---
+
+## Pull Request Guidelines
+
+1. **Fork** the repository and create a feature branch from `main`:
+   ```bash
+   git checkout -b fix/bug-02-persons-api
+   ```
+
+2. **Write tests** for any new tool or bug fix. Live tests go in `tests/` with the `@pytest.mark.live` marker.
+
+3. **Update documentation** – if you add or change a tool, update both `README.md` (English) and `README.de.md` (German). Keep the language toggle links at the top of each file.
+
+4. **Update `CHANGELOG.md`** – add an entry under `[Unreleased]` using [Conventional Commits](https://www.conventionalcommits.org/) style:
+   - `fix:` – bug fix
+   - `feat:` – new feature or tool
+   - `docs:` – documentation only
+   - `refactor:` – code change with no functional impact
+
+5. **Open a Pull Request** against `main` with a clear description of what changed and why.
+
+---
+
+## Commit Message Convention
+
+```
+<type>: <short description>
+
+# Examples
+fix: resolve BUG-02 Persons API 404 with updated endpoint
+feat: add eth_search_collections tool for collection-level browsing
+docs: add query syntax examples to README
+```
+
+---
+
+## Adding a New Tool
+
+New tools go in `eth_library_mcp/server.py`. Follow the existing pattern:
+
+```python
+@mcp.tool()
+async def eth_your_new_tool(param: str) -> str:
+    """
+    One-line description for the AI model.
+
+    Args:
+        param: What this parameter does.
+
+    Returns:
+        JSON string with results.
+    """
+    ...
+```
+
+After adding a tool:
+- Add it to the **Available Tools** table in `README.md` and `README.de.md`
+- Add at least one unit test in `tests/`
+- Add an example query to the **Example Use Cases** table in the README files
+
+---
+
+## Data & Licensing Notes
+
+- **Server code:** MIT License
+- **Bibliographic metadata** returned by the ETH Library API: **Public Domain** – no restrictions on reuse
+- Do not embed or cache API responses in the repository
+
+---
+
+## Questions
+
+Open a [GitHub Discussion](https://github.com/malkreide/eth-library-mcp/discussions) or contact the maintainer via GitHub.

eth_library_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Schulamt der Stadt Zürich
+
+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.

eth_library_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: eth-library-mcp
+Version: 0.2.0
+Summary: MCP Server für die ETH-Bibliothek Zürich – Zugriff auf 30+ Millionen Ressourcen via Discovery, Persons und Research Collection API
+Author: Schulamt der Stadt Zürich
+License: MIT
+License-File: LICENSE
+Keywords: discovery,eth,library,mcp,open-data,research
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.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.2.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)
+
+> MCP server giving AI models direct access to 30M+ resources at ETH Library Zurich – books, maps, images, archival material, and linked-data person records.
+
+[🇩🇪 Deutsche Version](README.de.md)
+
+---
+
+## 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**
+
+> ⚠️ **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."*
+
+---
+
+## 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
+MCP_TRANSPORT=sse PORT=8000 python -m eth_library_mcp.server
+```
+
+> 💡 *"stdio for the developer laptop, SSE for the browser."*
+
+---
+
+## 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/
+├── eth_library_mcp/           # Main package
+│   └── server.py              # FastMCP server, tool definitions
+├── CHANGELOG.md
+├── CONTRIBUTING.md
+├── LICENSE
+├── README.md                  # This file (English)
+├── README.de.md               # German version
+├── TEST_PLAN.md
+├── claude_desktop_config.json # Example Claude Desktop configuration
+└── pyproject.toml             # Build configuration
+```
+
+---
+
+## Known Limitations
+
+- **BUG-02 (Persons API):** `eth_search_persons` returns HTTP 404 – correct endpoint URL to be verified at [developer.library.ethz.ch](https://developer.library.ethz.ch)
+- **Bibliographic metadata:** Licensed as Public Domain – free for all uses, no restrictions
+- **Rate limits:** Governed by the ETH Library API terms; no built-in throttling in this server version
+
+---
+
+## Testing
+
+```bash
+# Unit tests (no API key required)
+PYTHONPATH=. pytest tests/ -m "not live"
+
+# Integration tests (API key required)
+ETH_LIBRARY_API_KEY=xxx pytest tests/ -m "live"
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+## 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)
+
+---
+
+## Author
+
+Hayal Oezkan · [github.com/malkreide](https://github.com/malkreide)
+
+---
+
+## Credits & Related Projects
+
+- **Data:** [ETH Library Zurich](https://library.ethz.ch) – Discovery & Persons APIs
+- **Protocol:** [Model Context Protocol](https://modelcontextprotocol.io/) – Anthropic / Linux Foundation
+- **Related:** [swiss-transport-mcp](https://github.com/malkreide/swiss-transport-mcp) – MCP server for Swiss public transport
+- **Related:** [zurich-opendata-mcp](https://github.com/malkreide/zurich-opendata-mcp) – MCP server for Zurich city open data
+- **Portfolio:** [Swiss Public Data MCP Portfolio](https://github.com/malkreide)