marklogic_mcp

An MCP server for MarkLogic: read, write, search, query, and schema-validate documents across configured environments.

Tools

Tool	Purpose
read_document	Fetch a document by URI.
write_document	Insert/replace a document, with collections and permissions.
search_documents	Search by full-text query and/or collection; returns total + URIs.
eval_xquery	Run XQuery. Updates permitted.
eval_xquery_readonly	Run XQuery with updates rejected. Use for all read/inspect work.
eval_xquery_to_file	Run XQuery and write the results to a local file.
validate_documents	Validate stored documents against their in-scope XSD.

database is required on every tool. server selects the environment and defaults to default_server from the config.

Setup

uv sync                                   # or: python -m venv .venv && pip install -e .
cp config.yaml.example config.yaml        # then fill in, or export the ${...} vars
cp config-local.yaml.example config-local.yaml

Both real config files are gitignored because they hold credentials. config.py interpolates ${VAR} from the environment and raises if a referenced variable is unset, so prefer environment variables over writing passwords into the file.

Select a config with ML_CONFIG_PATH:

ML_CONFIG_PATH=config-local.yaml .venv/bin/python src/server.py

Register with Claude Code as a stdio server, pointing ML_CONFIG_PATH at the config you want that entry to use. Two entries against different configs (e.g. local vs dev/prod) is a convenient way to keep environments apart.

Changes require a restart. The server is a long-lived stdio process; edits to src/ do not take effect until the MCP client restarts it.

Tests

.venv/bin/python tests/test_readonly_enforcement.py

The suite performs real writes and therefore hard-asserts that the loaded config declares exactly one server named local on localhost, refusing to run otherwise. It cannot reach dev or prod. It cleans up after itself and verifies it has done so.

Each blocking test asserts the absence of a side effect, not merely that an exception was raised — an exception alone can come from a syntax error and would pass vacuously. That distinction is what caught the read-only bug described below.

Behaviour worth knowing

Errors are raised, never returned. A call that returns without error succeeded. Failures surface as MarkLogicError carrying the parsed MarkLogic message code (XDMP-NOSUCHDB, RESTAPI-NODOCUMENT, XDMP-UPDATEFUNCTIONFROMQUERY, …), the primary diagnostic, and any stack frames — MarkLogic reports faults as HTML from /v1/eval and as JSON from /v1/documents, and neither is readable raw. TIMEOUT and CONNECTION are flagged retryable.

Read-only enforcement uses the <update>false</update> eval option, not a declare option xdmp:transaction-mode "query" prolog. Do not "simplify" it back; two separate bugs live down that road, and both are covered by tests:

1. The prolog does not reach the query body when a database is named — and because database is a required parameter, that was every call, so eval_xquery_readonly silently permitted writes.
2. The prolog is session-scoped, and the session is bound to the keep-alive HTTP connection — so one read-only query left the connection in query mode and broke every subsequent write on the same client.

XQuery string escaping doubles quotes (" → ""); XQuery has no backslash escapes. All interpolation goes through _xq_str().

validate_documents needs an XSD loaded in the schema database attached to the target database (e.g. protein-schemas). If none is loaded, the result carries schema_in_scope: false plus a warning, because otherwise lax mode would report invalid: 0 — a clean-looking result that verified nothing. Check schema_in_scope before trusting a clean run.