You:    "Analyze this repo -- show me hotspots, risk, and who knows the auth module best."
Claude: [calls hotspots, risk_assessment, knowledge_map in parallel, returns formatted analysis]

graph LR
    A[MCP Client<br/>Claude Code / Codex] <-->|stdio<br/>JSON-RPC| B[mcp-git-intel<br/>MCP Server]
    B -->|execFile| C[Git CLI]
    C --> D[Repository<br/>.git]
    B --> E[Analysis Engine<br/>scoring, formatting]

graph TD
    subgraph "Change Analysis"
        H[hotspots<br/>Change frequency]
        CH[churn<br/>Write/rewrite ratio]
        CT[complexity_trend<br/>Complexity over time]
    end
    subgraph "Dependency Analysis"
        CO[coupling<br/>Temporal coupling]
    end
    subgraph "Team Analysis"
        KM[knowledge_map<br/>Who knows what]
        CS[contributor_stats<br/>Team dynamics]
        CP[commit_patterns<br/>Work patterns]
    end
    subgraph "Risk & Release"
        RA[risk_assessment<br/>Change risk scoring]
        RN[release_notes<br/>Changelog generation]
        BR[branch_risk<br/>Branch health]
    end
    subgraph "Code Archaeology"
        FH[file_history<br/>File evolution]
        CA[code_age<br/>Staleness map]
    end

graph LR
    A["Git CLI<br/>raw output"] -->|parse| B["Structured Data<br/>LogEntry[], stats"]
    B -->|score| C["Scored Results<br/>normalized 0-100"]
    C -->|format| D["Formatted Output<br/>tables, bars, text"]
    D -->|wrap| E["MCP Response<br/>CallToolResult"]

git clone https://github.com/hoangsonww/GitIntel-MCP-Server.git
cd GitIntel-MCP-Server
npm install
npm run build

claude mcp add git-intel -- node /absolute/path/to/mcp-server/dist/index.js

claude mcp add git-intel -- node /absolute/path/to/mcp-server/dist/index.js /path/to/your/repo

{
  "mcpServers": {
    "git-intel": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "git-intel": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "GIT_INTEL_REPO": "/path/to/your/repo"
      }
    }
  }
}

{ "repo_path": "C:/Users/you/other-project", "days": 90 }

flowchart TD
    Start["Server starts"] --> CheckRepo{"Is cwd a\ngit repo?"}
    CheckRepo -->|Yes| Default["Set as default repo\nAll tools work immediately"]
    CheckRepo -->|No| NoDefault["Start with no default\nTools require repo_path"]
    Default --> Ready["Server ready\n12 tools, 2 resources"]
    NoDefault --> Ready
    Ready --> Call{"Tool called"}
    Call --> HasArg{"repo_path\nprovided?"}
    HasArg -->|Yes| UseArg["Use repo_path"]
    HasArg -->|No| HasDefault{"Default repo\navailable?"}
    HasDefault -->|Yes| UseDefault["Use default repo"]
    HasDefault -->|No| Error["Return helpful error:\n'Open Claude Code in a git repo\nor pass repo_path'"]
    UseArg --> Execute["Execute git analysis"]
    UseDefault --> Execute

graph LR
    subgraph "Development"
        Dev["npm run dev<br/>tsx auto-reload"]
        CLI["npm run cli<br/>Interactive REPL"]
    end
    subgraph "Testing"
        Unit["npm test<br/>Vitest unit tests"]
        Smoke["npm run smoke<br/>Full integration"]
    end
    subgraph "Quality"
        Lint["npm run lint<br/>tsc --noEmit"]
        Fmt["npm run format<br/>Prettier"]
    end
    subgraph "Ship"
        Build["npm run build<br/>TypeScript → dist/"]
    end

    Dev --> Unit --> Lint --> Build
    CLI --> Smoke

npm run dev          # Run server with tsx (auto-reload, uses cwd as repo)
npm run cli          # Interactive REPL for testing tools and resources
npm run smoke        # Automated smoke test -- runs every tool and resource
npm test             # Run unit tests (vitest)
npm run test:watch   # Watch mode
npm run lint         # Type check (tsc --noEmit)
npm run build        # Compile TypeScript to dist/

