Public catalog
Quartermaster can match local artifacts against a public catalog and resolve the latest upstream metadata. It is cache-only by default — a network request happens only behind an explicit double gate.
Cache-only mode (default)
Section titled “Cache-only mode (default)”With no configuration, the catalog is a local SQLite cache:
refresh_public_catalog({ entries })— import supplied static catalog entries (no network). With{ registryUrl, allowNetwork: true }(and the env gate open) it ingests entries live from an MCP registry URL instead; with either gate closed it skips without touching the network.list_public_catalog()— list cached entries.match_public_catalog({ itemId | path | name })— match an item against the cache.check_updates({ itemId })— compares installed vs the cached latest.
Catalog entries may carry content fingerprints (sha256, treeHash,
primaryFileHash, normalizedMarkdownHash, frontmatterStrippedHash) which
find_upstream uses for content-based matching.
Network-enabled mode (opt-in)
Section titled “Network-enabled mode (opt-in)”A network call is allowed only when both are true:
ALLOW_NETWORK_UPDATES=1 (env gate)allowNetwork: true (per-call argument)If either is missing, resolvers return { network: "disabled" } and no
request is made.
Supported resolvers
Section titled “Supported resolvers”| kind | source | fetched |
|---|---|---|
| GitHub | repoUrl / github:owner/repo | default branch, latest commit, release/tag, license, archived/moved/missing |
| npm | registry.npmjs.org/<pkg> | dist-tags.latest, repository.url, license |
| PyPI | pypi.org/pypi/<pkg>/json | info.version, project_urls, license |
| Docker/GHCR | registry tags API | latest version-like tag |
| MCP registry | URL or local fixture | server entries → candidates, dispatched to the matching package/repo resolver |
check_updates({ itemId, allowNetwork: true, refreshSnapshot: true })
additionally fetches the latest GitHub artifact subtree and stores it as an
upstream-latest snapshot for drift comparison.
Rate limits, timeouts, privacy
Section titled “Rate limits, timeouts, privacy”- Every request is time-bounded (
UPSTREAM_FETCH_TIMEOUT_MS, default 5 s); a hang degrades to a warning, not a stall. Rate-limit/403/404 responses surface as warnings. - Provide a
GITHUB_TOKENto raise GitHub limits — sent only as a bearer header, never stored. - Only public metadata (and, with
refreshSnapshot, public file contents) are fetched. Nothing about your local machine is sent. Secrets and local paths in stored evidence are redacted.
Snapshot caps: MAX_UPSTREAM_FILES (200) and MAX_UPSTREAM_BYTES (2 MB) bound
any fetched upstream snapshot.