UluOps Registry MCP README

UluOps · The operations layer for agentic work

@uluops/registry-mcp

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).

Requires Node.js 20.3 or newer. Create an API key at app.uluops.ai/settings/api-keys; API keys begin with ulr_.

Quick start

To check the package without changing your harness configuration, run:

npx -y @uluops/registry-mcp --version

To connect the server, 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": "ulr_your-api-key"
      }
    }
  }
}

Replace the example value with your API key, then restart your harness. To have your harness configuration written for you, use @uluops/setup: npx @uluops/setup.

Configuration

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

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" })
search_definitions({ query: "code-validator", match: "exact" })
search_definitions({ query: "code-", match: "prefix", page: 2, limit: 10, sort: "name", order: "asc" })

// 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", diff_contract: "combined-v1", full: true }) // patch + exact YAML

// 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)

render_definition uses the uluops-full render profile when render_profile is omitted: the full prompt the registry stores. render_profile: "core" is declared-only (registry on definition-factory ≥ 0.81.0): only what the definition declares, with no factory-supplied output contract, scoring instruction or tone. Before that factory, core meant the full prompt minus the UluOps blocks. Inline and file-write results report the effective profile.

Since 0.16.0 (registry-sdk 0.62.0) results also carry the renderer fields:

• factoryVersion and renderStack ({ factory, nunjucks, yaml });
• for agents, resolvedProfile, scaffolding and declaredOutputShape.

Pin a core hash on the definition version plus renderStack. scaffolding: false means the render is declared-only.

output_path writes on the MCP server host, within OUTPUT_BASE_DIR (default: server process cwd). Relative paths resolve from that cwd, even when a different root is configured. The root must exist; missing directories below it are created. Paths outside the root and traversal escaping it are refused. Existing symlinks in the file or directories below the root are checked and refused before rendering. Existing files require overwrite: true. Remote clients should omit output_path and consume markdown inline.

File responses retain the inline rendering metadata (target, renderProfile, selectedModel, promptHash, warnings, and any SDK metadata when supplied) alongside success, output_path, and UTF-8 bytes; markdown is written to disk. Warnings and optional metadata have the same presence and values as inline output.

// Inline output for remote clients
render_definition({ type: "agent", name: "code-validator", target: "codex" })
// Write beneath the server cwd (or use an absolute path inside OUTPUT_BASE_DIR)
render_definition({ type: "agent", name: "code-validator", target: "codex", output_path: "output/code-validator.toml" })
// Explicit replacement retains rendering diagnostics
render_definition({ type: "agent", name: "code-validator", target: "codex", output_path: "output/code-validator.toml", overwrite: true })

Definition management (P1)

Composite workflows (P1)

Versions & dependencies (P1)

Forks (P2)

Translation (P2)

upgrade_definition applies to legacy definitions without storage/translation metadata and creates a new major version. Current-format drafts and already translated definitions return a structured refusal with applicationState: not_applied, a reason, and recovery guidance. Use publish or retranslate when indicated.

If an upgrade response fails validation, the result carries applicationState: unknown: the write may already have committed. Read the definition and list its versions before retrying. Successful responses preserve the previous version and translated artifact metadata. These upgrade semantics require Registry API 0.59.4 or newer.

Lifecycle refusals now carry allowedTransitions; blocked deletion carries blockingResources: { present: true } and a specific recovery action without exposing hidden references. A bad render target lists available targets once. For any write whose SDK response validation fails, applicationState: unknown means read current state before retrying.

Models & languages (P2)

Execution & users (P2)

Analytics (P3)

Session

Available resources

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

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/config/server-options.ts (global), src/config/limits.ts (the shared envelope), src/config/tool-registry.ts (per-tool caps and quotas), and tool-policies.json (per-tool security level and relaxed fields — loaded explicitly since 0.8.2; yaml is not pattern-scanned at this layer, the registry API scans definitions at publish).

The four size settings share one value, ENVELOPE_BYTES. Because a string's characters can never outnumber the message's bytes, and the params are part of the message, the message size is the one that binds; the others never fire first. The per-tool maxArgsSize in tool-registry.ts is the tool-scoped gate beneath them (never above; exactly at it for the YAML tools). Each tool's maxEgressBytes is kept ≥ 16 × its maxArgsSize, because mcp-secure-server checks egress at request time as argument bytes × 16.

