marklogic-mcp: Skill for Claude Code

MarkLogic Server in Docker

Start from what already exists

This repo ships three ready-to-copy compose files at its root — start from whichever is closest before writing one from scratch:

templates/docker-compose.yml in this skill is the piece those three build on: a plain, standalone single-node MarkLogic service with no MCP server attached, for when the task is "stand up MarkLogic" rather than "run this MCP server."

The init/restart race — the most common false alarm

MarkLogic's own /manage/v2 and /admin/v1/timestamp endpoints can return 200 while the server is mid-restart applying a bootstrap or config change. A dependent service, or a healthcheck: that fires once and moves on, can connect during that window and get 503 Restarting to reload server config moments later — or connect to a MarkLogic that hasn't finished creating its default databases and app servers yet.

A longer start_period alone does not fix this — the problem isn't waiting long enough before the first check, it's that any single successful probe can land inside the restart window. Require several consecutive successful probes before trusting "ready":

ok_streak=0
for i in $(seq 1 36); do
  if curl -sf -u admin:admin http://localhost:8002/manage/v2 >/dev/null 2>&1; then
    ok_streak=$((ok_streak + 1))
    [ "$ok_streak" -ge 3 ] && break
    sleep 3
  else
    ok_streak=0
    sleep 5
  fi
done

This exact pattern is what this repo's own CI uses before seeding test data — see .github/workflows/integration.yml. Use the same "N consecutive OKs" shape for any consumer waiting on MarkLogic, not just a Compose healthcheck: block — a depends_on: condition: service_healthy only inherits whatever the healthcheck itself verifies, and a single-probe healthcheck reports healthy too early.