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., "@repo-pulse-mcp Draft release notes for v0.3.0 from recent commits"
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 gives an AI assistant insight into local git repositories, so it can answer questions like:
"What changed since the last release?"
"Which files change the most? Where is the churn?"
"Which branches look stale, and which are already merged?"
"Draft release notes for v0.3.0."
"Write this week's engineering update."
It runs locally over stdio, needs nothing but Node.js and git, and never modifies a repository.
It is platform-agnostic: it works with any local git repository, whether it was cloned from GitHub, GitLab, Bitbucket or anywhere else, or has no remote at all. It only reads local git history and never contacts a hosting service, so platform data such as pull requests, issues or CI status is out of scope.
A real Claude Code session on vitejs/vite. See how it was recorded.
There are already MCP servers for GitHub, GitLab and git itself, and coding agents with a shell
can run git log directly. repo-pulse does not try to replace them. It does a different job: it
turns local git history into answers and is safe to auto-approve.
repo-pulse | GitHub / GitLab MCP | Generic git MCP / shell | |
Returns | Aggregated insights | Platform API objects | Raw git output |
Can modify anything | No, enforced by an allowlist | Usually yes (token scopes) | Yes |
Needs a token or network | No | Yes | No |
Sees local and unpushed branches | Yes | No | Yes |
Works without a hosting platform | Yes | No | Yes |
Sees pull requests, issues, CI | No | Yes | No |
What that means in practice:
Fewer steps, correct numbers. Questions like "where is the churn?", "what goes into the release notes?" or "which branches are merged and stale?" otherwise take several shell commands and hand-written counting pipelines, which can be silently wrong. repo-pulse does the counting in tested code and returns deterministic JSON that says which filters it applied.
Read-only you can verify. Every tool is annotated readOnlyHint and backed by a git
subcommand allowlist (see Security model), so a client can run it without
asking for approval each time. You would not give the same permission to a shell or to a git
server that can commit and push.
Useful where there is no shell. Chat clients such as Claude Desktop cannot run git. With
repo-pulse, an engineering manager or tech lead can ask about a repository directly.
Works with anything git can open. It works offline and in air-gapped environments, on self-hosted or remote-less repositories, and it never returns author email addresses.
Use it alongside a platform server, not instead of one. Pair it with the GitHub or GitLab MCP
when you also need pull requests, issues or CI status. If you work in a coding agent that already
has a shell and you only need the occasional git log, you probably do not need repo-pulse.
Related MCP server: gitlog-mcp
Claude Code (Sonnet 5.5) answered the same four questions about vite and express twice: once with only a read-only shell and once with only repo-pulse. Full method, answers and caveats are in bench/README.md.
Question | Shell: turns · time · result | repo-pulse: turns · time · result |
Top 10 hotspots, last 90 days | 2 · 6.6 s · ✅ | 2 · 6.5 s · ✅ |
Files coupled to | 2 · 7.4 s · ❌ undercounted | 2 · 8.6 s · ✅ |
Release notes, latest vs previous | 3 · 14.0 s · ✅ | 3 · 12.5 s · ✅ |
Merged branches stale for 90 days | 5 · 15.9 s · ✅ | 2 · 4.3 s · ✅ |
The honest summary: repo-pulse is not cheaper in tokens for simple one-off questions, because a good model writes compact shell pipelines and repo-pulse's tool definitions cost about 2.5k tokens. It wins on multi-step questions, on getting the numbers right, and in clients that have no shell at all.
Kind | Name | What it does |
Tool |
| Commits from the last N days, filterable by author and path |
Tool |
| Search commit messages for text, optionally by window, author and path |
Tool |
| One file's commits with line stats, following it across renames |
Tool |
| Files ranked by how often they changed in a time window |
Tool |
| File pairs that keep changing in the same commits (hidden dependencies) |
Tool |
| Tags newest first, latest release on HEAD and unreleased commit count |
Tool |
| Commits between two refs grouped by conventional-commit type + Markdown |
Tool |
| Ahead/behind counts and commits between two branches, tags or commits |
Tool |
| Branches with no commits for N days, with "already merged" flag |
Tool |
| Commits per author in a time window |
Resource |
| Current branch, last commit, latest tag, commit/branch/tag counts |
Prompt |
| Guides the model to gather data with the tools and write an update |
All tools are annotated readOnlyHint: true, declare an outputSchema, and return both
structuredContent and a JSON text block for older clients.
Node.js 22.12+
git 2.24+ (for --end-of-options)
The package is published on npm, so there is nothing to clone or build. The server only serves
repositories you explicitly allow. Pass them as CLI arguments or an environment variable
(separated by : on macOS/Linux, ; on Windows):
npx -y repo-pulse-mcp --repo ~/code/my-app --repo ~/code/my-lib
# or
REPO_PULSE_REPOS=~/code/my-app:~/code/my-lib npx -y repo-pulse-mcpWithout any configured repository the server refuses to start. It is also listed in the
MCP Registry as io.github.hasanyelaldi/repo-pulse-mcp.
Run this inside the repository you want to ask about:
claude mcp add repo-pulse -- npx -y repo-pulse-mcp --repo "$PWD"Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/,
Windows: %APPDATA%\Claude\) and restart Claude Desktop. Use absolute paths:
{
"mcpServers": {
"repo-pulse": {
"command": "npx",
"args": ["-y", "repo-pulse-mcp", "--repo", "/absolute/path/to/your/repository"]
}
}
}git clone https://github.com/hasanyelaldi/repo-pulse-mcp.git
cd repo-pulse-mcp
npm ci
npm run build
node build/index.js --repo /absolute/path/to/your/repositorypodman build -t repo-pulse-mcp .
podman run -i --rm \
-v "$PWD:/repos/project:ro" \
-e REPO_PULSE_REPOS=/repos/project \
repo-pulse-mcpThe repository is mounted read-only. On SELinux hosts (Fedora, RHEL) add ,Z to the volume
options. Replace podman with docker if you prefer; the image uses no Docker-specific features.
For an MCP client, use podman as the command and the rest as args.
You: What changed since the last release?
Assistant (calls
release_notes_draftwith defaults: latest tag → HEAD): Since v0.2.0 there are 14 commits. One breaking change: the config file moved torepo-pulse.json. New features: an author filter for activity and branch merge detection. Three bug fixes, mostly around empty repositories. Here's a Markdown draft you can paste into the GitHub release: …
You: Where has most of the work happened this quarter? Anything risky?
Assistant (calls
file_hotspotswithdays: 90):src/core/insights.tschanged in 23 commits by 3 people, far more than anything else. That's a good candidate for splitting up or adding tests…
You: Can we clean up some branches?
Assistant (calls
stale_brancheswithdays: 30): 6 branches haven't seen a commit in 30+ days. 4 of them are already merged intomainand are safe to delete: …
You: (selects the
weekly_engineering_updateprompt)Assistant (calls
recent_activity,contributor_summary,file_hotspots,stale_branches): Highlights — …
Every tool accepts an optional repo argument: a repository name (the directory name, shown
in the overview resource) or its absolute path. It defaults to the first configured repository.
recent_activityInput | Type | Default | Notes |
| integer | 7 | 1–3650 |
| string | – | Substring of the author name, matched literally |
| string | – | Repository-relative file or directory |
| integer | 50 | 1–200 |
Output: { repo, windowDays, totalCommits, truncated, commits: [{ hash, shortHash, author, date, subject }] }
commit_searchInput | Type | Default | Notes |
| string | – | Required. Literal, case-insensitive; matches subject + body |
| integer | – | 1–3650. Omit to search the whole history |
| string | – | Substring of the author name, matched literally |
| string | – | Repository-relative file or directory |
| integer | 20 | 1–100 |
Output: { repo, query, windowDays, totalMatches, truncated, commits: [{ hash, shortHash, author, date, subject }] }
file_historyInput | Type | Default | Notes |
| string | – | Required. Repository-relative file, as at HEAD |
| integer | 20 | 1–100 |
Output: { repo, path, commitCount, truncated, renamed, commits: [{ hash, shortHash, author, date, subject, path, additions, deletions }] }
Renames are followed, so older commits report the path the file had at the time and renamed is
true when the listed commits span more than one path. Merge commits are skipped; additions and
deletions are null for binary files.
file_hotspotsInput | Type | Default | Notes |
| integer | 90 | 1–3650 |
| string | – | Restrict to a subtree |
| string[] | – | Up to 20 globs to skip, e.g. |
| integer | 10 | 1–100 |
Output: { repo, windowDays, commitsScanned, scanTruncated, filesChanged, hotspots: [{ path, changes, additions, deletions, authors, lastChanged }] }
Merge commits are excluded and renames are not followed, so a renamed file starts fresh. Use
file_history to trace a single file across renames.
change_couplingInput | Type | Default | Notes |
| integer | 90 | 1–3650 |
| string | – | Only pairs that include this file |
| string | – | Restrict to a subtree |
| string[] | – | Up to 20 globs to skip, same syntax as |
| integer | 2 | Minimum shared commits for a pair to be listed |
| integer | 30 | Commits touching more files are skipped |
| integer | 10 | 1–100 |
Output: { repo, windowDays, commitsScanned, scanTruncated, commitsSkipped, pairCount, pairs: [{ fileA, fileB, sharedCommits, revisionsA, revisionsB, degree }] }
degree is the number of shared commits as a percentage of the average number of commits that
touched each file: 100 means the two files always change together. A high degree between files
that do not import each other usually points to a hidden dependency (duplicated logic, a config
or fixture that must be kept in sync). Large commits such as bulk renames or formatting runs are
skipped because they would couple every file they touch. Merge commits are excluded and renames
are not followed.
list_tagsInput | Type | Default | Notes |
| integer | 20 | 1–200 |
Output: { repo, totalTags, latestOnHead, commitsSinceLatest, tags: [{ name, date, shortHash, subject }] }
Tags are sorted by tag date, newest first. latestOnHead is the latest tag reachable from HEAD,
which can differ from the newest tag when maintenance releases are tagged on other branches.
commitsSinceLatest counts the commits after it, i.e. unreleased work.
release_notes_draftInput | Type | Default | Notes |
| string | latest tag before | Exclusive. Tag, branch or commit hash |
| string |
| Inclusive |
Output: { repo, from, to, commitCount, truncated, sections: [{ key, title, entries: [{ shortHash, scope, description, author }] }], markdown }
Sections, in order: Breaking Changes, Features, Bug Fixes, Performance, Refactoring,
Documentation, Tests, Build System, Continuous Integration, Chores, Reverts, Other Changes.
A commit is breaking if its header has ! (feat!: …) or its body has a BREAKING CHANGE:
footer; breaking commits also appear in their type section. Merge commits are skipped.
compare_refsInput | Type | Default | Notes |
| string | – | Required. Ref to compare against (e.g. |
| string |
| Ref to compare |
| integer | 20 | 1–100, applies to each commit list separately |
Output: { repo, base, head, baseCommit, headCommit, ahead, behind, status, truncated, aheadCommits: [{ hash, shortHash, author, date, subject }], behindCommits: [...] }
ahead counts commits reachable from head but not base, behind the reverse. status is
identical, ahead, behind or diverged. Both refs go through the same validation as
release_notes_draft, and the counts include merge commits.
stale_branchesInput | Type | Default | Notes |
| integer | 30 | Minimum age of the latest commit |
| boolean | false | Also list remote-tracking branches |
| boolean | false | Only branches already merged into |
| integer | 50 | 1–200 |
Output: { repo, thresholdDays, totalBranches, staleCount, branches: [{ name, lastCommitDate, lastAuthor, daysSinceLastCommit, mergedIntoHead }] }
contributor_summaryInput | Type | Default | Notes |
| integer | 30 | 1–3650 |
| boolean | false | Count merges too |
| string | – | Restrict to a subtree |
| integer | 20 | 1–100 |
Output: { repo, windowDays, totalCommits, scanTruncated, contributorCount, contributors: [{ author, commits, firstCommit, lastCommit }] }
repo://{name}/overviewOne resource per configured repository (listed via resources/list, name completion supported):
{
"name": "my-app",
"path": "/home/me/code/my-app",
"currentBranch": "main",
"detachedHead": false,
"lastCommit": { "hash": "…", "shortHash": "1a2b3c4", "author": "…", "date": "…", "subject": "…" },
"latestTag": "v0.2.0",
"commitCount": 412,
"branchCount": 7,
"tagCount": 9
}weekly_engineering_updateArguments (strings, both optional): repo, days (default 7). Produces a user message that
tells the model which tools to call and how to structure a short stakeholder update.
The server is designed so that a confused or manipulated model cannot do damage:
Strictly read-only. git runs through a single function that only allows log, rev-list,
rev-parse, describe and for-each-ref. Anything else is rejected before a process starts.
No shell, ever. git is started with child_process.execFile and an argument array, so
arguments are never interpreted by a shell.
Repository allowlist. Only repositories passed via --repo / REPO_PULSE_REPOS are
served. Paths are canonicalized with realpath (symlinks resolved) at startup and compared
exactly; unknown repositories get the same error whether or not they exist on disk. If nothing
is configured, the server does not start (fail closed).
Input validation. All inputs go through zod schemas with bounds. Refs must look like a
branch, tag, hash or ~N/^N suffix: no leading -, no .. ranges, no @{} or : syntax,
and they are passed after --end-of-options, then resolved with rev-parse --verify. Paths
must be relative without .. segments and are passed after -- with --literal-pathspecs
(no globbing). Author filters use --fixed-strings, so they are not regexes.
Bounded work. Result counts are capped per tool, scans stop at 5,000 commits, git output is capped at 16 MB, and every git call times out after 15 s. Truncation is reported in the output.
Hardened git environment. Inherited GIT_* variables (e.g. GIT_DIR) are dropped,
prompts are disabled, optional locks are off, core.fsmonitor is forced off (a repository's
own config could otherwise make git run a program), and external diff/textconv drivers are
disabled where diffs are computed.
Less personal data. Only author names are returned, never email addresses.
Out of scope: the server trusts the git binary on PATH and the repositories you allowlist.
It is a local developer tool; it has no network transport and no authentication.
src/
├── index.ts # stdio entry point: config → registry → server → transport
├── server.ts # MCP layer: tools, resource and prompt with zod schemas
├── config.ts # --repo / REPO_PULSE_REPOS parsing, repo allowlist (RepoRegistry)
├── errors.ts # InputError (safe to show) and GitError
├── core/
│ ├── insights.ts # one method per feature: builds git args, aggregates results
│ └── release-notes.ts # pure conventional-commit parsing, grouping and Markdown
└── git/
├── runner.ts # the only place that spawns processes (allowlist, limits, env)
├── parsers.ts # pure parsers for git output (no I/O)
└── validation.ts # ref / path / author validationDesign notes:
Process I/O is isolated from parsing. runner.ts is the only module that spawns
processes; parsers.ts and release-notes.ts are pure functions tested with string fixtures.
Unambiguous output format. git output uses ASCII unit (0x1f) and record (0x1e)
separators instead of tabs or newlines, which can appear in commit subjects and file names.
Testable composition. createServer() takes its dependencies (allowlist, git runner,
clock) as arguments, so tests connect it to an in-memory transport with a fixed "now".
Errors become tool results. Validation and git failures surface as isError: true tool
results with an actionable message, so the model can correct itself instead of the session
failing.
stdout is sacred. It carries JSON-RPC, so logging goes to stderr and ESLint forbids
console.log.
Built on the official MCP TypeScript SDK v2 (@modelcontextprotocol/server).
npm ci
npm run dev -- --repo . # run from source with tsx
npm test # unit + integration tests (vitest)
npm run lint # ESLint
npm run format # Prettier
npm run typecheck
npm run build # compile to build/
npm run check # everything CI runs
npm run inspect # build first; opens MCP Inspector against this repositoryReleasing. Bump the version in package.json, server.json (both version fields) and
SERVER_VERSION in src/server.ts (a unit test fails if they differ), merge, then push a tag:
git tag v0.2.0 && git push origin v0.2.0. The release workflow runs the full check, publishes
to npm with provenance and registers the new version in the MCP Registry. Both use GitHub OIDC
(npm Trusted Publishing and the registry's github-oidc login), so no publishing token is
stored. If only the registry step fails, run the workflow manually (gh workflow run release.yml): it skips npm and retries the registry.
Tests. Unit tests cover the parsers, validation, config parsing and release-notes grouping. Integration tests create a temporary git repository with a scripted history (fictional authors, fixed dates) and exercise every feature, both directly and end to end through a real MCP client over an in-memory transport, including the security checks.
MCP Inspector. npm run build && npm run inspect opens the Inspector web UI connected to this
repository. For scripted checks, the CLI mode works too:
npx @modelcontextprotocol/inspector --cli node build/index.js -e REPO_PULSE_REPOS="$PWD" \
--method tools/call --tool-name release_notes_draftActivity, hotspot and contributor tools look at commits reachable from HEAD; work on unmerged
branches is not counted.
Renames are not followed in file_hotspots.
Possible next steps: an HTTP transport for team use, per-directory ownership stats.
Find pairs of files that are often changed in the same commits in the last N days (merge commits excluded), most shared commits first. Reveals hidden dependencies that imports do not show, e.g. code and the config or test it always drags along. Pass "file" to see what usually changes together with one file.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Size of the time window in days. | |
| file | No | Only pairs that include this repository-relative file. | |
| path | No | Restrict to this file or directory. | |
| repo | No | Repository name or absolute path from the allowlist. Defaults to the first configured repo. | |
| limit | No | Maximum number of results (1-100). | |
| exclude | No | Glob patterns for files to leave out, same syntax as in file_hotspots. | |
| minShared | No | Minimum number of shared commits for a pair to be listed. | |
| maxFilesPerCommit | No | Skip commits touching more files than this (bulk renames, formatting). |
| Name | Required | Description |
|---|---|---|
| repo | Yes | Name of the repository that was queried. |
| pairs | Yes | |
| pairCount | Yes | All pairs with at least minShared shared commits. |
| windowDays | Yes | |
| scanTruncated | Yes | |
| commitsScanned | Yes | |
| commitsSkipped | Yes | Commits ignored for touching more than maxFilesPerCommit. |
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 bar is lower. The description usefully adds behavioral context beyond them: merge commits are excluded and results are ordered most-shared-commits-first, which tell the agent how the analysis is computed.
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?
Three tight sentences, front-loaded with the core definition, then the value proposition, then the filter mode. No filler and every sentence 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?
An output schema exists, so return values need not be described, and annotations fully cover the safety profile. Combined with the concept, exclusions, and the file drill-down, the definition gives an agent everything needed to invoke it correctly.
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 every parameter is already documented and the baseline is 3. The description only reinforces the 'file' filter's intent and the shared-commit ordering; it adds little syntax or meaning beyond the schema.
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 verb and resource (find pairs of files changed together in commits) plus a clear scope (last N days, merge commits excluded). The concept of co-change coupling is intrinsically distinguishable from siblings like file_hotspots and file_history, so an agent can route to it without opening any 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?
Gives a concrete rationale for when this is valuable ('reveals hidden dependencies that imports do not show') and explains the drill-down mode ('pass file to see what usually changes together with one file'). It stops short of naming alternatives or stating when NOT to use it versus siblings like file_hotspots.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search commit messages (subject and body) on HEAD for a literal, case-insensitive text, newest first. Useful for finding when and why something changed, e.g. a ticket id, a feature name or "revert". Optionally limited to a time window, author and/or path.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Only search the last N days. Omit to search the whole history. | |
| path | No | Only commits touching this file or directory. | |
| repo | No | Repository name or absolute path from the allowlist. Defaults to the first configured repo. | |
| limit | No | Maximum number of results (1-100). | |
| query | Yes | Text to look for in commit messages. | |
| author | No | Only commits whose author name contains this text. |
| Name | Required | Description |
|---|---|---|
| repo | Yes | Name of the repository that was queried. |
| query | Yes | |
| commits | Yes | |
| truncated | Yes | |
| windowDays | Yes | Null when the whole history was searched. |
| totalMatches | Yes | All matching commits, before applying the limit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior. The description adds genuinely useful behavioral context beyond them: search is HEAD-only (not all branches), matching is literal rather than regex, matching is case-insensitive, and results are ordered newest first. It doesn't mention pagination or large-result behavior, but the HEAD-only constraint is a valuable disclosure.
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 tightly written sentences with zero filler. Scope, match semantics and ordering are front-loaded, and the second sentence covers use cases and optional filters compactly.
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-value explanation is unnecessary. The description covers scope, matching semantics, ordering, usage and the optional filter dimensions, which is sufficient for correct invocation. Minor gaps remain around result-count behavior and multi-repo selection nuance, but the schema covers repo defaults.
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 days, path, repo, limit, query and author are all already documented in the schema. The description only restates that the search can be 'optionally limited to a time window, author and/or path', adding no format or edge-case detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.
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 verb and resource (search commit messages), narrows scope to subject and body on HEAD, and specifies match semantics (literal, case-insensitive) plus result ordering (newest first). That level of detail lets an agent distinguish it from siblings like file_history or recent_activity 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?
Gives concrete usage motivation and examples ('when and why something changed, e.g. a ticket id, a feature name or "revert"'), which tells the agent when this tool is the right pick. It stops short of naming alternatives or stating when not to use it (e.g. vs. file_history for path-scoped history), so it misses the top tier.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare two refs (branches, tags or commits): how many commits "head" is ahead of and behind "base", and which commits those are, newest first. Useful for "how far behind main is my branch?" or "what is on this branch that is not released yet?".
| Name | Required | Description | Default |
|---|---|---|---|
| base | Yes | Ref to compare against, e.g. "main" or a tag. | |
| head | No | Ref to compare, e.g. a branch. | HEAD |
| repo | No | Repository name or absolute path from the allowlist. Defaults to the first configured repo. | |
| limit | No | Maximum number of results (1-100). |
| Name | Required | Description |
|---|---|---|
| base | Yes | |
| head | Yes | |
| repo | Yes | Name of the repository that was queried. |
| ahead | Yes | Commits reachable from head but not from base. |
| behind | Yes | Commits reachable from base but not from head. |
| status | Yes | |
| truncated | Yes | True if either commit list was cut off by the limit. |
| baseCommit | Yes | Full hash that "base" resolved to. |
| headCommit | Yes | Full hash that "head" resolved to. |
| aheadCommits | Yes | Commits only in head, newest first. |
| behindCommits | Yes | Commits only in base, newest first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds ordering semantics ("newest first") and clarifies the directional relationship between head and base, which is genuine value beyond the annotation set.
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 with no filler; the definition of what is returned comes first and the use-case examples follow as illustration. Every clause 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?
An output schema exists, so return-structure detail is not required, yet the description still previews the shape of the answer. For a 4-parameter, fully documented, read-only tool, nothing an agent needs to invoke 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?
Schema coverage is 100%, so baseline is 3, but the description adds directional meaning the schema does not: base is what head is measured against, and head is what is being compared. That resolves ambiguity between two similarly-worded schema fields.
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 verb (compare) and resource (two refs), and immediately defines what the comparison yields: ahead/behind commit counts plus the commit lists. This is clearly distinguished from sibling tools like recent_activity or commit_search.
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?
Provides concrete motivating scenarios ("how far behind main is my branch?", "what is on this branch that is not released yet?"), which sharpens when to reach for it. It does not, however, explicitly name alternatives such as stale_branches or commit_search for the cases it does not cover.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count commits per author on HEAD in the last N days, most active first. Optionally restricted to a path.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Size of the time window in days. | |
| path | No | Restrict to this file or directory. | |
| repo | No | Repository name or absolute path from the allowlist. Defaults to the first configured repo. | |
| limit | No | Maximum number of results (1-100). | |
| includeMerges | No | Count merge commits too. |
| Name | Required | Description |
|---|---|---|
| repo | Yes | Name of the repository that was queried. |
| windowDays | Yes | |
| contributors | Yes | |
| totalCommits | Yes | |
| scanTruncated | Yes | |
| contributorCount | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: the count is scoped to HEAD only and results are sorted most-active-first, though it says nothing about pagination or what happens when the window is empty.
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 zero filler, and the HEAD scope plus ordering are front-loaded where an agent will see them first.
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 needn't be explained, and annotations carry the safety profile. The description supplies the two behavioral facts an agent most needs (HEAD-only, sorted descending); only cross-tool routing guidance is absent.
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 every parameter is already documented in the schema; the baseline is 3. The description only restates days and path semantics (time window, path restriction) without adding format or edge-case detail.
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 verb+resource (count commits per author) with clear scope (on HEAD, last N days) and ordering (most active first). It is distinguishable in kind from siblings like commit_search or file_history, though it does not explicitly name which sibling to prefer.
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 and no mention of alternatives such as recent_activity or commit_search, which could overlap. The optional path restriction is noted but no condition selects this tool over its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the commits on HEAD that changed a single file, newest first, following the file across renames. Each commit includes the path it had then and lines added/removed. Useful for "how did this file evolve?" and "who reworked it, and when?".
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Repository-relative path of a single file, as named at HEAD. | |
| repo | No | Repository name or absolute path from the allowlist. Defaults to the first configured repo. | |
| limit | No | Maximum number of results (1-100). |
| Name | Required | Description |
|---|---|---|
| path | Yes | The requested path, as it is named at HEAD. |
| repo | Yes | Name of the repository that was queried. |
| commits | Yes | |
| renamed | Yes | True if the file had a different path in a listed commit. |
| truncated | Yes | |
| commitCount | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds behavior the annotations cannot: results are HEAD-scoped, newest-first, rename-following, and each entry carries the historical path plus added/removed line counts.
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, no filler: the first front-loads the operation, scope, ordering and rename behavior; the second anchors the use cases. Every clause carries information an agent needs.
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 annotations covering safety, an output schema covering return structure, and a fully documented schema for repo/limit/path, the description only needs to supply scope and rename semantics — which it does. Nothing required 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?
Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value for 'path': although it must be named as at HEAD, the traversal follows renames, clarifying that the parameter is a starting point rather than a strict revision filter.
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 verb and resource ('List the commits on HEAD that changed a single file') plus ordering ('newest first') and a distinctive scope ('following the file across renames'). This clearly separates it from siblings like commit_search (commit-message search) and file_hotspots (aggregate churn ranking) without needing their schemas.
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?
Gives concrete usage contexts via the example questions ('how did this file evolve?', 'who reworked it, and when?'), which tell an agent when this tool is the right pick. It stops short of naming alternatives or exclusions (e.g., 'for repo-wide search use commit_search'), so it is clear context without routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank files by how many commits changed them in the last N days (merge commits excluded). Useful for spotting churn, risky areas and refactoring candidates.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Size of the time window in days. | |
| path | No | Restrict to this file or directory. | |
| repo | No | Repository name or absolute path from the allowlist. Defaults to the first configured repo. | |
| limit | No | Maximum number of results (1-100). | |
| exclude | No | Glob patterns for files to leave out, e.g. ["*.lock", "dist/", "docs/**/*.md"]. A pattern without "/" matches at any depth; a trailing "/" excludes a directory. |
| Name | Required | Description |
|---|---|---|
| repo | Yes | Name of the repository that was queried. |
| hotspots | Yes | |
| windowDays | Yes | |
| filesChanged | Yes | |
| scanTruncated | Yes | |
| commitsScanned | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds a real behavioral trait beyond that: merge commits are excluded from the count, which changes how the ranking should be read.
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 tightly written sentences: the operation and its scope come first, the value proposition second. No filler, no restating the title.
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 described, and annotations carry the safety profile. The description covers the ranking basis and window, though it could note result ordering (descending churn) to be fully self-contained.
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 days, path, repo, limit and exclude are fully documented in the schema. The description only echoes the N-day window and implies filtering, adding no format or semantics beyond the schema.
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 precise verb and resource ('Rank files by how many commits changed them') plus the scoping window and a behavioral detail (merge commits excluded). It is clear what the tool computes, but it never distinguishes itself from close siblings like file_history or change_coupling.
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 second sentence gives motivation ('spotting churn, risky areas and refactoring candidates'), which implies when the tool is useful, but offers no explicit when-not guidance and names no alternative sibling for overlapping tasks such as file_history.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tags (releases) newest first with their date and tagged commit, plus the latest tag reachable from HEAD and how many commits were made since it (unreleased work). Use it to find tag names for release_notes_draft or compare_refs.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Repository name or absolute path from the allowlist. Defaults to the first configured repo. | |
| limit | No | Maximum number of results (1-200). |
| Name | Required | Description |
|---|---|---|
| repo | Yes | Name of the repository that was queried. |
| tags | Yes | |
| totalTags | Yes | |
| latestOnHead | Yes | Latest tag reachable from HEAD (the current release line), or null. |
| commitsSinceLatest | Yes | Commits on HEAD after latestOnHead, i.e. not released yet. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond them: default ordering (newest first), what each entry contains, and the extra HEAD-relative unreleased-work computation. It omits pagination/truncation behavior, so not a full 5.
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 tightly packed sentences with zero filler. The primary output content is front-loaded in sentence one and the usage routing is deferred to sentence two.
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, the description needn't enumerate return fields, and annotations already carry the safety profile. Given that, it covers purpose, output character, and sibling routing completely for a two-parameter, zero-required list tool.
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 and limit are fully documented in the schema, and the description's 'newest first' implicitly justifies the limit parameter's role. The description adds no syntax or format 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 verb and resource ('List tags (releases)') and enumerates the concrete output contents: date, tagged commit, latest tag reachable from HEAD, and unreleased commit count. This is far more specific than the title 'List tags' and lets an agent distinguish it from siblings like recent_activity or commit_search.
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?
Explicitly routes the agent: 'Use it to find tag names for release_notes_draft or compare_refs', naming two alternatives and the condition that selects this tool. It does not state when-not to use it, but the positive routing is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List commits on HEAD from the last N days, newest first. Optionally filter by author (case-sensitive substring of the author name) and/or a repository-relative path.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Size of the time window in days. | |
| path | No | Only commits touching this file or directory. | |
| repo | No | Repository name or absolute path from the allowlist. Defaults to the first configured repo. | |
| limit | No | Maximum number of results (1-200). | |
| author | No | Only commits whose author name contains this text. |
| Name | Required | Description |
|---|---|---|
| repo | Yes | Name of the repository that was queried. |
| commits | Yes | |
| truncated | Yes | |
| windowDays | Yes | |
| totalCommits | Yes | All matching commits in the window, before applying the limit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety burden is lifted. The description adds genuinely useful behavior beyond that: results are scoped to HEAD (not all refs) and returned newest-first, which shapes interpretation of results.
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, zero filler, with the core behavior and ordering front-loaded before the optional filters. Every clause carries information.
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 100%-covered schema, full annotations, and an output schema covering return values, the description is nearly sufficient. Minor gap: with a repo parameter present, 'HEAD' is ambiguous about which repository's HEAD is used when multiple repos are configured.
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 the baseline is 3. The description adds real meaning the schema lacks: author matching is a case-sensitive substring, and path is repository-relative. It says nothing extra about days, limit, or repo beyond what the schema documents.
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 verb (list), resource (commits), scope (on HEAD, last N days), ordering (newest first), and filter dimensions. It's clearly distinguishable from search-oriented siblings like commit_search or file_history, but it never names an alternative, so it falls just short of the top tier.
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?
Usage is implied by the scope: a recent-commits listing for a time window. There is no explicit when-to-use/when-not guidance, no prerequisites, and no routing to sibling tools such as commit_search or contributor_summary, leaving the agent to infer selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Group commits between two refs by conventional-commit type (breaking changes, features, fixes, ...) and return both structured sections and a Markdown draft. "from" defaults to the latest tag before "to"; without any tag, all commits up to "to" are used. To draft notes for an existing release, pass its tag as "to" (see list_tags).
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End ref, inclusive. | HEAD |
| from | No | Start ref, exclusive (tag, branch or commit). | |
| repo | No | Repository name or absolute path from the allowlist. Defaults to the first configured repo. |
| Name | Required | Description |
|---|---|---|
| to | Yes | |
| from | Yes | Start ref (exclusive); null means from the first commit. |
| repo | Yes | Name of the repository that was queried. |
| markdown | Yes | |
| sections | Yes | |
| truncated | Yes | |
| commitCount | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely new behavioral context: the resolution rule for 'from' (latest tag before 'to', or all commits up to 'to' when no tag exists) and the dual structured/Markdown return shape.
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?
Three sentences, front-loaded with the core action and outputs, then defaults, then the tag workflow. Each sentence carries distinct information with no padding.
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 fully spelled out, yet the description still characterizes them. With defaults, tag resolution, and the list_tags cross-reference covered, an agent has everything needed to invoke this correctly.
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 the baseline is 3. The description goes beyond the schema by explaining the derived default of 'from' and the tag-based selection for 'to', which the schema's terse 'Start ref, exclusive' does not convey.
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 verb and resource: groups commits between two refs by conventional-commit type and returns structured sections plus a Markdown draft. This is clearly distinguishable from siblings like compare_refs or commit_search, which do not produce grouped release notes.
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?
Gives concrete context for the common case ('to draft notes for an existing release, pass its tag as "to"') and cross-references list_tags for finding that tag. It does not explicitly say when NOT to use it (e.g., versus compare_refs), so it stops short of full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List branches whose latest commit is at least N days old, oldest first, and whether each is already merged into HEAD.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Size of the time window in days. | |
| repo | No | Repository name or absolute path from the allowlist. Defaults to the first configured repo. | |
| limit | No | Maximum number of results (1-200). | |
| mergedOnly | No | Only list branches already merged into HEAD, i.e. safe cleanup candidates. | |
| includeRemote | No | Also include remote-tracking branches. |
| Name | Required | Description |
|---|---|---|
| repo | Yes | Name of the repository that was queried. |
| branches | Yes | |
| staleCount | Yes | |
| thresholdDays | Yes | |
| totalBranches | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds genuinely useful behavioral context absent from annotations: deterministic ordering (oldest first) and that merge status relative to HEAD is returned per branch.
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 that is fully front-loaded with the verb and resource, then qualifiers. No filler or redundant restatement of the title.
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 full schema coverage plus annotations, the description carries little extra burden and covers the core behavior. It stops just short of explaining filtering interplay (e.g. how mergedOnly and days combine), but nothing essential is missing for correct invocation.
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 all five parameters are already documented in the schema. The description loosely echoes 'N days' and 'merged into HEAD' (days, mergedOnly) but adds no format, default, or range detail beyond what the schema provides. 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 verb (List) and resource (branches) with a precise scope: latest commit at least N days old, ordered oldest first, with per-branch merge status. This is clearly distinguishable from siblings like recent_activity or compare_refs, which do not deal with branch staleness.
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 'oldest first' ordering and merged-into-HEAD detail imply a cleanup/pruning use case, but the description never states when to use this versus alternatives (e.g. compare_refs, recent_activity) or any exclusions. Usage is implied rather than stated.
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.2.0change_couplingcommit_searchcompare_refscontributor_summaryfile_historyfile_hotspotslist_tagsrecent_activityrelease_notes_draftstale_branchesScored across 10 tools
Each tool has a distinct angle: recent_activity (time-windowed commits), commit_search (message text), file_history (single-file evolution), file_hotspots (churn ranking), change_coupling (co-change pairs). There is mild conceptual overlap among the commit-listing tools, but the descriptions clearly scope each one so an agent can select correctly.
All names use snake_case and are readable, but the convention is mixed: some are verb_noun (list_tags, compare_refs) while others are noun phrases (recent_activity, file_hotspots, change_coupling). Predictable enough but not a single consistent pattern.
10 tools is well within the ideal range and each earns its place in the analytics workflow. No obvious redundancy or bloat.
The surface covers commit history, file churn, co-change, tags, release drafting, ref comparison, stale branches, and contributors. Minor gaps like listing all branches (only stale ones) or per-commit diff detail exist, but core repo-pulse workflows are covered.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Git-backed platform for skills, tools, and context for AI agents
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
Generate SBOMs, scan vulnerabilities, and analyze dependencies from local projects or Git repos.
