Configuration Guide
Relevant source files
The following files were used as context for generating this wiki page:
The MCB (Memory Context Browser) configuration system is a multi-layered architecture designed to manage runtime settings, architecture validation rules, and environment-specific profiles. It utilizes the Loco framework's YAML-based configuration for application settings and a specialized TOML-based system for the mcb-validate engine. The system enforces strict validation to ensure that core infrastructure and security parameters are correctly defined across Development, Test, and Production environments.
Sources: AGENTS.md:214-230, crates/mcb-infrastructure/tests/integration/config/strict_config_tests.rs:104-125
Application Configuration Hierarchy
MCB employs a profile-based configuration strategy using YAML files. The application state is derived from AppConfig, which deserializes settings from the settings: block of the active environment profile.
Configuration Profiles
The system supports three primary execution profiles:
- Development: Uses
config/development.yaml, typically configured with local services like Ollama and SQLite. - Test: Uses
config/test.yaml, featuring dynamic ports and destructive database flags for CI/CD pipelines. - Production: Uses
config/production.yaml, enforcing strict security headers and production-grade providers.
Sources: AGENTS.md:214-222, crates/mcb-infrastructure/tests/integration/config/strict_config_tests.rs:253-259
Data Flow for Application Settings
The following diagram illustrates how the ConfigProvider resolves and validates application settings during startup.
The application enforces deny_unknown_fields during deserialization to prevent configuration drift and typos.
Sources: crates/mcb-infrastructure/tests/integration/config/strict_config_tests.rs:11-20, crates/mcb-infrastructure/tests/integration/config/strict_config_tests.rs:104-115
Architecture Validation Configuration
The mcb-validate module uses a distinct configuration system to enforce Clean Architecture boundaries and code quality standards. This configuration is managed through a hierarchy of TOML files.
Configuration Layers
| Layer | File Path | Description |
|---|---|---|
| Default | config/mcb-validate.toml | Embedded in the binary; provides base rules for all projects. |
| Internal | config/mcb-validate-internal.toml | Project-specific overrides for MCB's internal architecture. |
| Runtime | MCB_VALIDATE__* | Environment variables for ephemeral overrides. |
Sources: config/mcb-validate.toml:1-10, config/mcb-validate-internal.toml:1-5
Core Validation Rulesets
The validation engine categorizes rules into several domains:
- Layer Boundaries: Defines forbidden internal dependencies (e.g.,
mcb-domaincannot depend onmcb-infrastructure). - Code Quality: Sets thresholds for
max_file_lines(default 500) andmax_function_lines(default 50). - SOLID & KISS: Limits complexity by restricting
max_trait_methods,max_match_arms, andmax_function_params. - Naming Conventions: Enforces regex patterns for structs, enums, and variables.
Sources: config/mcb-validate.toml:15-130, config/mcb-validate-internal.toml:10-40
Security and Integrity Constraints
MCB implements strict enforcement checks to prevent configuration bypasses and maintain the "Single Source of Truth" (SSOT).
Prohibited Patterns
The project includes automated integration tests that fail if the following patterns are detected in production code:
- Direct Environment Access: Prohibits reading environment variables (e.g.,
MCB_SESSION_ID) outside the designated config loader. - Hardcoded Fallbacks: Security-sensitive IDs (e.g.,
project_id,org_id) must be detected from the workspace or fail; they cannot have "default" or "unknown" string fallbacks. - Default Config Impls: Operational configuration types are forbidden from implementing the
Defaulttrait; they must be explicitly provided via YAML profiles.
Sources: crates/mcb-infrastructure/tests/integration/config/strict_config_tests.rs:141-165, crates/mcb-infrastructure/tests/integration/config/strict_config_tests.rs:214-250
Configuration Integrity Diagram
The following diagram shows the relationship between the various validation domains within the mcb-validate config.
Web Administration Interface
The MCB server exposes a configuration viewing page via the Admin UI. This interface allows real-time inspection of the active providers and database settings.
Configuration UI Elements
| Component | Source Data | Description |
|---|---|---|
| Embedding Provider | McbState | Displays the active provider name and vector dimensions. |
| Vector Store | admin_config | Shows host, port, and provider type. |
| Database | admin_config | Displays the active URI (e.g., SQLite file path). |
Sources: crates/mcb-server/src/controllers/web/config.rs:40-70, tests/e2e/admin-functional.spec.ts:38-48
Conclusion
Configuration in MCB is a controlled process that prioritizes stability and architectural integrity. By separating runtime application settings (YAML) from static architectural rules (TOML), and backing both with strict integration tests, the system ensures that changes to the environment do not violate the project's Clean Architecture principles. Developers must ensure that all new operational settings are defined in the appropriate YAML profiles and that any new crate dependencies are reflected in the validation configuration.
Sources: AGENTS.md:223-230, crates/mcb-infrastructure/tests/integration/config/strict_config_tests.rs:262-270