open-museum-mcp 0.5.0 → 0.7.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![CI](https://github.com/cfpramod/open-museum-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/cfpramod/open-museum-mcp/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/open-museum-mcp.svg)](https://www.npmjs.com/package/open-museum-mcp)
+[![open-museum-mcp MCP server](https://glama.ai/mcp/servers/cfpramod/open-museum-mcp/badges/score.svg)](https://glama.ai/mcp/servers/cfpramod/open-museum-mcp)
 
 > One search across five open-access museum collections, with strict per-museum rights verification and ready-to-use citations.
 
@@ -87,7 +88,17 @@ A search call returns license-verified results in one normalized shape:
 
 > **Want to see it work before installing?** [pramod.ch/open-museum-mcp](https://pramod.ch/open-museum-mcp) walks through the three core workflows with real records and citations.
 
-The package is on npm. The simplest setup is to add it directly to your MCP client config; `npx` will fetch and run it on first launch:
+### One-click
+
+For supported clients, no JSON, no Node, no npm — pick your client:
+
+- **Claude Desktop:** [Download `open-museum-mcp.mcpb`](https://github.com/cfpramod/open-museum-mcp/releases/latest/download/open-museum-mcp.mcpb) from the latest release and double-click it. Claude Desktop opens the bundle and installs the server in one step.
+- **VS Code:** [Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22open-museum-mcp%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22open-museum-mcp%22%5D%7D) — opens VS Code with the install dialog prefilled (requires the GitHub Copilot Chat extension).
+- **Cursor:** [Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=open-museum-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm9wZW4tbXVzZXVtLW1jcCJdfQ==) — same idea, Cursor-flavoured (MCP support is built in).
+
+### JSON config (any MCP client)
+
+For ChatGPT with MCP, Cline, Goose, Continue, Zed, or anything else: paste this into your client's MCP config and restart. `npx` fetches and runs the server on first launch.
 
 ```json
 {
@@ -100,8 +111,6 @@ The package is on npm. The simplest setup is to add it directly to your MCP clie
 }
 ```
 
-That's it. Restart your MCP client and the tools below become available.
-
 ### From source (for contributors)
 
 ```bash
@@ -246,6 +255,14 @@ Highlights:
 - `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.
 
+### Compatibility
+
+`Artwork` field semantics are stable. New versions may add fields or tools, but won't repurpose or remove existing ones within a major version.
+
+- **Backward-compatible.** New server versions may add fields to `Artwork`, add new tools, or add new optional arguments. A v0.5 client calling a v0.6 server will continue to work; it just ignores fields it doesn't know.
+- **Forward-compatible.** A v0.6 client calling an older v0.5 server will get records that lack v0.6-only fields, but the records it does get will validate against the older client's schema.
+- **SemVer.** While in v0.x, MINOR bumps may include backward-incompatible changes (per the [SemVer spec](https://semver.org/) for pre-1.0 versions). From v1.0 onwards, only MAJOR bumps may break compatibility.
+
 ## Non-goals
 
 - **Not a full art-history ontology.** The dynasty and region tables cover the most-encountered cases; they are not exhaustive iconographic taxonomies.
@@ -257,13 +274,26 @@ Highlights:
 
 - v0.1: Met adapter, dynasty-aware date parser, license gate, `cite` tool, MCP resources.
 - v0.2: Cleveland and AIC adapters, `discover_random` with constraints, `list_traditions`.
-- v0.3: Wikimedia Commons adapter (per-record rights model; unlocks works whose home museums lack public APIs).
-- v0.4: Europeana adapter (federated European institutions, opt-in via API key); `year_min`/`year_max` date-range filter on `search_artworks`. **(here)**
+- v0.3: Wikimedia Commons adapter (per-record rights model; covers works whose home museums lack public APIs).
+- v0.4: Europeana adapter (federated European institutions, opt-in via API key); `year_min`/`year_max` date-range filter on `search_artworks`.
+- v0.5: `.mcpb` Desktop Extension bundle (one-click Claude Desktop install); migration to Node 22+ `node:sqlite` (no native compile required). **(here)**
 - v0.7: Wikidata enrichment (artist QIDs, movement, country, dedup across cache).
 - v0.8: Dominant-colour 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 direct integration, Walters Art Museum, more European institutions.
 
+### Release cadence
+
+This is a side project. New releases ship when one of three things happens: my own work needs a feature, a new museum is wired in, or a contributor's PR is merged. There is no fixed cadence. I do commit to reviewing and merging contributor PRs promptly.
+
+### Project status
+
+This is actively maintained as of the latest release. Because it is a side project, if active maintenance ever stops I will archive the repository and say so here, rather than leave it looking live. The published npm package, the adapters, and the `Artwork` schema remain usable either way, and the code is MIT-licensed, so anyone is free to fork and continue it. Governance and the path for new maintainers are described in [GOVERNANCE.md](GOVERNANCE.md).
+
+### Changelog
+
+[Releases](https://github.com/cfpramod/open-museum-mcp/releases) lists what shipped in each version, with notes.
+
 ## Contributing a museum adapter
 
 See [CONTRIBUTING.md](CONTRIBUTING.md). The short version:

package/dist/clearanceTool.d.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import type { Federation } from './core/index.js';
+/**
+ * Input schema for the `clearance_record` MCP tool.
+ *
+ * Deliberately does NOT regex-validate the id against ID_REGEX, unlike
+ * `get_artwork` and `cite`. The clearance tool's contract is that a non-cleared
+ * work — including a malformed id — returns a definitive DENY manifest, not an
+ * error. `federation.clearanceManifest` emits that deny for an invalid id, so
+ * gating the id here would wrongly convert a contractual deny into a ZodError.
+ */
+export declare const ClearanceInput: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Handle a `clearance_record` call. Returns a normal (non-error) tool result
+ * for every id: a cleared work yields a permitted manifest, a non-cleared or
+ * malformed id yields a deny manifest. Both are valid answers.
+ */
+export declare function handleClearanceRecord(federation: Federation, args: unknown): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/clearanceTool.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+/**
+ * Input schema for the `clearance_record` MCP tool.
+ *
+ * Deliberately does NOT regex-validate the id against ID_REGEX, unlike
+ * `get_artwork` and `cite`. The clearance tool's contract is that a non-cleared
+ * work — including a malformed id — returns a definitive DENY manifest, not an
+ * error. `federation.clearanceManifest` emits that deny for an invalid id, so
+ * gating the id here would wrongly convert a contractual deny into a ZodError.
+ */
+export const ClearanceInput = z.object({
+    id: z.string(),
+});
+/**
+ * Handle a `clearance_record` call. Returns a normal (non-error) tool result
+ * for every id: a cleared work yields a permitted manifest, a non-cleared or
+ * malformed id yields a deny manifest. Both are valid answers.
+ */
+export async function handleClearanceRecord(federation, args) {
+    const input = ClearanceInput.parse(args);
+    const env = await federation.clearanceManifest(input.id);
+    return { content: [{ type: 'text', text: JSON.stringify(env, null, 2) }] };
+}
+//# sourceMappingURL=clearanceTool.js.map

package/dist/clearanceTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clearanceTool.js","sourceRoot":"","sources":["../src/clearanceTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;CACf,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,UAAsB,EAAE,IAAa;IAC/E,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACzD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACtF,CAAC"}

package/dist/core/cache.d.ts

@@ -0,0 +1,20 @@
+import type { Artwork } from '../types.js';
+/** A value that may be returned synchronously or as a promise. */
+export type Awaitable<T> = T | Promise<T>;
+/**
+ * The minimal cache surface the federation engine depends on. Two methods for
+ * normalized objects, two for search-result ID lists.
+ *
+ * Implementations may be synchronous or asynchronous: the MCP server's
+ * `node:sqlite` cache returns values directly, while an edge deployment
+ * (e.g. Cloudflare KV) returns promises. The federation `await`s every call,
+ * so both satisfy this interface. Keeping the surface this small is what lets
+ * the same engine run on a stdio server and on a Workers runtime that cannot
+ * load `node:sqlite`.
+ */
+export interface CacheStore {
+    getObject(id: string): Awaitable<Artwork | null>;
+    upsertObject(art: Artwork): Awaitable<void>;
+    getQuery(cacheKey: string): Awaitable<string[] | null>;
+    putQuery(cacheKey: string, ids: string[]): Awaitable<void>;
+}

package/dist/core/cache.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cache.js.map

package/dist/core/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/core/cache.ts"],"names":[],"mappings":""}

package/dist/core/clearance/envelope.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Tier-0 envelope: integrity, not authenticity. It wraps a pure Clearance
+ * Manifest payload with a hash computed over the payload's RFC 8785 (JCS)
+ * canonical bytes. The hash lives HERE, never inside the payload — payload
+ * purity is a design invariant (the payload never carries its own hash, its
+ * signature, or any commercial data).
+ *
+ * This is what the distributed OSS MCP emits by default; it ships no key.
+ * Tiers 1/2 (C2PA signing) wrap the same payload with a signature — the payload
+ * shape is unchanged across tiers.
+ */
+export interface Tier0Envelope<T = unknown> {
+    tier: 0;
+    payload: T;
+    integrity: {
+        alg: 'sha-256';
+        jcs: true;
+        hash: string;
+    };
+}
+/**
+ * Wrap a payload in a Tier-0 envelope. Canonicalizes FIRST (RFC 8785), then
+ * hashes the canonical bytes with Web Crypto (`crypto.subtle`, Workers-safe).
+ * Throws if the payload is not canonicalizable JSON.
+ */
+export declare function wrapTier0<T>(payload: T): Promise<Tier0Envelope<T>>;

package/dist/core/clearance/envelope.js

@@ -0,0 +1,15 @@
+import { canonicalizeToBytes } from './jcs.js';
+/**
+ * Wrap a payload in a Tier-0 envelope. Canonicalizes FIRST (RFC 8785), then
+ * hashes the canonical bytes with Web Crypto (`crypto.subtle`, Workers-safe).
+ * Throws if the payload is not canonicalizable JSON.
+ */
+export async function wrapTier0(payload) {
+    const bytes = canonicalizeToBytes(payload);
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    const hash = Array.from(new Uint8Array(digest))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+    return { tier: 0, payload, integrity: { alg: 'sha-256', jcs: true, hash } };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/core/clearance/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../../src/core/clearance/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAmB/C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,OAAU;IAC3C,MAAM,KAAK,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;SAC5C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SAC3C,IAAI,CAAC,EAAE,CAAC,CAAC;IACZ,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;AAC9E,CAAC"}

package/dist/core/clearance/jcs.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Canonicalize a JSON-compatible value to its RFC 8785 string form.
+ * Throws on values JSON cannot represent (functions, symbols, undefined,
+ * non-finite numbers) — a Clearance Manifest payload must be canonicalizable.
+ */
+export declare function canonicalize(value: unknown): string;
+/** Canonicalize and encode to UTF-8 bytes (ArrayBuffer-backed, for Web Crypto). */
+export declare function canonicalizeToBytes(value: unknown): Uint8Array<ArrayBuffer>;

package/dist/core/clearance/jcs.js

@@ -0,0 +1,65 @@
+// RFC 8785 JSON Canonicalization Scheme (JCS).
+//
+// Produces the canonical UTF-8 serialization of a JSON value: object keys sorted
+// by UTF-16 code unit, ECMAScript number serialization, minimal string escaping,
+// no insignificant whitespace. This is the byte sequence a Clearance Manifest's
+// Tier-0 envelope hashes over.
+//
+// Lifted verbatim (ported to TypeScript) from the PIF sibling standard's vetted
+// dependency-free verifier (pif-spec/verifier/jcs.mjs). Runs unchanged in Node,
+// the browser, and Cloudflare Workers — no dependencies, no `node:` imports.
+//
+// IMPORTANT (the contract the spec must warn implementers about): canonicalize
+// FIRST, then hash the canonical bytes. Never hash the raw serialized string —
+// JSON.stringify on the same object can produce different bytes (key order,
+// whitespace) and therefore a different, non-interoperable hash.
+/**
+ * Canonicalize a JSON-compatible value to its RFC 8785 string form.
+ * Throws on values JSON cannot represent (functions, symbols, undefined,
+ * non-finite numbers) — a Clearance Manifest payload must be canonicalizable.
+ */
+export function canonicalize(value) {
+    if (value === null)
+        return 'null';
+    const t = typeof value;
+    if (t === 'boolean')
+        return value ? 'true' : 'false';
+    if (t === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new Error('JCS: non-finite numbers are not permitted in JSON');
+        }
+        // JSON.stringify uses ECMAScript Number-to-string, which is what JCS mandates.
+        return JSON.stringify(value);
+    }
+    if (t === 'string') {
+        // ECMAScript JSON string escaping (control chars as \u00XX, correct surrogate
+        // handling) is exactly the escaping RFC 8785 specifies.
+        //
+        // PORTABILITY NOTE for non-JS implementers (RFC 8785 §3.2.2.2): escape ONLY the
+        // two mandatory characters (" -> \", \ -> \\) and the C0 control range U+0000..U+001F,
+        // using the short forms \b \t \n \f \r where they exist and \u00XX (lowercase hex)
+        // otherwise. Do NOT escape the forward solidus "/", and do NOT escape any non-ASCII
+        // character; codepoints >= U+0080 are emitted as raw UTF-8. Over-escaping (e.g.
+        // \uXXXX for every non-ASCII char, as some language JSON encoders do by default) is
+        // the most common interop bug and will produce a different byte string, hence a
+        // different hash. V8's JSON.stringify already implements exactly this.
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map(canonicalize).join(',') + ']';
+    }
+    if (t === 'object') {
+        // Object.keys() then default Array sort: lexicographic by UTF-16 code unit,
+        // which is the ordering RFC 8785 requires.
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        const members = keys.map((k) => JSON.stringify(k) + ':' + canonicalize(obj[k]));
+        return '{' + members.join(',') + '}';
+    }
+    throw new Error(`JCS: unsupported value of type ${t}`);
+}
+/** Canonicalize and encode to UTF-8 bytes (ArrayBuffer-backed, for Web Crypto). */
+export function canonicalizeToBytes(value) {
+    return new TextEncoder().encode(canonicalize(value));
+}
+//# sourceMappingURL=jcs.js.map

package/dist/core/clearance/jcs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jcs.js","sourceRoot":"","sources":["../../../src/core/clearance/jcs.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,EAAE;AACF,iFAAiF;AACjF,iFAAiF;AACjF,gFAAgF;AAChF,+BAA+B;AAC/B,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,6EAA6E;AAC7E,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,4EAA4E;AAC5E,iEAAiE;AAEjE;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAElC,MAAM,CAAC,GAAG,OAAO,KAAK,CAAC;IAEvB,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IAErD,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;QACnB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,CAAC;QACD,+EAA+E;QAC/E,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;QACnB,8EAA8E;QAC9E,wDAAwD;QACxD,EAAE;QACF,gFAAgF;QAChF,uFAAuF;QACvF,mFAAmF;QACnF,oFAAoF;QACpF,gFAAgF;QAChF,oFAAoF;QACpF,gFAAgF;QAChF,uEAAuE;QACvE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACvD,CAAC;IAED,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;QACnB,4EAA4E;QAC5E,2CAA2C;QAC3C,MAAM,GAAG,GAAG,KAAgC,CAAC;QAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACrC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAChF,OAAO,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACvC,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,EAAE,CAAC,CAAC;AACzD,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AACvD,CAAC"}

package/dist/core/clearance/licenseMap.d.ts

@@ -0,0 +1,38 @@
+import type { LicenseType, RightsConfidence } from '../../types.js';
+/**
+ * The structured `basis` for a single clearance determination. Shape is normative
+ * (schema-enforced): `rule`, `inputs`, and `summary` are all required —
+ * honesty-by-architecture. A determination that cannot name its rule, cite its
+ * inputs, and state its reasoning is not a valid determination.
+ *
+ * `rule` is a stable id that resolves as a fragment under the rule registry:
+ * `https://openclearance.org/v0.1/rules#<rule>`. The set of ids is OPEN, not a
+ * closed enum — an unrecognised id yields a non-fatal `unrecognised_rule`
+ * advisory at verification time, never a schema rejection. See
+ * `spec/clearance/v0.1/rules.md`.
+ */
+export interface ClearanceBasis {
+    rule: string;
+    inputs: {
+        field: string;
+        value: unknown;
+    }[];
+    summary: string;
+}
+export interface ClearanceDecision {
+    statement: string | null;
+    commercialReproduction: {
+        permitted: boolean;
+        basis: ClearanceBasis;
+    };
+    derivatives: {
+        permitted: boolean;
+        basis: ClearanceBasis;
+    };
+    attributionRequired: {
+        required: boolean;
+        basis: ClearanceBasis;
+    };
+    confidence: RightsConfidence;
+}
+export declare function clearanceForLicense(type: LicenseType): ClearanceDecision;

package/dist/core/clearance/licenseMap.js

@@ -0,0 +1,68 @@
+// The ONLY place clearance determinations live. Fail-closed: a license type not
+// listed here resolves to all-false / default-deny. Adding a recognised
+// permissive license later is a single entry here + a rule-registry row + a test.
+const PERMISSIVE = {
+    CC0: {
+        statement: 'https://creativecommons.org/publicdomain/zero/1.0/',
+        rulePrefix: 'cc0',
+        summaryNoun: 'CC0 public-domain dedication',
+    },
+    // The gate only emits type=PD for the worldwide Creative Commons Public
+    // Domain Mark (Europeana `rights` = .../publicdomain/mark/1.0/) and the
+    // Wikimedia PD/PDM templates — never a jurisdiction-scoped rightsstatements.org
+    // value. The Public Domain Mark URI is therefore the accurate, gate-aligned
+    // statement; the old US-scoped NoC-US URI claimed a narrower (and incorrect)
+    // scope the gate never asserts.
+    PD: {
+        statement: 'https://creativecommons.org/publicdomain/mark/1.0/',
+        rulePrefix: 'pd',
+        summaryNoun: 'Public Domain Mark status',
+    },
+};
+export function clearanceForLicense(type) {
+    const ok = PERMISSIVE[type];
+    const inputs = [{ field: 'license.type', value: type }];
+    if (ok) {
+        return {
+            statement: ok.statement,
+            commercialReproduction: {
+                permitted: true,
+                basis: {
+                    rule: `${ok.rulePrefix}-grants-commercial`,
+                    inputs,
+                    summary: `${ok.summaryNoun} permits all uses, including commercial.`,
+                },
+            },
+            derivatives: {
+                permitted: true,
+                basis: {
+                    rule: `${ok.rulePrefix}-grants-derivatives`,
+                    inputs,
+                    summary: `${ok.summaryNoun} permits modification and derivative works.`,
+                },
+            },
+            attributionRequired: {
+                required: false,
+                basis: {
+                    rule: `${ok.rulePrefix}-waives-attribution`,
+                    inputs,
+                    summary: `${ok.summaryNoun} requires no attribution as a condition of reuse.`,
+                },
+            },
+            confidence: 'high',
+        };
+    }
+    const denyBasis = {
+        rule: 'default-deny',
+        inputs,
+        summary: `unrecognized or non-permissive license type '${type}' ⇒ default deny`,
+    };
+    return {
+        statement: null,
+        commercialReproduction: { permitted: false, basis: denyBasis },
+        derivatives: { permitted: false, basis: denyBasis },
+        attributionRequired: { required: false, basis: denyBasis },
+        confidence: 'low',
+    };
+}
+//# sourceMappingURL=licenseMap.js.map

package/dist/core/clearance/licenseMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"licenseMap.js","sourceRoot":"","sources":["../../../src/core/clearance/licenseMap.ts"],"names":[],"mappings":"AA4BA,gFAAgF;AAChF,wEAAwE;AACxE,kFAAkF;AAClF,MAAM,UAAU,GAEZ;IACF,GAAG,EAAE;QACH,SAAS,EAAE,oDAAoD;QAC/D,UAAU,EAAE,KAAK;QACjB,WAAW,EAAE,8BAA8B;KAC5C;IACD,wEAAwE;IACxE,wEAAwE;IACxE,gFAAgF;IAChF,4EAA4E;IAC5E,6EAA6E;IAC7E,gCAAgC;IAChC,EAAE,EAAE;QACF,SAAS,EAAE,oDAAoD;QAC/D,UAAU,EAAE,IAAI;QAChB,WAAW,EAAE,2BAA2B;KACzC;CACF,CAAC;AAEF,MAAM,UAAU,mBAAmB,CAAC,IAAiB;IACnD,MAAM,EAAE,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,MAAM,GAAG,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAExD,IAAI,EAAE,EAAE,CAAC;QACP,OAAO;YACL,SAAS,EAAE,EAAE,CAAC,SAAS;YACvB,sBAAsB,EAAE;gBACtB,SAAS,EAAE,IAAI;gBACf,KAAK,EAAE;oBACL,IAAI,EAAE,GAAG,EAAE,CAAC,UAAU,oBAAoB;oBAC1C,MAAM;oBACN,OAAO,EAAE,GAAG,EAAE,CAAC,WAAW,0CAA0C;iBACrE;aACF;YACD,WAAW,EAAE;gBACX,SAAS,EAAE,IAAI;gBACf,KAAK,EAAE;oBACL,IAAI,EAAE,GAAG,EAAE,CAAC,UAAU,qBAAqB;oBAC3C,MAAM;oBACN,OAAO,EAAE,GAAG,EAAE,CAAC,WAAW,6CAA6C;iBACxE;aACF;YACD,mBAAmB,EAAE;gBACnB,QAAQ,EAAE,KAAK;gBACf,KAAK,EAAE;oBACL,IAAI,EAAE,GAAG,EAAE,CAAC,UAAU,qBAAqB;oBAC3C,MAAM;oBACN,OAAO,EAAE,GAAG,EAAE,CAAC,WAAW,mDAAmD;iBAC9E;aACF;YACD,UAAU,EAAE,MAAM;SACnB,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAmB;QAChC,IAAI,EAAE,cAAc;QACpB,MAAM;QACN,OAAO,EAAE,gDAAgD,IAAI,kBAAkB;KAChF,CAAC;IACF,OAAO;QACL,SAAS,EAAE,IAAI;QACf,sBAAsB,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE;QAC9D,WAAW,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE;QACnD,mBAAmB,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE;QAC1D,UAAU,EAAE,KAAK;KAClB,CAAC;AACJ,CAAC"}

package/dist/core/clearance/manifest.d.ts

@@ -0,0 +1,104 @@
+import type { Artist, ArtworkImages, RightsConfidence, ValidationResult } from '../../types.js';
+import { type ClearanceBasis } from './licenseMap.js';
+/**
+ * The pure Clearance Manifest payload (JSON-LD). It never contains its own hash,
+ * its signature, or any commercial data — integrity lives in the Tier-0 envelope
+ * (see envelope.ts), commerce in a sibling vendor assertion that references this
+ * payload by content hash. The payload is byte-identical to what the engine
+ * emits and independently verifiable.
+ *
+ * Field names mirror the engine's canonical Artwork vocabulary wherever they map
+ * (`artist`, `displayDate`, `imageUrls`, `imageOpenAccess`, `metadataOpenAccess`,
+ * `museum`) so the open-museum.art data-model reconciliation is a thin mapping,
+ * not a translation. JSON-LD semantics are supplied by aliasing these terms to
+ * schema.org / Dublin Core IRIs in context.jsonld — the `@context` is the sole
+ * normative authority; `specVersion` is human-readable convenience only.
+ */
+export interface ClearanceManifestPayload {
+    '@context': string[];
+    type: 'ClearanceManifest';
+    specVersion: string;
+    work: ClearanceWork;
+    source: ClearanceSource;
+    rights: ClearanceRights;
+    clearance: ClearanceBlock;
+    verification: ClearanceVerification;
+    /** Omitted for rejected records, which carry no identified Artwork to cite. */
+    citation?: ClearanceCitation;
+}
+export interface ClearanceWork {
+    id: string;
+    title?: string;
+    artist?: Artist;
+    displayDate?: string;
+    yearStart?: number | null;
+    yearEnd?: number | null;
+    medium?: string;
+}
+export interface ClearanceMuseum {
+    code: string;
+    name?: string;
+    url?: string;
+}
+export interface ClearanceSource {
+    museum: ClearanceMuseum;
+    apiUrl?: string;
+    pageUrl?: string;
+    originalUrl?: string;
+    imageUrls?: ArtworkImages;
+}
+export interface ClearanceRights {
+    statement: string | null;
+    sourceApiValue: {
+        field: string;
+        value: unknown;
+    } | null;
+    imageOpenAccess: boolean;
+    metadataOpenAccess: boolean;
+    confidence: RightsConfidence;
+}
+export interface ClearanceBlock {
+    commercialReproduction: {
+        permitted: boolean;
+        basis: ClearanceBasis;
+    };
+    derivatives: {
+        permitted: boolean;
+        basis: ClearanceBasis;
+    };
+    attributionRequired: {
+        required: boolean;
+        basis: ClearanceBasis;
+    };
+}
+export interface ClearanceVerification {
+    determinedBy: {
+        actor: string;
+        role: string;
+    };
+    tool: string;
+    determinedAt: string;
+    ruleContext: string;
+    determinationSource: {
+        type: string;
+        field?: string;
+        url?: string;
+        retrievedAt: string;
+    };
+}
+export interface ClearanceCitation {
+    full: string;
+    caption: string;
+    short: string;
+}
+export interface BuildOptions {
+    /** Engine version string for the `verification.tool` provenance field. */
+    engineVersion: string;
+    /**
+     * Generation timestamp, used only where no determination timestamp exists in
+     * the data (the deny path has no `license.verifiedAt`). Injected so manifests
+     * are deterministic and reproducible as conformance fixtures.
+     */
+    now: string;
+}
+export declare function buildClearancePayload(result: ValidationResult, opts: BuildOptions): ClearanceManifestPayload;

package/dist/core/clearance/manifest.js

@@ -0,0 +1,112 @@
+import { cite } from '../../cite.js';
+import { clearanceForLicense } from './licenseMap.js';
+const CONTEXT = [
+    'https://schema.org/',
+    'http://purl.org/dc/terms/',
+    'https://openclearance.org/v0.1/context.jsonld',
+];
+const TYPE = 'ClearanceManifest';
+const SPEC_VERSION = '0.1';
+const TOOL_NAME = 'open-museum-mcp';
+/** Split `<museum>.<field path>` on the first dot. `met.isPublicDomain` → field `isPublicDomain`. */
+function apiFieldOf(verificationSource) {
+    const i = verificationSource.indexOf('.');
+    return i < 0 ? verificationSource : verificationSource.slice(i + 1);
+}
+export function buildClearancePayload(result, opts) {
+    return result.status === 'accepted'
+        ? buildAccepted(result.artwork, opts)
+        : buildRejected(result.rejection, opts);
+}
+function buildAccepted(art, opts) {
+    const decision = clearanceForLicense(art.license.type);
+    const field = apiFieldOf(art.license.verificationSource);
+    return {
+        '@context': CONTEXT,
+        type: TYPE,
+        specVersion: SPEC_VERSION,
+        work: {
+            id: art.id,
+            title: art.title,
+            artist: art.artist,
+            displayDate: art.displayDate,
+            yearStart: art.yearStart,
+            yearEnd: art.yearEnd,
+            medium: art.medium,
+        },
+        source: {
+            museum: { code: art.museum.code, name: art.museum.name, url: art.museum.url },
+            apiUrl: art.source.apiUrl,
+            pageUrl: art.source.pageUrl,
+            ...(art.source.originalUrl ? { originalUrl: art.source.originalUrl } : {}),
+            imageUrls: art.imageUrls,
+        },
+        rights: {
+            statement: decision.statement,
+            sourceApiValue: { field, value: art.license.rawValue },
+            imageOpenAccess: art.imageOpenAccess,
+            metadataOpenAccess: art.metadataOpenAccess,
+            confidence: decision.confidence,
+        },
+        clearance: {
+            commercialReproduction: decision.commercialReproduction,
+            derivatives: decision.derivatives,
+            attributionRequired: decision.attributionRequired,
+        },
+        verification: {
+            determinedBy: { actor: `museum:${art.museum.code}`, role: 'rights-source' },
+            tool: `${TOOL_NAME}@${opts.engineVersion} · ${art.license.verificationSource}`,
+            determinedAt: art.license.verifiedAt,
+            ruleContext: `${art.license.verificationSource}='${art.license.rawValue}' ⇒ ${art.license.type}`,
+            determinationSource: {
+                type: 'api-field',
+                field,
+                url: art.source.apiUrl,
+                retrievedAt: art.license.verifiedAt,
+            },
+        },
+        citation: {
+            full: cite(art, 'full'),
+            caption: cite(art, 'caption'),
+            short: cite(art, 'short'),
+        },
+    };
+}
+function buildRejected(rej, opts) {
+    // The deny determination (all-false booleans, default-deny rule, low
+    // confidence) comes from the single source of truth; the rejection supplies
+    // the case-specific evidence (the gate's verbatim reason) into each basis.
+    const decision = clearanceForLicense('UNKNOWN');
+    const basis = {
+        rule: 'default-deny',
+        inputs: [{ field: 'rejection.reason', value: rej.reason }],
+        summary: `rights gate rejected '${rej.id}': ${rej.reason} ⇒ default deny`,
+    };
+    return {
+        '@context': CONTEXT,
+        type: TYPE,
+        specVersion: SPEC_VERSION,
+        work: { id: rej.id },
+        source: { museum: { code: rej.museumCode } },
+        rights: {
+            statement: decision.statement,
+            sourceApiValue: null,
+            imageOpenAccess: false,
+            metadataOpenAccess: false,
+            confidence: decision.confidence,
+        },
+        clearance: {
+            commercialReproduction: { permitted: false, basis },
+            derivatives: { permitted: false, basis },
+            attributionRequired: { required: false, basis },
+        },
+        verification: {
+            determinedBy: { actor: 'engine:open-museum-mcp', role: 'rights-gate' },
+            tool: `${TOOL_NAME}@${opts.engineVersion} · rights-gate`,
+            determinedAt: opts.now,
+            ruleContext: `strict default deny: ${rej.reason}`,
+            determinationSource: { type: 'rights-gate-default', retrievedAt: opts.now },
+        },
+    };
+}
+//# sourceMappingURL=manifest.js.map

package/dist/core/clearance/manifest.js.map

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