Provides read-only analysis of local Git repository history, enabling queries about file change hotspots, author activity, file history, coupled files, and changelog drafting between refs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@git-insights-mcp which files in myapp change most often?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A read-only Model Context Protocol server that lets an AI client (Claude Code, Claude Desktop, MCP Inspector) ask questions about a local Git repository's history:
"Which files change most often, and where is the risk?"
"Who worked on what in the last three months?"
"Which files usually change together with auth.py?"
"Draft a changelog between v1.2 and v1.3."
The server returns structured data and leaves interpretation to the client. It works on any repository, needs no API keys, and never writes to the repository.
Built with the MCP Python SDK v2 (MCPServer) and
managed with uv.
Tools. All six are read-only, return Pydantic models with an output schema, and report expected failures as tool errors the model can act on:
Tool | Returns |
| Branch, HEAD, commit count, first/last commit date, authors, file extensions |
| Files ranked by change frequency, then churn, in a period (reports progress) |
| Commits and added/deleted lines per author in a period |
| Recent commits that touched a file, with per-commit line counts |
| Files that change in the same commits as a given file, with ratios |
| Commits between two refs grouped by conventional-commit type, plus "other" |
Periods are since / until ISO dates (YYYY-MM-DD), inclusive whole days in UTC.
Resources
URI | Content |
| JSON list of the configured repository aliases |
|
|
Prompts. onboarding, release_notes and risk_review each return a ready-made user
message telling the client which tools to call and what to write from the results.
Related MCP server: Code Time Machine MCP Server
You need uv and git. Repositories
are configured as alias=path pairs in GIT_INSIGHTS_REPOS; tools take the alias, never a path.
Try it straight from GitHub:
GIT_INSIGHTS_REPOS="myapp=$HOME/code/myapp" \
uvx --from git+https://github.com/andriilazor/git-insights-mcp git-insights-mcp --helpclaude mcp add git-insights \
-e GIT_INSIGHTS_REPOS="myapp=$HOME/code/myapp" \
-- uvx --from git+https://github.com/andriilazor/git-insights-mcp git-insights-mcpThen ask, for example: "Using git-insights, which files in myapp change most often?"
Add to claude_desktop_config.json (Settings → Developer → Edit Config) and restart:
{
"mcpServers": {
"git-insights": {
"command": "uvx",
"args": ["--from", "git+https://github.com/andriilazor/git-insights-mcp", "git-insights-mcp"],
"env": {
"GIT_INSIGHTS_REPOS": "myapp=/Users/you/code/myapp,lib=/Users/you/code/lib"
}
}
}
}Claude Desktop does not use your shell's PATH. If it cannot find uvx, use the full path
from which uvx.
From a clone of this repository (Node.js required):
npx @modelcontextprotocol/inspector -e GIT_INSIGHTS_REPOS="self=$PWD" \
uv --directory "$PWD" run git-insights-mcpThe Inspector does not pass your shell environment to the server, so set variables with -e.
uv run mcp dev src/git_insights/server.py also opens the Inspector, but because the
environment is not passed through, every call then answers
Server is not configured: GIT_INSIGHTS_REPOS is required.
Over HTTP the server requires a token:
export GIT_INSIGHTS_REPOS="myapp=$HOME/code/myapp"
export GIT_INSIGHTS_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
uvx --from git+https://github.com/andriilazor/git-insights-mcp \
git-insights-mcp --transport streamable-http --host 127.0.0.1 --port 8000The endpoint is http://127.0.0.1:8000/mcp. Requests without Authorization: Bearer <token>
get 401. Connect Claude Code with:
claude mcp add --transport http git-insights http://127.0.0.1:8000/mcp \
-H "Authorization: Bearer $GIT_INSIGHTS_TOKEN"The image is built with uv, runs as a non-root user, and expects repositories mounted read-only:
docker build -t git-insights-mcp .
docker run --rm -p 127.0.0.1:8000:8000 \
-v "$HOME/code/myapp:/repos/myapp:ro" \
-e GIT_INSIGHTS_REPOS=myapp=/repos/myapp \
-e GIT_INSIGHTS_TOKEN="$GIT_INSIGHTS_TOKEN" \
-e GIT_INSIGHTS_ALLOWED_HOSTS=localhost:8000,127.0.0.1:8000 \
git-insights-mcpOr use the compose example: cp .env.example .env, set GIT_INSIGHTS_TOKEN and REPO_PATH,
then run docker compose up --build. CI builds the image on every push, runs it this way and
checks the 401 and an authenticated tools/call over HTTP.
Variable | Default | Purpose |
| required |
|
| (none) | Bearer token, required for |
| (none) | Accepted |
|
| Authorization server advertised to HTTP clients (a stand-in, see below) |
|
| Seconds one git call may run before it is killed |
|
| Largest output one git call may produce |
The SDK v2 no longer reads MCP_* variables, so the server reads its own and passes them on.
Command line: git-insights-mcp [--transport stdio|streamable-http] [--host HOST] [--port PORT].
A real Claude Code session in print mode, connected to this server over stdio, run against this repository on 2026-10-21 when it had 10 commits.
Prompt: Using the git-insights tools on the repository 'git-insights-mcp': which files change most often, which files usually change together with src/git_insights/server.py, and who has worked on the project? Keep the answer short.
Tool calls made by the client:
hotspots {"repo": "git-insights-mcp", "limit": 10}
→ total_commits 10; pyproject.toml 3 commits (churn 58), src/git_insights/server.py 2 (415),
src/git_insights/analysis.py 2 (392), tests/test_analysis.py 2 (259), ...
coupled_files {"repo": "git-insights-mcp", "path": "src/git_insights/server.py", "limit": 10}
→ file_commits 2; pyproject.toml, src/git_insights/__init__.py, src/git_insights/config.py,
src/git_insights/security.py, tests/test_server.py, ... each co_changes 1, ratio 0.5
author_activity {"repo": "git-insights-mcp"}
→ AndriiLazor: 10 commits, +3910 / -25 linesAnswer:
The repo only has 10 commits, so treat these numbers as early signals rather than settled trends.
Files that change most often
pyproject.tomlchanged in 3 commits.
server.py,analysis.py,models.py,security.py,config.py,ci.yml,test_analysis.pyandtest_security.pychanged in 2 commits each.
server.pyhas the most churn (415 lines), followed byanalysis.py(392).Files that change with
src/git_insights/server.pyserver.pyhas only 2 commits. Each of these files changed alongside it in one of them (50%):pyproject.toml,__init__.py,config.py,security.py,tests/__init__.py,test_http_auth.py,test_security.pyandtest_server.py. With so little history, this doesn't show any real coupling yet.Contributors AndriiLazor (email omitted here) is the only author. They made all 10 commits, adding about 3,910 lines and deleting 25.
The hotspots tool. Its form comes from the input schema, and the READ-ONLY and IDEMPOTENT
badges come from the tool annotations:
Structured result, with the progress notification in the corner:
The git-insights://{repo}/summary resource template, read as application/json:
The release_notes prompt:
The server is read-only by design, and its defaults are restrictive:
Repository allowlist. Only repositories in GIT_INSIGHTS_REPOS can be read. Their
paths are resolved once at startup, and tools take the alias. Resource templates take the
alias as well, never a path.
File arguments stay inside the repository. Absolute paths, .., null bytes, leading
- and symlinks that resolve outside the repository are rejected. Paths are always passed
after --.
Refs cannot become options. A ref must be a single revision (branch, tag, hash,
HEAD~3). Anything starting with -, containing .., whitespace or shell
metacharacters is rejected.
Restricted git. Only log, rev-list, show, shortlog and diff in its
--stat/--numstat/--shortstat forms are allowed. Arguments go as a list, never through
a shell. core.fsmonitor is disabled, prompts are off, and optional locks are skipped.
Limits. Every git call has a timeout and an output cap. When a limit is hit, the client gets a tool error asking it to narrow the query, not silently truncated data.
HTTP auth. --transport streamable-http refuses to start without GIT_INSIGHTS_TOKEN.
The token is checked with a constant-time comparison through the SDK's TokenVerifier and
AuthSettings. The SDK requires an issuer_url, and GIT_INSIGHTS_ISSUER_URL is only a
stand-in for a real authorization server: this server never issues tokens and does not
implement OAuth. Put it behind a real identity provider before exposing it beyond your
machine.
DNS rebinding. Localhost binds check Host and Origin automatically. For any other
bind (Docker, remote), set GIT_INSIGHTS_ALLOWED_HOSTS. Without it, the server logs a
warning that Host headers are not checked.
Container. The image runs as uid 10001. Repositories should be mounted :ro, and the
compose example also makes the root filesystem read-only. The image trusts every mounted
directory for git (safe.directory '*'), because mounts belong to another uid.
Logging goes to stderr; stdout is reserved for the stdio protocol.
Configured repositories are trusted: git still honours a repository's own config for read
operations, so only configure repositories you would run git log in yourself.
uv sync # create .venv with runtime and dev dependencies
uv run pytest # unit + end-to-end tests (in-memory client, stdio, HTTP)
uv run ruff check # lint
uv run ruff format # format
uv run mypy # strict type checkingTests build a temporary repository with a hand-checked history (tests/conftest.py), so every
expected number in tests/test_analysis.py can be verified by reading the table there. CI runs
the same commands on Python 3.11, 3.12 and 3.13, plus the Docker smoke test.
src/git_insights/
├── server.py # MCPServer: tools, resources, prompts, result cache, CLI (--transport)
├── git.py # async git runner: subcommand allowlist, timeout, output cap
├── analysis.py # hotspots, coupling, changelog grouping and the other analyses
├── models.py # Pydantic result models
├── security.py # alias resolution, path/ref validation, bearer token verifier
└── config.py # GIT_INSIGHTS_* environment variablesResults are cached in memory, keyed by the commit hashes they depend on, so a new commit never serves stale data. The product requirements and implementation plan are in docs/PRD.md.
Commits and added/deleted lines per author in the period (merge commits excluded), ranked by commits.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository alias, see the git-insights://repos resource | |
| since | No | Start of the period (ISO date, inclusive, UTC); omit for all | |
| until | No | End of the period (ISO date, inclusive, UTC); omit for now |
| Name | Required | Description |
|---|---|---|
| repo | Yes | |
| since | Yes | |
| until | Yes | |
| authors | Yes | Ranked by commits, then changed lines |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the description is free to add the traits it does disclose: merge commits are excluded and results are ranked by commit count. Those are meaningful semantics an agent could not derive from the annotations or schema, though nothing is said about tie-breaking or result-size limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with the resource, scope, exclusion, and ordering front-loaded; every clause carries information and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need no explanation, annotations cover the safety profile, and all three parameters are schema-documented. The only gaps are operational details such as tie-breaking, truncation, and whether authors with zero commits appear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so repo/since/until are fully documented in the schema itself and the description need not repeat them. The description only gestures at 'the period', adding no format or boundary detail beyond what since/until already say.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names the exact resource (per-author commits and added/deleted lines), the scope (in the period), and the output ordering (ranked by commits), plus an explicit exclusion (merge commits). That is far more specific than a bare name, though it never contrasts itself with siblings like repo_summary or hotspots.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to reach for this tool versus the alternatives, no prerequisites, and no note on what happens with an empty period. The 'in the period' phrasing implies a time-boxed contribution report, but the agent must infer that on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Files that change in the same commits as the given file, with how often (co_changes) and the share of the file's commits (ratio). High ratios reveal hidden coupling.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path relative to the repository root | |
| repo | Yes | Repository alias, see the git-insights://repos resource | |
| limit | No | Maximum number of items to return |
| Name | Required | Description |
|---|---|---|
| path | Yes | |
| repo | Yes | |
| coupled | Yes | Ranked by co_changes, then path |
| file_commits | Yes | Non-merge commits that changed the given file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a safe, idempotent, read-only, closed-world operation, so the safety profile is fully covered. The description adds interpretive context (what co_changes/ratio mean and that high ratios signal hidden coupling) but no operational traits like ordering, pagination, or result limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the core purpose and returned fields front-loaded and an interpretive note at the end. Nothing is wasted, though it remains slightly terse given the tool's analytical nuance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a rich annotation set and an output schema present, the description needn't explain return values; it supplies purpose plus result interpretation. It stops short of full completeness only in that it never situates the tool against alternatives.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so repo, path, and limit are already documented, and an output schema exists. The description references the 'given file' but adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (files that co-change in the same commits as a given file) and even names the returned metrics (co_changes, ratio). It does not contrast itself against sibling analysis tools like hotspots or file_history, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use or when-not-to-use guidance and no named alternative among the siblings. The closing line 'High ratios reveal hidden coupling' implies the intended analytical use, but the agent must infer selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Commits in from_ref..to_ref grouped by conventional-commit type (feat, fix, docs, ...), with an 'other' section for subjects that do not follow the convention.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository alias, see the git-insights://repos resource | |
| to_ref | No | Inclusive end: tag, branch or commit | HEAD |
| from_ref | Yes | Exclusive start: tag, branch or commit |
| Name | Required | Description |
|---|---|---|
| repo | Yes | |
| to_ref | Yes | |
| from_ref | Yes | |
| sections | Yes | Non-empty sections in a fixed order |
| total_commits | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds the grouping semantics and the 'other' fallback section, which is genuinely useful output-shaping context, but it says nothing about empty ranges, ordering, or commit-limit behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single efficient sentence with no filler, and the range scope is stated up front before the grouping behavior. It is a fragment without an explicit verb, which slightly weakens the lead.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and 100% schema description coverage, the description need not restate parameter or return details; it complements them with the grouping rule. The only real gap is the absent when-to-use context, which is captured under usage guidelines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains the exclusive start, inclusive end, and the repo alias resource. The description's 'from_ref..to_ref' phrasing reinforces the range but adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the exact resource (commits in from_ref..to_ref) and the transformation applied (grouped by conventional-commit type, with an 'other' bucket), so an agent knows this produces a changelog-style grouping. It is implicitly distinguishable from siblings like repo_summary or hotspots, though it never states outright that it drafts a changelog nor contrasts itself with any sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites (e.g., that the repo alias must exist per the git-insights://repos resource), and no mention of alternatives among repo_summary, hotspots, author_activity, file_history, or coupled_files. The agent must infer usage entirely from the output format.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most recent commits that changed a file, newest first, with the lines each commit added to and deleted from it. Works for deleted files too.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path relative to the repository root | |
| repo | Yes | Repository alias, see the git-insights://repos resource | |
| limit | No | Maximum number of items to return |
| Name | Required | Description |
|---|---|---|
| path | Yes | |
| repo | Yes | |
| commits | Yes | Newest first |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds useful behavioral context beyond those annotations: ordering ('newest first'), per-commit added/deleted line counts, and support for deleted files.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with what the tool returns and how it is ordered. The trailing deleted-file note is a useful, non-redundant edge case, and every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With full schema descriptions, an output schema, and read-only annotations, the description is complete enough for correct invocation. It covers purpose, ordering, return content, and the deleted-file edge case; the only gap is sibling routing, which belongs to usage guidelines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents repo alias, file path, and limit. The description adds no parameter syntax, defaults, or constraints beyond what the schema provides, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource (commits that changed a file) and scope (newest first, with added/deleted lines), plus an edge case (deleted files). It is clearly distinct from repo-wide siblings like repo_summary, hotspots, and author_activity, though it does not explicitly name an alternative to differentiate itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No alternative tool is named and no 'use when' condition is given beyond the implicit file-history query. 'Works for deleted files too' is an edge-case capability, not routing guidance, so the agent gets no explicit when/when-not direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Files ranked by how often they changed in the period, then by churn (added + deleted lines). Frequently changed, high-churn files are where risk and maintenance cost concentrate.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository alias, see the git-insights://repos resource | |
| limit | No | Maximum number of items to return | |
| since | No | Start of the period (ISO date, inclusive, UTC); omit for all | |
| until | No | End of the period (ISO date, inclusive, UTC); omit for now |
| Name | Required | Description |
|---|---|---|
| repo | Yes | |
| since | Yes | |
| until | Yes | |
| hotspots | Yes | Ranked by commits, then churn |
| total_commits | Yes | Non-merge commits in the period |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety and side-effect profile is fully covered without the description. The description adds the conceptual ranking semantics (frequency first, churn tiebreaker), which is useful context but no operational traits such as pagination or limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with no filler; the ranking rule is front-loaded and the rationale follows. Slight redundancy between the sentence about ranking and the rationale, but nothing egregious.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and annotations carry the safety profile. For a read-only ranked-list tool with fully documented parameters, the description is nearly sufficient, missing only explicit sibling differentiation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so repo, limit, since, and until are already documented in the schema. The description references 'the period' but adds no format, default, or range detail beyond the schema, so it meets the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (rank) and resource (files) and gives the ranking criteria: change frequency then added+deleted lines churn. It does not name or distinguish itself from siblings like file_history or coupled_files, so the agent must infer the difference, but the resource and ordering are clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance, no prerequisites, and no named alternative among the siblings. The closing rationale ('where risk and maintenance cost concentrate') hints at analytical intent but is not an operational usage instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Overview of a repository: checked-out branch, commit count, first and last commit dates, authors by commit count, and the file-extension distribution of HEAD.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository alias, see the git-insights://repos resource |
| Name | Required | Description |
|---|---|---|
| head | Yes | Full hash of HEAD |
| repo | Yes | Repository alias |
| branch | Yes | Checked-out branch, or null for a detached HEAD |
| authors | Yes | Authors by commit count, descending |
| file_count | Yes | Files in the HEAD tree |
| commit_count | Yes | |
| last_commit_at | Yes | |
| file_extensions | Yes | Files in HEAD per extension |
| first_commit_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Rich annotations (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false) already carry the safety profile, so the bar is lower. The description adds one genuinely useful behavioral detail, that the branch data reflects the currently checked-out branch and the extension distribution is computed at HEAD, but says nothing about cost, caching, or behavior on large/empty repos.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence, front-loaded with the scope ('Overview of a repository') followed by a tight enumeration of outputs; there is no filler. The field list is slightly long and partly overlaps the output schema, which keeps it just short of a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be spelled out, annotations cover the read-only/idempotent profile, and the single parameter is fully documented in the schema. For a low-complexity one-argument aggregate query, nothing an agent needs in order to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one parameter and schema description coverage is 100%; the schema already explains that 'repo' is a repository alias pointing at the git-insights://repos resource. The description adds no additional parameter meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource ('a repository') and enumerates exactly what is produced: checked-out branch, commit count, first/last commit dates, authors by commit count, and file-extension distribution. This content scope cleanly separates it from the per-author sibling (author_activity) and the per-file/analysis siblings (hotspots, file_history, coupled_files), so an agent can route to it without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description is purely a content inventory; it never says when to reach for this overview versus running author_activity, hotspots, or coupled_files for a narrower question, and it states no prerequisites. Only the implicit 'reach for this when you want a repo-level overview' signal is present, which is minimal guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0author_activitycoupled_filesdraft_changelogfile_historyhotspotsrepo_summaryScored across 6 tools
Each tool targets a distinct analytical dimension: repo_summary (overview), hotspots (file churn ranking), author_activity (per-author stats), file_history (commits for one file), coupled_files (co-change relationships), and draft_changelog (commit categorization). Overlap is minimal; even where author commit counts appear in both repo_summary and author_activity, the scope and depth are clearly different.
All names use consistent snake_case and are highly readable. The slight inconsistency is that most are compound noun phrases (repo_summary, author_activity, file_history, coupled_files) while 'hotspots' is a single word and 'draft_changelog' uses a verb+noun pattern, but the overall style remains predictable.
Six tools is well-scoped for a git insights server, covering the core analytics without redundancy. Each tool earns its place and the count sits comfortably within the typical 3-15 range.
The surface covers repository overview, file risk, author activity, file history, coupling, and changelog generation, which addresses the main insights domain. Minor gaps exist: there is no tool to fetch full details of a single commit (e.g., message and diff) or to search commits by message, but these are workaroundable and not core to the stated purpose.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Generate SBOMs, scan vulnerabilities, and analyze dependencies from local projects or Git repos.
Search indexed code, trace dependencies, assess change impact, and recall repository memory.
Read-only AI coding tools for change verification, release readiness, capacity, and guidance.
