@uluops/registry-mcp 0.1.0 → 0.2.4

package/CHANGELOG.md

@@ -7,11 +7,136 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.4] - 2026-06-07
+
+Docs + packaging polish. Adds the standard 5-badge set to the README matching the rest of the public UluOps packages, and closes a packaging hygiene gap — the package declared `"license": "MIT"` but shipped without the LICENSE file. No behavioural change.
+
+### Added
+
+- LICENSE file (MIT, Copyright (c) 2026 UluOps) at the repo root. The package previously declared `"license": "MIT"` in `package.json` but the file was absent. Adding it makes the license terms reachable both from a GitHub-cloned consumer and from an unpacked npm tarball.
+- LICENSE listed in the `files` array so it ships in the published tarball. Without this entry the LICENSE would have been added to the repo but excluded from the npm package — the same hygiene gap from a different angle.
+
+### Changed
+
+- README header gains the five shields.io badges (npm version, MIT license, node engine, TypeScript 5.7+, tests passing) immediately under the package name, matching the `@uluops/core` package presentation. The tagline was already present from the v0.2.3 ship; this completes the visual alignment with the rest of the public UluOps surface. Tests badge points to `src/__tests__/` (the actual test home in this repo).
+
+## [0.2.3] - 2026-06-05
+
+Polish release. Six tracker findings closed: documentation freshness,
+filesystem availability + symlink hardening, src-tree naming alignment,
+402 upgrade-URL prompt-injection guard, and 19 lint warnings removed
+from the security-boundary module.
+
+### Fixed
+
+- **`readYamlFile` now wraps `realpathSync(WORKSPACE_DIR)` in a try/catch.** A typo'd `WORKSPACE_DIR` env var, an unmounted NFS path, or a fresh container where the dir hadn't been created yet previously threw an opaque `ENOENT` for the workspace root rather than the file the user actually asked about. The error message now names WORKSPACE_DIR explicitly and tells the user how to fix it.
+- **`validateLogDir` now dereferences symlinks before the containment check (CWE-59).** A symlink at `LOG_DIR` could previously escape the cwd/`/tmp/` constraint because `resolve()` doesn't follow symlinks. Also dereferences the comparison anchors (cwd, `/tmp/`) so macOS's `/tmp` → `/private/tmp` symlink no longer breaks the legitimate `/tmp/...` case. Only active when `ENABLE_FILE_LOGGING=true`.
+- **402 `upgradeUrl` now passes through a protocol/host guard before being embedded in MCP responses (CWE-601).** A compromised or malicious registry server could previously emit `javascript:`, `data:`, or off-domain URLs in the 402 response body, landing them in the consuming agent's context window as prompt-injection bait. The guard restricts the embedded URL to `https://` and host suffix `.uluops.ai` (or apex `uluops.ai`); anything else is dropped and the agent sees an upgrade message without a follow-able URL. Mirrors the SSRF defense in `config/index.ts`.
+
+### Changed
+
+- **`src/tools/check-forkable.ts` renamed to `src/tools/is-forkable.ts`.** The file registers `is_forkable` (renamed in v1.13.0 of the legacy package); the source filename was a legacy artifact. Internal-only rename — the tool name, schema, and behavior are unchanged.
+- **19 `@typescript-eslint/strict-boolean-expressions` lint warnings cleared from `sdk-error-mapper.ts`.** The security-boundary module is now lint-clean. Every implicit truthiness check was converted to explicit `!== undefined` / `!== ''` / `=== true` form. No behavior change — but the file is now easier to reason about as code paths near credential redaction.
+- **`isApiKey` detection in `src/index.ts` uses explicit `=== true`** for the optional-chained `startsWith('ulr_')`. Same intent as before; falls through to session-token auth when `apiKey` is undefined. Linter-friendly.
+- **README test count updated to 348** (was stale at 329).
+
+
+
+Hardening pass against the ship-pipeline findings. No new tools. No
+breaking changes to existing tool contracts (the new `render_definition`
+`overwrite` parameter defaults to `false` — agents that previously
+silently overwrote files now receive a clear error response and need to
+opt in).
+
+### Fixed
+
+- **`patchYamlVersion` now handles prerelease and build-metadata semver.**
+  The regex `\d+\.\d+\.\d+` was extended to `\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?(?:\+[A-Za-z0-9.-]+)?`. Previously, source YAML with `version: 1.0.0-rc.1` would leave the `-rc.1` suffix stranded after the replacement, producing malformed YAML that the API would reject. Closes the AF-006 audit trigger that was acknowledged at v0.2.0 ship time.
+- **`update_and_publish` create-fallback now guards `created.version`.** A malformed SDK response with a missing `version` field would have been silently passed through to `publish()`, producing a `/versions/undefined` URL and a 404 for a draft that was just successfully created. The handler now throws a descriptive error if `created.version` is missing or empty.
+- **`render_definition` no longer silently overwrites existing files.** New `overwrite: boolean` parameter (default `false`). When false (the default) and `output_path` resolves to an existing file, the tool returns a clear MCP error rather than destroying the prior content. Agents that need replacement semantics must explicitly pass `overwrite: true`.
+- **`batch_publish` per-item errors now carry rich SDK context.** Previously each failed-item entry only carried `error` (message) and `status`. The per-item catch now routes through a new `extractErrorContext(error)` helper that surfaces 402 `upgrade_url` + `required_tier` + `current_tier`, 429 `retry_after`, and 409 `nextAvailable` exactly as single-call tools do via `mapSdkErrorToMcp`.
+- **MCP server now auto-runs on the proper ESM entry-point check** instead of `NODE_ENV !== 'test'`. A stray `NODE_ENV=test` in the user's shell, CI, or `direnv` no longer silently disables `main()` — the harness would have started and hung waiting for stdio JSON-RPC that never arrived. Tests already import `main` directly and call it; no test changes needed.
+
+### Changed
+
+- **`isNumericSchema` swapped Zod `_def.innerType` access for Zod's public `unwrap()` / `removeDefault()` API.** Avoids coupling to Zod private internals that can rename across minor versions and would silently disable numeric coercion at the MCP boundary if Zod's `_def` shape ever changes.
+- **`isPublishedStatusError` extracted to a shared `src/utils/error-guards.ts` module.** Previously this 3-line guard was duplicated verbatim across `update-definition.ts` and `update-and-publish.ts`. A future change to the underlying API error message now updates one location instead of two.
+- **Added `prepublishOnly: npm run build` script.** Future `npm publish` runs no longer rely on the maintainer remembering to build first.
+
+### Added
+
+- **`extractErrorContext(error)` helper in `client/sdk-error-mapper.ts`** — returns the same structured fields (`status`, `required_tier`, `upgrade_url`, `retry_after`, `nextAvailable`) that `mapSdkErrorToMcp` produces, but without wrapping them in an MCP envelope. Used by `batch_publish`.
+
+### Tests
+
+348 tests pass (was 345, +3 regression coverage):
+- New: `patches prerelease semver versions in yaml during create fallback`
+- New: `refuses to overwrite an existing file when overwrite is not opted into`
+- New: `writes to existing file when overwrite: true is passed`
+
+## [0.2.1] - 2026-06-05
+
+### Changed
+
+- **Backend URL resolution deferred to the SDK.** Previously the MCP server
+  shadowed `@uluops/registry-sdk`'s `DEFAULT_BASE_URL` with its own copy
+  and effectively required `ULUOPS_REGISTRY_URL` (treating empty/undefined
+  as "use the shadow constant"). The SDK already resolves the correct
+  production URL (`https://api.uluops.ai/api/v1/registry`) by default and
+  switches to localhost when `NODE_ENV=development`; the MCP now passes
+  `baseUrl` through as `undefined` when the env var is unset/empty and lets
+  the SDK own URL resolution. Public consumers no longer set anything but
+  `ULUOPS_API_KEY`. README's configuration table reduced to consumer-
+  relevant variables; `ULUOPS_REGISTRY_URL` removed from the public
+  surface (still honored by the code when explicitly set).
+- **SSRF defense and host allowlist now gate on `baseUrl !== undefined`.**
+  When the operator does not set `ULUOPS_REGISTRY_URL` the SDK uses a
+  trusted compile-time constant, so the URL-parse/allowlist/private-host
+  checks are skipped — they only run when an operator explicitly provides
+  a URL that needs validation. Identical behavior for any URL that was
+  previously accepted; previously-rejected URLs are still rejected.
+- **Pairs with `@uluops/setup@0.6.4`** which stopped stamping
+  `ULUOPS_REGISTRY_URL` into `.mcp.json` files during onboarding, and with
+  `@uluops/ops-mcp@0.2.1` which applied the same fix to the ops tracker.
+
+### Internal
+
+- `DEFAULT_BASE_URL` constant removed from `src/config/index.ts`.
+- `ApiClientConfig.baseUrl` type widened to `string | undefined`.
+- Startup log apiUrl line shows `(SDK default)` when baseUrl is unset.
+
+## [0.2.0] - 2026-06-05
+
+First release of the monorepo `@uluops/registry-mcp` package at parity
+with the standalone `uluops-registry-mcp` 0.1.1 codebase, prepared for
+first public npm publish under the scoped name.
+
+### Added
+
+- **`list_languages` and `get_language` tools** — language registry
+  read tools surfaced through the MCP server.
+
 ### Changed
 
