UluOps · Operating Intelligence as Infrastructure

---

@uluops/registry-mcp

npm version License: MIT Node.js Version TypeScript Tests

MCP (Model Context Protocol) server for the UluOps Registry API. Provides 44 tools and 4 resources that let Claude Code, OpenCode, Gemini CLI, and other MCP-compatible harnesses browse, create, validate, version, and analyze AI workflow definitions (agents, commands, workflows, pipelines).

Quick start

The recommended way to install this is via @uluops/setup, which writes the MCP config for you:

npx @uluops/setup

If you'd rather wire it up by hand, add this block to your harness's MCP config (e.g. ~/.claude.json for Claude Code, ~/.config/opencode/opencode.json for OpenCode):

{
  "mcpServers": {
    "uluops-registry": {
      "command": "npx",
      "args": ["-y", "@uluops/registry-mcp"],
      "env": {
        "ULUOPS_API_KEY": "your-api-key"
      }
    }
  }
}

Get an API key at app.uluops.ai/settings/api-keys, then restart your harness.

Configuration

All configuration is passed via environment variables in the env block. No .env file is needed.

Variable	Description	Required	Default
ULUOPS_API_KEY	API authentication key	Yes	—
ULUOPS_ORG_SLUG	Organization slug for scoped requests	No	—
ULUOPS_REGISTRY_TIMEOUT	Request timeout (ms)	No	30000
ULUOPS_REGISTRY_RETRIES	Retry attempts	No	3
LOG_LEVEL	Logging level (error, warn, info, debug)	No	info
ENABLE_FILE_LOGGING	Write logs to disk	No	false
LOG_DIR	Log file directory	No	./logs
VERBOSE_LOGGING	Verbose security decision logging	No	false
LOG_PERFORMANCE_METRICS	Log performance metrics	No	false
WORKSPACE_DIR	Base directory for file_path containment (CWE-22 protection)	No	cwd
OUTPUT_BASE_DIR	Base directory for output_path containment (CWE-22 protection)	No	cwd

Design philosophy

Thin client pattern. This MCP server contains zero business logic. All data processing, validation, storage, and rendering are handled by the registry API. The server's sole responsibility is protocol translation between MCP's stdio JSON-RPC and the backend REST API.

Quick examples

Once configured, your harness can invoke these tools through MCP:

// Browse published definitions
list_definitions({ "type": "agent", "status": "published", "limit": 10 })

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

// Search across all definition types
search_definitions({ query: "validation", type: "agent" })

// Validate YAML before publishing (inline or by file path)
validate_definition({ type: "agent", yaml: "..." })
validate_definition({ type: "agent", file_path: "/path/to/agent.yaml" })

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

// One-call create-or-update-and-publish
update_and_publish({ type: "agent", name: "my-agent", version: "1.1.0", yaml: "..." })

// Compare versions in three different formats
diff_versions({ type: "agent", name: "code-validator", from: "1.0.0", to: "1.1.0" })                  // section summary
diff_versions({ type: "agent", name: "code-validator", from: "1.0.0", to: "1.1.0", format: "fields" })  // structural diff + suggested bump
diff_versions({ type: "agent", name: "code-validator", from: "1.0.0", to: "1.1.0", format: "unified" }) // git-style diff

// Analytics
get_effectiveness({ type: "agent", name: "code-validator", version: "1.1.0" })
compare_effectiveness({ type: "agent", name: "code-validator", versions: ["1.0.0", "1.1.0"] })

Available tools

Core tools (P0)

Tool	Description
list_definitions	List definitions with filters (type, status, domain, visibility, search, tags, pagination)
get_definition	Get a single definition by type + name, optionally with YAML / runtime / refs
search_definitions	Search definitions by keyword
list_models	List AI models with optional filters
resolve_alias	Resolve an alias (e.g. sonnet) to provider + modelId
validate_definition	Validate YAML without storing (accepts yaml or file_path)
render_definition	Get rendered markdown for a definition. output_path writes directly to a file

Definition management (P1)

