feat(ai-integrations): add 'mcp-registry-provider' openspec files

[michael-valdron]

Hey, I just made a Pull Request!

Contributes openspecs for MCP Registry Provider plugin implementation.

https://redhat.atlassian.net/browse/RHIDP-15658

✔️ Checklist

• A changeset describing the change and affected packages. (more info)
• Added or Updated documentation
• Tests for new functionality and regression tests for bug fixes
• Screenshots attached (for UI changes)

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 11:48 PM UTC · Ended 11:51 PM UTC

Commit: fac73c7 · View workflow run →

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 11:52 PM UTC · Ended 11:54 PM UTC

Commit: 501a837 · View workflow run →

[rhdh-qodo-merge]

PR Summary by Qodo

Specify MCP registry mapping and catalog provider

✨ Enhancement 📝 Documentation 🕐 40+ Minutes

AI Description

• Defines deterministic, secret-safe server.json mapping into Backstage mcp-server entities.
• Specifies scheduled multi-registry ingestion with cursor pagination and atomic catalog
 reconciliation.
• Documents architecture, requirements, risks, audits, and implementation plans for both
 capabilities.

Diagram

graph TD
  S["Scheduler"] --> R["Registry API"] --> P{"More pages?"}
  P -->|Yes| R
  P -->|No| M["Mapping transform"] --> E["MCP entities"] --> C["Catalog mutation"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Combine mapping and provider

• ➕ Reduces initial package and integration surface
• ➕ Allows provider-specific assumptions inside the transform
• ➖ Couples pure transformation rules to ingestion lifecycle concerns
• ➖ Makes reuse, deterministic testing, and schema evolution harder
• ➖ Increases the risk of mapping drift across future ingestion paths

2. Expose a registry proxy

• ➕ Builds more directly on the existing reference prototype
• ➕ Keeps registry responses available to live API consumers
• ➖ Does not provide catalog discovery or reconciliation semantics
• ➖ Leaves clients responsible for transformation and pagination
• ➖ Adds an HTTP surface that catalog ingestion does not require

Recommendation: Retain the proposed split between a pure mapping capability and per-registry catalog providers. It provides clear ownership, reusable deterministic transformation, independent scheduling and failure isolation, while full mutations safely preserve catalog convergence. A proxy should remain separate if live pass-through access is later required.

Files changed (15) +882 / -0

Enhancement (5) +483 / -0

proposal.mdPropose the MCP registry catalog provider +51/-0

Propose the MCP registry catalog provider

• Establishes the need for scheduled MCP registry ingestion and outlines multi-registry configuration, pagination, full mutations, and resilient error handling. It scopes out proxying, authentication, runtime invocation, and UI changes.

workspaces/ai-integrations/openspec/changes/mcp-registry-provider/proposal.md

spec.mdSpecify provider behavior and acceptance scenarios +129/-0

Specify provider behavior and acceptance scenarios

• Defines normative requirements for configuration, scheduling, endpoint construction, cursor traversal, mapping delegation, catalog reconciliation, and failure handling. Includes scenarios for multi-registry operation, pruning, malformed entries, and registry-level errors.

workspaces/ai-integrations/openspec/changes/mcp-registry-provider/specs/mcp-registry-provider/spec.md

proposal.mdPropose the canonical MCP server mapping +75/-0

Propose the canonical MCP server mapping

• Proposes a deterministic server.json-to-mcp-server entity contract with native fields and lossless annotation projection. Anchors the output to the upstream Backstage schema and explicitly redacts secret values.

workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/proposal.md

spec.mdSpecify safe annotation projection rules +113/-0

Specify safe annotation projection rules

• Defines recursive scalar projection, dot-path key encoding, sanitization, truncation, collision handling, and no-overwrite behavior. Requires uniform redaction of secret defaults and values while preserving non-secret metadata.

workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/specs/mcp-registry-annotation-projection/spec.md

spec.mdSpecify server.json to mcp-server transformation +115/-0

Specify server.json to mcp-server transformation

• Defines required-field validation, remote mapping, version-unique names, descriptive metadata, owner and lifecycle defaults, and deterministic output. Requires conformance with Backstage's dedicated mcp-server API entity schema.

workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/specs/mcp-registry-server-mapping/spec.md

Documentation (8) +395 / -0

audit.mdRecord a clean provider specification audit +29/-0

Record a clean provider specification audit

• Documents the provider change's audit results across coherence, ownership, convention, and security categories, with no outstanding findings.

workspaces/ai-integrations/openspec/changes/mcp-registry-provider/audit.md

design.mdDesign scheduled MCP registry catalog ingestion +102/-0

Design scheduled MCP registry catalog ingestion

• Defines configuration, provider isolation, scheduling, complete cursor pagination, mapping delegation, and atomic failure behavior. It also documents operational risks, deployment guidance, and deferred authentication and deduplication concerns.

workspaces/ai-integrations/openspec/changes/mcp-registry-provider/design.md

journal.jsonlCapture provider specification decisions +13/-0

Capture provider specification decisions

• Records creation, authoring, configuration, pagination, and audit events for the provider OpenSpec workflow.

workspaces/ai-integrations/openspec/changes/mcp-registry-provider/journal.jsonl

tasks.mdPlan provider implementation and verification +49/-0

Plan provider implementation and verification

• Breaks implementation into plugin scaffolding, configuration, registry client, scheduling, mapping integration, tests, and documentation. Captures dependencies and parallelizable work groups.

workspaces/ai-integrations/openspec/changes/mcp-registry-provider/tasks.md

audit.mdDocument resolved mapping audit findings +45/-0

Document resolved mapping audit findings

• Records the clean final audit and the resolution of earlier mapping consistency findings. It also clarifies annotation ownership relative to sibling changes.

workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/audit.md

design.mdDesign deterministic server-to-entity mapping +99/-0

Design deterministic server-to-entity mapping

• Defines entity shape, identity generation, native field mapping, annotation fallback, deterministic defaults, secret redaction, and source links. Documents alternatives, schema risks, and deferred cross-registry deduplication.

workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/design.md

journal.jsonlCapture mapping specification evolution +21/-0

Capture mapping specification evolution

• Records mapping authoring decisions and subsequent revisions involving lifecycle defaults, source links, annotation projection, secret handling, and audit results.

workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/journal.jsonl

tasks.mdPlan mapping implementation and conformance testing +37/-0

Plan mapping implementation and conformance testing

• Organizes schema pinning, direct mapping, annotation projection, secret redaction, fixtures, schema validation, and consumer documentation into implementation tasks.

workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/tasks.md

Other (2) +4 / -0

.openspec.yamlRegister the provider OpenSpec change +2/-0

Register the provider OpenSpec change

• Declares the RHDH spec-driven schema and creation date for the MCP registry provider change.

workspaces/ai-integrations/openspec/changes/mcp-registry-provider/.openspec.yaml

.openspec.yamlRegister the mapping OpenSpec change +2/-0

Register the mapping OpenSpec change

• Declares the RHDH spec-driven schema and creation date for the MCP registry server mapping change.

workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/.openspec.yaml

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 62.05%. Comparing base (c3d945b) to head (501a837).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4527   +/-   ##
=======================================
  Coverage   62.05%   62.05%           
=======================================
  Files        2603     2603           
  Lines      104463   104463           
  Branches    29341    29340    -1     
=======================================
  Hits        64822    64822           
- Misses      37784    37795   +11     
+ Partials     1857     1846   -11     

Flag	Coverage Δ		*Carryforward flag
adoption-insights	84.30% <ø> (ø)		Carriedforward from c3d945b
ai-integrations	76.15% <ø> (ø)
app-defaults	56.22% <ø> (ø)		Carriedforward from c3d945b
augment	46.67% <ø> (ø)		Carriedforward from c3d945b
boost	80.51% <ø> (ø)		Carriedforward from c3d945b
bulk-import	72.79% <ø> (ø)		Carriedforward from c3d945b
cost-management	13.55% <ø> (ø)		Carriedforward from c3d945b
dcm	72.09% <ø> (ø)		Carriedforward from c3d945b
e2e-adoption-insights	60.00% <ø> (ø)		Carriedforward from c3d945b
e2e-extensions	62.32% <ø> (ø)		Carriedforward from c3d945b
e2e-global-header	50.35% <ø> (ø)		Carriedforward from c3d945b
e2e-homepage	61.11% <ø> (ø)		Carriedforward from c3d945b
e2e-intelligent-assistant	47.04% <ø> (ø)		Carriedforward from c3d945b
e2e-orchestrator	49.52% <ø> (ø)		Carriedforward from c3d945b
e2e-orchestrator-plugin	49.51% <ø> (ø)		Carriedforward from c3d945b
e2e-quickstart	55.21% <ø> (ø)		Carriedforward from c3d945b
e2e-scorecard	50.21% <ø> (ø)		Carriedforward from c3d945b
e2e-theme	16.36% <ø> (ø)		Carriedforward from c3d945b
extensions	56.66% <ø> (ø)		Carriedforward from c3d945b
global-floating-action-button	71.18% <ø> (ø)		Carriedforward from c3d945b
global-header	68.09% <ø> (ø)		Carriedforward from c3d945b
homepage	48.48% <ø> (ø)		Carriedforward from c3d945b
install-dynamic-plugins	58.57% <ø> (ø)		Carriedforward from c3d945b
intelligent-assistant	76.40% <ø> (ø)		Carriedforward from c3d945b
konflux	91.98% <ø> (ø)		Carriedforward from c3d945b
lightspeed	69.02% <ø> (ø)		Carriedforward from c3d945b
mcp-integrations	84.14% <ø> (ø)		Carriedforward from c3d945b
orchestrator	71.13% <ø> (ø)		Carriedforward from c3d945b
quickstart	63.74% <ø> (ø)		Carriedforward from c3d945b
sandbox	79.56% <ø> (ø)		Carriedforward from c3d945b
scorecard	87.65% <ø> (ø)		Carriedforward from c3d945b
theme	87.91% <ø> (ø)		Carriedforward from c3d945b
translations	5.12% <ø> (ø)		Carriedforward from c3d945b
x2a	77.10% <ø> (ø)		Carriedforward from c3d945b

*This pull request uses carry forward flags. Click here to find out more.

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update c3d945b...501a837. Read the comment docs.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 11:55 PM UTC · Completed 12:12 AM UTC

Commit: 501a837 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Cost: $6.24

[rhdh-qodo-merge]

Code Review by Qodo

🐞 Bugs (7) 📘 Rule violations (0) 🔗 Cross-repo conflicts (1) 📜 Skill insights (0)

1. Mutation location key omitted 🐞 Bug ≡ Correctness

Description

The provider requirements express source ownership only through entity annotations, but catalog full
mutations require locationKey on each mutation entry to scope provider ownership and pruning. An
implementation following the normative spec can therefore produce incorrectly scoped mutations even
though the implementation task mentions locationKey.

Code

workspaces/ai-integrations/openspec/changes/mcp-registry-provider/specs/mcp-registry-provider/spec.md[R98-101]

+#### Scenario: Provider attribution annotations present
+
+- **WHEN** the provider produces an entity
+- **THEN** the entity carries the provider instance's managed-location annotation so the catalog associates the entity with this provider and can prune it on removal

Relevance

●●● Strong

The finding identifies a concrete mismatch between normative requirements and required catalog
mutation ownership semantics.

PR-#4132

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The new requirement says attribution and pruning come from an annotation, while the existing
provider implementation separately annotates entities and wraps each entity with locationKey when
applying the full mutation.

workspaces/ai-integrations/openspec/changes/mcp-registry-provider/specs/mcp-registry-provider/spec.md[84-105]
workspaces/ai-integrations/plugins/catalog-backend-module-model-catalog/src/providers/ModelCatalogResourceEntityProvider.ts[206-228]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The provider specification conflates managed-location annotations with the `locationKey` required on catalog mutation entries. Specify both concepts separately and require every full-mutation entry to be shaped as `{ entity, locationKey: providerName }`.

## Issue Context
Existing providers add annotations to the entity but independently attach `locationKey` to each mutation wrapper. The latter is what scopes provider ownership and pruning.

## Fix Focus Areas
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/specs/mcp-registry-provider/spec.md[84-105]
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/design.md[59-61]
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/tasks.md[31-35]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Source location lacks prefix 🐞 Bug ≡ Correctness

Description

The mapping requires backstage.io/source-location to carry the raw repository URL, but Backstage
source locations are typed location references such as url:https://…. The resulting annotation
will not be interpreted as the canonical URL location by source-aware tooling.

Code

workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/specs/mcp-registry-server-mapping/spec.md[R74-77]

+#### Scenario: Repository maps to a source link and a source-location annotation
+
+- **WHEN** a `server.json` provides `repository.url` and `repository.subfolder`
+- **THEN** the entity has a `metadata.links` entry whose `url` references the repository URL (and subfolder when present) and whose `title` is `Source Code`, a `backstage.io/source-location` annotation carrying the same repository URL (and subfolder when present) is also emitted, and the remaining `repository` sub-fields (`source`, `id`) are projected into `modelcontextprotocol.io/*` annotations

Relevance

●●● Strong

Backstage source-location values require typed location references; this workspace accepted the same
URL-prefix issue.

PR-#3956

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The new mapping says the annotation carries the repository URL itself, whereas the repository's
ingestion specification requires the normal url:https://… location-ref form and its validator uses
parseLocationRef for the same annotation.

workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/specs/mcp-registry-server-mapping/spec.md[65-77]
workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/specs/ai-resource-catalog-ingestion/spec.md[19-26]
workspaces/ai-integrations/plugins/catalog-backend-module-ai-resource-extensions/src/collectOciErrors.ts[27-32]
PR-#3956

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Require `backstage.io/source-location` to use the Backstage location-ref format, specifically `url:<repository URL and subfolder target>`, rather than copying the bare repository URL.

## Issue Context
Repository conventions explicitly use `url:https://…` and parse source-location annotations as typed location references. Keep the human-visible `metadata.links` URL unprefixed.

## Fix Focus Areas
- workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/specs/mcp-registry-server-mapping/spec.md[65-77]
- workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/design.md[79-81]
- workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/tasks.md[14-17]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. MCP schema module missing 🔗 Cross-repo conflict ≡ Correctness

Description

The specification requires emitting API entities with spec.type: mcp-server, spec.remotes, and
no spec.definition, but the pinned RHDH backend does not install
@backstage/plugin-catalog-backend-module-ai-model, which registers support for that specialized
entity model. Without adding that module or defining a fallback, RHDH may validate these entities as
generic APIs and reject them for missing spec.definition.

Code

workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/specs/mcp-registry-server-mapping/spec.md[15]

+The mapping SHALL transform one `server.json` document into one `API` entity with `apiVersion: backstage.io/v1alpha1`, `kind: API`, and `spec.type: mcp-server`, such that the produced entity passes the upstream Backstage `mcp-server` `API` entity schema (`McpServerApiEntity`), which for `spec.type: mcp-server` requires `spec.remotes` and does not include `spec.definition` — overriding the generic base `API` schema. When the source omits a `server.json`-required field (`name`, `description`, or `version`), the mapping SHALL fail with an actionable error that names the missing field and references the MCP server schema, rather than emitting a partial entity.

Relevance

●●● Strong

Missing specialized catalog-model support is a concrete integration dependency, consistent with
accepted upstream-schema alignment feedback.

PR-#3938

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The new mapping mandates the specialized MCP API schema. Another specification in the PR branch
explicitly states that this shape is available only when
@backstage/plugin-catalog-backend-module-ai-model is installed and otherwise requires a Resource
fallback, while RHDH's complete backend dependency section includes its catalog modules but not that
package.

workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/specs/mcp-registry-server-mapping/spec.md[13-20]
workspaces/boost/openspec/changes/agent-creation-discovery/specs/catalog-entities/spec.md[19-23]
External repo: redhat-developer/rhdh, packages/backend/package.json [23-43]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The provider is specified to emit the specialized `McpServerApiEntity` shape, but the target RHDH backend does not include the catalog AI model module that enables this shape.

## Issue Context
Make deployment of `@backstage/plugin-catalog-backend-module-ai-model` an explicit prerequisite and implementation task, including the required RHDH coordination. Alternatively, specify and test the existing `Resource` fallback when that module is unavailable.

## Fix Focus Areas
- workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/specs/mcp-registry-server-mapping/spec.md[13-20]
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/design.md[93-95]
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/tasks.md[43-48]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View high (1)

4. Rollback leaves entities behind 🐞 Bug ☼ Reliability

Description

The migration plan claims that removing the module or its configuration causes ingested entities to
be pruned on the next reconciliation, but an absent provider cannot issue the empty full mutation
needed for pruning. Rollback therefore leaves stale MCP entities in the catalog unless an explicit
cleanup is performed before unregistering the provider.

Code

workspaces/ai-integrations/openspec/changes/mcp-registry-provider/design.md[R93-95]

+## Migration Plan
+
+Not applicable to existing data — this is additive and introduces no migration of prior state. Deployment: publish the backend module package, add it to the backend via `backend.add(...)`, and configure at least one `catalog.providers.mcpRegistry.<id>` with a `baseUrl`. Rollback: remove the module registration (or the config block); ingested entities are pruned on the next catalog reconciliation because they are provider-managed via `locationKey`. The provider is inert when unconfigured, so shipping the package without config is a safe no-op.

Relevance

●● Moderate

The rollback claim conflicts with provider mutation semantics, but no close accepted or rejected
rollback precedent appeared.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The migration plan promises pruning after the provider is removed, while the repository's provider
implementation performs pruning only from a live applyMutation call inside its sync path.

workspaces/ai-integrations/openspec/changes/mcp-registry-provider/design.md[93-95]
workspaces/ai-integrations/plugins/catalog-backend-module-model-catalog/src/providers/ModelCatalogResourceEntityProvider.ts[219-228]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Correct the rollback plan so it does not claim that removing an inactive provider automatically prunes its entities. Define an explicit cleanup procedure, such as applying an empty full mutation while the provider is still registered, or document the supported catalog cleanup mechanism.

## Issue Context
Pruning happens when a connected provider calls `applyMutation({ type: 'full', ... })`; deleting its module or configuration prevents that call.

## Fix Focus Areas
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/design.md[93-95]
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/specs/mcp-registry-provider/spec.md[103-110]
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/tasks.md[31-35]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. Collision handling violates purity 🐞 Bug ≡ Correctness

Description

The single-document mapping is required to detect when two distinct name/version pairs sanitize to
the same identity, but a pure invocation has no knowledge of other documents. Implementing that
requirement needs batch state and makes results set-dependent, or else leaves the promised
uniqueness unenforced.

Code

workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/specs/mcp-registry-server-mapping/spec.md[R60-63]

+#### Scenario: Over-length or colliding names remain unique
+
+- **WHEN** two distinct (name, version) pairs sanitize to the same `<name>__<version>`, or the combined value exceeds the 63-character limit after sanitization
+- **THEN** the mapping produces a deterministic, unique `metadata.name` by truncating and appending a stable hash suffix derived from the canonical name and version

Relevance

●●● Strong

The specification has a concrete internal contradiction between pure single-document mapping and
cross-document collision detection.

PR-#4132

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

One requirement conditionally disambiguates collisions between two documents, while another states
that output is a pure function only of the current document and caller defaults; the provider also
invokes the transform independently per entry.

workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/specs/mcp-registry-server-mapping/spec.md[60-63]
workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/specs/mcp-registry-server-mapping/spec.md[108-115]
workspaces/ai-integrations/openspec/changes/mcp-registry-provider/specs/mcp-registry-provider/spec.md[84-86]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Replace cross-document collision detection with an identity algorithm that is deterministic from the current document alone. For example, append a stable hash whenever sanitization is lossy or always include a bounded hash derived from the original name/version pair.

## Issue Context
The mapping is explicitly a pure function of one server document and caller defaults, so it cannot conditionally react to another document that happens to sanitize to the same value.

## Fix Focus Areas
- workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/specs/mcp-registry-server-mapping/spec.md[46-63]
- workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/specs/mcp-registry-server-mapping/spec.md[108-115]
- workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/design.md[55-65]
- workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/tasks.md[14-16]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

6. Opaque cursors lack encoding 🐞 Bug ≡ Correctness

Description

The pagination contract requires opaque cursors to be passed “verbatim” but does not require
serialization as an encoded query-parameter value. A cursor containing &, #, ?, or % can be
split or altered by an implementation that interpolates it directly into the URL, causing skipped
pages or unintended parameters.

Code

workspaces/ai-integrations/openspec/changes/mcp-registry-provider/specs/mcp-registry-provider/spec.md[R65-68]

+#### Scenario: Opaque cursor is passed unchanged
+
+- **WHEN** a response's `metadata.nextCursor` is an opaque token
+- **THEN** the provider passes that token verbatim as the `cursor` query parameter without parsing or altering it

Relevance

●●● Strong

Reserved-character URL encoding bugs are accepted, including path/query construction that only
handles spaces.

PR-#3833

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The specification mandates opaque passthrough but only mentions placing the value in a query
parameter, and the implementation tasks contain no URL-encoding or reserved-character test
requirement. A past accepted bug in this workspace demonstrates the same failure mode when reserved
URL characters were not encoded.

workspaces/ai-integrations/openspec/changes/mcp-registry-provider/specs/mcp-registry-provider/spec.md[51-68]
workspaces/ai-integrations/openspec/changes/mcp-registry-provider/tasks.md[20-27]
PR-#3833

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Clarify that “opaque and unchanged” refers to the cursor's decoded value and require construction through `URL`/`URLSearchParams` or equivalent query-value encoding. Add a test cursor containing reserved query and fragment characters.

## Issue Context
Direct URL interpolation does not preserve arbitrary opaque values because reserved characters affect URL parsing. Encoding must happen exactly once while the registry receives the original decoded token.

## Fix Focus Areas
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/specs/mcp-registry-provider/spec.md[51-68]
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/design.md[67-69]
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/tasks.md[20-27]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

7. Audit suppresses recorded warning 🐞 Bug ⚙ Maintainability

Description

The audit report claims zero warnings even though the journal records one schedule-type warning and
says the user chose report-only rather than fixing it. This makes the committed audit status
unreliable and hides an unresolved naming inconsistency from implementers.

Code

workspaces/ai-integrations/openspec/changes/mcp-registry-provider/audit.md[R15-17]

+| G — Extended coherence     | 0        | 0       | 0          |
+| H — Security lint          | 0        | 0       | 0          |
+| **Total**                  | **0**    | **0**   | **0**      |

Relevance

●●● Strong

Audit/report inconsistencies are accepted in this workspace when journals or artifacts contradict
committed status summaries.

PR-#4132

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The report's summary and detail sections say there are no warnings, while the final journal event
explicitly records one warning and a report-only decision.

workspaces/ai-integrations/openspec/changes/mcp-registry-provider/audit.md[7-29]
workspaces/ai-integrations/openspec/changes/mcp-registry-provider/journal.jsonl[10-13]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Make `audit.md` reflect the warning recorded in the journal, or resolve the schedule-type terminology and record a subsequent clean re-audit. Do not report a zero total while the latest audit outcome is report-only with one warning.

## Issue Context
The requirements use the runtime schedule-definition name while `config.d.ts` correctly needs the configuration-shape type; the intended distinction should be documented consistently rather than hidden by the audit summary.

## Fix Focus Areas
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/audit.md[5-29]
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/journal.jsonl[10-13]
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/specs/mcp-registry-provider/spec.md[13-15]
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/tasks.md[13-18]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

8. Registries share entity identities 🐞 Bug ≡ Correctness

Description

Multiple configured registries that publish the same server name and version produce the same
kind/namespace/name identity because registry identity is excluded from the mapping. Separate
provider locationKey values only scope ownership and pruning; they do not make duplicate catalog
entity references coexist.

Code

workspaces/ai-integrations/openspec/changes/mcp-registry-provider/specs/mcp-registry-provider/spec.md[R22-25]

+#### Scenario: Multiple registry instances configured
+
+- **WHEN** `catalog.providers.mcpRegistry` contains two keys `internal` and `public`, each with its own `baseUrl` and `schedule`
+- **THEN** two independent provider instances are registered, each syncing its own registry on its own schedule

Relevance

● Weak

Cross-registry deduplication is explicitly documented as out of scope, matching prior rejection of
scope-expansion findings.

PR-#4132

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The provider requires one independent provider per registry, while the consumed mapping derives
metadata.name solely from source name and version; the provider design itself acknowledges that
equal names and versions collide across registries.

workspaces/ai-integrations/openspec/changes/mcp-registry-provider/specs/mcp-registry-provider/spec.md[13-25]
workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/specs/mcp-registry-server-mapping/spec.md[46-63]
workspaces/ai-integrations/openspec/changes/mcp-registry-provider/design.md[83-90]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Define how entities from different registry instances receive distinct catalog identities when they contain the same server name and version. Pass a deterministic registry namespace or identity seed into the mapping, or explicitly reject conflicting multi-registry configuration before mutation.

## Issue Context
The provider promises independent multi-registry operation, but the mapping derives identity only from server name and version. `locationKey` cannot distinguish two entities with the same catalog entity reference.

## Fix Focus Areas
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/specs/mcp-registry-provider/spec.md[13-25]
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/design.md[55-61]
- workspaces/ai-integrations/openspec/changes/mcp-registry-provider/design.md[83-90]
- workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping/specs/mcp-registry-server-mapping/spec.md[46-63]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

⚠️ Tickets: not configured — ticket URL found in PR but could not be fetched — check ticket provider credentials

✅ Compliance rules (platform): 14 rules

✅ Cross-repo context — repo relationships

  Explored: repo: redhat-developer/rhdh (sha: 1fbff2d3)

Tip of the day

💡 Did you know, you can describe a rule in plain language on the Rules page and Qodo drafts it for you

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[fullsend-ai-review]

Review

Findings

Medium

• [naming-convention] workspaces/ai-integrations/openspec/changes/mcp-registry-provider/.openspec.yaml:1 — Both new .openspec.yaml files use schema: rhdh-spec-driven while all 7 existing openspec changes in this workspace consistently use schema: spec-driven. This introduces a schema name divergence. The same deviation appears in mcp-registry-server-mapping/.openspec.yaml.
  Remediation: Change schema: rhdh-spec-driven to schema: spec-driven in both .openspec.yaml files to match the established convention, or document the new schema name and its relationship to spec-driven.

• [scope-mismatch] workspaces/ai-integrations/openspec/changes/mcp-registry-server-mapping — The PR title references only mcp-registry-provider openspec files, but the PR actually adds two independent openspec change sets: mcp-registry-provider (7 files) and mcp-registry-server-mapping (8 files). The server-mapping change defines a standalone capability with its own proposal, design, tasks, two specs, audit, and journal. Its journal shows it was created a week before the provider (2026-08-18 vs 2026-08-26).
  Remediation: Update the PR title and body to reflect the full scope, e.g. feat(ai-integrations): add mcp-registry-server-mapping and mcp-registry-provider openspec files.

Low

• [internal-consistency] workspaces/ai-integrations/openspec/changes/mcp-registry-provider/audit.md — The journal.jsonl final entry records the audit outcome as "1 WARNING (schedule type name drift), 1 SUGGESTION (cursor safeguard wording)" but audit.md reports all zeros across every category. The sibling mcp-registry-server-mapping/audit.md includes a "Pass 1 findings (all resolved)" section documenting what was found and fixed — this audit report lacks an equivalent section.

• [doc-style] workspaces/ai-integrations/openspec/changes/mcp-registry-provider/proposal.md:1 — Both new openspec changes start proposal.md, design.md, and tasks.md with H2 headings directly, omitting the H1 title. Six of seven existing openspec changes follow the pattern # Proposal: <Title>, # Design: <Title>, # Tasks: <Title> as the opening H1 heading.

• [convention-deviation] workspaces/ai-integrations/openspec/changes/mcp-registry-provider — Both new openspec changes introduce audit.md and journal.jsonl files that do not exist in any of the seven prior openspec changes. The workspace AGENTS.md documents the expected openspec file set as "proposal, design, tasks, and behavioral requirements" without mentioning audit reports or journal logs.

[michael-valdron]

/fs-fix apply [naming-convention] fix

[michael-valdron]

/fs-fix Change schema: rhdh-spec-driven to schema: spec-driven in both .openspec.yaml files to match the established convention

[michael-valdron]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure (validation failed after 2 iteration(s)) · Started 6:21 PM UTC · Completed 6:23 PM UTC

Commit: 501a837 · View workflow run →

Runtime: claude · Model: opus → claude-opus-5

[michael-valdron]

Closing this fork PR in favour of #4667 to give fullsend write permissions to revise my changes.

[fullsend-ai-retro]

🤖 Finished Retro · ❌ Failure (validation failed after 2 iteration(s)) · Started 6:36 PM UTC · Completed 6:38 PM UTC

Commit: 501a837 · View workflow run →

Runtime: claude · Model: opus → claude-opus-5 · Effort: high