-- Bumps `@uluops/sdk-core` from `^0.9.0` to `0.11.0` (exact pin) and `@uluops/registry-sdk`
-  to `0.30.0` (exact pin). Aligns with the sdk-core schema-removal cascade. The MCP server's
-  own Zod-based tool input parsing is unaffected — it never used sdk-core's `options.schema`.
+- **`@uluops/registry-sdk` bumped `^0.27.2` → `0.30.2`** (three minor
+  versions). Pulls in 0.29.0 publish-warning surfacing, 0.30.x sdk-core
+  security hardening cascade, and the schema-removal cleanup.
+- **`@uluops/sdk-core` confirmed at `0.11.1`** with `redirect: 'error'`
+  on all fetch sites, control-character stripping, and widened sensitive-
+  key coverage (`x-api-key`, `set-cookie`, `proxy-authorization`).
+- **All runtime and dev dependencies pinned to exact versions** per the
+  2026-06-01 UluOps supply-chain hardening policy.
+- **`vitest` and `@vitest/coverage-v8` bumped to `4.1.8`** — eliminates
+  the moderate-severity esbuild advisory chained through vite. `npm audit`
+  now reports 0 vulnerabilities.
+
+### Not included
+
+- **`sync_models` admin tool deliberately excluded.** Calls a private
+  registry admin endpoint not exposed through the public SDK; reserved
+  for internal use and intentionally never shipped in this public package.
+
+### Historical lineage (legacy `uluops-registry-mcp` versions below)
 
 ## [1.14.0] - 2026-05-20
 
