Add tool annotations to server-git (12 tools, 0 annotated)

[olaservo]

Request: Add tool annotations — @modelcontextprotocol/server-git

Context

The git server currently provides zero annotations on all 12 tools. One tool (git_reset) performs a destructive operation, and four tools (git_add, git_commit, git_create_branch, git_checkout) perform write operations — none of them signal this to clients. For reference, @modelcontextprotocol/server-filesystem annotates all 14 of its tools. We're requesting the same treatment here.

Current state — 0/12 tools annotated

#	Tool	readOnlyHint	destructiveHint	idempotentHint	openWorldHint
1	git_status	—	—	—	—
2	git_diff_unstaged	—	—	—	—
3	git_diff_staged	—	—	—	—
4	git_diff	—	—	—	—
5	git_log	—	—	—	—
6	git_show	—	—	—	—
7	git_branch	—	—	—	—
8	git_add	—	—	—	—
9	git_commit	—	—	—	—
10	git_create_branch	—	—	—	—
11	git_checkout	—	—	—	—
12	git_reset	—	—	—	—

Suggested annotations

#	Tool	readOnlyHint	destructiveHint	idempotentHint	openWorldHint
1	git_status	true	false	true	false
2	git_diff_unstaged	true	false	true	false
3	git_diff_staged	true	false	true	false
4	git_diff	true	false	true	false
5	git_log	true	false	true	false
6	git_show	true	false	true	false
7	git_branch	true	false	true	false
8	git_add	false	false	true	false
9	git_commit	false	false	false	false
10	git_create_branch	false	false	false	false
11	git_checkout	false	false	false	false
12	git_reset	false	true	true	false

Rationale

Read-only tools (7 tools)

git_status, git_diff_unstaged, git_diff_staged, git_diff, git_log, git_show, git_branch
Pure reads. No state mutation. Idempotent — calling them repeatedly returns the same result given the same repo state.

Write tools (4 tools)

git_add → destructiveHint: false, idempotentHint: true
Stages files to the index. Non-destructive (reversible via reset). Idempotent — staging the same file twice is a no-op.

git_commit → destructiveHint: false, idempotentHint: false
Creates a new commit. Non-destructive (additive). Not idempotent — committing twice creates two separate commits.

git_create_branch → destructiveHint: false, idempotentHint: false
Creates a new branch. Non-destructive. Not idempotent — creating the same branch twice will fail.

git_checkout → destructiveHint: false, idempotentHint: false
Switches branches. Can discard uncommitted working directory changes. Marked non-destructive since it operates on tracked state, but this is a judgment call.

Destructive tool (1 tool)

git_reset → destructiveHint: true, idempotentHint: true
Unstages all staged changes. This discards the staging state — the index is wiped. Idempotent — resetting an already-clean index is a no-op.

All tools → openWorldHint: false

All operations are local. No network calls (no push, pull, or fetch).

Impact

A client that relies on annotations currently sees all 12 tools as identical — no risk differentiation. Proper annotations make it clear that git_reset is destructive while git_status is safe. The change is roughly 50 lines of metadata additions across 12 tool registrations. No behavior changes.

[SupunGeethanjana]

Implementation Plan - Add Tool Annotations to @modelcontextprotocol/server-git

The objective is to add semantic annotations to the 12 tools provided by the Git server to help clients differentiate between safe, destructive, and idempotent operations.

Proposed Changes

[Component Name] Git Server (Python)

[MODIFY] server.py

Update the list_tools function to include the annotations field for each Tool object.

• Read-only tools: git_status, git_diff_unstaged, git_diff_staged, git_diff, git_log, git_show, git_branch
  • readOnlyHint: True
  • destructiveHint: False
  • idempotentHint: True
• Write tools:
  • git_add: readOnlyHint: False, destructiveHint: False, idempotentHint: True
  • git_commit: readOnlyHint: False, destructiveHint: False, idempotentHint: False
  • git_create_branch: readOnlyHint: False, destructiveHint: False, idempotentHint: False
  • git_checkout: readOnlyHint: False, destructiveHint: False, idempotentHint: False
• Destructive tool:
  • git_reset: readOnlyHint: False, destructiveHint: True, idempotentHint: True
• All tools:
  • openWorldHint: False

Verification Plan

Automated Tests

• Review the code changes against the requested mapping.
• Attempt to run the server locally to ensure no syntax errors were introduced.

Manual Verification

• None required as this is purely a metadata update.

[SupunGeethanjana]

#3589