Add minimal response to CRUD tools, `repositories` and `search` toolsets #988

mattdholloway · 2025-08-27T14:42:00Z

This aims to reduce the output from the 'worst offending' MCP tools for response length. The main changes are the introduction of new minimal types for API responses, updates to CRUD handlers to use these minimal types, and enhancements to search and commit tools for more configurable output. These changes simplify responses and make the API easier to consume for clients that only need essential information.

Tools Modified

Search and Listing Tools (Added Parameters)

search_repositories - Added minimal_output parameter (default: true) to return minimal repository information instead of full GitHub API objects
get_commit - Added include_diff parameter (default: true) to optionally include file diffs and stats in the response

List Tools (Modified to Return Minimal Objects)

list_commits - Modified to return minimal commit objects with essential fields only
list_branches - Modified to return minimal branch objects (name, SHA, protected status)

CRUD Tools (Modified to Return URL-Only Response)

create_repository - Modified to return minimal response containing only the repository URL
fork_repository - Modified to return minimal response containing only the repository URL
create_pull_request - Modified to return minimal response containing only the pull request URL
update_pull_request - Modified to return minimal response containing only the pull request URL
create_issue - Modified to return minimal response containing only the issue URL
update_issue - Modified to return minimal response containing only the issue URL
create_gist - Modified to return minimal response containing only the gist URL
update_gist - Modified to return minimal response containing only the gist URL

pkg/github/repositories.go

pkg/github/search.go

pkg/github/minimal_types.go

tonytrg · 2025-08-28T12:30:30Z

Great work! I have not been much involved in the recent discussions about the size of tool call responses,
so this is just some thinking out loud. Nothing that blocks this pr.

but do you think instead of selectively picking specific tools and downsizing their response we could do:

new param responsemode
- optional
- default minimal
- values: minimal, full

Something reusable for every other tool where the api response is unnecessary long.

So kinda stays the same as this pr, only now they can fall back to the old/full response if they need to.

Co-authored-by: Lulu <59149422+LuluBeatson@users.noreply.github.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull Request Overview

This PR adds minimal response options to various GitHub MCP tools to reduce output verbosity. The changes introduce optional parameters to return concise responses instead of full GitHub API objects, addressing the need for more efficient data transfer in MCP tools.

Added minimal_output parameter to search_repositories (default: true) and include_diff parameter to get_commit (default: true)
Modified list operations (list_commits, list_branches) to return minimal objects by default
Updated CRUD operations to return only URLs in minimal response format

Reviewed Changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pkg/github/server.go	Added `OptionalBoolParamWithDefault` helper function
pkg/github/search.go	Added minimal output option to repository search
pkg/github/repositories.go	Updated commit and branch operations to use minimal responses
pkg/github/pullrequests.go	Modified PR CRUD operations to return minimal responses
pkg/github/issues.go	Updated issue CRUD operations to return minimal responses
pkg/github/gists.go	Modified gist CRUD operations to return minimal responses
pkg/github/minimal_types.go	Added new minimal response type definitions
Test files	Updated tests to verify minimal response formats
Documentation	Updated README and tool snapshots with new parameters

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

pkg/github/repositories.go

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

LuluBeatson · 2025-09-01T17:11:10Z

Estimated output length savings

Token counts provided with OpenAI tokenizer for reference, but proporional savings will be similar across models.

List Commits (5.2x)

{
  "owner": "github",
  "repo": "github-mcp-server",
  "sha": "e72c1430debb8b0410cbaa9ba0a0cae33adae91a"
}

New: 7,673 tokens

[
  ...,
  {
      "sha": "586a0d6591a9b408890c39195e36dccccd3d7e40",
      "html_url": "https://github.com/github/github-mcp-server/commit/586a0d6591a9b408890c39195e36dccccd3d7e40",
      "commit": {
          "message": "Update pkg/github/repositories.go\n\nCo-authored-by: Copilot \u003c175728472+Copilot@users.noreply.github.com\u003e",
          "author": {
              "name": "Matt Holloway",
              "email": "mattdholloway@github.com",
              "date": "2025-09-01T16:31:51Z"
          },
          "committer": {
              "name": "GitHub",
              "email": "noreply@github.com",
              "date": "2025-09-01T16:31:51Z"
          }
      },
      "author": {
          "login": "mattdholloway",
          "id": 918573,
          "profile_url": "https://github.com/mattdholloway",
          "avatar_url": "https://avatars.githubusercontent.com/u/918573?v=4"
      },
      "committer": {
          "login": "web-flow",
          "id": 19864447,
          "profile_url": "https://github.com/web-flow",
          "avatar_url": "https://avatars.githubusercontent.com/u/19864447?v=4"
      }
  },
  ...
]

