The server exposes MESA/mesa-mcp tools for iRODS data management, AVU metadata, DataCite records, OLS ontology lookup, MESA policies, and DuckLake project history.
Check liveness with ds_ping.
Browse and CRUD iRODS files/collections: list, tree, info, search, read/write, copy, move, delete, make directories, and get upload/download instructions.
Manage AVUs: add one or many, list, get, delete, search by attribute/value/unit, and apply canonical ontology or DataCite AVUs.
Work with OLS ontologies: list ontologies, fetch ontology/term/hierarchy, search terms, generate SCHEMAS templates, and build canonical AVU triples from terms.
Handle DataCite records: get a field template, validate AVUs, export XML/JSON, and apply validated records as AVUs.
Control MESA policies: list, enable, or disable project policies; introspect PCF/rule configs where supported.
Manage iRODS tickets: create, list, get info, modify, delete, and use tickets with expiry, use, host, user, and byte restrictions.
Administer access and rules: modify access and inheritance, and execute or list iRODS rules.
Enroll projects and record history by initializing DuckLake projects and mirroring AVU changes into DuckLake snapshots.
Serves as the provenance store backend for the MCP server: provenance data is written to a DuckDB database via a duckdb:// DSN, recording every metadata annotation decision in a provenance sidecar alongside the AVU (attribute-value-unit) history kept by mesa-ducklake.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mesa-clm propose OBO-grounded AVUs for dataset neon-soil-samples and explain the top picks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Calibrated, ontology-grounded metadata annotation for the MESA stack with Contrastive LM.
mesa-clm proposes OBO-grounded AVUs for a dataset the way its sibling
mesa-anyjev does, but asks
Contrastive LM (CLM) instead of AnyJev: every fit
question is one rank over the candidate terms plus a fixed "none of these" anchor, scored by a
frozen Qwen3-8B encoder and CLM's projection heads behind a loopback HTTP server. A reasoning
model only plans (which ontologies are in play, what to search); deterministic code drives
mesa-mcp's OBO/OLS tools; every decision is recorded in
a provenance sidecar next to the AVU history kept by
mesa-ducklake. The core is a torch-free client;
the encoder and clm-serve run as separate processes.
Status: pre-alpha, milestone M2 done (2026-10-03). The registered framing experiment
(bench/results/2026-10-03/) chose the F9 framing on clm-latest for column.ontology_fits and
found no qualifying framing for term.fits (K1), so term.fits proposals are the OLS top-1
(ols_rank) by default (DESIGN A1; every number in RESEARCH.md, "M2 results"). The same run
measured CLM's zero-shot answers to the closed choices (annotate, aspect, value kind) below their
majority class, so, by the user's decision after the results (DESIGN A6, product safety, not a
scientific claim), rules answer them by default and CLM's answers are kept for audit only.
Everything is proposed-only. M1 delivered the serving stack on sparky-1 and the hermetic
rank-first pipeline (annotate, explain, review, feedback). See DESIGN.md for the
decisions (U1–U4, D0–D33, the pre-registered experiments, amendments A1–A6), RESEARCH.md for the verified facts the
design rests on, design/plan-2026-09-28.md for the plan, and CLAUDE.md for how to work here.
mesa-anyjev's AnyJev readout works through next-token logprobs: a top-20 logprob cap, one slow
prompt per candidate, K>8 choices split into yes/no twins. CLM scores candidate texts against a
state with cacheable candidate vectors and no option limit. Its released head is weak zero-shot
on typed questions (state-independent Score answers, suffix collapse, inverted calibration,
and a logistic regression on the frozen embeddings that beats the fine-tuned head; upstream
issues #3, #13, #15), and a no-model lookup that copies labels across cards already scores
leave-one-card-out accuracy 0.772 on term.fits, above AnyJev L2's 0.765. So mesa-clm asks
rank-first questions with an anchor, fingerprints everything that depends on the encoder,
earns trust only through pre-registered, leakage-aware, nested-selection bench cells that beat
that lookup on novel keys, and ships proposed-only first.
Related MCP server: Universal Ontology MCP
uv sync --all-extras # dev install; nothing here pulls torch or vllm
uv run pytest -q # hermetic suite
sha256sum -c vendored.sha256 # vendored CLM and AnyJev files are byte-identicalRequires Python 3.11+. mesa-mcp and mesa-ducklake are installed from pinned git commits
(neither is on PyPI). Serving (a vLLM pooling container plus a patched clm-serve) runs on the
GPU host; see docs/concepts/serving.md and the runbook docs/deploy/serving.md.
uv run mesa-clm doctor # pins, versions, mesa-mcp plugin API, policy, stores (--quick, --json)
export MESA_CLM_OLS__FIXTURES=replay MESA_CLM_PROVENANCE__DSN=duckdb:///labels.duckdb
uv run mesa-clm labels ingest-neon-eval --eval-root tests/fixtures/neon-avu-eval # silver labels
uv run mesa-clm labels stats # counts per task, source, label
uv run mesa-clm labels snapshot --out bench/snapshots/today.parquet # frozen labels + labels_sha256
uv run mesa-clm bench baselines --snapshot bench/snapshots/today.parquet # lookup_prob, novel-key, LOPO
uv run mesa-clm bench mde --snapshot bench/snapshots/today.parquet # minimum detectable effectlabels import-anyjev --dsn <sidecar> reads a mesa-anyjev sidecar read-only (its curator rows
arrive as weight-0 agent_pick unless --trust-curator is given at a terminal).
Annotation (milestone M1; every outcome is proposed-only until evidence-cited autos land in M4):
export MESA_CLM_OLS__FIXTURES=replay MESA_CLM_OLS__FIXTURES_DIR=tests/fixtures/ols
uv run mesa-clm --provenance duckdb:////tmp/clm.duckdb annotate \
--card tests/fixtures/cards/DP1.10003.001.brd_countdata.md --provider fake --out run.json
uv run mesa-clm --provenance duckdb:////tmp/clm.duckdb explain --run-id <id or prefix>
uv run mesa-clm --provenance duckdb:////tmp/clm.duckdb review --run-id <id or prefix> # interactive
uv run mesa-clm framings --check # framing keys match framings.lock.jsonBy default term.fits groups are decided by ols_rank (the OLS top-1, proposed-only; K1, DESIGN
A1) and column.ontology_fits is asked with F9; --ols-rank-tasks none asks CLM for term.fits
too, an audit run. The closed choices are answered by rules (DESIGN A6: every non-identifier
column annotated whatever the planner says; aspects from the planner's hint and the M0 lookup
over a table frozen from the registered labels snapshot and shipped in the package, else the
first two in the lookup's prior order; value kind "the term label"), CLM's answers to them
recorded audit-only; --closed-choice clm runs the M2 behaviour. Answers given at an interactive terminal are curator labels; review --pick and
feedback run without one (a script, an agent's shell) are recorded as an agent's answers at weight
0 and say so (DESIGN A2). On the serving host, --provider clm (the default) talks to the loopback
encoder and clm-serve with the keys mesa-clm serve keys --init writes,
~/.mesa/clm/secrets/clm.key and encoder.key, read by default (MESA_CLM_CLM__API_KEY_FILE and
MESA_CLM_ENCODER__API_KEY_FILE name others); mesa-clm doctor --serve checks the stack first.
features build|export-npz|project|stats keep the per-encoder feature cache, and provenance migrate|export|import|prune maintain the sidecar. plan, apply, revert and the mesa_clm_*
MCP tools arrive with M3; mesa-clm --help lists what exists.
Documentation: https://idss-mesa.github.io/mesa-clm/ (OKF v0.2 bundle; llms.txt,
llms-full.txt)
Decisions: DESIGN.md · Facts: RESEARCH.md · Plan: design/plan-2026-09-28.md
Sibling: https://github.com/idss-mesa/mesa-anyjev · Upstream: https://github.com/Contrastive-LM/CLM
MIT, Copyright (c) 2026 The Regents of the University of New Mexico. CLM and its vendored
schema.py are Apache-2.0 and not affiliated with TypeSafe AI or Jev; NEON metadata in the
fixtures is CC BY 4.0; see THIRD_PARTY.md.
Add a new AVU (attribute-value-unit) to a file (data-object), directory (collection), resource, or user.
Inputs: value (required), target (required), attribute (required), target_type (required), +1 more.
Add MULTIPLE AVUs to one data-object/collection in a single call and mirror them all into DuckLake as ONE snapshot (efficient bulk tagging).
Inputs: avus (required), target (required), target_type.
Copy a file (data-object) or directory (collection) to a new location.
Inputs: source_path (required), destination_path (required).
Create a read or write iRODS ticket on a data object or collection. Returns the ticket string plus the restrictions that were applied. Anonymous users may not create tickets.
Inputs: mode (required), path (required), expiry, uses_allowed, +3 more.
Delete an AVU (attribute-value-unit) from a file, directory, resource, or user.
Inputs: target (required), target_type (required), id, unit, +2 more.
Delete a file (data-object) or directory (collection).
Inputs: path (required).
Revoke an existing iRODS ticket. Issuer or admin only — the server enforces this. Anonymous callers are rejected at the tool layer.
Inputs: ticket (required).
Get a recursive tree view of files (data-objects) and directories (collections). The specified path must be an iRODS path. The output is in JSON format. The output contains all entries in the given directory (collection) path.
Inputs: path (required), depth.
Returns how to download the full contgent of a file (data-object) with the specified path. The specified path must be an iRODS path. Returns how to download the file using WebDAV, GoCommands (gocmd), and iCommands.
Inputs: irods_path (required), local_path (required).
Run an iRODS rule. Supply either rule_name (server-installed) or rule_text (inline iRL). Output parameters are returned as a dict; iRODS stdout/stderr are returned when output_parameters includes 'ruleExecOut'. Path-typed input parameters are checked against the caller's accessible paths before the rule fires.
Inputs: rule_name, rule_text, instance_name, input_parameters, +1 more.
Retrieve detailed metadata about a file or directory.
Inputs: path (required).
Fetch the full AVU metadata bundle for an iRODS path (data object or collection). Returns the resolved target type alongside the AVU list.
Inputs: path (required).
Return the configuration of a named Policy Composition Framework policy. iRODS does not expose PCF config through PRC; this is a stub that returns config=None and a note documenting the limitation.
Inputs: name (required).
Return the source of a named iRODS rule. iRODS does not expose rule sources through PRC; this is a best-effort tool whose definition field is None on most servers.
Inputs: name (required).
Get information about a specific iRODS ticket, such as its ID and expiration time, in JSON format. Anonymous users are not allowed to get ticket information.
Inputs: name (required).
Get a list of directories (collections) that this server is allowed to access. The output also contains API names that can be requested to each directory (collection).
Inputs: no named parameters.
List AVUs (attribute-value-unit) from a file (data-object), directory (collection), resource, or user.
Inputs: target (required), target_type (required).
Get a list of files (data-objects) and directories (collections) in a specified path. The specified path must be an iRODS path. The output is in JSON format. The output contains entries in the given directory (collection) path. Use offset and limit parameters to paginate through large directories.
Inputs: path (required), limit, offset.
Get a list of files (data-objects) and directories (collections) in a specified path with full detailed info. The specified path must be an iRODS path. The output is in JSON format. The output contains entries in the given directory (collection) path, and users or groups who can access the files (data-ojects). Files (data-objects) will also have replica information. Use offset and limit parameters to paginate through large directories.
Inputs: path (required), limit, offset.
List policies in effect for the Data Store. With project_path, returns the MESA policy AVUs (mesa.policy.*) set on that project root — the policies mesa-mcp itself honours. Always includes the server-side Policy Composition Framework envelope; iRODS does not expose PCF state through PRC, so that part is a documented stub.
Inputs: project_path.
List iRODS rules visible to the caller. Returns a best-effort list of delayed rules; the static rule base is not exposed by PRC and the note field documents that limitation.
Inputs: no named parameters.
Get a list of iRODS tickets. Return information about the tickets, such as their IDs and expiration times, in JSON format. Anonymous users are not allowed to list tickets.
Inputs: no named parameters.
Make a new directory (collection).
Inputs: path (required).
Modify data access of a user or group to a file (data-object) or directory (collection).
Inputs: path (required), access_level (required), user_or_group (required), recurse.
Modify data access inheritance flag of a file or directory.
Inputs: path (required), inherit (required), recurse.
Modify restrictions on an existing iRODS ticket. Cannot change the ticket's mode — that is set at issuance time. Returns the applied restrictions. Anonymous users are not allowed to modify tickets.
Inputs: ticket (required), uses, expiry, host_restriction, +2 more.
Move a file (data-object) or directory (collection) to a new location.
Inputs: new_path (required), old_path (required).
Liveness check. Echoes back the supplied message (or 'ok') and the running mesa-mcp version. No iRODS access required.
Inputs: message. Returns: Output schema for ``ds_ping``. Reference implementation of the opt-in ``output_…
Read the partial content of a file (data-object) with the specified path and offset. The specified path must be an iRODS path. If the file is too large to be displayed inline, use the WebDAV URI to access it.
Inputs: path (required), length, offset.
Recursively search for files (data-objects) and directories (collections) matching a pattern. The specified search root path must be an iRODS path. Use unix wildcards, such as '?' and '*', for the search pattern. The matching entries are returned in JSON format.
Inputs: path (required).
Search for files (data-objects) and directories (collections) matching iRODS AVU (attribute-value-units) using specified attribute and value. The matching entries are returned in JSON format.
Inputs: value (required), attribute (required).
Search iRODS by AVU attribute/value/unit. More permissive than ds_search_files_by_avu: any combination of attribute, value, and unit can be supplied and you can restrict the result type to data objects, collections, or both.
Inputs: unit, value, target, attribute.
Returns how to upload the full contgent of a file (data-object) to the specified path. The specified path must be an iRODS path. Returns how to upload the file using WebDAV, GoCommands (gocmd), and iCommands.
Inputs: irods_path (required), local_path (required), is_dir.
Supply an iRODS ticket to the caller's iRODS session. Subsequent operations by the same caller run with the ticket applied, and their AVU writes record the ticket id in DuckLake's via_ticket column. Other callers' sessions are unaffected.
Inputs: ticket (required).
Write the partial content to a file (data-object) with the specified path and offset. The specified path must be an iRODS path. If the file is too large to be displayed inline, use the WebDAV URI to access it.
Inputs: path (required), content (required), offset.
Validate a DataCite 4.x record and write it to an iRODS path as AVUs (canonical and/or CyVerse-template naming), mirrored to DuckLake as one snapshot.
Inputs: record (required), target (required), naming.
Resolve an OLS term, build the canonical AVU triple (.<snake_label>, , ), write it to the iRODS path, and record the change in the project's DuckLake. Composite of mesa_avu_from_term + ds_add_avu, in one call.
Inputs: path (required), value (required), ontology_id (required), iri, +2 more.
Pure transformation: turn an OLS term + user value into the canonical AVU triple (attribute='.<snake_case_label>', value=, unit=) without writing to iRODS.
Inputs: value (required), ontology_id (required), iri, curie, +1 more.
Export DataCite AVUs as a DataCite 4.x XML (for DOI registration) or REST JSON document.
Inputs: avus (required), format.
Return the DataCite 4.x field scaffold (field, required?, repeatable?, controlled vocabulary, canonical AVU key) to drive a complete, valid record.
Inputs: no named parameters.
Validate DataCite AVUs against the 4.x kernel: report missing mandatory fields, invalid controlled-vocabulary values, and whether the record is DOI-ready.
Inputs: avus (required).
Enroll an iRODS collection as a MESA project. Creates the <irods_path>/.mesa/ducklake/ sub-collection (or the configured ducklake.data_collection), sets the mesa.enabled=true AVU on the project root, and registers the project in the DuckLake catalog. Idempotent — safe to re-run.
Inputs: irods_path (required).
Generate a SCHEMAS-compatible template (prefix + top-level term fields) for an ontology. This is the function that drives the esiil-portal auto-generated AVU forms.
Inputs: ontology_id (required).
Fetch metadata for a single OLS ontology (term count, version, homepage, preferred prefix).
Inputs: ontology_id (required).
Get the full record (label, CURIE, synonyms, definition, parents/children) for a single OLS term by IRI.
Inputs: iri (required), ontology_id (required).
List the direct children of an OLS term. Use this to walk an ontology's class hierarchy one level at a time.
Inputs: iri (required), ontology_id (required), size.
List ontologies available in the EMBL-EBI Ontology Lookup Service (OLS4), paginated. Returns 266+ ontologies (ENVO, GO, CHEBI, etc.).
Inputs: page, size.
Search OLS terms across all ontologies or scoped to one. Optionally restrict to descendants of a parent IRI (hierarchy walk).
Inputs: query (required), size, ontology_id, descendants_of.
Disable a MESA policy on a project root collection by removing the mesa.policy.<policy_name> AVU. Records the change into the project's DuckLake when MESA-enabled.
Inputs: policy_name (required), project_path (required).
Enable a MESA policy on a project root collection by writing the mesa.policy.<policy_name>=true AVU. Records the change into the project's DuckLake when MESA-enabled.
Inputs: policy_name (required), project_path (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 50 tools
Most tools have distinct resource+action targets, but several pairs overlap: ds_list_directory vs ds_list_directory_details, ds_search_files_by_avu vs ds_search_metadata (both AVU search), ds_list_avus vs ds_get_metadata, and ds_add_avu vs ds_add_avus. The detailed descriptions do help an agent choose, and the mesa_* vs ds_* split separates higher-level workflows from raw iRODS ops, but the boundaries are not crisp.
A consistent verb_noun snake_case pattern (ds_add_avu, ds_delete_file, ds_make_directory, ds_list_rules) holds across the dominant ds_ family, with namespace prefixes (mesa_ols_, mesa_avu_, mesa_datacite_, mesa_policy_) grouping related tools predictably. Minor deviations exist, e.g. singular/plural drift (ds_add_avu vs ds_add_avus, ds_list_avus) and redundant qualifiers (ds_search_files_by_avu vs ds_search_metadata).
50 tools is very heavy and near the extreme end of the scale. While the surface genuinely spans multiple subsystems (iRODS CRUD, AVUs, tickets, policies, OLS ontologies, DataCite, DuckLake), the count suggests feature bloat and several entries are documented stubs (ds_get_policy_config, ds_get_rule_definition, ds_list_rules) that dilute the set.
Coverage is broad and near-complete: file/directory CRUD, AVU CRUD and search, ticket lifecycle, access and inheritance management, ontology lookup/hierarchy, DataCite validation/export, and project enrollment all exist. Gaps are minor (some PCF/rule inspection is a documented stub), and agents have viable workarounds via rules and search tools.
Machine-readable entity discovery with provenance, trust and verified source evidence.
Provenance-carrying memory for AI agents: corrections supersede, never overwrite. Free, API + MCP.
Provenance-first database for teams and agents: every value carries sources, rules and coverage.
Knowledge graph ingestion, entity search, ontology analysis, and CoSync scoring.
