Catalog Decorators Server

Overview

The Catalog Decorators Server provides MCP tools for managing catalog entity decorators/fragments in Roadie. It enables AI assistants to retrieve, create and update fragments that enhance catalog entities with additional metadata.

Fragments are partial entity data that are “decorated” onto an existing entity in the catalog to enrich its metadata.

Server Endpoint: https://api.roadie.so/api/mcp/v1/catalog-decorators

Capabilities

Fragment Discovery: List all entity fragments or fragments for a specific entity
Fragment Creation: Create new fragments to decorate entities with additional metadata
Fragment Updates: Add and change data in existing fragments for an entity
Entity Enhancement: Add specifications, metadata, and other information to catalog entities

Available Tools

List Fragments

Retrieve a list of all entity fragments with optional filtering capabilities.

Parameters:

entityRef (string, optional): Filter fragments for a specific entity
limit (number, optional): Maximum number of results to return (default: 100)
offset (number, optional): Pagination offset for results (default: 0)

Example Usage:

{
  "entityRef": "component:default/user-service",
  "limit": 20,
  "offset": 0
}

Alternative Usage (List All):

{
  "limit": 100
}

Returns: List of fragments including:

Fragment identifiers and metadata
Associated entity references
Fragment content and specifications
Creation and modification timestamps

Return Schema:

{
  fragments: {
    id: string, // Fragment identifier
    entityRef: string, // Associated entity reference
    fragment: {
      metadata?: Record<string, any>, // Additional metadata
      spec?: Record<string, any>, // Specification data
      // Other fragment properties
    },
    createdAt: string, // Creation timestamp
    updatedAt?: string // Last modification timestamp
  }[],
  total: number, // Total number of fragments available
  hasMore: boolean // Whether more results are available
}

Required Permissions:

Fragment entity read - roadie.entity-fragment.read - Permission to view entity fragments

Create Fragment

Create a new fragment to decorate a catalog entity with additional metadata and specifications.

Parameters:

entityRef (string): Target entity reference to decorate
fragment (object): Fragment data containing metadata and spec information

Example Usage:

{
  "entityRef": "component:default/payment-service",
  "fragment": {
    "metadata": {
      "annotations": {
        "example.com/responsible-team": "payments-team",
        "example.com/deployment-strategy": "blue-green"
      },
      "labels": {
        "tier": "critical",
        "environment": "production"
      }
    },
    "spec": {
      "type": "something-new",
      "additionalConfig": {
        "monitoring": "enabled",
        "backup": "daily"
      }
    }
  }
}

Fragment Schema:

{
  entityRef: string, // Target entity reference
  fragment: {
    metadata?: {
      annotations?: Record<string, string>, // Additional annotations
      labels?: Record<string, string>, // Additional labels
      tags?: string[], // Additional tags
      // Other metadata fields
    },
    spec?: Record<string, any>, // Custom specification data
  }
}

Returns: Created fragment information including:

Fragment ID and entity reference
Confirmation of applied decorations
Any validation warnings or notes

Required Permissions:

Fragment entity create - roadie.entity-fragment.create - Permission to create and modify entity fragments

Common Use Cases

Fragment Discovery and Management

“What fragments exist for the payment-service component?”
“List all fragments in the system”
“Find fragments that have been modified recently”

Entity Enhancement

“Update the decription of the user-service to say …”
“Add prometheus monitoring annotations to the user-service component”

Bulk Operations and Analysis

“Show me all fragments that modify descriptions”
“List fragments that enhance entities with monitoring configurations”
“Find all custom specifications added to payment-related services”

Fragment Use Cases

Adding Team Responsibility Information

{
  "entityRef": "component:default/user-service",
  "fragment": {
    "metadata": {
      "annotations": {
        "roadie.io/responsible-team": "platform-team",
        "roadie.io/on-call-schedule": "https://pagerduty.com/schedules/platform"
      }
    }
  }
}

Enhancing with Deployment Information

{
  "entityRef": "resource:default/payment-gateway",
  "fragment": {
    "metadata": {
      "labels": {
        "deployment-strategy": "canary",
        "release-cycle": "weekly"
      }
    },
    "spec": {
      "deployment": {
        "replicas": 3,
        "strategy": "RollingUpdate"
      }
    }
  }
}

Adding Monitoring and Observability

{
  "entityRef": "api:default/orders-api",
  "fragment": {
    "metadata": {
      "annotations": {
        "datadog.com/dashboard": "https://app.datadoghq.com/dashboard/orders-api",
        "prometheus.io/scrape": "true"
      },
      "monitoring": {
        "alerts": ["high-error-rate", "high-latency"],
        "slos": [
          {
            "name": "availability",
            "target": 99.9
          }
        ]
      }
    },
    "spec": {}
  }
}

Example Workflows

Entity Enhancement Workflow

User: “I want to add team ownership information to all payment services”

AI Response using MCP:

Uses list-fragments to find existing fragments for payment services
Identifies services that need team ownership information
Uses create-fragment to add responsible team annotations
Provides summary of enhanced entities and their new metadata

Fragment Audit and Discovery

User: “Show me all custom monitoring configurations added to our services”

AI Response using MCP:

Uses list-fragments to retrieve all fragments
Filters fragments containing monitoring-related specifications
Analyzes monitoring patterns and configurations
Provides summary of monitoring setups across services

Systematic Entity Decoration

User: “Add deployment strategy labels to all components in the production namespace”

AI Response using MCP:

Uses entity search to find all production components
Uses list-fragments to check existing decorations
Uses create-fragment to add deployment strategy information
Confirms successful application and provides summary

Best Practices

Fragment Design

Specific Purpose: Create fragments for specific enhancement purposes (monitoring, ownership, deployment info)
Update the source YAML file if possible: Fragments allow easier updates to entity data and allow updates to entities not defined in YAML, but its always preferable to update the source entity of it comes from a YAML file in an SCM.

Entity Reference Management

Precise References: Use exact entity references (kind:namespace/name format)
Validation: Verify target entities exist before creating fragments
Confirmation Creating a fragment successfully does not mean it necessarily has been applied if there was an error. You can check if a Fragment was actually applied to an entity using the Get Entity MCP tool.

Security Considerations

Fragment Permissions

Fragment mutations requires appropriate write permissions of roadie.entity-fragment.create

Data Validation

Fragment content is validated against entity schemas
Malformed fragments are rejected with clear error messages

Troubleshooting

Common Issues

Permission Errors:
- Verify you have the relevant roadie.entity-fragment.<action> permission
- Ensure access to target entities before creating fragments
Entity Reference Issues:
- Use exact entity reference format: kind:namespace/name
- Verify target entities exist in the catalog
- Check for typos in entity names or namespaces
Validation Failures:
- Ensure fragment content follows expected schemas
- Validate JSON structure and data types
- Check that required fields are provided