Tool	Description
create_definition	Create a new draft definition (accepts yaml or file_path)
update_definition	Update a draft definition. Smart version-up: if target version is published or doesn't exist and YAML is provided, automatically creates a new draft
publish_definition	Publish a draft definition
deprecate_definition	Deprecate with reason and optional successor
archive_definition	Archive a deprecated definition (terminal lifecycle state)
delete_definition	Delete a draft (published definitions cannot be deleted)

Composite workflows (P1)

Tool	Description
update_and_publish	Update a draft and publish it in one call. Inherits smart version-up + create fallback from update_definition
batch_publish	Publish up to 20 definition versions in one call. Continues on individual failures, returns both published and failed items

Versions & dependencies (P1)

Tool	Description
list_versions	List all versions of a definition
diff_versions	Compare two versions. format: sections (default), fields (structural + suggested bump), unified (git-style)
get_dependencies	Forward dependency graph
get_dependents	Reverse dependency graph
get_execution_stats	Execution statistics for a definition version
list_forks	List forks of a definition

Forks (P2)

Tool	Description
fork_definition	Fork a definition
is_forkable	Check if a definition version can be forked
get_fork_lineage	Fork ancestry chain

Translation (P2)

Tool	Description
retranslate_definition	Retranslate with the latest translator version
upgrade_definition	Upgrade a definition from legacy format (accepts yaml or file_path)
get_translator_version	Get current translator version

Models & languages (P2)

Tool	Description
get_model	Get specific model details by provider + modelId
list_providers	List AI providers
list_aliases	List all model aliases
list_languages	List supported definition languages (ADL, CDL, WDL, PDL)
get_language	Get a definition language with its JSON Schema. format: compact (default — condensed digest sufficient to author a definition, ~50–75% smaller), full (complete JSON Schema with patterns, bounds, and examples)

Execution & users (P2)

Tool	Description
record_execution	Record a definition execution (idempotent)
get_user	Get public user profile
batch_users	Batch user lookup (max 100)

Analytics (P3)

Tool	Description
get_effectiveness	Effectiveness metrics: voter-weighted quality (one actor, one vote) with the provenance block — independent vs selfReported split, confidence label. Agents are score-only (passRate: null)
get_health	Health grade and issue profile for a definition; the pass-rate factor requires 3+ qualifying actors
get_ecosystem_overview	Ecosystem-wide analytics overview
get_lineage	Lineage graph for a definition (versions + forks as a tree)
get_evolution	Version-over-version metrics with trend detection
get_translation_analytics	Versions grouped by translator version with aggregate metrics
compare_effectiveness	Compare effectiveness across 2–5 definition versions side-by-side
get_diff_impact	Structural diff combined with metric deltas between two versions

Session

Tool	Description
set_default_type	Set (or clear) a session-level default for the type parameter. When set, definition tools use this type unless explicitly overridden

Available resources

MCP resources provide read-only access to registry data via the registry:// URI scheme.

Resource	URI	Description
Definitions	registry://definitions	Published definitions (up to 100)
Models	registry://models	AI model catalog
Definition types	registry://definition-types	Static list: agent, command, workflow, pipeline
Providers	registry://providers	AI provider list

read_resource("registry://definitions")
read_resource("registry://models")
read_resource("registry://definition-types")

Rate limiting

This server uses mcp-secure-server with configuration tuned for typical harness usage patterns. Source of truth: src/index.ts (global) and src/config/tool-registry.ts (per-tool).

Setting	Value	Notes
Security level	basic
Max requests/min	120	Global rate limit
Burst threshold	15	Requests within burst window
Burst window	5000 ms
Automation detection	Disabled	The calling harness is trusted automation

Per-tool quotas are configured in src/config/tool-registry.ts. Read-heavy tools (list, get, search) allow up to 240 req/min. Write tools (create, update, publish) are 30–60 req/min.

Development

git clone [email protected]:Uluops/-uluops-registry-mcp.git
cd -uluops-registry-mcp
npm install
npm run build
npm test            # 348 tests
npm run typecheck
npm run lint

Requirements

• Node.js: ≥ 18
• Platform: Linux, macOS, or WSL2
• Auth: UluOps API key (get one here)

License

MIT