Roo-Code/docs/package-manager-structure.md

Package Manager Repository Structure

Directory Structure Overview

The package manager repository uses a flat directory structure where component types are determined by metadata rather than directory hierarchy. This approach:

1. Simplified Navigation

   • No deep nested directories like items/mcp-servers/ or packages/
   • Components are placed directly in their parent directory
   • Type information is stored in metadata, not directory structure

2. Type Determination

   • Each component's type is specified in its metadata.yml
   • Types include: mcp-server, memory, role, package, group
   • Type field determines how the component is handled and displayed

3. Localization

   • Each component has language-specific metadata files named metadata.{locale}.yml
   • English metadata (metadata.en.yml) is required for component visibility
   • Other languages are optional (e.g., metadata.es.yml, metadata.fr.yml)

4. Organization

   • Groups can contain any type of component
   • Packages reference their components by path
   • Components can be standalone or part of a package/group

Real-World Examples

1. Simple Single-Item Repository

Basic repository sharing individual components:

simple-tools/
├── metadata.en.yml
├── log-analyzer/        # Type determined by metadata
│   ├── metadata.en.yml
│   └── server.js
└── reviewer/           # Type determined by metadata
    ├── metadata.en.yml
    └── role.md

# simple-tools/metadata.en.yml
name: "Simple Tools Collection"
description: "Collection of independent development tools"
version: "1.0.0"

# log-analyzer/metadata.en.yml
name: "Log Analyzer"
description: "Simple log analysis tool"
type: "mcp-server"
version: "1.0.0"
tags: ["logs", "analysis"]

Note: The items field is only needed when referencing components that exist outside the package's directory.

2. Complex Development Toolkit Package

Full-featured development environment setup:

dev-toolkit/
├── metadata.en.yml
├── full-dev-env/           # Type: package
│   ├── metadata.en.yml
│   ├── metadata.es.yml
│   ├── code-analyzer/      # Type: mcp-server
│   │   ├── metadata.en.yml
│   │   ├── metadata.es.yml
│   │   └── server.js
│   ├── git-memory/        # Type: memory
│   │   ├── metadata.en.yml
│   │   ├── metadata.es.yml
│   │   └── memory.js
│   └── dev-role/          # Type: role
│       ├── metadata.en.yml
│       ├── metadata.es.yml
│       └── role.md

# full-dev-env/metadata.en.yml
name: "Full Development Environment"
description: "Complete development setup with code analysis and version control"
version: "2.0.0"
type: "package"

Example with external component reference:

# full-dev-env/metadata.en.yml
name: "Full Development Environment"
description: "Complete development setup with code analysis and version control"
version: "2.0.0"
type: "package"
items: # Only needed for components outside this directory
    - type: "mcp-server"
      path: "../shared/security-scanner" # External component

# full-dev-env/metadata.es.yml
name: "Entorno de Desarrollo Completo"
description: "Configuración completa de desarrollo con análisis de código y control de versiones"
version: "2.0.0"
type: "package"

3. Large Enterprise Data Platform

Complex organization with multiple groups and shared resources:

data-platform/
├── metadata.en.yml          # Repository metadata
├── metadata.es.yml
├── data-engineering/        # Type: group
│   ├── metadata.en.yml
│   ├── metadata.es.yml
│   ├── base-role/          # Type: role
│   │   ├── metadata.en.yml
│   │   └── metadata.es.yml
│   ├── data-lake-memory/   # Type: memory
│   │   ├── metadata.en.yml
│   │   └── metadata.es.yml
│   ├── batch-processor/    # Type: mcp-server
│   │   ├── metadata.en.yml
│   │   └── metadata.es.yml
│   ├── stream-processor/   # Type: mcp-server
│   │   ├── metadata.en.yml
│   │   └── metadata.es.yml
│   ├── model-trainer/      # Type: mcp-server
│   │   ├── metadata.en.yml
│   │   └── metadata.es.yml
│   └── model-inference/    # Type: mcp-server
│       ├── metadata.en.yml
│       └── metadata.es.yml
├── analytics/             # Type: group
│   ├── metadata.en.yml
│   ├── metadata.es.yml
│   ├── reporting-tool/    # Type: mcp-server
│   │   ├── metadata.en.yml
│   │   └── metadata.es.yml
│   └── dashboard-builder/ # Type: mcp-server
│       ├── metadata.en.yml
│       └── metadata.es.yml
└── starter-kit/          # Type: package
    ├── metadata.en.yml
    └── metadata.es.yml

# data-engineering/en/metadata.yml
name: "Data Engineering"
type: "group"
tags: ["data-engineering"]

4. Localized Community Tools

Repository with multilingual support, using language-specific metadata:

community-tools/
└── web-dev-toolkit/        # Type: package
    ├── metadata.en.yml     # English metadata
    ├── metadata.es.yml     # Spanish metadata
    ├── metadata.fr.yml     # French metadata
    ├── code-formatter/     # Type: mcp-server
    │   ├── metadata.en.yml
    │   ├── metadata.es.yml
    │   ├── metadata.fr.yml
    │   └── server.js
    └── web-role/           # Type: role
        ├── metadata.en.yml
        ├── metadata.es.yml
        ├── metadata.fr.yml
        └── role.md

# web-dev-toolkit/metadata.en.yml
name: "Web Development Toolkit"
description: "Complete toolkit for web development"
version: "1.0.0"
type: "package"

# web-dev-toolkit/metadata.es.yml
name: "Herramientas de Desarrollo Web"
description: "Kit de herramientas completo para desarrollo web"
version: "1.0.0"
type: "package"

Note: Components (code-formatter and web-role) are automatically discovered by scanning subdirectories and reading their metadata files.

# web-dev-toolkit/code-formatter/metadata.es.yml
name: "Formateador de Código"
description: "Herramienta de formateo de código"
version: "1.0.0"
type: "mcp-server"

This structure:

• Places all metadata in language-specific folders
• Uses 'en' as the fallback locale
• Components without 'en' metadata are not displayed
• Supports independent translation management
• Simplifies locale resolution logic

5. Evolution Example: From Simple to Complex

Stage 1: Simple Single Component

code-formatter/
└── metadata.en.yml

# metadata.en.yml
name: "Simple Code Formatter"
description: "Basic code formatting tool"
version: "1.0.0"
type: "mcp-server"

Stage 2: Basic Package with Local Components

code-formatter-plus/
├── metadata.en.yml      # Basic package metadata
├── formatter/
│   ├── metadata.en.yml  # MCP server metadata
│   └── server.js
└── git-memory/
    ├── metadata.en.yml  # Memory metadata
    └── memory.js

# metadata.en.yml
name: "Code Formatter Plus"
description: "Enhanced code formatting with git integration"
version: "1.5.0"
type: "package"

Stage 3: Package with External Component

code-quality-suite/
├── metadata.en.yml
├── metadata.es.yml
├── formatter/           # Local component
│   ├── metadata.en.yml
│   ├── metadata.es.yml
│   └── server.js
└── shared-scanner/     # Reference to external component
    └── metadata.yml    # Points to actual component elsewhere

# metadata.en.yml
name: "Code Quality Suite"
description: "Complete code quality toolkit"
version: "2.0.0"
type: "package"
items: # Only needed because we reference an external component
    - type: "mcp-server"
      path: "../security/vulnerability-scanner"

# metadata.es.yml
name: "Suite de Calidad de Código"
description: "Kit de herramientas completo para calidad de código"
version: "2.0.0"
type: "package"

Note: Advanced features like dependencies and configuration can be added later when needed. The basic structure focuses on essential metadata and local components.

[Previous sections unchanged]