# Met research MCP

Public source repository: <https://github.com/evenwestvang/met-mcp>.
The distribution/package name remains `met-research-mcp` and the Python module is
`met_mcp`.

A read-only, snapshot-backed MCP server for collection research. It exposes six
tools without bundling a catalogue, embeddings, images, or model files:

- `collection_capabilities` reports the loaded snapshot, fields, rank methods,
  coverage, unavailable features, and limits.
- `collection_facets` lists exact recorded values, optionally within a selection.
- `collection_select` applies bounded typed predicates and returns a
  snapshot-bound selection receipt.
- `collection_rank` ranks that exact eligible selection with an explicitly
  supported anchor, axis, and method.
- `collection_objects` hydrates bounded batches of source-scoped object metadata.
- `collection_evidence` resolves source and vector evidence IDs.

Selection is deliberately separate from ranking: hard filters and missing/conflict
policies determine eligibility first, then ranking orders only those candidates.
Metadata-only methods remain available without vectors. Visual ranking scores only
objects with compatible stored vectors and reports the rest as unscored; it does not
infer style, authorship, culture, provenance, or historical relationships.

The optional paired text path adds `topic_text / visual /
siglip2_text_cosine_v1` to `collection_rank` only when a compatible fixed encoder
identity and sidecar are configured. It adds no seventh tool and never falls back to
another ranker. Clients must inspect capabilities before use.

This is an independent research tool. It is not affiliated with, endorsed by, or an
official service of The Metropolitan Museum of Art.

## Install

Python 3.11 is required. `requirements.lock` contains the exact dependency versions
used for the ordinary server, imports, and tests; it is a version pin set, not a
hash-locked supply-chain attestation.

```sh
python3.11 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock
```

For a network-isolated install, first obtain all wheels through your own reviewed
process, then use the same pins from a local wheelhouse:

```sh
.venv/bin/python -m pip install --no-index --find-links /path/to/wheelhouse \
  -r requirements.lock
```

The source tree runs directly with `PYTHONPATH=src`; installing this project as a
package is optional.

## Supply and import data

No `data/` directory is included. A serving directory must contain
`catalogue.sqlite`, `manifest.json`, `vector_ids.npy`, and `vectors.npy` as produced
by the importer. Metadata records may greatly outnumber available vectors; the
generated manifest and `collection_capabilities` expose the actual denominators.

The primary bounded fixture import uses two publicly obtainable,
checksum-verified inputs: the pinned Met Open Access CSV and the pinned first
published SigLIP2 shard.

```sh
export MET_CSV=/path/to/MetObjects.csv
export MET_VECTOR_SHARD=/path/to/siglip2-00000-of-00052.parquet
export MET_OUTPUT=/path/to/generated/met-mcp-dataset

sha256sum "$MET_CSV" "$MET_VECTOR_SHARD"
PYTHONPATH=src .venv/bin/python -m met_mcp.build_fixture \
  --csv "$MET_CSV" \
  --vectors "$MET_VECTOR_SHARD" \
  --output "$MET_OUTPUT"
```

With the pinned inputs, this default fixture deterministically selects 1,000 CSV
records and stores 200 vectors from the supplied first shard that intersect that
selection. It does not provide all 484,956 CSV records or full-vector coverage. The
expected hashes, revisions, upstream paths, licenses, and limits are recorded in
[DATA-SOURCES.md](DATA-SOURCES.md). The importer performs no fetches and rejects the
wrong CSV or vector shard.

The public-input test builds that no-seed fixture twice in temporary directories,
compares its snapshot, selection, and every derived receipt, then serves it over
loopback and exercises all six tools through the official MCP Python SDK:

```sh
PYTHONPATH=src:. .venv/bin/pytest -q tests/test_public_import.py \
  --external-csv "$MET_CSV" \
  --external-vectors "$MET_VECTOR_SHARD"
```

`--api-seeds` is optional, separately dated enrichment from captures supplied by
the user. The importer verifies every declared response hash and keeps API evidence
separate from CSV evidence. The historical nine-object capture used by regression
tests is not distributed publicly and cannot be reproduced by GETting today's API:
current responses are new observations, not the original dated bytes or state. See
[DATA-SOURCES.md](DATA-SOURCES.md) for the manifest format and limitation.

For full pinned-CSV metadata with only the 4,996 compatible vectors joined from the
first shard, use the existing larger mode (not exercised by the bounded quickstart
or public-input test):

```sh
PYTHONPATH=src .venv/bin/python -m met_mcp.build_fixture \
  --dataset-mode csv_baseline \
  --csv "$MET_CSV" \
  --vectors "$MET_VECTOR_SHARD" \
  --output /path/to/generated/met-mcp-csv-baseline
```

The ancillary `met_mcp.full_vectors` path is not a portable three-input complete
release rebuild. Its import requires all 52 pinned shards plus project-specific
census/ID-column receipts, a completed download checkpoint, and the specifically
accepted `csv-baseline-efac7fc7083c9ee44eb6` base dataset. It is retained for the
historical release workflow, not presented as part of this public quickstart.

