marklogic-mcp: Skill for Claude Code

MarkLogic Server-Side Code

Module type → signature

Type	Shape
Library	module.exports = {...} or exports.fn = …
REST resource extension	export GET / PUT / POST / DELETE, each (context, params, input)
REST transform (CTF)	export a transform function (content, context)
Flux reader (phase 1)	returns a Sequence/Array of URI strings — no declareUpdate()
Flux transform (phase 2)	declareUpdate() first, var URI injected, one output doc per call
Scheduled task	self-contained script; declareUpdate() if it writes

Universal conventions: 'use strict'; at the top, xdmp.log() for server-side logging, cts.search() rather than fn.doc() for retrieval, try/catch around fallible work, and JSDoc on exported functions.

If require() fails inside a REST resource extension

The REST API Developer's Guide states that JavaScript library modules are not available to resource service extensions, because the REST API imports them dynamically, and recommends a Data Service endpoint when an endpoint needs shared library code. The worked extension in the marklogic-project-setup skill's REST-extensions reference does use require(), so the restriction is either version-specific or narrower than the guide's wording — verify on your own version before designing around either claim.

What holds regardless: the import happens at request time, so a successful ml_extension_put is not evidence the extension works. Call the endpoint before believing it. If require() does fail there, inline the logic or move to a Data Service rather than assuming the module path is wrong.

The same interface backs the Java, Node.js, and REST client APIs, so one extension serves all three.

Application coding practices

references/coding-practices.md covers the practices that decide whether a module is production-grade, with worked examples:

1. Never concatenate untrusted input into a query string — bind instead (sem.sparql bindings map, cts.parse constraint bindings, xdmp.eval external variables), and prefer cts constructors over any string grammar.
2. xdmp.eval is almost never right — require(), xdmp.invokeFunction, xdmp.invoke, and xdmp.spawn, and when each applies.
3. Amps, not broad roles, for privilege escalation — including the SJS namespace rule that makes amps fail silently.
4. Transaction discipline — the 600 s timeout, why a query transaction cannot read its own writes, and the spawn-batching pattern.
5. Writes carry permissions and collections explicitly.
6. Error handling that reaches the caller — fn.error with RESTAPI-SRVEXERR.
7. Testing with marklogic-unit-test rather than ad-hoc eval calls.