Gitintel MCP Server

GitIntel-用于AI代理的Git智能MCP服务器

Git智能MCP服务器 -根据您的提交历史在本地计算的深度存储库分析。

展示与CodeScene和GitPrime等工具相同的见解：热点、时间耦合、知识图、流失分析、复杂性趋势、风险评分等。一切都在本地运行。没有外部API，没有数据离开你的机器。

这是一个 本地构建的MCP服务器它没有发布到npm。您可以克隆、构建并向MCP客户端和AI代理（Claude Code、Codex等）注册它。

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]

______________________________________________________________________

建筑

GitIntel是一个独立的MCP服务器，它提供了一套用于分析git存储库的工具和资源。它使用JSON-RPC通过stdio与任何MCP客户端（Claude Code、Codex等）通信。

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

所有沟通都结束了 标准 使用模型上下文协议。服务器通过以下方式调用Git execFile （从来没有 exec)以防止外壳注射。所有操作都是 严格只读.

______________________________________________________________________

工具

12个分析工具，每个工具都返回格式化的表格、评分条和可操作的建议，而不是原始的git输出。

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

数据管道

每个工具都通过多级管道转换原始git输出：

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

资源

资源是预先计算的摘要或提要，可以在没有参数的情况下直接读取。可用于快速快照或嵌入到提示中。

______________________________________________________________________

安装

此服务器是 未发布到npm。您必须在本地克隆、构建和注册它。

先决条件

• Node.js >= 18
• Git >= 2.20

从源代码构建

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

使用克劳德代码注册

\[！重要\] 重要：为了获得最佳效果，请始终在git存储库目录中打开Claude Code。服务器会自动检测您工作目录中的repo。如果你从非repo文件夹（例如你的主目录）打开Claude Code，你需要传递 repo_path 手动调用每个工具。

快速注册（默认情况下分析cwd）：

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

在任何MCP客户端注册（手动JSON）

添加到MCP客户端的配置文件中（例如。 ~/.claude.json 对于Claude Code全局配置）：

{
  "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"
      }
    }
  }
}

\[！提示\] 小贴士：The ~ 主目录扩展在repo路径参数中起作用（例如。 ~/projects/my-repo). 此外：在全球注册时（在 ~/.claude.json)，服务器会自动检测您当前工作目录中的git repo。不 GIT_INTEL_REPO 需要——只需在任何git仓库中打开Claude Code。

______________________________________________________________________

配置

默认存储库解决方案

服务器决定使用哪个git存储库作为 默认 使用此优先级顺序：

这 ~ 前缀在所有路径输入中都扩展到用户的主目录。

每个工具 repo_path 以（权力）否决

每个工具都接受一个可选 repo_path 参数，用于覆盖该特定调用的默认存储库。这允许在不重新配置服务器的情况下分析磁盘上的任何存储库：

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

弹性启动（无崩溃模式）

服务器 永不崩溃 启动时，即使从非git目录启动。相反：

1. 如果找到git存储库，它将成为所有工具的默认存储库。
2. 如果 无git存储库 如果找到，服务器无论如何都会启动，没有默认的仓库。工具需要 repo_path 参数，指定要分析的仓库。
3. 资源(git://repo/summary, git://repo/activity)返回信息性消息，指导用户在git仓库中打开Claude Code或使用 repo_path.

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

这种设计意味着服务器可以作为 全局MCP服务器 在Claude Code中，无论您打开哪个项目目录，它都会成功连接。

______________________________________________________________________

使用示例

一旦注册，这些工具就可以通过自然语言使用。你不直接调用它们——AI客户端根据你的提示决定调用哪些工具。

查找易出错的文件：

“显示过去60天的更改热点”

分析代码稳定性：

“上个季度src/api目录的流失分析是什么？”

查找隐藏的依赖关系：

“哪些文件在时间上与src/auth/login.ts耦合？”

找到合适的审阅者：

“谁最了解src/api目录？”

跟踪复杂性增长：

“显示src/services/payment.ts的复杂性趋势”

合并前评估变更风险：

“未提交变更的风险评估是什么？” “评估主要分支和特征分支之间发生变化的风险”

生成发行说明：

“生成从v1.0.0到HEAD的发行说明”

了解团队动态：

“显示过去6个月的贡献者统计数据” “谁是顶级合作者，知识孤岛在哪里？”

跟踪文件的演变：

“显示src/auth/login.ts的完整历史记录”

查找过时或废弃的代码：

“src/目录中最旧的文件是什么？” “显示项目的代码年龄分析”

分析工作模式：

“过去3个月的提交模式是什么？” “团队通常什么时候承诺？”

分行卫生：

“哪些树枝已经枯萎或分化严重？” “向我展示主分行风险分析”

完整回购分析：

“使用git intel，对这个存储库进行全面分析”

看 docs/EXAMPLES.md 获取完整回购分析会话的完整真实世界记录。

______________________________________________________________________

发展

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

CLI REPL

交互式CLI(npm run cli)将MCP服务器作为子进程生成，通过stdio作为真正的MCP客户端连接，并提供用于调用工具和读取资源的REPL。

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()

启动CLI：

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.

看 docs/CLI.md 以获取完整的CLI参考。

\[！提示\] 这对于不需要通过AI客户端进行手动测试和调试非常有用。

冒烟测试

npm run smoke 连接到服务器，调用当前仓库中的每个工具和每个资源，打印所有结果。可用于验证更改后没有任何损坏。

______________________________________________________________________

安全模型

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

我们认真对待安全问题。此服务器设计为可以在任何可以访问git存储库的机器上安全运行。以下是针对潜在攻击媒介的关键缓解措施：

______________________________________________________________________

项目结构

代码被组织成清晰的模块，用于git交互、分析工具、资源和实用程序。入口点(index.ts)设置MCP服务器并注册所有工具和资源。

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

______________________________________________________________________

更多文件

此README提供了一个高层次的概述。有关更深入的技术细节，请参阅：

• ARCHITECTURE.md --深层次的技术架构、设计决策、模块依赖性
• docs/TOOLS.md --每个工具的详细参考（模式、示例、解释）
• docs/CLI.md --包含所有命令、参数和示例的完整CLI参考
• docs/EXAMPLES.md --真实世界的使用记录，显示完整的回购分析会话

许可证

MIT。看 许可证 了解详情。

作者