GitHub Workflow MCP tool handbook slice

Context

Release classification: post-release / boardless (MCP context-budget reduction; not a v13 release blocker).

#9953 is the broad MCP progressive-disclosure parent. #13268 / PR #13269 delivered the shared ToolService compact-description + lazy handbook seam and the file-system first slice. #13734 / PR #13735 then migrated the Knowledge Base MCP server.

Fresh measurement on 2026-06-21 shows github-workflow is the largest remaining primary MCP description surface: 23 tools, about 14,169 always-loaded description characters, with update_issue_relationship alone at about 1,266 characters. That makes it the next highest-value server slice after Knowledge Base.

Live latest-open sweep: checked the latest 20 open issues on 2026-06-21; no equivalent GitHub Workflow MCP handbook migration leaf found. Exact live search for "github-workflow" "tool handbook" found only the existing Knowledge Base leaf #13734 and broad parents #9953 / #9950. A2A recency sweep: latest 30 messages had no competing #9953 / github-workflow handbook claim.

The Problem

ai/mcp/server/github-workflow/openapi.yaml carries detailed operational guidance in operation descriptions. That detail is useful, especially for graph relationship updates and GitHub workflow mutation tools, but before this slice it is projected directly into the MCP tools/list payload. Agents pay that context cost even when they only need routing-level descriptions.

The shared #13268 seam means the right fix is a server migration: keep the detailed text available through get_mcp_tool_handbook, make tools/list compact, and preserve OpenAPI / serviceMapping / access-policy alignment.

The Architectural Reality

• ai/mcp/ToolService.mjs already supports compactToolDescriptions, toolListDescriptionMaxLength, and getToolHandbook().
• ai/mcp/server/github-workflow/toolService.mjs has a large serviceMapping plus access-policy guard helpers; every new OpenAPI operation must be mirrored through serviceMapping and remain compatible with assertCompleteGitHubToolAccessPolicy() / guarded write-tool policy.
• test/playwright/unit/ai/mcp/server/McpServerListToolsSmoke.spec.mjs verifies cross-server tools/list shape and serviceMapping alignment.
• test/playwright/unit/ai/mcp/validation/OpenApiValidatorCompliance.spec.mjs catches OpenAPI operationId vs serviceMapping drift.

The Fix

Migrate the GitHub Workflow MCP server onto the existing handbook seam:

1. Add get_mcp_tool_handbook to the GitHub Workflow OpenAPI contract and service mapping.
2. Enable compact list descriptions for the GitHub Workflow server with the existing ToolService options.
3. Add short routing summaries for the largest / most frequently loaded GitHub Workflow tool descriptions.
4. Preserve detailed usage guidance through lazy-loaded handbook content via existing OpenAPI descriptions or dedicated handbook metadata where needed.
5. Extend focused MCP smoke coverage to prove compact projection, valid handbook lookup, missing handbook lookup, and policy/mapping compatibility.

Contract Ledger Matrix

Decision Record impact

Aligned with #10757 V4.1, #13268, and #13734. No ADR change required.

Acceptance Criteria

• GitHub Workflow MCP exposes get_mcp_tool_handbook through normal MCP tool dispatch.
• GitHub Workflow tools/list emits compact routing descriptions while preserving schemas, annotations, and existing access-policy guard behavior.
• Detailed guidance for at least one high-context GitHub Workflow tool remains available through the lazy-loaded handbook lookup.
• Unknown handbook ids return structured not-found output.
• Focused tests cover list compaction, valid handbook lookup, missing handbook lookup, and OpenAPI/serviceMapping/policy compatibility.

Out of Scope

• Migrating memory-core, neural-link, or gitlab-workflow.
• Closing #9953.
• Changing the shared ToolService API created by #13268.
• Changing GitHub workflow tool semantics, auth policy, or write guards.

Avoided Traps

• Do not add a second handbook mechanism. Reuse ToolService.getToolHandbook().
• Do not weaken GitHub write-tool policy while adding the read-only handbook route.
• Do not remove schemas, annotations, or tool names from tools/list; the context win is description compaction only.
• Do not claim the broad #9953 parent is complete from this single server slice.

Related

Parent: #9953

Related: #10757, #13268, #13734, PR #13269, PR #13735

Retrieval Hint: GitHub Workflow MCP get_mcp_tool_handbook compact tools/list descriptions #9953 #13268 #13734