From 7d246370e0b36482784a19d7aa82929bf210ce97 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Wed, 18 Nov 2026 12:59:42 -0500 Subject: [PATCH] feat(git): say git_log is newest-first and its timestamp filters are optional git_log's description was "Shows the commit logs". A small model asked for the most recent commit passed start_timestamp="now" and end_timestamp="now", got a bare "Commit history:" and concluded the repository had no commits (#5552). The description now says results are newest first and that both timestamps are optional filters to leave out unless a period is asked for, and each timestamp's description says what omitting it means. When a timestamp filter matches no commits, the result names the filter as the cause and says to omit both, instead of an empty history. The tool's name, parameters and schema types are unchanged. Co-Authored-By: Claude Fable 5.2 Signed-off-by: cliffhall --- src/git/README.md | 8 ++-- src/git/src/mcp_server_git/server.py | 29 ++++++++++++-- src/git/tests/snapshots/list_tools.json | 6 +-- src/git/tests/test_protocol.py | 50 ++++++++++++++++++++++++- 4 files changed, 81 insertions(+), 12 deletions(-) diff --git a/src/git/README.md b/src/git/README.md index 95d5a00875..b5d31497b4 100644 --- a/src/git/README.md +++ b/src/git/README.md @@ -63,13 +63,13 @@ Please note that mcp-server-git is currently in early development. The functiona - Returns: Confirmation of reset operation 8. `git_log` - - Shows the commit logs with optional date filtering + - Shows the commit log, newest commit first. With only `repo_path` it returns the latest commits; the two timestamps are optional filters for a date range - Inputs: - `repo_path` (string): Path to Git repository - `max_count` (number, optional): Maximum number of commits to show, at least 1 (default: 10) - - `start_timestamp` (string, optional): Start timestamp for filtering commits. Accepts ISO 8601 format (e.g., '2024-01-15T14:30:25'), relative dates (e.g., '2 weeks ago', 'yesterday'), or absolute dates (e.g., '2024-01-15', 'Jan 15 2024') - - `end_timestamp` (string, optional): End timestamp for filtering commits. Accepts ISO 8601 format (e.g., '2024-01-15T14:30:25'), relative dates (e.g., '2 weeks ago', 'yesterday'), or absolute dates (e.g., '2024-01-15', 'Jan 15 2024') - - Returns: Array of commit entries with hash, author, date, and message + - `start_timestamp` (string, optional): Only show commits at or after this time; omit for no lower bound. Accepts ISO 8601 format (e.g., '2024-01-15T14:30:25'), relative dates (e.g., '2 weeks ago', 'yesterday'), or absolute dates (e.g., '2024-01-15', 'Jan 15 2024') + - `end_timestamp` (string, optional): Only show commits at or before this time; omit for no upper bound. Accepts ISO 8601 format (e.g., '2024-01-15T14:30:25'), relative dates (e.g., '2 weeks ago', 'yesterday'), or absolute dates (e.g., '2024-01-15', 'Jan 15 2024') + - Returns: `Commit history:` followed by one entry per commit (hash, author, date and message), newest first. When a timestamp filter matches no commits, the text says so and suggests omitting both timestamps, rather than returning an empty history 9. `git_create_branch` - Creates a new branch diff --git a/src/git/src/mcp_server_git/server.py b/src/git/src/mcp_server_git/server.py index a6116db44b..228cc20c35 100644 --- a/src/git/src/mcp_server_git/server.py +++ b/src/git/src/mcp_server_git/server.py @@ -1621,7 +1621,16 @@ def reset(repo_path: str) -> str: @server.tool( name=GitTools.LOG.value, - description="Shows the commit logs", + # #5552: small models read the old one-line description as "a time + # window is required" and filtered to an empty one. Say the order and + # that the filters are optional, where the model picks its arguments. + description=( + "Shows the commit log, newest commit first. For the latest " + "commits, pass only repo_path (and optionally max_count). " + "start_timestamp and end_timestamp are optional filters for a " + "date range: omit them unless a specific period is asked for, " + "because a range that holds no commits returns none." + ), annotations=READ_ONLY, structured_output=False, ) @@ -1638,19 +1647,33 @@ def log( start_timestamp: Annotated[ str | None, Field( - description=f"Start timestamp for filtering commits. {TIMESTAMP_FORMATS}" + description=( + "Optional: only show commits at or after this time. " + f"Omit for no lower bound. {TIMESTAMP_FORMATS}" + ) ), ] = None, end_timestamp: Annotated[ str | None, Field( - description=f"End timestamp for filtering commits. {TIMESTAMP_FORMATS}" + description=( + "Optional: only show commits at or before this time. " + f"Omit for no upper bound. {TIMESTAMP_FORMATS}" + ) ), ] = None, ) -> str: entries = git_log( open_repo(repo_path), max_count, start_timestamp, end_timestamp ) + if not entries and (start_timestamp or end_timestamp): + # #5552: an empty history under a filter reads as "the repository + # has no commits". Name the filter as the cause and the way out. + return ( + "Commit history:\n" + "No commits match the given start_timestamp/end_timestamp. " + "Omit both to see the latest commits." + ) return "Commit history:\n" + "\n".join(entries) @server.tool( diff --git a/src/git/tests/snapshots/list_tools.json b/src/git/tests/snapshots/list_tools.json index 12953ca0f2..79849cd1b0 100644 --- a/src/git/tests/snapshots/list_tools.json +++ b/src/git/tests/snapshots/list_tools.json @@ -197,7 +197,7 @@ }, { "name": "git_log", - "description": "Shows the commit logs", + "description": "Shows the commit log, newest commit first. For the latest commits, pass only repo_path (and optionally max_count). start_timestamp and end_timestamp are optional filters for a date range: omit them unless a specific period is asked for, because a range that holds no commits returns none.", "inputSchema": { "properties": { "repo_path": { @@ -221,7 +221,7 @@ } ], "default": null, - "description": "Start timestamp for filtering commits. Accepts: ISO 8601 format (e.g., '2024-01-15T14:30:25'), relative dates (e.g., '2 weeks ago', 'yesterday'), or absolute dates (e.g., '2024-01-15', 'Jan 15 2024')", + "description": "Optional: only show commits at or after this time. Omit for no lower bound. Accepts: ISO 8601 format (e.g., '2024-01-15T14:30:25'), relative dates (e.g., '2 weeks ago', 'yesterday'), or absolute dates (e.g., '2024-01-15', 'Jan 15 2024')", "title": "Start Timestamp" }, "end_timestamp": { @@ -234,7 +234,7 @@ } ], "default": null, - "description": "End timestamp for filtering commits. Accepts: ISO 8601 format (e.g., '2024-01-15T14:30:25'), relative dates (e.g., '2 weeks ago', 'yesterday'), or absolute dates (e.g., '2024-01-15', 'Jan 15 2024')", + "description": "Optional: only show commits at or before this time. Omit for no upper bound. Accepts: ISO 8601 format (e.g., '2024-01-15T14:30:25'), relative dates (e.g., '2 weeks ago', 'yesterday'), or absolute dates (e.g., '2024-01-15', 'Jan 15 2024')", "title": "End Timestamp" } }, diff --git a/src/git/tests/test_protocol.py b/src/git/tests/test_protocol.py index ffdaf91276..82d3865ee0 100644 --- a/src/git/tests/test_protocol.py +++ b/src/git/tests/test_protocol.py @@ -635,6 +635,14 @@ def add_commits(repo: git.Repo, n: int) -> list[git.Commit]: return commits +# #5552: what git_log returns when a timestamp filter matches nothing. +NO_COMMITS_IN_RANGE = ( + "Commit history:\n" + "No commits match the given start_timestamp/end_timestamp. " + "Omit both to see the latest commits." +) + + async def test_git_log_default(repo: git.Repo): commits = add_commits(repo, 2) initial = repo.head.commit.parents[0].parents[0] @@ -691,11 +699,11 @@ async def test_git_log_timestamps_filter(repo: git.Repo): future = await call( None, "git_log", {"repo_path": root, "start_timestamp": "2099-01-01"} ) - assert future == text_result("Commit history:\n") + assert future == text_result(NO_COMMITS_IN_RANGE) past = await call( None, "git_log", {"repo_path": root, "end_timestamp": "2000-01-01"} ) - assert past == text_result("Commit history:\n") + assert past == text_result(NO_COMMITS_IN_RANGE) both = await call( None, "git_log", @@ -708,6 +716,44 @@ async def test_git_log_timestamps_filter(repo: git.Repo): assert both == text_result("Commit history:\n" + log_entry(repo.head.commit)) +async def test_git_log_empty_window_names_the_filter(repo: git.Repo): + # #5552: a small model asked for the latest commit passed "now" for both + # timestamps, got a bare "Commit history:" and concluded the repository + # had no commits. The reply now says the filter matched nothing. + add_commits(repo, 2) + root = str(root_of(repo)) + # Committed a moment ago, so the window that ends before them is empty. + result = await call( + None, + "git_log", + { + "repo_path": root, + "max_count": 1, + "start_timestamp": "2000-01-01", + "end_timestamp": "2000-01-02", + }, + ) + assert result == text_result(NO_COMMITS_IN_RANGE) + # The same call with no filter returns the newest commit, with no hint. + latest = await call(None, "git_log", {"repo_path": root, "max_count": 1}) + assert latest == text_result("Commit history:\n" + log_entry(repo.head.commit)) + + +async def test_git_log_description_states_order_and_optional_filters(): + # #5552: the description is where a model decides its arguments, so it + # says the order and that both timestamps can be left out. + async with connect(None) as session: + tools = wire(await session.list_tools())["tools"] + log = next(t for t in tools if t["name"] == "git_log") + assert "newest commit first" in log["description"] + assert "optional" in log["description"] + assert log["inputSchema"]["required"] == ["repo_path"] + for name in ("start_timestamp", "end_timestamp"): + assert log["inputSchema"]["properties"][name]["description"].startswith( + "Optional: " + ) + + async def test_git_log_rejects_timestamp_flag_injection(repo: git.Repo): root = str(root_of(repo)) assert await call(