## Run locally

The bearer secret is required. Prefer a protected token file, and keep the default
loopback bind unless you have separately designed the network boundary.

```sh
export MET_MCP_TOKEN_FILE=/path/to/private/met-mcp-token
install -m 600 /dev/null "$MET_MCP_TOKEN_FILE"
.venv/bin/python -c 'import secrets; print(secrets.token_urlsafe(32))' > "$MET_MCP_TOKEN_FILE"
export MET_MCP_DATA_DIR=/path/to/generated/met-mcp-dataset
export MET_MCP_BEARER_TOKEN_FILE="$MET_MCP_TOKEN_FILE"
export MET_MCP_ALLOWED_HOSTS='127.0.0.1:8000,localhost:8000'
export MET_MCP_ALLOWED_ORIGINS='http://127.0.0.1:3000,http://localhost:3000'
PYTHONPATH=src .venv/bin/python -m met_mcp.cli serve
```

`/healthz` and `/readyz` disclose only status. `/mcp` requires the exact bearer
token, an allowed Host, and (when present) an allowed Origin. The server defaults to
one expensive query at a time, a 10-second query budget, bounded bodies, concurrency,
and backlog. Generic local-only container configuration is in
[deploy/README.md](deploy/README.md).

## Optional paired SigLIP2 text encoder

This path requires separately obtained files for
`google/siglip2-so400m-patch14-384` at revision
`e8e487298228002f3d8a82e0cd5c8ea9c567f57f`. Verify every source file listed in
[DATA-SOURCES.md](DATA-SOURCES.md), then derive the text-only artifact without
network access or modification of the source directory:

```sh
PYTHONPATH=src .venv/bin/python scripts/build_siglip2_text_assets.py \
  --source-dir /path/to/verified/full-checkpoint \
  --derived-dir /path/to/derived/text-tower
```

Install `requirements-siglip2-text.lock` in a separate Python 3.11 environment from
the MCP server and start the sidecar from the derived directory. Plan a separate
4 GiB memory envelope for this optional process and validate capacity on your own
host; this is a planning limit, not a host acceptance result. The sidecar forces
offline library modes, validates all serving-file hashes against
`encoder-identity.json`, serves on loopback by default, and admits one inference at
a time.

```sh
SIGLIP2_TEXT_MODEL_DIR=/path/to/derived/text-tower \
  /path/to/text-venv/bin/python scripts/siglip2_text_encoder.py

export MET_MCP_SIGLIP2_ENCODER_URL=http://127.0.0.1:8080
export MET_MCP_SIGLIP2_ENCODER_IDENTITY_FILE=/path/to/derived/text-tower/encoder-identity.json
export MET_MCP_SIGLIP2_ENCODER_TIMEOUT_SECONDS=6
```

Set those encoder variables in the environment used to launch the MCP server, then
start or restart the MCP process. Exporting them in another shell does not modify an
already running process. The sidecar and MCP server remain separate environments.

The exact recipe—including lowercasing, 64-token padded input, no attention mask,
and L2-normalized `SiglipTextModel.pooler_output`—is part of the identity. Cosine
scores are discovery signals, not calibrated relevance or factual evidence. The
published image vectors do not identify their original image-generation checkpoint
revision or preprocessing, so cross-modal compatibility remains a documented limit.

## Test

Asset-free coverage uses synthetic records only for mocked API capture state:

```sh
PYTHONPATH=src:. .venv/bin/pytest -q -m 'not external_data'
```

That command currently reports 57 passed and 23 deselected. An unqualified run with
no external inputs reports 57 passed and 23 skipped. External modes are explicit:

- `--external-data-dir` (or `MET_MCP_TEST_DATA_DIR`) supplies the historical seeded
  fixture expected by existing service, ranking, boundary, and SDK regression
  assertions. Those assertions refer to specific historical objects and are not a
  generic validator for an arbitrary generated dataset.
- `--external-api-seeds` (or `MET_MCP_TEST_API_SEEDS`) supplies the exact dated set
  for historical manifest/hash regression validation.
- `--external-csv` and `--external-vectors` (or `MET_MCP_TEST_CSV` and
  `MET_MCP_TEST_VECTORS`) enable the public no-seed two-build/SDK proof. Together
  with `--external-api-seeds`, they also enable the historical seeded importer
  regression. `pyarrow` from `requirements.lock` is required.

For example, the first two modes run with:

```sh
PYTHONPATH=src:. .venv/bin/pytest -q tests \
  --external-data-dir /path/to/historical-seeded-fixture \
  --external-api-seeds /path/to/api-seeds
```

Tests skip—not silently substitute—any external mode whose inputs are absent. The
public-input command above is the portable generated-dataset check; the historical
suite requires the undistributed dated fixture and seeds explicitly.

The six-tool schemas and examples are under [contract/](contract/). Examples that
show Met records retain their source labels and are illustrative rather than bundled
data. Review [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md) before redistributing
external inputs or generated datasets.