Add source links to GitHub MCP tools report

[Copilot]

The github-mcp-tools-report workflow generated discussions with no clickable links to the source files it references, making it harder to navigate from the report to the actual data and documentation.

Changes to .github/workflows/github-mcp-tools-report.md

• Executive Summary — added Source and Instructions File fields with GitHub blob links to pkg/workflow/data/github_toolsets_permissions.json and .github/instructions/github-mcp-server.instructions.md
• JSON Mapping Comparison — made the pkg/workflow/data/github_toolsets_permissions.json reference a clickable link
• Action field — updated PR creation instruction to include a linked PR reference: "Created pull request [#NUMBER](URL) with updated JSON mapping."
• Methodology — added JSON Mapping, Instructions, and MCP Server Source entries with direct blob links (including a link to github/github-mcp-server/tree/main/pkg/github)
• Report Quality — added Link Sources rule instructing the agent to always use full GitHub URLs when referencing files and PRs
• Phase 1 step 5 (new) — added a "Cross-Reference Toolset Source Files" step with a verified mapping of each toolset to its source file in github/github-mcp-server/pkg/github/ (e.g. issues → issues.go, users/orgs → search.go, stargazers → repositories.go)
• Phase 3 — added Source File as item 6 in per-tool documentation, linking to the toolset's source in github-mcp-server
• Report template (Tools by Toolset) — each toolset section now includes a Source: link to the corresponding pkg/github/*.go file
• Missing JSON handling — updated Phase 1 step 4, Phase 2, and Output Requirements to create pkg/workflow/data/github_toolsets_permissions.json from scratch if the file does not exist, rather than only updating it when discrepancies are found

Expected Improvement

Future report runs will produce discussions with clickable links to both the local data files and the upstream github-mcp-server source files, making it easier to navigate from the report to the actual implementation. The workflow will also self-heal if the JSON mapping file is ever missing.

Validation

Workflow compiled successfully: ✅ github-mcp-tools-report

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[q] Add source links to GitHub MCP tools report</issue_title>
<issue_description>## Summary

Updates the github-mcp-tools-report workflow to include clickable links to source files in the generated discussion report, as requested in discussion #17701.

Changes Made

.github/workflows/github-mcp-tools-report.md

The report template now includes links to:

1. Executive Summary — added Source and Instructions File fields with GitHub blob links:

   • pkg/workflow/data/github_toolsets_permissions.json
   • .github/instructions/github-mcp-server.instructions.md

2. JSON Mapping Comparison section — the reference to pkg/workflow/data/github_toolsets_permissions.json is now a clickable link.

3. Action field — when a PR is created for JSON mapping updates, the report now instructs the agent to include a link to the PR number and URL.

4. Methodology section — added JSON Mapping and Instructions entries with clickable links to the referenced files.

5. Report Quality guidelines — added "Link Sources" rule to ensure the agent always uses full GitHub URLs when referencing files and PRs.

Expected Improvement

Future report runs will produce discussions with clickable links to the source files, making it easier to navigate from the report to the actual data and documentation files.

Validation

Workflow compiled successfully: ✅ github-mcp-tools-report

Triggered by: discussion #17701 comment from @pelikhan

🎩 Equipped by Q

• expires on Feb 24, 2026, 1:09 PM UTC

---

[!NOTE]
This was originally intended as a pull request, but the git push operation failed.

Workflow Run: View run details and download patch artifact

The patch file is available in the agent-artifacts artifact in the workflow run linked above.

To apply the patch locally:

# Download the artifact from the workflow run https://github.com/github/gh-aw/actions/runs/22277703782
# (Use GitHub MCP tools if gh CLI is not available)
gh run download 22277703782 -n agent-artifacts -D /tmp/agent-artifacts-22277703782

# The patch file will be at agent-artifacts/tmp/gh-aw/aw-q-mcp-tools-report-add-source-links.patch after download
# Apply the patch
git am /tmp/agent-artifacts-22277703782/aw-q-mcp-tools-report-add-source-links.patch

Show patch preview (72 of 72 lines)

From 89e64f30799dfba69444d657ff1859fbd66692b5 Mon Sep 17 00:00:00 2001
From: Copilot <copilot@github.com>
Date: Sun, 22 Feb 2026 13:08:12 +0000
Subject: [PATCH] feat: add source links to GitHub MCP tools report

Update the github-mcp-tools-report workflow to include clickable
links to source files in the generated discussion report:

- Link JSON mapping file in Executive Summary
- Link instructions file in Executive Summary
- Link JSON mapping file in JSON Mapping Comparison section
- Link PR when created for JSON mapping updates
- Link sources in Methodology section
- Add 'Link Sources' guideline to Report Quality section

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/workflows/github-mcp-tools-report.md | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/github-mcp-tools-report.md b/.github/workflows/github-mcp-tools-report.md
index efc40a5..6bf4d5e 100644
--- a/.github/workflows/github-mcp-tools-report.md
+++ b/.github/workflows/github-mcp-tools-report.md
@@ -163,6 +163,8 @@ Create a detailed markdown report with the following structure:
 - **Total Tools Discovered**: [NUMBER]
 - **Toolset Categories**: [NUMBER]
 - **Report Date**: [DATE]
+- **Source**: [`pkg/workflow/data/github_toolsets_permissions.json`](https://github.com/${{ github.repository }}/blob/main/pkg/workflow/data/github_toolsets_permissions.json)
+- **Instructions File**: [`.github/instructions/github-mcp-server.instructions.md`](https://github.com/${{ github.repository }}/blob/main/.github/instructions/github-mcp-server.instructions.md)
 - **Changes Since Last Report**: [If previous data exists, show changes summary]
   - **New Tools**: [NUMBER]
   - **Removed Tools**: [NUMBER]
@@ -186,7 +188,7 @@ Report any inconsistencies discovered during the systematic exploration:
 
 ### Discrepancies Between MCP Server and JSON Mapping
 
-Report on the comparison between the MCP server tools and the `pkg/workflow/data/github_tools
... (truncated)

Comments on the Issue (you are @copilot in this section)

• Fixes [q] Add source links to GitHub MCP tools report #17706

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[pelikhan]

@copilot always cross correlate sources to GitHub file URLs in the GitHub-MCP-server repo.

Update agentic workflows that generates the .json if missing

[Copilot]

@copilot always cross correlate sources to GitHub file URLs in the GitHub-MCP-server repo.

Update agentic workflows that generates the .json if missing

Done in f85fd65.

Cross-correlating sources to github-mcp-server URLs: Added Phase 1 step 5 with a verified toolset→source file mapping pointing to pkg/github/*.go in github/github-mcp-server. Each toolset is mapped to its verified Go source file (e.g., issues → issues.go, users → search.go where SearchUsers is defined with ToolsetMetadataUsers, orgs → search.go for SearchOrgs with a note that list_org_repository_security_advisories is in security_advisories.go). These links are also added to Phase 3 tool documentation, the per-toolset sections in the report template, and the Methodology section.

Handle missing JSON: Updated Phase 1 step 4 (try to read, note if missing), Phase 2 (create from scratch if missing), and Output Requirements + execution steps list to cover the create-from-scratch case alongside the existing update-on-discrepancy logic.

[Copilot]

Pull request overview

This PR enhances the github-mcp-tools-report workflow by adding clickable source links to the generated discussion reports and adding handling for missing JSON mapping files. The changes make it easier to navigate from reports to source code and data files.

Changes:

• Added source file links throughout the report template pointing to both local repository files and upstream github-mcp-server source files
• Added a new Phase 1 step 5 to cross-reference each toolset with its source file in the github-mcp-server repository
• Updated JSON mapping handling to create the file from scratch if missing, rather than only updating when discrepancies exist

Comments suppressed due to low confidence (3)

.github/workflows/github-mcp-tools-report.md:217

• The repository is hardcoded as github/gh-aw in this URL. This should use the template variable ${{ github.repository }} instead: https://github.com/${{ github.repository }}/blob/main/pkg/workflow/data/github_toolsets_permissions.json

Report on the comparison between the MCP server tools and the [`pkg/workflow/data/github_toolsets_permissions.json`](https://github.com/github/gh-aw/blob/main/pkg/workflow/data/github_toolsets_permissions.json) file:

.github/workflows/github-mcp-tools-report.md:351

• The repository is hardcoded as github/gh-aw in these URLs. This should use the template variable ${{ github.repository }} instead. For example: https://github.com/${{ github.repository }}/blob/main/pkg/workflow/data/github_toolsets_permissions.json

- **JSON Mapping**: [pkg/workflow/data/github_toolsets_permissions.json](https://github.com/github/gh-aw/blob/main/pkg/workflow/data/github_toolsets_permissions.json)
- **Instructions**: [.github/instructions/github-mcp-server.instructions.md](https://github.com/github/gh-aw/blob/main/.github/instructions/github-mcp-server.instructions.md)

.github/workflows/github-mcp-tools-report.md:367

• The example URL in this guideline hardcodes github/gh-aw. This should be changed to use the template variable ${{ github.repository }} in the example to demonstrate the correct pattern: https://github.com/${{ github.repository }}/blob/main/...

- **Link Sources**: Always use full GitHub URLs (e.g., `https://github.com/github/gh-aw/blob/main/...`) when referencing files and PRs

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The repository owner and name are hardcoded as github/gh-aw in these URLs. This should use the template variable ${{ github.repository }} instead to make the workflow portable and work correctly if the repository is forked or the workflow is reused in a different repository. The pattern used elsewhere in the codebase (e.g., .github/workflows/copilot-pr-merged-report.md:248) shows: https://github.com/${{ github.repository }}/blob/main/...

This issue also appears in the following locations of the same file:

• line 217
• line 350
• line 367

Suggested change

	- **Source**: [pkg/workflow/data/github_toolsets_permissions.json](https://github.com/github/gh-aw/blob/main/pkg/workflow/data/github_toolsets_permissions.json)
	- **Instructions File**: [.github/instructions/github-mcp-server.instructions.md](https://github.com/github/gh-aw/blob/main/.github/instructions/github-mcp-server.instructions.md)
	- **Source**: [pkg/workflow/data/github_toolsets_permissions.json](https://github.com/${{ github.repository }}/blob/main/pkg/workflow/data/github_toolsets_permissions.json)
	- **Instructions File**: [.github/instructions/github-mcp-server.instructions.md](https://github.com/${{ github.repository }}/blob/main/.github/instructions/github-mcp-server.instructions.md)