sequenceDiagram
    participant User as Developer
    participant CLI as cli.ts (MCP Client)
    participant Server as index.ts (MCP Server)
    participant Git as Git CLI

    User->>CLI: npm run cli [repo_path]
    CLI->>Server: Spawn via StdioClientTransport
    Server-->>CLI: Connected (JSON-RPC over stdio)
    CLI->>User: git-intel> prompt

    User->>CLI: call hotspots {"days": 60}
    CLI->>Server: callTool("hotspots", {days: 60})
    Server->>Git: git log --since=...
    Git-->>Server: raw output
    Server-->>CLI: formatted analysis
    CLI->>User: Display result + elapsed time

    User->>CLI: read git://repo/summary
    CLI->>Server: readResource("git://repo/summary")
    Server-->>CLI: repo snapshot
    CLI->>User: Display result

    User->>CLI: exit
    CLI->>Server: close()

npm run cli                    # Uses current directory as repo
npm run cli ~/projects/myapp   # Analyze a specific repo

git-intel> tools
  Available tools (12):
  hotspots               Identify files that change most frequently...
                         params: repo_path, days, limit, path_filter
  churn                  Analyze code churn...
                         params: repo_path, days, limit, path_filter
  ...

git-intel> call hotspots {"days": 60, "limit": 5}
  Calling hotspots...
  (42ms)

## Change Hotspots (last 60 days)
File                  Changes  Authors  Last Changed  Heat
--------------------  -------  -------  ------------  ---------------
src/index.ts               12        2    2026-03-08  [██████████] 100
src/tools/risk.ts           8        1    2026-03-07  [██████░░░░] 67
...

git-intel> call knowledge_map {"path": "src/auth"}
  Calling knowledge_map...
  (38ms)

## Knowledge Map: src/auth (last 365 days)
...

git-intel> call risk_assessment
  Calling risk_assessment...
  (125ms)

## Risk Assessment: uncommitted changes
...

git-intel> read git://repo/summary
  Reading git://repo/summary...
  (15ms)

Branch: master
Last commit: c4934239 by dav nguyxn on 2026-03-09
...

git-intel> exit
Bye.

graph LR
    Input["User / AI Input"] --> V1["validatePathFilter()<br/>Blocks .. and abs paths"]
    Input --> V2["validateRef()<br/>Strict char whitelist"]
    V1 --> Safe["Sanitized Args<br/>(string array)"]
    V2 --> Safe
    Safe --> ExecFile["execFile()<br/>No shell involved"]
    ExecFile --> Git["Git CLI<br/>read-only commands only"]
    Git --> Repo[".git<br/>No writes ever"]

    subgraph "Environment Hardening"
        E1["GIT_TERMINAL_PROMPT=0"]
        E2["GIT_PAGER=''"]
        E3["LC_ALL=C"]
        E4["30s timeout"]
        E5["50MB buffer limit"]
    end

    ExecFile -.-> E1 & E2 & E3 & E4 & E5

src/
  index.ts              Entry point, server setup, tool/resource registration (resilient startup)
  cli.ts                Interactive REPL for testing
  smoke-test.ts         Automated smoke test
  git/
    executor.ts         Safe git command runner (execFile, timeouts, env)
    parser.ts           Git output parsers (log, numstat, conventional commits)
    repo.ts             Repo validation, path/ref sanitization
  tools/
    hotspots.ts         Change frequency analysis
    churn.ts            Code churn (additions vs deletions)
    coupling.ts         Temporal coupling detection
    knowledge-map.ts    Knowledge scoring per author
    complexity.ts       Complexity trend over time
    risk.ts             Multi-factor risk assessment
    release-notes.ts    Changelog from conventional commits
    contributors.ts     Contributor analytics and collaboration
    file-history.ts     Single-file evolution with rename tracking
    code-age.ts         File staleness and age distribution
    commit-patterns.ts  Work pattern analytics (time, size)
    branch-risk.ts      Branch staleness and divergence detection
  resources/
    summary.ts          Repository snapshot resource (graceful degradation)
    activity.ts         Recent commit activity feed (graceful degradation)
  util/
    scoring.ts          Normalization, recency decay, coupling, risk scoring
    formatting.ts       Tables, score bars, text output helpers
    resolve-repo.ts     Per-call repo resolution with fallback chain and error messages