Old: 39,860 tokens

[
  ...
  {
      "node_id": "C_kwDOODGMVNoAKDU4NmEwZDY1OTFhOWI0MDg4OTBjMzkxOTVlMzZkY2NjY2QzZDdlNDA",
      "sha": "586a0d6591a9b408890c39195e36dccccd3d7e40",
      "commit": {
          "author": {
              "date": "2025-09-01T16:31:51Z",
              "name": "Matt Holloway",
              "email": "mattdholloway@github.com"
          },
          "committer": {
              "date": "2025-09-01T16:31:51Z",
              "name": "GitHub",
              "email": "noreply@github.com"
          },
          "message": "Update pkg/github/repositories.go\n\nCo-authored-by: Copilot \u003c175728472+Copilot@users.noreply.github.com\u003e",
          "tree": { "sha": "415f5817de2ecbafcaddc7bf709482b875cb6f45" },
          "url": "https://api.github.com/repos/github/github-mcp-server/git/commits/586a0d6591a9b408890c39195e36dccccd3d7e40",
          "verification": {
              "verified": true,
              "reason": "valid",
              "signature": "-----BEGIN PGP SIGNATURE-----\n\nwsFcBAABCAAQBQJotcp3CRC1aQ7uu5UhlAAAZ3UQAB5FlbZqLwFWX6kfDb7i10Gk\n6oIi1lXRUo1fhB3JbwzQXIXQJL8vVxCG7DzDl9z+PX+1yCrRR1pr/Yo3zd01MLoy\n4XWrrBxXhX4LUoniBDpckIG003+l2uvTl9p2gGuzV9R4awFpoDm47zVD4oj2wJzp\ngbiW7DTnsqQ9/EDxeMJe41HsC1VFvEUatv20y7mqne6xLDKYXRNLJ0ZJPn9B1x3E\n1R1XGxlTBXMgkdxM0D0lJuiZLolCnPKH8PuXAFQ0SHeaGmjfHdg6wj4uW2uK2Ri8\neATJfTWI48oCll78bZgcfwJlHE++pDt8wgZmBNNKdgqes/jJ2vsW+7qggrw8hA63\nZBYNG2Szlg0r2N9cO1oKz8gP3o/jMUknXf+9SQFYg7+oI2s+MIPfUGuKUds1EZHB\n664CKF8SPFXzY+9OxMkMfQNuRunkfgRRksEpPMdygeVD8FFIEk1fW16hRzIvDvW3\n6qiMiBJDJNzEG4hfKM3VpNqom18qSPupLlHU3BgBVWE0bcBCdxlgnJ4THX4bgDx6\ne7hF7Za9BgRvUhnyaZjozh65grl/HyKSD81JJNeDdSgKL9Yee9TLu3OsLbXMLEf2\nqqcqn3vFQCvK/AziQd+vj+9SLnmiDSKlIOlE6ywhZwp7dMDMaT8WlnExF7FlYh4I\nqKSQCxuMcJS/visAK9Fe\n=ZNXS\n-----END PGP SIGNATURE-----\n",
              "payload": "tree 415f5817de2ecbafcaddc7bf709482b875cb6f45\nparent cfeed3d5e3095f0de2de2e4916d867a7379f98fb\nauthor Matt Holloway \u003cmattdholloway@github.com\u003e 1756744311 +0100\ncommitter GitHub \u003cnoreply@github.com\u003e 1756744311 +0100\n\nUpdate pkg/github/repositories.go\n\nCo-authored-by: Copilot \u003c175728472+Copilot@users.noreply.github.com\u003e"
          },
          "comment_count": 0
      },
      "author": {
          "login": "mattdholloway",
          "id": 918573,
          "node_id": "MDQ6VXNlcjkxODU3Mw==",
          "avatar_url": "https://avatars.githubusercontent.com/u/918573?v=4",
          "html_url": "https://github.com/mattdholloway",
          "gravatar_id": "",
          "type": "User",
          "site_admin": true,
          "url": "https://api.github.com/users/mattdholloway",
          "events_url": "https://api.github.com/users/mattdholloway/events{/privacy}",
          "following_url": "https://api.github.com/users/mattdholloway/following{/other_user}",
          "followers_url": "https://api.github.com/users/mattdholloway/followers",
          "gists_url": "https://api.github.com/users/mattdholloway/gists{/gist_id}",
          "organizations_url": "https://api.github.com/users/mattdholloway/orgs",
          "received_events_url": "https://api.github.com/users/mattdholloway/received_events",
          "repos_url": "https://api.github.com/users/mattdholloway/repos",
          "starred_url": "https://api.github.com/users/mattdholloway/starred{/owner}{/repo}",
          "subscriptions_url": "https://api.github.com/users/mattdholloway/subscriptions"
      },
      "committer": {
          "login": "web-flow",
          "id": 19864447,
          "node_id": "MDQ6VXNlcjE5ODY0NDQ3",
          "avatar_url": "https://avatars.githubusercontent.com/u/19864447?v=4",
          "html_url": "https://github.com/web-flow",
          "gravatar_id": "",
          "type": "User",
          "site_admin": false,
          "url": "https://api.github.com/users/web-flow",
          "events_url": "https://api.github.com/users/web-flow/events{/privacy}",
          "following_url": "https://api.github.com/users/web-flow/following{/other_user}",
          "followers_url": "https://api.github.com/users/web-flow/followers",
          "gists_url": "https://api.github.com/users/web-flow/gists{/gist_id}",
          "organizations_url": "https://api.github.com/users/web-flow/orgs",
          "received_events_url": "https://api.github.com/users/web-flow/received_events",
          "repos_url": "https://api.github.com/users/web-flow/repos",
          "starred_url": "https://api.github.com/users/web-flow/starred{/owner}{/repo}",
          "subscriptions_url": "https://api.github.com/users/web-flow/subscriptions"
      },
      "parents": [
          {
              "sha": "cfeed3d5e3095f0de2de2e4916d867a7379f98fb",
              "html_url": "https://github.com/github/github-mcp-server/commit/cfeed3d5e3095f0de2de2e4916d867a7379f98fb",
              "url": "https://api.github.com/repos/github/github-mcp-server/commits/cfeed3d5e3095f0de2de2e4916d867a7379f98fb"
          }
      ],
      "html_url": "https://github.com/github/github-mcp-server/commit/586a0d6591a9b408890c39195e36dccccd3d7e40",
      "url": "https://api.github.com/repos/github/github-mcp-server/commits/586a0d6591a9b408890c39195e36dccccd3d7e40",
      "comments_url": "https://api.github.com/repos/github/github-mcp-server/commits/586a0d6591a9b408890c39195e36dccccd3d7e40/comments"
  },
  ...
]