Why this envelope: it is the registry API's own body limit on definition routes (1 MiB, express.json({ limit: '1mb' })) plus 64 KiB for the JSON-RPC wrapper, so any body the API accepts fits. Until 0.18.0 it was 500 KiB, which a draft create with a CJK YAML at the 153,600-character limit and maximal provenance (50 contributors with CJK names, about 540 KB) did not fit.

Tool schemas mirror the API's field caps (src/config/api-limits.ts), so an over-limit request is refused locally, by field name, instead of after a round trip:

• yaml at most 153,600 characters on create, update, validate, upgrade and update-and-publish, including YAML read from file_path;
• on update_and_publish only, yaml also at most 153,600 UTF-8 bytes. The registry API limits YAML in two units: every route counts characters, while validation and publishing also count UTF-8 bytes, so non-ASCII YAML reaches the byte limit first (a CJK YAML over 51,200 characters can be saved as a draft but not published). update_and_publish checks bytes before it writes anything, so it cannot leave a draft whose publish then fails. validate_definition passes the API's valid: false verdict (PAYLOAD_TOO_LARGE) through instead;
• description at most 1000 chars;
• tags at most 32, each at most 50 chars;
• deprecation reason at most 500 chars, successor as name or name@x.y.z;
• fork new_name at most 200 chars, lowercase letters, digits and hyphens;
• execution source at most 32 chars, run_id at most 64.

Here "character" means a UTF-16 code unit (JavaScript string length), as the API counts it.

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 git@github.com:Uluops/-uluops-registry-mcp.git
cd -uluops-registry-mcp
npm install
npm run build
npm test
npm run typecheck
npm run lint

License

MIT

Quality metric contracts (F04)

compare_effectiveness and get_diff_impact accept optional quality_contract: "nullable-v1". Select it to preserve absent gate rates/deltas as null with run-weighted basis, gate denominator, and fraction units. Agent gate rates are null. Omission keeps legacy behavior. Requires the F04-capable Registry SDK and producer capability; unsupported selection returns UNSUPPORTED_CONTRACT instead of legacy numbers. Release the tolerant SDK and producer before enabling this option.

Applicable unified diffs

Call diff_versions with format: "unified" and diff_contract: "combined-v1". Add full: true to receive exact sourceYaml/targetYaml alongside unified. An unchanged pair returns an empty patch. The SDK negotiates support and refuses unsupported servers without falling back. Legacy omission keeps full=true precedence (raw fromYaml/toYaml, no patch) until a future major release with at least 90 days notice.

Definition search semantics

list_definitions({ name: 'code-validator' }) defaults to exact identifier matching; match: 'prefix' selects a literal prefix. Identifiers are trimmed and lowercased, with 1–100 printable ASCII characters before trimming; punctuation, quotes, %, _, and backslashes are preserved. name cannot combine with search or match: 'text'. For search_definitions, exact/prefix modes use the required query as the name. Omitting match retains existing keyword behavior; explicit match: 'text' requires a nonblank search/query of 1–100 printable ASCII characters before trimming. New name or explicit match requests negotiate the server's name-v1 capability and refuse unsupported servers without fallback.

Keyword terms of at least three characters after sanitization use FULLTEXT over name, display_name, and description. Short original searches fall back to name/display_name; longer searches whose sanitized terms are shorter than three characters also fall back across description. Tags filter independently by OR-any and are not keyword searched. Actual FULLTEXT rows may include numeric relevance, retained in compact list output. Search responses retain the full list rows. A list request with page and no limit explicitly uses limit 50, matching the API's default. list_definitions and search_definitions cap limit at 100; list_versions and list_providers at 200.

batch_users defaults to the existing map (format: 'map' is also accepted). With format: 'envelope', UUID inputs are normalized to lowercase and deduplicated in request order; both ID arrays use that order and canonical spelling. Unknown, deleted, and null profiles appear in missingIds. The 100-input limit applies before deduplication. The SDK requires consistent producer found/notFound metadata and returns a response-validation error when it is absent or invalid. In envelope format, fields selects public profile fields inside data while retaining user keys and both foundIds and missingIds. For example, fields: ['id'] trims profiles to their IDs; fields: ['data'] keeps complete profiles. Public profile fields remain selectable for all-missing batches, and unknown fields are rejected. Selecting only metadata leaves empty profile objects under their user keys. Default map field selection retains its existing behavior.