Story (Required)

As a developer interacting with RHDH via an MCP client I want to retrieve comprehensive metadata about entities in the RHDH catalog so that I can access detailed specifications, relationships, and configuration information for informed development decisions

This story enables AI clients to access detailed metadata for specific catalog entities through MCP tools, providing deep inspection capabilities for components, APIs, resources, systems, etc. The goal is to allow developers to retrieve complete entity information including YAML specifications, API schemas, dependency relationships, and ownership details through natural language interactions, facilitating better understanding and manipulation of catalog resources.

Background (Required)

The Backstage Software Catalog stores comprehensive metadata for entities including specifications, relationships, annotations, and configuration details. While the search functionality helps discover entities, developers need access to the complete metadata and YAML definitions to understand entity details, API specifications, component dependencies, and system relationships. This detailed metadata access through MCP tools will enable AI assistants to provide richer context and more accurate recommendations when helping developers work with catalog entities.

Out of scope

Metadata modification or updates, bulk metadata retrieval, caching of metadata responses, integration with external metadata sources, metadata validation or schema enforcement, real-time metadata change notifications

Approach (Required)

1. Implement MCP tool for retrieving complete entity metadata using Backstage Catalog API, and delivered as a backend plugin implementing MCP actions (as described in https://github.com/backstage/backstage/tree/master/plugins/mcp-actions-backend)
2. Support retrieval by entity reference (kind:namespace/name format)
3. Format response data for optimal MCP client consumption and manipulation (see previous tool implementations in https://github.com/gabemontero/rhdh-plugins/tree/mcp-proto)
4. Include comprehensive entity data: metadata, spec, relations, status, and source location
5. Handle different entity types with type-specific formatting (Component APIs, Resource configs, etc.)
6. Implement proper error handling for missing or inaccessible entities

Dependencies

Backstage Catalog API access, MCP server implementation, ActionRegistry integration, understanding of catalog entity schemas and YAML format specifications

Acceptance Criteria (Required)

1. MCP tool successfully retrieves complete metadata for any catalog entity by reference and response includes all entity fields: metadata, spec, relations, status, and annotations
2. Tool handles different entity types appropriately (Components, APIs, Resources, Systems, etc.)
3. API specifications and schemas properly extracted and formatted for component APIs
4. Entity relationships and dependencies clearly represented in response
5. Proper error handling for non-existent entities or access permissions. Edge cases to consider:

• Entities with large specifications or complex relationships
• Malformed entity references and input validation
• Entities with missing or incomplete metadata
• Cross-namespace entity references

6. Unit test coverage

7. Evaluation data covering known-good questions and responses for the tool

(✓) documentation updates (design docs, release notes etc)
(✓) demo needed
SOP required
education module update (Filled by RHDHPAI team only)
R&D label required (Filled by RHDHPAI team only)

Done Checklist

Code is completed, reviewed, documented and checked in
Unit and integration test automation have been delivered and running cleanly in continuous integration/staging/canary environment
Continuous Delivery pipeline(s) is able to proceed with new code included
Customer facing documentation, API docs, design docs etc. are produced/updated, reviewed and published
Acceptance criteria are met
If the Grafana dashboard is updated, ensure the corresponding SOP is updated as well