Adding New Providers
Relevant source files
The following files were used as context for generating this wiki page:
Adding new providers to the Memory Context Browser (MCB) is a core extension activity that allows the system to support new embedding models, vector databases, or language parsers. The project follows a strict Clean Architecture pattern where the logic for a specific provider is decoupled from the core business logic through "Ports" (traits) and "Adapters" (implementations).
Providers are primarily located in the mcb-providers crate, which implements traits defined in mcb-domain. This structure ensures that the core server (mcb-server) remains agnostic of the underlying technology, whether it be a specific cloud API like OpenAI or a local engine like Ollama.
Sources: README.md:84-95, AGENTS.md:214-220, crates/mcb-providers/src/lib.rs:1-12
Architecture Overview
MCB utilizes a Multi-Provider Architecture that currently supports various categories of technical adapters. Every implementation must reside in the mcb-providers crate and adhere to the dependency flow: mcb-providers -> mcb-domain.
Provider Categories
Providers are grouped into specialized modules within mcb-providers/src/.
| Category | Domain Port (Trait) | Description |
|---|---|---|
| Embedding | EmbeddingProvider | Generates vector embeddings from text (e.g., OpenAI, Ollama). |
| Vector Store | VectorStoreProvider | Stores and retrieves vectors (e.g., Milvus, Qdrant, EdgeVec). |
| Language | LanguageChunkingProvider | Handles AST-aware code parsing and chunking. |
| Hybrid Search | HybridSearchProvider | Combines semantic and keyword-based search. |
| VCS | N/A | Handles Git repository operations and submodule discovery. |
Sources: crates/mcb-providers/src/lib.rs:14-25, AGENTS.md:214-220
Dependency Flow and Registration
MCB uses the linkme crate for distributed slices, allowing for zero-runtime-overhead provider registration. This means implementations can be "discovered" at compile time without hardcoding them into a central registry.
The diagram shows how a provider implementation in the mcb-providers crate fulfills a contract defined in mcb-domain and is wired through mcb-infrastructure.
Sources: README.md:92-95, AGENTS.md:209-220, crates/mcb-providers/src/lib.rs:43-46
Implementation Steps
1. Define or Reference the Port
Before implementing a new provider, ensure the corresponding trait exists in mcb-domain. For example, a new embedding provider must implement the EmbeddingProvider trait.
Sources: crates/mcb-providers/src/lib.rs:6-12
2. Create the Adapter Implementation
Create a new module in crates/mcb-providers/src/ under the appropriate category (e.g., embedding/my_provider.rs).
- Traits: Use
#[async_trait]as most provider operations are I/O bound. - Errors: Use the
Errorconstructors andResultaliases frommcb-domain.
Sources: crates/mcb-providers/Cargo.toml:44-50, AGENTS.md:280-285
3. Manage Dependencies
Add necessary third-party libraries to crates/mcb-providers/Cargo.toml. The project prefers workspace-level dependency management.
[dependencies]
# Example: Adding a new client for a specific API
new-provider-sdk = { workspace = true, optional = true }
[features]
# Add a feature flag for the new provider
embedding-new-provider = ["dep:new-provider-sdk"]
Sources: crates/mcb-providers/Cargo.toml:110-125, Cargo.toml:130-150
4. Registration and DI Wiring
Use the project's macro-based registration system. MCB uses centralized macros for provider implementations to handle linkme registration.
Sources: crates/mcb-providers/src/lib.rs:31-33, AGENTS.md:215-218
Configuration and Runtime Selection
Providers are selected at runtime based on the application configuration, typically defined in YAML files (config/development.yaml, config/production.yaml).
Configuration Logic
The mcb-infrastructure layer handles the deserialization of configuration into AppConfig. The ConfigProvider validates these settings to ensure that required keys (like API keys) are present for the selected provider.
This sequence illustrates how the system transitions from a YAML configuration entry to a functional provider instance.
Sources: crates/mcb-infrastructure/tests/integration/config/strict_config_tests.rs:90-110, AGENTS.md:228-235
Configuration Example
When adding a new provider, you must update the settings block in the YAML profiles.
| Field | Type | Description |
|---|---|---|
EMBEDDING_PROVIDER | String | Key name for the provider (e.g., openai, ollama). |
*_API_KEY | String | (Optional) Sensitive key for cloud-based providers. |
*_BASE_URL | String | (Optional) Custom endpoint for local providers like Ollama. |
Sources: README.md:43-55, crates/mcb-infrastructure/tests/integration/config/strict_config_tests.rs:25-45
Validation and Quality Gates
All new providers must pass the architecture and quality gates enforced by mcb-validate.
- No Direct Env Access: Providers must not read environment variables directly. They must receive configuration through the DI container.
- Error Handling: Providers must never use
unwrap()orexpect()in production code paths. Use?for propagation. - Surgical Edits: Edits should be scoped and utilize existing macros like
tool_action!if the provider exposes new functionality to the MCP protocol.
Sources: crates/mcb-infrastructure/tests/integration/config/strict_config_tests.rs:135-150, AGENTS.md:280-290, CONVENTIONS.md:12-20
Conclusion
The Multi-Provider Architecture of MCB is designed for high extensibility while maintaining the integrity of the core system. By defining contracts in the domain layer and implementing them as adapters in the provider layer, developers can integrate diverse technologies—from local ML models to enterprise cloud databases—without modifying the fundamental MCP server logic.
Sources: README.md:14-16, crates/mcb-providers/src/lib.rs:1-12