git_analysis MCP Tool Specification

16 tools in category git_analysis. All return {"status": "success", ...} on success or {"status": "error", "message": "<message>"} on failure.

---

GitNexus Tools (structural code analysis — requires Node.js/npx)

git_analysis_index_repo

Index a repository with GitNexus. Creates .gitnexus/ knowledge graph. Must be called before query/context/impact tools.

Parameters:

Name	Type	Required	Description
repo_path	str	Yes	Absolute or relative path to the git repository

Returns on success:

{
  "status": "success",
  "repo_path": "/path/to/repo",
  "result": {"stdout": "...", "stderr": "...", "indexed": true}
}

---

git_analysis_query

Hybrid BM25 + semantic search over the GitNexus knowledge graph.

Parameters:

Name	Type	Required	Default	Description
repo_path	str	Yes	—	Path to the indexed repository
query_text	str	Yes	—	Natural language or symbol name to search
limit	int	No	10	Maximum number of results

Returns on success:

{
  "status": "success",
  "query": "authentication module",
  "results": { ... }
}

---

git_analysis_symbol_context

360-degree symbol analysis: all incoming and outgoing dependencies.

Parameters:

Name	Type	Required	Description
repo_path	str	Yes	Path to the indexed repository
symbol	str	Yes	Fully-qualified symbol (e.g., "MyClass.my_method")

Returns on success:

{
  "status": "success",
  "symbol": "GitHistoryAnalyzer",
  "context": { "incoming": [...], "outgoing": [...] }
}

---

git_analysis_impact

Blast-radius assessment: all symbols transitively affected by changing symbol.

Parameters:

Name	Type	Required	Description
repo_path	str	Yes	Path to the indexed repository
symbol	str	Yes	Symbol to assess blast radius for

Returns on success:

{
  "status": "success",
  "symbol": "GitHistoryAnalyzer",
  "impact": { "affected": [...], "confidence": 0.87 }
}

---

git_analysis_detect_changes

Map a git diff to architectural impact using the knowledge graph.

Parameters:

Name	Type	Required	Default	Description
repo_path	str	Yes	—	Path to the indexed repository
diff	str	No	null	Unified diff string. Uses HEAD diff if null

Returns on success:

{
  "status": "success",
  "impact": { "modules_affected": [...], "symbols_changed": [...] }
}

---

git_analysis_cypher_query

Execute a raw Cypher query against the KuzuDB knowledge graph.

Parameters:

Name	Type	Required	Description
repo_path	str	Yes	Path to the indexed repository
cypher_query	str	Yes	Cypher query string (KuzuDB dialect)

Returns on success:

{
  "status": "success",
  "query": "MATCH (n:Function) RETURN n.name LIMIT 10",
  "result": { "rows": [...] }
}

---

git_analysis_list_indexed

List all repositories in the global ~/.gitnexus registry.

Parameters: None

Returns on success:

{
  "status": "success",
  "repos": [{"name": "codomyrmex", "path": "/path/to/repo"}],
  "count": 1
}

---

GitPython Tools (git history analysis — always available)

git_analysis_commit_history

Detailed commit history with per-commit statistics.

Parameters:

Name	Type	Required	Default	Description
repo_path	str	No	"."	Path to the git repository
max_count	int	No	50	Maximum commits to return
branch	`str \	null`	No	null Branch to walk (default: active branch)

Returns on success:

{
  "status": "success",
  "count": 50,
  "commits": [
    {
      "sha": "b81e9dabeae1",
      "author": "Daniel Ari Friedman",
      "email": "daniel@example.com",
      "date": "2026-02-24T07:16:25-08:00",
      "message": "fix: replace flaky PDF test with SVG",
      "insertions": 42,
      "deletions": 18,
      "files_changed": 5
    }
  ]
}

---

git_analysis_contributor_stats

Per-author aggregate statistics across all commits.

Parameters:

Name	Type	Required	Default	Description
repo_path	str	No	"."	Path to the git repository

Returns on success:

{
  "status": "success",
  "count": 4,
  "contributors": [
    {
      "author": "Daniel Ari Friedman",
      "commits": 124,
      "insertions": 4704311,
      "deletions": 4013172,
      "first_commit": "2025-05-16T09:36:36-07:00",
      "last_commit": "2026-02-12T16:37:30-08:00"
    }
  ]
}

---

git_analysis_code_churn

Top N most-frequently-changed files.

Parameters:

Name	Type	Required	Default	Description
repo_path	str	No	"."	Path to the git repository
top_n	int	No	20	Number of top-churned files

Returns on success:

{
  "status": "success",
  "count": 20,
  "files": [
    {"file": "README.md", "change_count": 58},
    {"file": "TO-DO.md", "change_count": 46}
  ]
}

---

git_analysis_branch_topology

Branch names, tip commits, and active branch.

Parameters:

Name	Type	Required	Default	Description
repo_path	str	No	"."	Path to the git repository

Returns on success:

{
  "status": "success",
  "active_branch": "main",
  "branch_count": 2,
  "branches": [
    {
      "name": "main",
      "tip_sha": "b81e9dabeae1",
      "tip_message": "fix: replace flaky PDF test with SVG",
      "tip_date": "2026-02-24T07:16:25-08:00"
    }
  ]
}

---

git_analysis_commit_frequency

Commit counts bucketed by time period.

Parameters:

Name	Type	Required	Default	Description
repo_path	str	No	"."	Path to the git repository
by	str	No	"week"	Bucket: "day" (YYYY-MM-DD), "week" (YYYY-WNN), "month" (YYYY-MM)

Returns on success:

{
  "status": "success",
  "bucket": "month",
  "frequency": {
    "2025-05": 6,
    "2026-02": 144
  }
}

---

git_analysis_filtered_history

Filtered commit history with optional date range, author, and branch constraints.

Parameters:

Name	Type	Required	Default	Description
repo_path	str	No	"."	Path to the git repository
max_count	int	No	50	Maximum commits to return
since	`str \	null`	No	null ISO-8601 date — only commits after this date
until	`str \	null`	No	null ISO-8601 date — only commits before this date
author	`str \	null`	No	null Author name substring filter (case-insensitive)
branch	`str \	null`	No	null Branch to walk (default: active branch)

Returns on success: Same shape as git_analysis_commit_history.

{
  "status": "success",
  "count": 12,
  "commits": [{ "sha": "...", "author": "...", "date": "...", "message": "..." }]
}

---

git_analysis_file_history

All commits that touched a specific file path.

Parameters:

Name	Type	Required	Default	Description
repo_path	str	No	"."	Path to the git repository
file_path	str	Yes	—	Relative path to the file within the repository
max_count	int	No	50	Maximum commits to return

Returns on success:

{
  "status": "success",
  "file": "src/codomyrmex/git_analysis/mcp_tools.py",
  "count": 8,
  "commits": [{ "sha": "...", "author": "...", "date": "...", "message": "..." }]
}

---

git_analysis_directory_churn

Commit frequency aggregated by top-level directory. Identifies which modules have the most git activity.

Parameters:

Name	Type	Required	Default	Description
repo_path	str	No	"."	Path to the git repository
top_n	int	No	10	Number of top directories to return

Returns on success:

{
  "status": "success",
  "count": 10,
  "directories": [
    {"directory": "src", "change_count": 312, "files": 87}
  ]
}

---

git_analysis_hotspots

Hotspot analysis combining churn frequency with recency. Score = change_count / (1 + days_since_last_change / 30). High-score files are both frequently changed and recently touched.

Parameters:

Name	Type	Required	Default	Description
repo_path	str	No	"."	Path to the git repository
top_n	int	No	20	Number of top hotspot files to return

Returns on success:

{
  "status": "success",
  "count": 20,
  "hotspots": [
    {
      "file": "README.md",
      "change_count": 58,
      "last_changed": "2026-02-24T07:16:25",
      "hotspot_score": 55.2
    }
  ]
}