Git Context MCP

1# git-context-mcp
2 
3A **local Model Context Protocol (MCP) server** that provides structured, high-signal insight into a Git repository, enabling AI coding agents to understand **project state, structure, activity, and risk** — without uploading or modifying the codebase.
4 
5> **Note**  
6> This README was generated using `git-context-mcp` itself, by connecting an AI assistant to the repository through the exposed MCP tools.
7 
8---
9 
10## Problem This Project Solves
11 
12AI coding agents (Claude Code, Cursor, Codex, Gemini, etc.) are powerful, but they lack **situational awareness** when working with non-trivial codebases.
13 
14They often struggle to answer questions like:
15- What is the current state of this project?
16- Where are the real entry points?
17- What parts of the code are actively changing?
18- Which files are risky to touch?
19 
20`git-context-mcp` solves this by turning **Git history and repository structure** into **explicit, machine-readable context** that AI agents can consume before writing or reviewing code.
21 
22---
23 
24## What This MCP Does (and Does Not)
25 
26### What it does
27- Runs locally as a standalone MCP process
28- Reads only Git metadata and repository files
29- Exposes read-only analysis tools
30- Works over STDIO (compatible with MCP Inspector and desktop coding agents)
31- Provides high-level context, not raw source dumps
32 
33### What it does not do
34- Does not modify the repository
35- Does not upload code anywhere
36- Does not execute project code
37- Does not depend on external services or APIs
38 
39---
40 
41## Overview
42 
43`git-context-mcp` is a **local-first MCP server** focused on **development context extraction**, not repository manipulation.
44 
45It exposes Git-based analysis tools that help AI coding agents quickly understand:
46- Repository structure and entry points
47- Current working state and sync status
48- Recent development activity and churn
49- Technical debt indicators (TODO / FIXME)
50- Files with elevated maintenance or bug risk
51 
52---
53 
54## Typical Usage Flow
55 
561. **project_status** – understand branch, cleanliness, and sync state  
572. **code_map** – locate entry points and important modules  
583. **recent_activity** – identify active or volatile areas  
594. **work_summary** – understand recent work and open debt  
605. **risk_scan** – flag risky files before editing  
61 
62---
63 
64## Features
65 
66### project_status
67Snapshot of the current Git repository state.
68 
69### code_map
70Structured directory tree with identification of important files.
71 
72### recent_activity
73Analysis of Git history to surface frequently modified files.
74 
75### work_summary
76High-level summary of recent development and technical debt.
77 
78### risk_scan
79Detection of large, complex, or high-churn files.
80 
81---
82 
83## Requirements
84 
85- Python 3.10+
86- Git installed and available on PATH
87- A local Git repository to analyze
88 
89---
90 
91## Installation
92 
93```bash
94git clone https://github.com/TamiShaks-2/git-context-mcp.git
95cd git-context-mcp
96 
97python -m venv .venv
98source .venv/bin/activate   # macOS / Linux
99# or
100.venv\Scripts\activate    # Windows
101 
102pip install -e .
103```
104 
105---
106 
107## Running with MCP Inspector
108 
109Transport Type: STDIO  
110 
111Command:
112```
113<path-to-venv>/python
114```
115 
116Arguments:
117```
118src/server.py
119```
120 
121---
122 
123## Available MCP Tools
124 
125| Tool | Purpose |
126|------|---------|
127| project_status | Repository state awareness |
128| code_map | Structural understanding |
129| recent_activity | Development churn analysis |
130| work_summary | High-level progress overview |
131| risk_scan | Maintenance risk detection |
132 
133All tools operate in read-only mode.
134 
135---
136 
137## Project Structure
138 
139```
140git-context-mcp/
141├── src/
142│   ├── tools/
143│   │   ├── code_map.py
144│   │   ├── git_activity.py
145│   │   ├── git_ops.py
146│   │   ├── project_status.py
147│   │   ├── risk_scan.py
148│   │   └── work_summary.py
149│   └── server.py
150├── tests/
151├── pyproject.toml
152└── README.md
153```
154 
155---
156 
157## Testing
158 
159```bash
160pytest
161```
162 
163---
164 
165## License
166 
167MIT License
168