@@ -134,7 +259,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Error sanitization stripping sensitive data (API keys, tokens, stack traces) from MCP responses
 - Test suite with 194 tests covering all tools, resources, and registry config
 
-[Unreleased]: https://github.com/Uluops/-uluops-registry-mcp/compare/v1.14.0...HEAD
+[Unreleased]: https://github.com/Uluops/-uluops-registry-mcp/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/Uluops/-uluops-registry-mcp/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/Uluops/-uluops-registry-mcp/releases/tag/v0.2.0
 [1.14.0]: https://github.com/Uluops/-uluops-registry-mcp/compare/v1.13.0...v1.14.0
 [1.13.0]: https://github.com/Uluops/-uluops-registry-mcp/compare/v1.12.0...v1.13.0
 [1.12.0]: https://github.com/Uluops/-uluops-registry-mcp/compare/v1.11.0...v1.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UluOps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,33 +1,34 @@
-# UluOps Registry MCP Client v1.1.0
+**[UluOps](https://uluops.ai)** · Operating Intelligence as Infrastructure
 
-MCP (Model Context Protocol) client for the UluOps Registry API. Provides **31 tools** and **4 resources** that enable Claude Code to browse, create, validate, and manage AI workflow definitions (agents, commands, workflows, pipelines).
+---
 
-## Quick Setup (30 seconds)
+# @uluops/registry-mcp
 
-```bash
-git clone git@github.com:Uluops/-uluops-registry-mcp.git
-cd -uluops-registry-mcp
-./setup.sh YOUR_API_KEY
-```
+[![npm version](https://img.shields.io/npm/v/@uluops/registry-mcp.svg)](https://www.npmjs.com/package/@uluops/registry-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js Version](https://img.shields.io/node/v/@uluops/registry-mcp)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue.svg)](https://www.typescriptlang.org/)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](src/__tests__/)
+
+MCP (Model Context Protocol) server for the [UluOps](https://uluops.ai) 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).
 
-The setup script installs dependencies, builds the project, and prints the `.mcp.json` config snippet to paste into your project or `~/.claude/.mcp.json`.
+## Quick start
 
-Or do it manually:
+The recommended way to install this is via [@uluops/setup](https://www.npmjs.com/package/@uluops/setup), which writes the MCP config for you:
 
 ```bash
-npm install && npm run build
+npx @uluops/setup
 ```
 
-Then add to your `.mcp.json`:
+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):
 
 ```json
 {
   "mcpServers": {
     "uluops-registry": {
-      "command": "node",
-      "args": ["/absolute/path/to/registry-uluops-mcp/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "@uluops/registry-mcp"],
       "env": {
-        "ULUOPS_REGISTRY_URL": "http://localhost:3001/api/v1",
         "ULUOPS_API_KEY": "your-api-key"
       }
     }
@@ -35,39 +36,35 @@ Then add to your `.mcp.json`:
 }
 ```
 
-Restart Claude Code to pick up the new server.
-
-## Design Philosophy
-
-**Thin Client Pattern**: This MCP client contains **zero business logic**. All data processing, validation, storage, and rendering are handled by the registry API. The client's sole responsibility is protocol translation between MCP's stdio-based JSON-RPC and the backend's REST API.
+Get an API key at [app.uluops.ai/settings/api-keys](https://app.uluops.ai/settings/api-keys), then restart your harness.
 
 ## Configuration
 
-All configuration is passed via environment variables in the `env` block of `.mcp.json`. No `.env` file needed.
+All configuration is passed via environment variables in the `env` block. No `.env` file is needed.
 
 | Variable | Description | Required | Default |
 |----------|-------------|----------|---------|
-| `ULUOPS_REGISTRY_URL` | Registry API URL | Yes | - |
-| `ULUOPS_API_KEY` | API authentication key | Yes | - |
-| `ULUOPS_REGISTRY_TIMEOUT` | Request timeout (ms) | No | 30000 |
-| `ULUOPS_REGISTRY_RETRIES` | Retry attempts | No | 3 |
-| `LOG_LEVEL` | Logging level | 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 |
+| `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 |
 
-A `.env.example` is included as a template showing available variables. This file is **not** auto-loaded — copy it to `.env` or set variables directly in `.mcp.json`.
+## Design philosophy
 
-## Quick Start Examples
+**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.
 
-Once configured, Claude Code can use the registry tools:
+## Quick examples
 
-```jsonc
-// These are MCP tool calls — Claude Code invokes them automatically.
+Once configured, your harness can invoke these tools through MCP:
 
+```jsonc
 // Browse published definitions
 list_definitions({ "type": "agent", "status": "published", "limit": 10 })
 
@@ -77,93 +74,114 @@ get_definition({ type: "agent", name: "code-validator", include_yaml: true })
 // Search across all definition types
 search_definitions({ query: "validation", type: "agent" })
 
-// Resolve a model alias
-resolve_alias({ alias: "sonnet" })
-
-// Validate YAML before publishing
+// Validate YAML before publishing (inline or by file path)
 validate_definition({ type: "agent", yaml: "..." })
-
-// Or validate from a file path instead of inline YAML
 validate_definition({ type: "agent", file_path: "/path/to/agent.yaml" })
 
 // Create and publish a definition
-create_definition({ type: "agent", name: "my-agent", yaml: "name: my-agent\nversion: 1.0.0\n..." })
+create_definition({ type: "agent", name: "my-agent", yaml: "..." })
 publish_definition({ type: "agent", name: "my-agent", version: "1.0.0" })
 
-// Compare versions — section summary (default)
-diff_versions({ type: "agent", name: "code-validator", from: "1.0.0", to: "1.1.0" })
+// One-call create-or-update-and-publish
+update_and_publish({ type: "agent", name: "my-agent", version: "1.1.0", yaml: "..." })
 
-// Compare versions — structural diff with classification
-diff_versions({ type: "agent", name: "code-validator", from: "1.0.0", to: "1.1.0", format: "fields" })
-// Returns: fields[], classified[], suggestedBump, summary, sections
+// 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
 
-// Compare versions — unified line diff
-diff_versions({ type: "agent", name: "code-validator", from: "1.0.0", to: "1.1.0", format: "unified" })
-// Returns: unified (git-style diff string)
+// 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
+## Available tools
 
-### Core Tools (P0)
+### 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 |
+| `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 alias (e.g. "sonnet") to provider+modelId |
+| `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. Use `output_path` to write directly to a file |
+| `render_definition` | Get rendered markdown for a definition. `output_path` writes directly to a file |
 
-### Definition Management Tools (P1)
+### Definition management (P1)
 | Tool | Description |
 |------|-------------|
 | `create_definition` | Create a new draft definition (accepts `yaml` or `file_path`) |
-| `update_definition` | Update a draft definition (`yaml`/`file_path`, visibility, description, tags). Smart version-up: if the target version is published or doesn't exist and YAML is provided, automatically creates a new draft instead of failing |
+| `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) |
 
-### Version & Dependency Tools (P1)
+### 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. Supports `format`: `sections` (default summary), `fields` (structural diff with classification + suggested bump), `unified` (git-style line diff) |
+| `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 |
 
-### Fork Tools (P2)
+### 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 Tools (P2)
+### 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 |
 
-### Model Tools (P2)
+### Models & languages (P2)
 | Tool | Description |
 |------|-------------|
-| `get_model` | Get specific model details by provider+modelId |
+| `get_model` | Get specific model details by provider + modelId |
 | `list_providers` | List AI providers |
 | `list_aliases` | List all model aliases |
-| `sync_models` | Sync model catalog (admin) |
+| `list_languages` | List supported definition languages (ADL, CDL, WDL, PDL) |
+| `get_language` | Get a definition language with its current JSON Schema |
 
-### Execution & User Tools (P2)
+### 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) |
 
-## Available Resources
+### Analytics (P3)
+| Tool | Description |
+|------|-------------|
+| `get_effectiveness` | Effectiveness metrics for a definition: pass rate, scores, taxonomy, health score |
+| `get_health` | Health grade and issue profile for a definition |
+| `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.
 
@@ -171,58 +189,47 @@ MCP resources provide read-only access to registry data via the `registry://` UR
 |----------|-----|-------------|
 | 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 |
+| Definition types | `registry://definition-types` | Static list: agent, command, workflow, pipeline |
 | Providers | `registry://providers` | AI provider list |
 
-### Resource Usage
-
 ```typescript
-// List published definitions
 read_resource("registry://definitions")
-
-// Browse available AI models
 read_resource("registry://models")
-
-// Get supported definition types with descriptions
 read_resource("registry://definition-types")
 ```
 
-## Rate Limiting Configuration
+## Rate limiting
 
-This client uses [mcp-secure-server](https://github.com/anthropics/mcp-secure-server) with configuration optimized for Claude Code's usage patterns. Source of truth: `src/index.ts` (global) and `src/config/tool-registry.ts` (per-tool).
+This server uses [mcp-secure-server](https://github.com/aself101/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 | 5000ms | |
-| Automation detection | Disabled | Claude Code is trusted automation |
+| 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. Admin operations like `sync_models` are tightly limited (10 req/min).
+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
 
 ```bash
-# Install dependencies
+git clone git@github.com:Uluops/-uluops-registry-mcp.git
+cd -uluops-registry-mcp
 npm install
-
-# Development mode with watch
-npm run dev
-
-# Run tests
-npm test
-
-# Type checking
+npm run build
+npm test            # 348 tests
 npm run typecheck
-
-# Linting
 npm run lint
-
-# Build for production
-npm run build
 ```
 
+## Requirements
+
+- **Node.js:** ≥ 18
+- **Platform:** Linux, macOS, or WSL2
+- **Auth:** UluOps API key ([get one here](https://app.uluops.ai/settings/api-keys))
+
 ## License
 
 MIT

package/dist/client/sdk-error-mapper.d.ts

@@ -12,6 +12,35 @@ import type { McpToolResponse } from '../types/index.js';
  * and truncation.
  */
 export declare const sanitizeErrorMessage: typeof sanitizeString;
+export interface ExtractedErrorContext {
+    /** Sanitized human-readable message. */
+    message: string;
+    /** HTTP status code if available on the SDK error. */
+    status?: number;
+    /** 402-only: tier required for access. */
+    required_tier?: string;
+    /** 402-only: caller's current tier. */
+    current_tier?: string;
+    /** 402-only: definition reference. */
+    definition?: {
+        type?: string;
+        name?: string;
+    };
+    /** 402-only: upgrade URL (mcp-source-tagged). */
+    upgrade_url?: string;
+    /** 409-only: next available version hint. */
+    nextAvailable?: unknown;
+    /** 429-only: server-recommended retry delay in seconds. */
+    retry_after?: number;
+}
+/**
+ * Extract the same structured-error fields as `mapSdkErrorToMcp` produces,
+ * but without wrapping them in an `McpToolResponse`. Useful inside batch
+ * loops where each per-item failure should embed the rich error context
+ * (402 upgrade URL, 429 retry-after, 409 nextAvailable) into the parent
+ * response rather than producing one MCP error envelope per failure.
+ */
+export declare function extractErrorContext(error: unknown): ExtractedErrorContext;
 /**
  * Map an SDK error to an MCP tool response.
  *

package/dist/client/sdk-error-mapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk-error-mapper.d.ts","sourceRoot":"","sources":["../../src/client/sdk-error-mapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,uBAAiB,CAAC;AAkCnD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAqGhE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAahE"}
+{"version":3,"file":"sdk-error-mapper.d.ts","sourceRoot":"","sources":["../../src/client/sdk-error-mapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,uBAAiB,CAAC;AA6DnD,MAAM,WAAW,qBAAqB;IACpC,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,UAAU,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAuDzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAkHhE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAahE"}