# 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 ``` ```yaml # simple-tools/metadata.en.yml name: "Simple Tools Collection" description: "Collection of independent development tools" version: "1.0.0" ``` ```yaml # 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 ``` ```yaml # 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: ```yaml # 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 ``` ```yaml # 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 ``` ```yaml # 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 ``` ```yaml # web-dev-toolkit/metadata.en.yml name: "Web Development Toolkit" description: "Complete toolkit for web development" version: "1.0.0" type: "package" ``` ```yaml # 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. ```yaml # 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 ``` ```yaml # 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 ``` ```yaml # 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 ``` ```yaml # 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" ``` ```yaml # 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]