# artsmia-mcp

> Model Context Protocol (MCP) server, CLI toolkit, and API library for the **Minneapolis Institute of Art (Mia)** collection ([search.artsmia.org](https://search.artsmia.org/)).

Search over 90,000 artworks, fetch high-resolution images, explore gallery locations, look up artists and historical constituents, and query collection highlights.

[![CI](https://github.com/aminamos/artsmia-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/aminamos/artsmia-mcp/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

---

## Features

- 🏛️ **Full Collection Search**: Elasticsearch queries across titles, artists, descriptions, provenance, curatorial text, dates, cultures, and departments.
- 🖼️ **High-Res Imagery**: Automatic link resolution for 400px, 600px, 800px, and full-resolution uncompressed master images on Mia's CDN (`1.api.artsmia.org`).
- 📍 **Gallery Locations & On-View Filter**: Discover artworks physically on view on floors 1, 2, or 3, or query specific galleries (e.g., `G355`).
- 🎲 **Random Art Exploration**: Fetch random collection pieces, optionally filtered by gallery floor, genre, or artist.
- ⭐ **Curated Highlights**: Access Mia's permanent masterwork collection highlights.
- 👤 **Artist & Constituent Bios**: Retrieve artist metadata, Wikidata IDs, Wikipedia links, and cross-museum identifiers (Art Institute of Chicago, MoMA, SAAM).
- 🤖 **MCP Protocol Support**: 7 tools, 2 resource templates (`artsmia://highlights`, `artsmia://random`, `artsmia://artwork/{id}`), and 2 guided prompts (`curate_tour`, `artwork_critique`).
- 💻 **Dual Mode**: Runs as a standard stdio MCP server or as a standalone CLI.

---

## Installation

### Run with `npx` (No installation needed)

```bash
npx artsmia-mcp
```

### Global Installation

```bash
npm install -g artsmia-mcp
```

---

## MCP Client Configuration

### Claude Desktop

Add this to your `claude_desktop_config.json`:

#### macOS / Linux
```json
{
  "mcpServers": {
    "artsmia": {
      "command": "npx",
      "args": ["-y", "artsmia-mcp"]
    }
  }
}
```

#### Windows
```json
{
  "mcpServers": {
    "artsmia": {
      "command": "cmd.exe",
      "args": ["/c", "npx -y artsmia-mcp"]
    }
  }
}
```

### Cursor (`.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "artsmia": {
      "command": "npx",
      "args": ["-y", "artsmia-mcp"]
    }
  }
}
```

---

## MCP Tools Reference

| Tool Name | Description | Key Arguments |
|-----------|-------------|---------------|
| `search_artworks` | Search artworks with Elasticsearch syntax, filters, and pagination | `query` (required), `size`, `from`, `sort` |
| `get_artwork` | Retrieve complete metadata and high-res image links by object ID | `id` (required, number) |
| `get_artworks_batch` | Retrieve multiple artworks by list of IDs in a single batch | `ids` (required, number[]) |
| `get_random_artwork` | Retrieve random artworks, optionally filtered by query/floor | `size`, `query` |
| `search_highlights` | Discover masterworks and curated collection highlights | `query`, `size`, `from` |
| `get_on_view_artworks` | Find artworks on physical exhibition in museum galleries | `floor` (1-3), `room` (e.g. 'G355'), `size`, `from` |
| `get_person` | Look up artist constituent information, Wikidata, and museum IDs | `id` (required, number) |

---

## CLI Usage

### Search Artworks
```bash
# Search for artist or title
artsmia search "Claude Monet"

# Search with Elasticsearch query syntax
artsmia search "classification:Paintings AND country:Japan"

# Output raw JSON
artsmia search "Vincent van Gogh" --json
```

### Inspect an Artwork
```bash
artsmia get 10436
```

### Batch Lookup
```bash
artsmia batch 10436,1218,1413
```

### Random Art
```bash
artsmia random
artsmia random --query="room:G3*" --size=3
```

### Highlights & On-View
```bash
artsmia highlights --size=5
artsmia on-view --room=G355
artsmia on-view --floor=3
```

### Person / Artist Constituent
```bash
artsmia person 1
```

---

## Programmatic Library Usage

You can also import `artsmia-mcp` directly in Node.js or TypeScript:

```typescript
import {
  searchArtworks,
  getArtworkById,
  getRandomArt,
  searchHighlights
} from "artsmia-mcp";

// Search artworks
const results = await searchArtworks({ query: "Monet", size: 5 });
for (const hit of results.hits.hits) {
  console.log(hit._source.title, hit._source.image_urls?.large);
}

// Get specific artwork with resolved images
const artwork = await getArtworkById(10436);
console.log(artwork?.title, artwork?.image_urls?.full);
```

---

## Testing & Quality Assurance

The codebase includes a full test suite with 100% unit and integration test coverage across all tools, CLI flags, error paths, and resource handlers:

```bash
npm test
npm run test -- --coverage
```

---

## License

MIT © Amin