Backstage Catalog Documentation Capability

naftiko: 1.0.0-alpha2
info:
  title: Backstage Catalog Documentation Capability
  description: A capability over Backstage that pulls catalog entities and their TechDocs and exposes them as composed documentation context for AI agents.
  tags: [Naftiko, Backstage, TechDocs]
  created: '2026-05-01'
  modified: '2026-05-04'
binds:
- namespace: backstage-env
  keys: {BACKSTAGE_HOST: BACKSTAGE_HOST, BACKSTAGE_TOKEN: BACKSTAGE_TOKEN}
capability:
  consumes:
  - namespace: backstage
    type: http
    baseUri: https://{{BACKSTAGE_HOST}}
    authentication: {type: bearer, token: '{{BACKSTAGE_TOKEN}}'}
    resources:
    - {name: entities, path: /api/catalog/entities, operations: [{name: list-entities, method: GET}]}
    - name: entity
      path: /api/catalog/entities/by-name/{{kind}}/{{namespace}}/{{name}}
      operations:
      - {name: get-entity, method: GET, inputParameters: [{name: kind, in: path}, {name: namespace, in: path}, {name: name, in: path}]}
    - name: techdocs
      path: /api/techdocs/static/docs/{{namespace}}/{{kind}}/{{name}}/index.html
      operations:
      - {name: get-techdocs, method: GET, inputParameters: [{name: kind, in: path}, {name: namespace, in: path}, {name: name, in: path}]}
  exposes:
  - type: rest
    address: 0.0.0.0
    port: 8080
    namespace: backstage-catalog-documentation-capability-rest
    description: REST surface for Backstage catalog + TechDocs.
    resources:
    - {name: entities, path: /entities, operations: [{method: GET, name: list-entities, call: backstage.list-entities}]}
  - type: mcp
    address: 0.0.0.0
    port: 3010
    namespace: backstage-catalog-documentation-capability-mcp
    description: MCP for Backstage catalog/TechDocs.
    tools:
    - {name: list-entities, hints: {readOnly: true}, call: backstage.list-entities}
    - name: get-entity
      hints: {readOnly: true}
      inputParameters: [{name: kind, type: string, required: true}, {name: namespace, type: string, required: true}, {name: name, type: string, required: true}]
      call: backstage.get-entity
    - name: get-techdocs
      hints: {readOnly: true}
      inputParameters: [{name: kind, type: string, required: true}, {name: namespace, type: string, required: true}, {name: name, type: string, required: true}]
      call: backstage.get-techdocs
  - type: skill
    address: 0.0.0.0
    port: 3011
    namespace: backstage-catalog-documentation-capability-skills
    description: Skill for Backstage catalog+docs context.
    skills:
    - name: backstage-catalog-documentation-capability
      description: Backstage catalog + TechDocs context for agents.
      location: file:///opt/naftiko/skills/backstage-catalog-documentation-capability
      allowed-tools: list-entities,get-entity,get-techdocs
      tools:
      - {name: list-entities, from: {sourceNamespace: backstage-catalog-documentation-capability-mcp, action: list-entities}}
      - {name: get-entity, from: {sourceNamespace: backstage-catalog-documentation-capability-mcp, action: get-entity}}
      - {name: get-techdocs, from: {sourceNamespace: backstage-catalog-documentation-capability-mcp, action: get-techdocs}}