registry-mcp

MCP client for the UluOps Registry API — 44 tools for definition management, analytics, and publishing.

Overview

MCP client for the UluOps Registry API. Browse definitions, fetch versions, publish updates, manage forks, and track effectiveness — all from Claude Code. Backed by @uluops/registry-sdk.

Installation

bash

npm install @uluops/registry-mcp

This installs the uluops-registry-mcp binary. To install it globally instead, use npm install -g @uluops/registry-mcp.

Configuration

Add to your Claude Code MCP configuration (.mcp.json):

json

{
  "mcpServers": {
    "uluops-registry": {
      "command": "uluops-registry-mcp",
      "args": [],
      "env": {
        "ULUOPS_API_KEY": "ulr_your-api-key-here"
      }
    }
  }
}

The server connects to https://api.uluops.ai/api/v1/registry by default. Override with ULUOPS_REGISTRY_URL only if you're running a local or custom API instance.

Variable	Description	Required
`ULUOPS_API_KEY`	API key (must start with `ulr_`)	Yes
`ULUOPS_REGISTRY_URL`	Registry API URL	No (default: `https://api.uluops.ai/api/v1/registry`)

Quick Start

typescript

// List all published agents
list_definitions({ type: "agent", status: "published" })

// Get a specific definition with YAML
get_definition({ type: "agent", name: "code-validator", include_yaml: true })

// Create and publish
create_definition({
  type: "agent",
  name: "my-validator",
  file_path: "my-validator.agent.yaml"
})
publish_definition({ type: "agent", name: "my-validator", version: "1.0.0" })

// Update and publish in one step
update_and_publish({
  type: "agent",
  name: "my-validator",
  version: "1.1.0",
  file_path: "my-validator.agent.yaml"
})

// Fork an existing definition
fork_definition({
  type: "agent",
  name: "code-validator",
  version: "3.2.0",
  new_name: "my-code-validator"
})

// Set a session default to avoid repeating type
set_default_type({ type: "agent" })

Tools Reference

Definition Management

Tool	Description
`list_definitions`	List definitions with type, status, domain, agent_type, visibility, tags, authorship, and fork filters. Supports sorting by name, date, or execution count
`get_definition`	Get a definition by type and name. Options: `include_yaml`, `include_runtime`, `include_refs`, `normalize`
`create_definition`	Create a new draft definition from YAML string or `file_path`. Supports `visibility` and `provenance`
`update_definition`	Update a draft — YAML, visibility, description, tags, provenance, tier, or subscription level
`delete_definition`	Delete a definition version. Blocked if other definitions fork from or depend on it
`search_definitions`	Full-text search across names and descriptions with type, domain, status, tags, authorship, and fork filters
`validate_definition`	Validate YAML against the schema without storing it
`upgrade_definition`	Upgrade a definition from legacy format to the current schema version
`set_default_type`	Set a session-level default for the `type` parameter. Tools use this type unless explicitly overridden

Version Management

Tool	Description
`list_versions`	List all versions of a definition with status and metadata
`publish_definition`	Publish a draft as an immutable version
`batch_publish`	Publish multiple definition versions in one call (max 20). Continues on individual failures
`deprecate_definition`	Mark a version as deprecated with a reason and optional successor
`archive_definition`	Archive a deprecated version — removes from discovery, keeps resolvable by ID
`update_and_publish`	Update YAML and publish in one step. Auto-creates a new draft if needed
`diff_versions`	Compare two versions: `sections` (default), `fields` (structural diff), or `unified` (git-style)

Forks and Lineage

Tool	Description
`is_forkable`	Check if a definition version can be forked
`fork_definition`	Create a fork of a published definition under a new name
`list_forks`	List all forks of a definition version
`get_fork_lineage`	Trace the fork ancestry chain back to the original
`get_lineage`	Get the full lineage graph — versions and forks as a tree with health scores per node
`get_dependencies`	Get the forward dependency graph for a definition version
`get_dependents`	Find definitions that depend on a given definition version

Rendering and Execution

Tool	Description
`render_definition`	Render YAML to runtime markdown. Supports `target` (opencode, codex, gemini) and `output_path` for direct file write
`retranslate_definition`	Re-render with the latest translator. Use `force: true` to retranslate even if already current
`get_execution_stats`	Get execution history for a definition version with optional time window
`record_execution`	Record a definition execution (idempotent)

Analytics and Health

Tool	Description
`get_effectiveness`	Effectiveness metrics: pass rate, scores, taxonomy distribution, health score, and composition lift
`compare_effectiveness`	Compare effectiveness across 2–5 versions side-by-side: pass rate, avg score, run count, health
`get_health`	Health grade (A–F), issue profile, and contributing factors. Scores are provisional
`get_evolution`	Version-over-version metrics timeline with trend detection (improving/declining/stable) and confidence
`get_ecosystem_overview`	Ecosystem-wide overview: definition counts, aggregate health, top performers, and definitions needing attention
`get_diff_impact`	Structural diff combined with metric deltas between two versions. Deltas are observational, not causal
`get_translation_analytics`	Versions grouped by translator version with aggregate metrics — shows translator impact on quality
`get_translator_version`	Get the current definition translator version

Models

Tool	Description
`list_models`	List available AI models with provider, tier, and status filters
`get_model`	Get model details by provider and model ID
`list_providers`	List available AI model providers
`list_aliases`	List all model aliases and their resolved provider+model mappings
`resolve_alias`	Resolve a model alias (e.g., "sonnet", "haiku") to its provider and model ID

Languages

Tool	Description
`list_languages`	List all definition languages (ADL, CDL, WDL, PDL) with current schema version info
`get_language`	Get a definition language with its JSON Schema (compact digest by default)

Users

Tool	Description
`get_user`	Get a public user profile by ID
`batch_users`	Batch fetch user profiles (max 100)

Response Field Filtering

All tools accept an optional fields parameter to filter response fields. This reduces payload size for large responses:

typescript

// Only return name, version, and status
list_definitions({ type: "agent", fields: ["name", "version", "status"] })

// Get just the health grade
get_health({ type: "agent", name: "code-validator", fields: ["grade", "score"] })

Pagination metadata (total, limit, offset, hasMore) is always preserved regardless of field filtering.

SDK vs MCP

Both access the same Registry API. Use MCP from Claude Code for interactive work. Use the Registry SDK for programmatic access in TypeScript applications and CI/CD pipelines.