open-museum-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pramod Prasanth
+
+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.

package/README.md

@@ -0,0 +1,216 @@
+# open-museum-mcp
+
+> Open-access museum search for MCP clients, with rights verification per museum.
+
+## Why I built this
+
+I kept wanting reuse-safe artwork for my writing, and every museum's rights model is different. So I built one MCP interface that only returns records that pass per-museum verification rules, with strict deny on ambiguity. It lets me search by artist, period, region, and other fields, and pulls the image and description back in one normalized shape.
+
+If anyone else is exploring open-access art, I hope this helps. The plan is to keep adding museums from around the world.
+
+## What you get
+
+- **One interface, registered museums.** The Met is live. Cleveland and the Art Institute of Chicago are next.
+- **Strict deny on ambiguity.** Records are validated against per-museum rights rules in code. Missing or unclear indicators drop the record; nothing is defaulted to "open".
+- **Catalog-grade metadata.** A dynasty-aware date parser handles Tang, Edo, Safavid, Mughal and the rest. Regions normalize across museums. Attribution separates named artists from anonymous, workshop, "after", and attributed works.
+- **Listable resources and deterministic citations.** `museum://{code}/{id}` resources, three citation styles, structured JSON search results.
+
+## Quick example
+
+A search call returns license-verified results in one normalized shape:
+
+```jsonc
+// Tool call: search_artworks({ query: "van gogh wheat", museum: "met", limit: 1 })
+{
+  "count": 1,
+  "results": [
+    {
+      "id": "met:436535",
+      "museum": {
+        "code": "met",
+        "name": "The Metropolitan Museum of Art",
+        "url": "https://www.metmuseum.org"
+      },
+      "title": "Wheat Field with Cypresses",
+      "artist": {
+        "name": "Vincent van Gogh",
+        "nationality": "Dutch",
+        "lifespan": "1853–1890",
+        "attributionType": "named"
+      },
+      "displayDate": "1889",
+      "yearStart": 1889,
+      "yearEnd": 1889,
+      "medium": "Oil on canvas",
+      "region": "netherlands",
+      "period": null,
+      "imageUrls": { "full": "https://images.metmuseum.org/..." },
+      "imageOpenAccess": true,
+      "metadataOpenAccess": true,
+      "license": {
+        "type": "CC0",
+        "rawValue": "true",
+        "verificationSource": "met.isPublicDomain",
+        "verifiedAt": "2026-04-25T12:00:00.000Z",
+        "confidence": "high"
+      },
+      "source": {
+        "apiUrl": "https://collectionapi.metmuseum.org/public/collection/v1/objects/436535",
+        "pageUrl": "https://www.metmuseum.org/art/collection/search/436535"
+      }
+    }
+  ]
+}
+```
+
+## Install
+
+```bash
+npm install
+npm run build
+```
+
+### Wire into Claude Code
+
+Add to your MCP config (`.mcp.json` in a project, or your user-level config):
+
+```json
+{
+  "mcpServers": {
+    "open-museum": {
+      "command": "node",
+      "args": ["/absolute/path/to/open-museum-mcp/dist/server.js"]
+    }
+  }
+}
+```
+
+After restarting your MCP client, the tools below become available.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `search_artworks(query, museum?, has_image?, limit?)` | Search across registered museums. Returns only records that pass the rights gate. |
+| `get_artwork(id)` | Fetch a single artwork by its normalized ID (e.g. `met:436535`). |
+| `cite(id, style?)` | Render a citation. `style`: `full` (artist, title, date, museum, license, URL), `caption` (image attribution), `short` (inline). |
+
+### `cite` example outputs
+
+For Van Gogh's *Wheat Field with Cypresses* (`met:436535`):
+
+```text
+caption: "Vincent van Gogh, Wheat Field with Cypresses, 1889. Oil on canvas.
+          The Metropolitan Museum of Art, CC0.
+          https://www.metmuseum.org/art/collection/search/436535"
+
+full:    "Vincent van Gogh, Wheat Field with Cypresses. 1889. The Metropolitan
+          Museum of Art. CC0. https://www.metmuseum.org/art/collection/search/436535."
+
+short:   "Wheat Field with Cypresses (Vincent van Gogh, 1889)"
+```
+
+The `caption` style follows museum-publication convention: comma-separated head, medium called out, terse end. The `full` style is suitable for footnotes and bibliographies. The `short` style is for inline references where you've already established context.
+
+For anonymous works (e.g. a Tang dynasty funerary vessel), the artist field becomes `"Unknown artist"` in caption form.
+
+## Resources
+
+- `museum://{museum_code}/{id}`: read or list any indexed artwork by URI. Listable resources let you build a per-session shortlist without re-invoking tools.
+
+## Performance notes
+
+- The Met API has no batch endpoint for object retrieval. A `search_artworks` call with `limit: 10` makes one search request plus up to ten parallel object fetches (eleven HTTP round trips total on a cold cache). On warm cache the search is one round trip and most objects are local.
+- Where possible, search-side filters are pushed to the museum (`isPublicDomain=true` is sent with every Met search) so the rights gate has fewer rejections to handle.
+- Object records are cached for 90 days (artworks don't change). Search result IDs are cached for 14 days (museums add new open-access objects regularly).
+
+## Verification model
+
+This is the heart of the project. Each museum exposes rights information in its own way; the server's job is to decide acceptance per museum and never default to "open" on ambiguity.
+
+**Default policy: strict deny.** If a record's rights signal is missing, malformed, or non-affirmative, the record is dropped and the rejection reason is logged.
+
+| Museum | Verification source | Accept condition |
+|---|---|---|
+| The Met | `isPublicDomain` (boolean) | `=== true` |
+| Cleveland Museum of Art | `share_license_status` (string) | `=== "CC0"` (case-insensitive) |
+| Art Institute of Chicago | `is_public_domain` (boolean) | `=== true` |
+
+Each accepted record carries:
+
+- `imageOpenAccess`: the artwork's image may be reused under the recorded license.
+- `metadataOpenAccess`: the artwork's catalog metadata may be reused (often broader than image rights).
+- `license.type`: normalized license tier (`CC0`, `PD`, `CC-BY`, …; v0.1 only emits `CC0`).
+- `license.rawValue`: the museum's own field value, preserved.
+- `license.verificationSource`: the exact museum field that was checked (e.g. `met.isPublicDomain`).
+- `license.confidence`: `high` for unambiguous accepts (the only level v0.1 emits).
+- `license.verifiedAt`: ISO timestamp of when this verification ran.
+
+This is what "rights-verified" means here: validated against published museum metadata using source-specific rules implemented in this repo, with strict deny on ambiguity. It is **not** a guarantee of third-party rights beyond what each museum's API publicly represents. See [Disclaimer](#disclaimer).
+
+## Supported museums
+
+| Museum | Code | Auth | Status |
+|---|---|---|---|
+| The Metropolitan Museum of Art | `met` | none | ✅ v0.1 |
+| Cleveland Museum of Art | `cleveland` | none | 🚧 next |
+| Art Institute of Chicago | `aic` | none | 🚧 next |
+| Smithsonian Open Access | `si` | API key (free) | 📋 v2 |
+| Rijksmuseum | `rijks` | API key (free) | 📋 v2 |
+
+## Schema
+
+Full TypeScript definitions in [`src/types.ts`](src/types.ts). The `Artwork` shape is stable; additional fields may be added but existing fields will not be repurposed.
+
+Highlights:
+
+- `displayDate` (string, museum-provided) preserved alongside parsed `yearStart` / `yearEnd` (signed integers, BCE encoded as negatives).
+- `region` and `period` normalized across museums (`china`, `japan`, `tang dynasty`, etc.).
+- `artist.attributionType` distinguishes `named` / `anonymous` / `workshop` / `after` / `attributed` / `circle` / `follower`.
+- `imageOpenAccess` is held distinct from `metadataOpenAccess` because museums frequently publish open metadata for objects whose images are not openly licensed.
+
+## Non-goals
+
+- **Not a full art-history ontology.** The dynasty and region tables cover the most-encountered cases; they are not exhaustive iconographic taxonomies.
+- **Not a generic museum API client.** The server only returns records that pass rights verification. If you need raw, unfiltered API access, talk to the museum APIs directly.
+- **Not a rights advisor.** The verification model establishes machine-checkable acceptance rules; final rights decisions in commercial or sensitive contexts remain the user's responsibility.
+- **Not a content host.** Image URLs point at each museum's CDN; this server does not rehost media.
+
+## Roadmap
+
+- v0.1: Met adapter, dynasty-aware date parser, license gate, `cite` tool, MCP resources. **(here)**
+- v0.2: Cleveland and AIC adapters, `discover_random` with constraints (`region`, `period`, `not_artist`), `list_traditions`.
+- v0.5: Dominant-color extraction across museums (`color: "#3a5f7d"` discovery via `sharp`).
+- v1.0: Artist-obscurity scoring (`object_count_total`, `museum_count`) for deliberate exploration of less-canonical work.
+- v2.0: Smithsonian, Rijksmuseum, Wikimedia Commons (long-tail).
+
+## Contributing a museum adapter
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The short version:
+
+1. Implement the `Fetcher` interface in `src/fetchers/{code}.ts`.
+2. Add a `validate{Code}License` function in `src/licenseGate.ts` with explicit accept rules and strict default deny.
+3. Add region/period mappings to `src/data/regions.json` and `src/data/dynasties.json` if the new collection introduces unmapped traditions.
+4. Add fixture-based tests in `tests/{code}.test.ts` covering: one accepted record, one rejected (non-open) record, one rejected (missing field) record.
+5. Register the adapter in `src/server.ts`.
+
+The license gate is the most opinionated part of the codebase. Additions should err strict.
+
+## Security
+
+- **`npm audit` clean at launch.** Zero vulnerabilities at any severity level across runtime and dev dependencies as of v0.1.
+- **stdio-only transport.** No HTTP listener, no auth surface to bypass. The server only speaks to the MCP client over standard streams.
+- **Strict input validation.** All tool arguments pass through Zod schemas; artwork IDs are constrained to `/^[a-z]+:[1-9]\d*$/`. The resource URI handler re-validates the constructed ID against the same regex, so URI-form requests can't bypass the constraint.
+- **Defense-in-depth on rights.** The Met search filter `isPublicDomain=true` is sometimes inconsistent with the per-object boolean. The license gate runs again on every fetched record and rejects any disagreement.
+- **Parameterized SQL.** All `better-sqlite3` calls use named/positional parameters; zero string-concatenated SQL paths.
+- **No file writes from user input.** The cache directory is created at `~/.open-museum-mcp/cache.db` (or wherever `OMM_CACHE_PATH` points) with mode `0o700` and the cache file at `0o600`; no fetcher rehosts media bytes locally.
+
+If you find a record the gate accepts that shouldn't pass, please open an issue with the artwork ID and the museum's raw API response. Rights correctness is the project's most important property, and the part where outside review most helps.
+
+## Disclaimer
+
+This software validates open-access status against the rights metadata each museum publishes and the rules each museum requests. It cannot independently verify third-party rights, derived works, model release issues, or sensitive cultural-heritage considerations beyond what the source museum represents. Several museums (e.g. the Art Institute of Chicago) explicitly note that even CC0-marked images may carry obligations around third-party permissions or culturally sensitive material. **Always confirm against the source museum's terms before commercial or sensitive use.**
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

package/dist/cite.d.ts

@@ -0,0 +1,17 @@
+import type { Artwork } from './types.js';
+export type CiteStyle = 'short' | 'full' | 'caption';
+/**
+ * Render an attribution string for an artwork.
+ *
+ * Style semantics:
+ *   - `full`: footnote/bibliography form. Period-separated.
+ *   - `caption`: museum-publication caption convention. Comma-separated head
+ *     (artist, title, date), medium called out, terse end with museum + license.
+ *   - `short`: inline reference like "Title (Artist, Date)".
+ *
+ * Per-museum overrides live in the PER_MUSEUM_FULL / PER_MUSEUM_CAPTION
+ * tables. Museums without an entry fall back to the Met formatters — keep
+ * them general-purpose enough to read sensibly across collections until a
+ * museum-specific style is contributed.
+ */
+export declare function cite(artwork: Artwork, style?: CiteStyle): string;

package/dist/cite.js

@@ -0,0 +1,61 @@
+function joinNonEmpty(parts, sep) {
+    return parts.filter((p) => Boolean(p && p.trim())).join(sep);
+}
+function metFull(a) {
+    const artist = a.artist.attributionType === 'anonymous' ? '' : a.artist.name;
+    const head = joinNonEmpty([artist, a.title], ', ');
+    const date = a.displayDate;
+    const tail = `${a.museum.name}. ${a.license.type}. ${a.source.pageUrl}`;
+    const joined = joinNonEmpty([head, date, tail], '. ');
+    return joined.endsWith('.') ? joined : `${joined}.`;
+}
+function metCaption(a) {
+    const artist = a.artist.attributionType === 'anonymous' ? 'Unknown artist' : a.artist.name;
+    const parts = [`${artist}, ${a.title}, ${a.displayDate}`];
+    if (a.medium && a.medium.trim())
+        parts.push(a.medium.trim());
+    parts.push(`${a.museum.name}, ${a.license.type}`);
+    const body = parts.join('. ');
+    const terminated = body.endsWith('.') ? body : `${body}.`;
+    return `${terminated} ${a.source.pageUrl}`;
+}
+// Short uses bare "Unknown" rather than caption's "Unknown artist" because
+// the parenthetical inline form reads better with a single word: prefer
+// "Title (Unknown, 1500)" over "Title (Unknown artist, 1500)". Captions are
+// standalone sentences where the longer form is conventional.
+function shortStyle(a) {
+    const artist = a.artist.attributionType === 'anonymous' ? 'Unknown' : a.artist.name;
+    const date = a.displayDate || (a.yearStart != null ? String(a.yearStart) : '');
+    return `${a.title} (${artist}, ${date})`;
+}
+const PER_MUSEUM_FULL = {
+    met: metFull,
+};
+const PER_MUSEUM_CAPTION = {
+    met: metCaption,
+};
+/**
+ * Render an attribution string for an artwork.
+ *
+ * Style semantics:
+ *   - `full`: footnote/bibliography form. Period-separated.
+ *   - `caption`: museum-publication caption convention. Comma-separated head
+ *     (artist, title, date), medium called out, terse end with museum + license.
+ *   - `short`: inline reference like "Title (Artist, Date)".
+ *
+ * Per-museum overrides live in the PER_MUSEUM_FULL / PER_MUSEUM_CAPTION
+ * tables. Museums without an entry fall back to the Met formatters — keep
+ * them general-purpose enough to read sensibly across collections until a
+ * museum-specific style is contributed.
+ */
+export function cite(artwork, style = 'full') {
+    if (style === 'short')
+        return shortStyle(artwork);
+    if (style === 'caption') {
+        const fn = PER_MUSEUM_CAPTION[artwork.museum.code] ?? metCaption;
+        return fn(artwork);
+    }
+    const fn = PER_MUSEUM_FULL[artwork.museum.code] ?? metFull;
+    return fn(artwork);
+}
+//# sourceMappingURL=cite.js.map

package/dist/cite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cite.js","sourceRoot":"","sources":["../src/cite.ts"],"names":[],"mappings":"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"}

package/dist/data/dynasties.json

@@ -0,0 +1,93 @@
+{
+    "japan": {
+        "jomon": [-14000, -300],
+        "yayoi": [-300, 250],
+        "kofun": [250, 538],
+        "asuka": [538, 710],
+        "nara": [710, 794],
+        "heian": [794, 1185],
+        "kamakura": [1185, 1333],
+        "muromachi": [1336, 1573],
+        "azuchi-momoyama": [1573, 1603],
+        "momoyama": [1573, 1603],
+        "edo": [1603, 1868],
+        "meiji": [1868, 1912],
+        "taisho": [1912, 1926],
+        "showa": [1926, 1989]
+    },
+    "china": {
+        "shang": [-1600, -1046],
+        "zhou": [-1046, -256],
+        "qin": [-221, -206],
+        "han": [-206, 220],
+        "three kingdoms": [220, 280],
+        "jin": [266, 420],
+        "northern and southern": [420, 589],
+        "sui": [581, 618],
+        "tang": [618, 907],
+        "five dynasties": [907, 960],
+        "song": [960, 1279],
+        "northern song": [960, 1127],
+        "southern song": [1127, 1279],
+        "yuan": [1271, 1368],
+        "ming": [1368, 1644],
+        "qing": [1644, 1912]
+    },
+    "korea": {
+        "three kingdoms korea": [-57, 668],
+        "silla": [-57, 935],
+        "unified silla": [668, 935],
+        "goryeo": [918, 1392],
+        "joseon": [1392, 1897]
+    },
+    "iran": {
+        "achaemenid": [-550, -330],
+        "parthian": [-247, 224],
+        "sasanian": [224, 651],
+        "umayyad caliphate": [661, 750],
+        "abbasid caliphate": [750, 1258],
+        "ilkhanid": [1256, 1335],
+        "timurid": [1370, 1507],
+        "safavid": [1501, 1736],
+        "qajar": [1789, 1925],
+        "pahlavi": [1925, 1979]
+    },
+    "india": {
+        "maurya": [-322, -185],
+        "gupta": [320, 550],
+        "chola": [848, 1279],
+        "delhi sultanate": [1206, 1526],
+        "mughal": [1526, 1857],
+        "british raj": [1858, 1947]
+    },
+    "islamic": {
+        "umayyad": [661, 750],
+        "abbasid": [750, 1258],
+        "fatimid": [909, 1171],
+        "ayyubid": [1171, 1260],
+        "mamluk": [1250, 1517],
+        "ottoman": [1299, 1922]
+    },
+    "egypt": {
+        "old kingdom": [-2686, -2181],
+        "middle kingdom": [-2055, -1650],
+        "new kingdom": [-1550, -1069],
+        "ptolemaic": [-305, -30],
+        "late period": [-664, -332]
+    },
+    "europe": {
+        "merovingian": [481, 751],
+        "carolingian": [800, 888],
+        "ottonian": [919, 1024],
+        "romanesque": [1000, 1200],
+        "gothic": [1200, 1500],
+        "early renaissance": [1400, 1495],
+        "high renaissance": [1495, 1527],
+        "mannerism": [1527, 1600],
+        "baroque": [1600, 1750],
+        "rococo": [1730, 1770],
+        "neoclassical": [1750, 1830],
+        "romanticism": [1800, 1850],
+        "victorian": [1837, 1901]
+    }
+}

package/dist/data/regions.json

@@ -0,0 +1,21 @@
+{
+    "japan": ["japan", "japanese", "edo", "kyoto", "tokyo", "osaka"],
+    "china": ["china", "chinese", "tang", "song", "ming", "qing", "tibet"],
+    "korea": ["korea", "korean", "joseon", "goryeo"],
+    "iran": ["iran", "iranian", "persian", "persia", "safavid", "qajar"],
+    "india": ["india", "indian", "mughal", "rajasthani", "punjabi"],
+    "islamic": ["islamic art", "ottoman", "mamluk", "fatimid"],
+    "egypt": ["egypt", "egyptian", "ptolemaic"],
+    "greece": ["greece", "greek", "hellenistic", "attic"],
+    "rome": ["rome", "roman", "roman empire"],
+    "byzantine": ["byzantine", "byzantium"],
+    "italy": ["italy", "italian", "florentine", "venetian", "roman renaissance"],
+    "france": ["france", "french", "parisian"],
+    "netherlands": ["netherlands", "dutch", "flemish", "holland"],
+    "germany": ["germany", "german", "bavarian", "prussian"],
+    "spain": ["spain", "spanish", "andalusian", "catalan"],
+    "england": ["england", "english", "british", "great britain"],
+    "americas": ["united states", "american", "mexican", "peruvian"],
+    "africa": ["africa", "african", "yoruba", "kongo", "asante"],
+    "oceania": ["oceania", "polynesian", "maori", "papua"]
+}

package/dist/dateParser.d.ts

@@ -0,0 +1,17 @@
+import type { DateRange } from './types.js';
+/**
+ * Parse a museum-supplied display date into a {yearStart, yearEnd} range.
+ *
+ * Strategies are tried in this exact order — earlier strategies win:
+ *   1. cross-era range ("500 BCE – 50 CE")
+ *   2. numeric range ("1820–1830", "1820-5", "1899–05")
+ *   3. ordinal-century range ("14th-15th century")
+ *   4. ordinal century with optional early/mid/late qualifier
+ *   5. decade ("1820s")
+ *   6. single year ("1888", "ca. 1820", "500 BCE")
+ *   7. dynasty/period lookup (longest key first to avoid prefix shadowing)
+ *
+ * Returns {null, null} when nothing matches — never guesses. BCE is encoded
+ * as negative integers so range arithmetic Just Works.
+ */
+export declare function parseDisplayDate(input: string | null | undefined): DateRange;