Ctx Git¶

ctx_git — Git version control MCP component (25 ops)

Cluster: Context & Retrieval | Type: component | MCP Tools: 26

Overview¶

Git version control MCP component providing 25 programmatic git operations via GitPython, with every call audit-logged to a SQLite store. This is a DevOps/SCM adapter, not a passive context/retrieval component. Operations span repository lifecycle (init, clone, status, repo_info), staging (add, diff, reset_staged), commits (commit, log, show, blame), branches (create, delete, switch, merge), remotes (fetch, pull, push), stashes, and tags.

When to use:

Automating git workflows from inside an agent or pipeline without shelling out
Logging every git operation to SQLite for compliance or rollback audit trails
Integrating version-controlled artefact management into a CI/CD or deploy flow

Safety defaults: force branch deletion and force push require safety_confirm=True. Branch switch, merge, pull, and stash pop refuse dirty worktrees unless allow_dirty_worktree=True is set after reviewing status. Production-mode calls require an intentional reviewer_signature acknowledgement.

Reliability envelope: handler failures surface completion_state, warning_card, evidence, stable G6_E_GIT_* codes, and available_with instructions. Safety refusals are blocked; invalid repositories and command failures are failed.

Capability discovery: repo_info is read-only and includes live capability metadata: GitPython availability, git executable/version, repo validity, branch/HEAD, remotes, dirty state, safety-gated ops, audit limitations, and advisory log-rerank mode. Remote auth/network state is intentionally reported as unknown unless a remote op is attempted.

Remote limitations: fetch, pull, and push classify common auth, network, branch protection, non-fast-forward, and host-policy failures. Provider-specific hosted Git behavior still depends on the remote service and configured credentials.

Example:

from mvp.ctx_git import CtxGitMCPBlock, GitMCPInput

block = CtxGitMCPBlock(name="git", db_path=":memory:")
result = block.infer(GitMCPInput(op="status", repo_path="."))
# result.value.status_summary → {"modified": [...], "untracked": [...]}

Works well with: csf, workspace_manager, meta_programming

Public API¶

`CommitRerankDecision`¶

Validated advisory rerank verdict over a returned commit set.

Field	Type	Default
`ordered_indices`	`tuple[int, ...]`	required
`dropped_indices`	`tuple[int, ...]`	()
`rationale`	`str`	''
`eligible_fingerprint`	`str`	''
`confidence`	`float`	0.0
`degraded`	`bool`	False
`raw_response`	`str`	''

`LLMCommitRerankRuntime`¶

Provider-neutral commit-rerank runtime backed by G6's LLM caller.

Constructor:

Parameter	Type	Default
`llm`	`LLMCaller \\| None`	None

Methods:

`rerank(query: str, commits: list[Any]) -> CommitRerankDecision`¶

`CtxGitRerankPatternRuntime`¶

Stateless, load-bearing returned-set-ceiling enforcement.

Methods:

`enforce_eligibility(decision: CommitRerankDecision, commits: list[Any]) -> tuple[list[Any], bool, bool]`¶

`CtxGitPlanner`¶

Runtime-first advisory commit-rerank facade with returned-order fallback.

Constructor:

Parameter	Type	Default
`runtime`	`CommitRerankRuntime \\| None`	None
`pattern_runtime`	`CtxGitRerankPatternRuntime \\| None`	None

Methods:

`rerank(query: str, commits: list[Any]) -> list[Any]`¶

`CtxGitMCPBlock(AIBlock[GitMCPInput, GitMCPOutput, dict])`¶

25-op git MCP block with SQLite audit logging.

Field	Type	Default
`name`	`str`	'ctx_git_mcp'
`state`	`dict`	field(default_factory=dict)
`db_path`	`str`	field(default_factory=lambda: os.environ.get('GIT_MCP_DB_PATH', ':memory:'))
`resource_bounds`	`ResourceBounds`	field(default_factory=ResourceBounds)
`usage`	`ResourceUsage`	field(default_factory=ResourceUsage)
`agentic_planner`	`CtxGitPlanner \\| None`	None

