Add lean projection to GitHub Workflow issue lists

Context

Operator surfaced a concrete MX friction point during the v13 finish session: using the GitHub Workflow MCP list_issues tool to scan the latest 30-40 open tickets for quick wins returned full issue bodies. The response became noisy and token-heavy, so the agent fell back to a live GitHub GraphQL title-only query to get the actual triage surface.

This is a small but recurring agent-UX gap: list_issues is the right MCP substrate for backlog scans, but the default shape is too heavy for title-first triage.

Pre-creation evidence on 2026-06-08:

• Live latest-open sweep: checked the latest 20 open issues through list_issues({state:'open', limit:20}); no equivalent open issue for list_issues title-only / lean projection was visible.
• Label sweep: confirmed enhancement, ai, model-experience, and architecture labels exist.
• Knowledge Base query for GitHub Workflow MCP list_issues body title only fields projection issue list output shape did not surface an existing implementation or ticket; it only identified the general GitHub Workflow documentation.
• Source V-B-A: ai/mcp/server/github-workflow/openapi.yaml exposes limit, state, labels, and assignee for /issues, but no projection / fields / title-only parameter.
• Source V-B-A: ai/services/github-workflow/IssueService.mjs listIssues() returns raw GraphQL issue nodes after only label and assignee node flattening; it does not trim body for triage calls.
• Test sweep: current unit coverage only verifies list_issues tool registration; no list payload-shape coverage was found.

The Problem

Backlog triage has two different use cases that currently share one payload shape:

1. Context intake: an agent needs full issue bodies to understand one or a few tickets.
2. Queue scanning: an agent needs only issue number, title, labels, assignees, state, dates, and URL to choose the next lane or identify quick wins.

Today list_issues serves both with the heavier context-intake shape. That creates three failure modes:

• Title-first scans waste tokens on bodies that are not being read yet.
• Agents bypass the MCP with ad hoc GitHub GraphQL / CLI queries for lean output, losing tool-contract consistency.
• The user-facing update stream becomes noisier because tool output includes irrelevant prose while the agent is only ranking ticket titles.

The Architectural Reality

The owning surface is the GitHub Workflow MCP server:

• ai/mcp/server/github-workflow/openapi.yaml documents the list_issues operation and its query parameters.
• ai/services/github-workflow/IssueService.mjs implements listIssues({limit, state, labels, assignee, cursor}) via GraphQL and returns {count, issues}.
• ai/mcp/server/github-workflow/toolService.mjs maps list_issues directly to IssueService.listIssues.

This is an MCP response-shape / tool-contract improvement, not a GitHub sync change. It should not alter issue syncing, local markdown files, or get_conversation, which remains the right tool for full context.

The Fix

Add a backwards-compatible lean projection option for list_issues.

Recommended implementation shape:

• Add an optional OpenAPI parameter such as projection, defaulting to full.
• Supported values should be small and explicit, e.g.:
  • full — current behavior, preserving backwards compatibility.
  • summary — omit issue body, keep triage metadata: number, title, state, labels, assignees, author, URL, created/updated timestamps.
  • title or title_only — minimal title-scan shape: number, title, URL, labels, assignees, state.
• Implement the trimming in IssueService.listIssues() after filtering, before returning the response.
• Add unit coverage for default/full compatibility and lean projection body omission.
• Update the tool description so agents know to use lean projection for backlog scans and full context only when selecting a specific issue.

Avoid a broad arbitrary fields DSL unless implementation evidence shows it is worth the extra API complexity. A small enum is enough for the observed friction and easier for MCP clients to validate.

Contract Ledger Matrix

Decision Record impact

none. This is a narrow MCP tool contract improvement aligned with existing GitHub Workflow service boundaries.

Acceptance Criteria

• list_issues accepts a documented lean projection parameter while preserving current default/full behavior.
• Lean projection omits issue body and returns enough triage metadata to rank or select tickets: number, title, URL, state, labels, assignees, and relevant timestamps or author where supported.
• Label and assignee filters still work before projection trimming.
• Unit coverage proves full/default compatibility and lean-projection body omission.
• Tool documentation tells agents to use lean projection for queue scans and get_conversation for full issue context.
• No changes to issue sync, local markdown issue files, or conversation retrieval behavior.

Out of Scope

• Arbitrary GraphQL field selection or a general-purpose response-shaping DSL.
• Changing get_conversation payload shape.
• Changing issue sync or local content mirror behavior.
• Reworking GitHub pagination beyond the existing limit/cursor behavior.

Avoided Traps

• Rejected: making lean output the default. Existing callers may rely on body availability.
• Rejected: continuing to use ad hoc GitHub GraphQL for title scans. That works around the MCP instead of improving it.
• Rejected: adding a broad fields DSL as the first fix. The observed friction is solved by a small projection enum with lower validation and documentation cost.

Related

• Surfaced during v13 release quick-win scan after #12698 weighting work.
• Adjacent workflow UX ticket: #12705 (test.yml docs-only CI path scope), another quick-win surfaced by release-note PR friction.
• GitHub Workflow MCP surface: ai/mcp/server/github-workflow/openapi.yaml, ai/services/github-workflow/IssueService.mjs, ai/mcp/server/github-workflow/toolService.mjs.

Origin Session ID: e8f07ef9-ef7e-4815-8ff4-7abe13720621

Retrieval Hint: list_issues title-only projection lean issue scan body token noise GitHub Workflow MCP IssueService