VCS Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Version Control System (VCS) Integration in MCB provides repository-level context, branch comparison, and impact analysis for AI coding agents. It is built as a core protocol family within the Memory Context Browser, enabling tools to interact with Git repositories, track changes, and analyze the impact of code modifications. The integration follows a Clean Architecture pattern, separating domain entities and port traits from concrete implementations using libgit2.
Sources: README.md:14-14, README.md:92-92, crates/mcb-providers/src/vcs/git.rs:13-28
Architecture and Components
The VCS module is structured into three primary layers: the Service/Handler layer (MCP tools), the Domain layer (Entities and Ports), and the Provider layer (Concrete Git implementation).
Domain Entities and Ports
The system defines several core entities to represent version control concepts independently of the underlying provider:
- VcsRepository: Represents a local or remote repository with its path, default branch, and remote URL.
- VcsBranch: Represents a specific branch within a repository, including its head commit and upstream status.
- VcsCommit: Encapsulates commit metadata such as hash, author, message, and timestamp.
- RefDiff: Represents the result of a comparison between two references, including file changes and addition/deletion counts.
The VcsProvider trait in mcb-domain defines the interface for repository operations, such as opening repositories, listing branches, and reading files.
Sources: crates/mcb-domain/src/entities/vcs.rs, crates/mcb-providers/src/vcs/git.rs:25-27
Implementation Flow
The following diagram illustrates the flow from an MCP tool request through the VCS handler to the Git provider.
MCP Tools and Actions
MCB exposes several public tools for VCS interaction. These tools are grouped under the vcs operation family and handled by the VcsHandler.
Supported VCS Actions
| Action | Description | Key Parameters |
|---|---|---|
ListRepositories | Scans a directory for Git repositories. | repo_path, limit |
IndexRepository | Gathers metadata and history for a repository. | repo_path, depth, include_commits |
CompareBranches | Generates a diff between two branches. | base_branch, target_branch |
AnalyzeImpact | Evaluates the effect of changes in specific branches. | branches, depth |
SearchBranch | Finds branches matching a query string. | query |
Sources: crates/mcb-server/src/args/vcs.rs:11-26, crates/mcb-server/src/args/vcs.rs:77-133
VCS Entity CRUD
In addition to operational tools, the VcsEntityHandler manages the lifecycle of persisted VCS records (Repositories, Branches, Worktrees) within the MCB database.
Git Provider Implementation
The GitProvider implementation utilizes libgit2 to perform low-level repository operations. It handles the translation between Git-specific data structures and MCB domain entities.
Key Implementation Details
- Repository Scanning: The provider uses
WalkDirto scan local paths up to a depth of 3 to discover.gitdirectories. - Diffing Logic: Comparisons between branches involve resolving references to trees and calculating deltas using
diff_tree_to_tree. - Commit Parsing: Commits are converted to
VcsCommitentities, extracting author information, timestamps, and parent hashes.
Sources: crates/mcb-providers/src/vcs/git.rs:163-195, crates/mcb-providers/src/vcs/git.rs:348-384, crates/mcb-providers/src/vcs/git.rs:108-121
Data Mapping: Git to Domain
| Git Concept | Domain Entity | Implementation |
|---|---|---|
git2::Repository | VcsRepository | Identified by the hash of the root commit. |
git2::Branch | VcsBranch | Maps local branches and their upstream tracking. |
git2::Commit | VcsCommit | Formats ID as {repo_id}:{oid}. |
git2::Diff | RefDiff | Aggregates additions, deletions, and status. |
Sources: crates/mcb-providers/src/vcs/git.rs:204-222, crates/mcb-providers/src/vcs/git.rs:108-121, crates/mcb-providers/src/vcs/git.rs:145-161
Summary
VCS Integration in MCB provides a unified interface for codebases managed by version control systems. By abstracting Git operations through domain ports and MCP tools, it allows AI agents to perform complex tasks like impact analysis and branch comparison without direct knowledge of filesystem or Git internals. The system ensures data consistency through strictly typed arguments and entity validation while leveraging the performance of the libgit2 library for underlying operations.
Sources: README.md:28-28, crates/mcb-server/src/handlers/vcs/handler.rs:34-56