Request: Add tool annotations — @modelcontextprotocol/server-github v0.6.2

Context

We ran an automated scan of this server via live JSON-RPC handshake. This server exposes 26 tools with zero annotations — the largest unannotated tool surface of any official MCP server.

Several of these tools perform irreversible operations on shared state (merge_pull_request, push_files), but provide no metadata to signal this. For reference, @modelcontextprotocol/server-filesystem annotates all 14 of its tools. We're requesting the same treatment here.

Current state — 0/26 tools annotated

Every tool returns empty annotations: {}.

Suggested annotations — per tool

Write / mutate tools (12 tools)

Read-only tools (14 tools)

Suggested code change — top 3 priority tools

merge_pull_request (highest priority)

server.registerTool(
  "merge_pull_request",
  {
    description: "Merge a pull request",
    inputSchema: {
      owner: z.string(),
      repo: z.string(),
      pullNumber: z.number(),
      commitTitle: z.string().optional(),
      commitMessage: z.string().optional(),
      mergeMethod: z.enum(["merge", "squash", "rebase"]).optional(),
    },
    annotations: {
      readOnlyHint: false,
      destructiveHint: true,
      idempotentHint: false,
      openWorldHint: true,
    },
  },
  handler
);

push_files

server.registerTool(
  "push_files",
  {
    description: "Push multiple files to a GitHub repository in a single commit",
    inputSchema: {
      owner: z.string(),
      repo: z.string(),
      branch: z.string(),
      files: z.array(z.object({ path: z.string(), content: z.string() })),
      message: z.string(),
    },
    annotations: {
      readOnlyHint: false,
      destructiveHint: false,
      idempotentHint: false,
      openWorldHint: true,
    },
  },
  handler
);

get_file_contents (read-only template — same pattern for all 14 read tools)

server.registerTool(
  "get_file_contents",
  {
    description: "Get the contents of a file or directory from a GitHub repository",
    inputSchema: { owner: z.string(), repo: z.string(), path: z.string(), branch: z.string().optional() },
    annotations: {
      readOnlyHint: true,
      idempotentHint: true,
      openWorldHint: true,
    },
  },
  handler
);

The 14 read-only tools all share the same annotation values — readOnlyHint: true, idempotentHint: true, openWorldHint: true — and can be annotated in a single pass.

Rationale for key tools

merge_pull_request → destructiveHint: true
This is the most consequential tool on this server. Merging a PR into a target branch is irreversible without force-push (which requires elevated permissions most tokens don't have). An agent that calls this by mistake or through prompt injection permanently alters the target branch. This is the single most important annotation to add.

push_files → destructiveHint: false, idempotentHint: false
Pushes commits to a remote branch. While not destructive in the "data loss" sense (git preserves history), it modifies shared remote state that other developers rely on. Not idempotent — pushing the same files twice creates two commits.

add_issue_comment → idempotentHint: false
Posting a comment twice creates duplicate comments. In a retry loop, this is publicly visible noise. The annotation signals clients to avoid automatic retries.

create_or_update_file → idempotentHint: true
Upserting the same file with the same content and SHA is a no-op. Safe for retries.

All tools → openWorldHint: true
Every tool on this server makes external API calls to api.github.com. The server has side effects outside the local machine — public repos are visible to everyone, comments trigger notifications, merges trigger CI.

Why this matters — chaining risks in multi-server setups

This server is the most common "write-to-the-outside-world" MCP server. When paired with local data sources, the composition risks become real as MCP adoption grows and agents gain access to more tools simultaneously:

• filesystem.read_file → github.push_files → An agent reading local files (config, .env, private keys) could push them to a public repo. Without readOnlyHint: false on push_files, annotation-aware clients can't distinguish it from the 14 read-only tools on this server — they all look identical with empty annotations.

• Prompt injection → github.merge_pull_request → An agent processing untrusted content could be instructed to merge an open PR. destructiveHint: true on merge_pull_request enables any spec-compliant client to add a confirmation step before irreversible merges. Without it, the merge is indistinguishable from get_pull_request to annotation-aware tooling.

• github.get_file_contents → outbound send → Source code from private repos could be exfiltrated if chained with a network or email tool. readOnlyHint: true on get_file_contents clarifies the read is safe in isolation — enabling a "allow reads, gate outbound sends" policy pattern.

These composition risks grow as agents gain access to more servers simultaneously. Annotations are cheap to add now and become increasingly valuable as MCP client tooling matures.

Impact

This is the largest tool surface of any official MCP server. Adding annotations is a metadata-only change — roughly 130 lines of additions across 26 tool registrations. No behavior changes.

Suggested triage order if you want to start small:

1. merge_pull_request — irreversible, highest consequence
2. push_files — modifies shared remote state
3. All 14 read-only tools in one batch — identical values, mechanical change

Found via automated scan with AgentWard. Enumerated via live JSON-RPC handshake, protocol 2024-11-05.