# Swedish Portrait Archive MCP Server (`swedish-portrait-archive-mcp`)

A Model Context Protocol (MCP) server for searching and retrieving historical Swedish portraits, biographies, and printed matrikel sources from **[Svenskt Porträttarkiv (Swedish Portrait Archive)](https://portrattarkiv.se)**.

Svenskt Porträttarkiv contains over one million portraits scanned from printed Swedish biographical collections, military rolls, professional directories, and anniversary publications from the 19th and 20th centuries.

---

## Features

* **Historical Portrait Search (`search-portraits`)**: Search by first name, last name, birth/death year, birth parish/county, occupation, and free-text queries.
* **Biographical Details & Transcriptions (`get-portrait-details`)**: Fetch full biographical texts, printed book references, Swedish Death Index cross-references (*Sveriges Dödbok* ID), and formatted genealogical citations.
* **Direct Image Access (`get-portrait-image`)**: Generate direct URLs to high-resolution portrait scans (JPEG) and online archive records.
* **Genney Compatibility**: Produces ready-to-paste citation blocks designed for Swedish genealogical software (**Genney**).

---

## Ethics, Politeness & Fair Use

Svenskt Porträttarkiv is operated as a volunteer, non-profit community initiative founded by Omar Henriksson. To ensure respectful, fair, and responsible integration, this MCP server adheres to strict ethical guidelines:

1. **Strict Rate Limiting (`RequestQueue`)**: All outgoing network requests are queued sequentially with an enforced delay of at least 400 ms (+ randomized jitter) between requests.
2. **Transparent User-Agent**: Every request identifies itself clearly:
   ```http
   User-Agent: SwedishPortraitArchiveMCP/1.0 (+https://github.com/tobbaz/swedish-portrait-archive-mcp)
   ```
3. **No Bulk Scraping**: The tools operate exclusively **on-demand** for targeted genealogical queries. The server does not support mass harvesting or mirroring of the archive.
4. **Attribution & Licensing**:
   * Individual portraits and biographical texts are generally licensed under **Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)**.
   * The composite archive collection is licensed under **Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)**.
   * Every search result and detail query provides direct links back to the original entry at `https://portrattarkiv.se/details/{id}`.

---

## MCP Tools

### 1. `search-portraits`
Searches the archive for portraits matching given genealogical parameters.

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `firstName` | `string` (optional) | Given name (e.g. `"Emanuel"` or `"Carl August"`) |
| `lastName` | `string` (optional) | Surname (e.g. `"Kastengren"` or `"Lindahl"`) |
| `birthYear` | `string \| number` (optional) | Birth year (e.g. `1826`) |
| `deathYear` | `string \| number` (optional) | Death year (e.g. `1904`) |
| `birthPlace` | `string` (optional) | Parish, town or county of birth |
| `occupation` | `string` (optional) | Occupation or title (e.g. `"Löjtnant"`, `"Veterinär"`) |
| `employmentPlace` | `string` (optional) | Workplace or place of residence |
| `query` | `string` (optional) | Free-text search across all metadata |
| `limit` | `number` (optional) | Results limit (default: 20, max: 100) |
| `from` | `number` (optional) | Pagination offset |

### 2. `get-portrait-details`
Retrieves full details for a portrait record.

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `portraitId` | `string` (required) | Portrait unique ID (e.g. `"sj9PGLAlnmUAAAAAABlg4w"`) |

Returns transcribed biographies, source collections/books, Sveriges Dödbok ID, and a Genney-formatted citation.

### 3. `get-portrait-image`
Returns direct links to the high-resolution JPEG image and archive web page.

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `portraitId` | `string` (required) | Portrait unique ID |

---

## Installation & Building

### Prerequisites
* Node.js 18+ or 20+
* npm

### Setup
```bash
git clone https://github.com/tobbaz/swedish-portrait-archive-mcp.git
cd swedish-portrait-archive-mcp
npm install
npm run build
```

### Running Tests
```bash
npm test
```

---

## MCP Configuration

### Antigravity / Claude Desktop Configuration

Add the server to your `mcp_config.json` (or `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "swedish-portrait-archive": {
      "command": "node",
      "args": [
        "/absolute/path/to/swedish-portrait-archive-mcp/build/index.js"
      ]
    }
  }
}
```

---

## License

* **Code**: Released under the [MIT License](LICENSE).
* **Archive Data & Portraits**: Provided by Svenskt Porträttarkiv under Creative Commons licenses (CC BY-SA 4.0 / CC BY-NC-SA 4.0).