List Branches (4.1x)

{
  "owner": "github",
  "repo": "github-mcp-server"
}

New: 1,373 tokens

[
  ...,
  {
      "name": "SamMorrowDrums-patch-1",
      "sha": "884c0e66eee260e1bbd58e1470311d66764a2bc5",
      "protected": true
  },
  ...
]

Old: 5,606 tokens

[
  ...,
  {
      "name": "SamMorrowDrums-patch-1",
      "commit": {
          "sha": "884c0e66eee260e1bbd58e1470311d66764a2bc5",
          "url": "https://api.github.com/repos/github/github-mcp-server/commits/884c0e66eee260e1bbd58e1470311d66764a2bc5"
      },
      "protected": true,
      "protection": {
          "required_status_checks": {
              "strict": false,
              "contexts": [],
              "checks": []
          },
          "required_pull_request_reviews": null,
          "enforce_admins": null,
          "restrictions": null,
          "required_linear_history": null,
          "allow_force_pushes": null,
          "allow_deletions": null,
          "required_conversation_resolution": null
      },
      "protection_url": "https://api.github.com/repos/github/github-mcp-server/branches/SamMorrowDrums-patch-1/protection"
  },
  ...

Create Issue (34.3x*)

* highly variable depending on issue body length

{
  "owner": "lulubeatson",
  "repo": "ghmcp-test",
  "title": "Add a pun to the README",
  "body": "## Description\nThe README could use some humor! Let's add a pun to make it more engaging and fun to read.\n\n## Acceptance Criteria\n- [ ] Add a clever pun related to the repository or its purpose\n- [ ] Ensure the pun fits naturally within the existing README content\n- [ ] Keep it appropriate and professional\n\n## Suggestions\nSome ideas for puns:\n- Something related to GitHub/Git (e.g., \"This repo is commit-ted to excellence!\")\n- Something about testing or development\n- A play on words related to the project name\n\n## Priority\nLow - this is a fun enhancement to improve the developer experience"
}

New: 20 tokens

{"url":"https://github.com/LuluBeatson/ghmcp-test/issues/28"}

Old: 685 tokens

{"id":3373361799,"number":27,"state":"open","locked":false,"title":"Add a pun to the README","body":"## Description\nThe README could use some humor! Let's add a pun to make it more engaging and fun to read.\n\n## Acceptance Criteria\n- [ ] Add a clever pun related to the repository or its purpose\n- [ ] Ensure the pun fits naturally within the existing README content\n- [ ] Keep it appropriate and professional\n\n## Suggestions\nSome ideas for puns:\n- Something related to GitHub/Git (e.g., \"This repo is commit-ted to excellence!\")\n- Something about testing or development\n- A play on words related to the project name\n\n## Priority\nLow - this is a fun enhancement to improve the developer experience","author_association":"OWNER","user":{"login":"LuluBeatson","id":59149422,"node_id":"MDQ6VXNlcjU5MTQ5NDIy","avatar_url":"https://avatars.githubusercontent.com/u/59149422?v=4","html_url":"https://github.com/LuluBeatson","gravatar_id":"","type":"User","site_admin":true,"url":"https://api.github.com/users/LuluBeatson","events_url":"https://api.github.com/users/LuluBeatson/events{/privacy}","following_url":"https://api.github.com/users/LuluBeatson/following{/other_user}","followers_url":"https://api.github.com/users/LuluBeatson/followers","gists_url":"https://api.github.com/users/LuluBeatson/gists{/gist_id}","organizations_url":"https://api.github.com/users/LuluBeatson/orgs","received_events_url":"https://api.github.com/users/LuluBeatson/received_events","repos_url":"https://api.github.com/users/LuluBeatson/repos","starred_url":"https://api.github.com/users/LuluBeatson/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/LuluBeatson/subscriptions"},"comments":0,"created_at":"2025-09-01T17:12:58Z","updated_at":"2025-09-01T17:12:58Z","url":"https://api.github.com/repos/LuluBeatson/ghmcp-test/issues/27","html_url":"https://github.com/LuluBeatson/ghmcp-test/issues/27","comments_url":"https://api.github.com/repos/LuluBeatson/ghmcp-test/issues/27/comments","events_url":"https://api.github.com/repos/LuluBeatson/ghmcp-test/issues/27/events","labels_url":"https://api.github.com/repos/LuluBeatson/ghmcp-test/issues/27/labels{/name}","repository_url":"https://api.github.com/repos/LuluBeatson/ghmcp-test","reactions":{"total_count":0,"+1":0,"-1":0,"laugh":0,"confused":0,"heart":0,"hooray":0,"rocket":0,"eyes":0,"url":"https://api.github.com/repos/LuluBeatson/ghmcp-test/issues/27/reactions"},"node_id":"I_kwDOPNjcb87JEWqH"}

…ets (github#988) * add comprehensive minimal response where appropriate * remove unneeded comments * remove incorrect diff param * update docs * rm comment * Update pkg/github/repositories.go Co-authored-by: Lulu <59149422+LuluBeatson@users.noreply.github.com> * update toolsnaps and docs * change minimal_output to use new OptionalBoolParamWithDefault * Update pkg/github/repositories.go Co-authored-by: Lulu <59149422+LuluBeatson@users.noreply.github.com> * refactor minimal conversion funcs to minimal_types.go * consolidate response structs and remove unneeded message field * consolidate response further * remove CloneURL field * Update pkg/github/repositories.go Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update pkg/github/server.go Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix undefined * change incorrect comment * remove old err var declaration * Update pkg/github/repositories.go Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix syntax issue * update toolsnaps --------- Co-authored-by: Lulu <59149422+LuluBeatson@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

add comprehensive minimal response where appropriate

ba785d2

mattdholloway changed the title ~~add comprehensive minimal response where appropriate~~ Add comprehensive minimal response where appropriate Aug 27, 2025

mattdholloway marked this pull request as ready for review August 27, 2025 14:42

mattdholloway requested a review from a team as a code owner August 27, 2025 14:42

Copilot AI review requested due to automatic review settings August 27, 2025 14:42

This comment was marked as outdated.

Sign in to view

mattdholloway changed the title ~~Add comprehensive minimal response where appropriate~~ Add comprehensive minimal response to CRUD tools, repositories and search toolsets Aug 27, 2025

mattdholloway added 3 commits August 27, 2025 15:49

remove unneeded comments

bf3e789

remove incorrect diff param

278b94e

update docs

0ebdf30

mattdholloway changed the title ~~Add comprehensive minimal response to CRUD tools, repositories and search toolsets~~ Add minimal response to CRUD tools, repositories and search toolsets Aug 27, 2025

rm comment

26ebb0d

LuluBeatson requested changes Aug 28, 2025

View reviewed changes

mattdholloway and others added 8 commits August 28, 2025 14:16

Update pkg/github/repositories.go

4a32e08

Co-authored-by: Lulu <59149422+LuluBeatson@users.noreply.github.com>

update toolsnaps and docs

ca91a80

change minimal_output to use new OptionalBoolParamWithDefault

9ea0ac9

Update pkg/github/repositories.go

4142f93

Co-authored-by: Lulu <59149422+LuluBeatson@users.noreply.github.com>

refactor minimal conversion funcs to minimal_types.go

17c8564

consolidate response structs and remove unneeded message field

c82651f

consolidate response further

60213e6

remove CloneURL field

c36e4ce

mattdholloway requested review from LuluBeatson and Copilot August 29, 2025 09:24

This comment was marked as outdated.

Sign in to view

mattdholloway and others added 5 commits August 29, 2025 10:33

Update pkg/github/repositories.go

8e49c3f

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update pkg/github/server.go

7e4616e

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fix undefined

093f86f

change incorrect comment

4fa0729

Merge branch 'main' into reduce-output-fields

43cc7b4

LuluBeatson linked an issue Sep 1, 2025 that may be closed by this pull request

Enable concise responses to API requests #957

Closed

remove old err var declaration

cfeed3d

mattdholloway requested a review from Copilot September 1, 2025 16:28

Copilot AI reviewed Sep 1, 2025

View reviewed changes

pkg/github/repositories.go Show resolved Hide resolved

mattdholloway and others added 3 commits September 1, 2025 17:31

Update pkg/github/repositories.go

586a0d6

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fix syntax issue

debef3e

update toolsnaps

e72c143

LuluBeatson approved these changes Sep 1, 2025

View reviewed changes

mattdholloway merged commit 358a415 into main Sep 1, 2025
16 checks passed

mattdholloway deleted the reduce-output-fields branch September 1, 2025 17:13

BrewTestBot mentioned this pull request Sep 3, 2025

github-mcp-server 0.14.0 Homebrew/homebrew-core#235999

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add minimal response to CRUD tools, `repositories` and `search` toolsets #988

Add minimal response to CRUD tools, `repositories` and `search` toolsets #988

Uh oh!

mattdholloway commented Aug 27, 2025 •

edited

Loading

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tonytrg commented Aug 28, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

LuluBeatson commented Sep 1, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Add minimal response to CRUD tools, repositories and search toolsets #988

Add minimal response to CRUD tools, repositories and search toolsets #988

Uh oh!

Conversation

mattdholloway commented Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Tools Modified

Search and Listing Tools (Added Parameters)

List Tools (Modified to Return Minimal Objects)

CRUD Tools (Modified to Return URL-Only Response)

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tonytrg commented Aug 28, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

LuluBeatson commented Sep 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Estimated output length savings

List Commits (5.2x)

List Branches (4.1x)

Create Issue (34.3x*)

Uh oh!

Uh oh!

Uh oh!

Add minimal response to CRUD tools, `repositories` and `search` toolsets #988

Add minimal response to CRUD tools, `repositories` and `search` toolsets #988

mattdholloway commented Aug 27, 2025 •

edited

Loading

LuluBeatson commented Sep 1, 2025 •

edited

Loading