mcp-zenml: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Running and testing

• Run MCP server locally: uv run server/zenml_server.py (stdio). For HTTP: uv run server/zenml_server.py --transport streamable-http --port 8001
• Smoke test (needs ZENML_STORE_URL, ZENML_STORE_API_KEY, ZENML_ACTIVE_PROJECT_ID): uv run scripts/test_mcp_server.py server/zenml_server.py --profile compact --write-policy read_write. Pass --profile legacy or --write-policy read_only to check the other tool inventories; the test fails if the advertised tool list does not exactly match zenml_tool_catalog.tool_names().
• Analytics test: uv run scripts/test_analytics.py --full-diagnostic
• Credential-free test suite (the same list CI runs in pr-test.yml; run each with uv run):
  • scripts/test_datetime_normalization.py - datetime filter normalization and exception classification
  • scripts/test_resource_registry.py, test_resource_operations.py, test_resource_mutations.py, test_resource_actions.py - the generic resource catalog and its read, create/update/delete and action dispatch
  • scripts/test_resource_integration.py - skips its live part unless run through the disposable-server script below
  • scripts/test_sdk_contracts.py - checks the ZenML SDK method signatures the dispatcher calls still match
  • scripts/test_credential_isolation.py - uses the real SDK in separate processes with temporary credentials files to check that explicit API keys stay in memory while connections without API keys retain zenml login support
  • scripts/test_tool_contracts.py, test_tool_profiles.py - tool schemas, and which tools each profile/write policy advertises
  • scripts/test_step_logs.py - get_step_logs against fake ZenML servers: cursor paging on the 0.97+ /logs/{id}/entries endpoint, the fallback to /steps/{id}/logs on 0.96, tail, the possibly_truncated flag and its note, and login through the ZenML client's session
  • scripts/test_mcp_transport.py - the MCP 2.2 runtime: protocol negotiation, HTTP host/origin security, timeouts and cancellation, error sanitising, analytics allowlist
  • scripts/test_mcp_apps.py - drives both MCP Apps in headless Chromium. Install the browser first with uv run --with playwright==1.64.0 playwright install --with-deps chromium, or point PLAYWRIGHT_CHROMIUM_EXECUTABLE at an existing Chromium
  • scripts/test_distributions.py self-test
  • scripts/test_runner_tls.py - network-free regression checks for TLS rejection classification; python scripts/check_runner_tls.py probes healthy HTTPS and the compromised direct/cross-signed chains with Python, curl, Git, and uv
• Live integration against a throwaway ZenML server: bash scripts/run_disposable_resource_integration.sh. It starts a local ZenML OSS server (the version pinned in pyproject.toml) on a random loopback port with a temporary database, runs test_resource_integration.py against it (real create/update/delete calls, plus a check that two projects with same-named resources stay separate), then deletes everything. No credentials needed. Extra opt-in integration gates (ZENML_MCP_ACTION_INTEGRATION, ZENML_MCP_RESTRICTED_INTEGRATION) need an external server; see RELEASE.md.
• Manifest check: uv run scripts/generate_manifest_fields.py --check (drop --check to regenerate the tools/prompts fields in manifest.json). CI fails if the manifest does not match the registered tools.
• MCPB bundle: bash scripts/build_mcpb.sh builds mcp-zenml.mcpb (needs Node/npm; CI uses Node 20). uv run scripts/test_distributions.py reproducible mcp-zenml.mcpb rebuilds it and checks the bytes match and the unpacked bundle starts and lists the right tools.
• Docker: docker build -t mcp-zenml:test . && uv run scripts/test_distributions.py docker mcp-zenml:test (the second command starts MCP inside the container and checks the tool list).