Methods:

`infer(data: GitMCPInput) -> Result[GitMCPOutput]`¶

`GitMCPInput(BaseModel)`¶

Input to CtxGitMCPBlock — 25 ops.

Field	Type	Default
`op`	`Literal['init', 'clone', 'status', 'repo_info', 'add', 'reset_staged', 'diff', 'commit', 'log', 'show', 'blame', 'branch_list', 'branch_create', 'branch_delete', 'branch_switch', 'merge', 'remote_list', 'fetch', 'pull', 'push', 'stash_save', 'stash_pop', 'stash_list', 'tag_create', 'tag_list', 'list_patterns']`	required
`repo_path`	`str`	''
`url`	`str`	''
`dest_path`	`str`	''
`file_paths`	`list[str]`	Field(default_factory=list)
`all_files`	`bool`	False
`cached`	`bool`	False
`target`	`str`	''
`message`	`str`	''
`author_name`	`str`	''
`author_email`	`str`	''
`commit_sha`	`str`	''
`n`	`int`	10
`file_path`	`str`	''
`branch`	`str`	''
`source_branch`	`str`	''
`remote`	`str`	'origin'
`force`	`bool`	False
`set_upstream`	`bool`	False
`safety_confirm`	`bool`	False
`allow_dirty_worktree`	`bool`	False
`stash_index`	`int`	0
`tag_name`	`str`	''
`tag_message`	`str`	''
`agentic_rerank`	`bool \\| None`	None
`query`	`str`	''
`run_mode`	`Literal['beta', 'production']`	'beta'
`reviewer_signature`	`str`	''

`GitMCPOutput(BaseModel)`¶

Output from CtxGitMCPBlock.

Field	Type	Default
`op`	`str`	required
`message`	`str`	''
`records`	`list[dict]`	Field(default_factory=list)
`count`	`int`	0
`found`	`bool`	False
`commit_sha`	`str`	''
`diff_text`	`str`	''
`status_summary`	`dict`	Field(default_factory=dict)
`metadata`	`dict`	Field(default_factory=dict)
`degraded`	`bool`	False
`degradation_reason`	`str`	''
`available_with`	`str`	''
`completion_state`	`Literal['verified', 'qualified-draft', 'blocked-escalated']`	'qualified-draft'
`warning_card`	`dict`	Field(default_factory=dict)
`evidence`	`dict`	Field(default_factory=dict)
`request_id`	`str`	''
`task_id`	`str`	''
`run_id`	`str`	''
`agentic_evidence`	`dict`	Field(default_factory=dict)

`GitStore`¶

SQLite-backed audit store for the ctx_git MCP sub-package.

Constructor:

Parameter	Type	Default
`db_path`	`str`	':memory:'

Methods:

`log_operation(op: str, repo_path: str = '', success: bool = True, detail: str = '') -> None`¶

`log_commit(repo_path: str, commit_sha: str, message: str, author: str = '') -> None`¶

`log_branch_event(repo_path: str, branch: str, event: str) -> None`¶

`log_stash_event(repo_path: str, event: str, message: str = '') -> None`¶

`log_error(op: str, error_message: str, repo_path: str = '') -> None`¶

`count_all() -> dict[str, int]`¶

Functions¶

`agentic_planner_enabled(default_enabled: bool) -> bool`¶

Decide whether the agentic commit-rerank planner should be used.

`validate_commit_rerank_decision(decision: CommitRerankDecision, n_eligible: int, expected_fingerprint: str) -> None`¶

Returned-set / anti-injection guard for a commit-rerank decision.

`applied_agentic_patterns() -> list[dict[str, Any]]`¶

Return compact metadata for ctx_git-applied vendored patterns.

`get_skill_catalog() -> CtxGitSkillCatalog`¶

MCP Tools¶

