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.

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:

.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.

Related MCP server: governed-rag-mcp

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.

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. 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:

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 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):

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.

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.

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, then derive the text-only artifact without network access or modification of the source directory:

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.

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:

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:

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/. Examples that show Met records retain their source labels and are illustrative rather than bundled data. Review THIRD-PARTY-NOTICES.md before redistributing external inputs or generated datasets.