Operation	Source
`init`	git_mcp
`clone`	git_mcp
`status`	git_mcp
`repo_info`	git_mcp
`add`	git_mcp
`reset_staged`	git_mcp
`diff`	git_mcp
`commit`	git_mcp
`log`	git_mcp
`show`	git_mcp
`blame`	git_mcp
`branch_list`	git_mcp
`branch_create`	git_mcp
`branch_delete`	git_mcp
`branch_switch`	git_mcp
`merge`	git_mcp
`remote_list`	git_mcp
`fetch`	git_mcp
`pull`	git_mcp
`push`	git_mcp
`stash_save`	git_mcp
`stash_pop`	git_mcp
`stash_list`	git_mcp
`tag_create`	git_mcp
`tag_list`	git_mcp
`list_patterns`	git_mcp

Ctx Git¶

Overview¶

Public API¶

CommitRerankDecision¶

LLMCommitRerankRuntime¶

rerank(query: str, commits: list[Any]) -> CommitRerankDecision¶

CtxGitRerankPatternRuntime¶

enforce_eligibility(decision: CommitRerankDecision, commits: list[Any]) -> tuple[list[Any], bool, bool]¶

CtxGitPlanner¶

rerank(query: str, commits: list[Any]) -> list[Any]¶

CtxGitMCPBlock(AIBlock[GitMCPInput, GitMCPOutput, dict])¶

infer(data: GitMCPInput) -> Result[GitMCPOutput]¶

GitMCPInput(BaseModel)¶

GitMCPOutput(BaseModel)¶

GitStore¶

log_operation(op: str, repo_path: str = '', success: bool = True, detail: str = '') -> None¶

log_commit(repo_path: str, commit_sha: str, message: str, author: str = '') -> None¶

log_branch_event(repo_path: str, branch: str, event: str) -> None¶

log_stash_event(repo_path: str, event: str, message: str = '') -> None¶

log_error(op: str, error_message: str, repo_path: str = '') -> None¶

count_all() -> dict[str, int]¶

Functions¶

agentic_planner_enabled(default_enabled: bool) -> bool¶

validate_commit_rerank_decision(decision: CommitRerankDecision, n_eligible: int, expected_fingerprint: str) -> None¶

applied_agentic_patterns() -> list[dict[str, Any]]¶

get_skill_catalog() -> CtxGitSkillCatalog¶

MCP Tools¶

`CommitRerankDecision`¶

`LLMCommitRerankRuntime`¶

`rerank(query: str, commits: list[Any]) -> CommitRerankDecision`¶

`CtxGitRerankPatternRuntime`¶

`enforce_eligibility(decision: CommitRerankDecision, commits: list[Any]) -> tuple[list[Any], bool, bool]`¶

`CtxGitPlanner`¶

`rerank(query: str, commits: list[Any]) -> list[Any]`¶

`CtxGitMCPBlock(AIBlock[GitMCPInput, GitMCPOutput, dict])`¶

`infer(data: GitMCPInput) -> Result[GitMCPOutput]`¶

`GitMCPInput(BaseModel)`¶

`GitMCPOutput(BaseModel)`¶

`GitStore`¶

`log_operation(op: str, repo_path: str = '', success: bool = True, detail: str = '') -> None`¶

`log_commit(repo_path: str, commit_sha: str, message: str, author: str = '') -> None`¶

`log_branch_event(repo_path: str, branch: str, event: str) -> None`¶

`log_stash_event(repo_path: str, event: str, message: str = '') -> None`¶

`log_error(op: str, error_message: str, repo_path: str = '') -> None`¶

`count_all() -> dict[str, int]`¶

`agentic_planner_enabled(default_enabled: bool) -> bool`¶

`validate_commit_rerank_decision(decision: CommitRerankDecision, n_eligible: int, expected_fingerprint: str) -> None`¶

`applied_agentic_patterns() -> list[dict[str, Any]]`¶

`get_skill_catalog() -> CtxGitSkillCatalog`¶