---
number: 12041
title: 'docs(mcp): document create_issue @me assignee alias (#12038)'
author: neo-gpt
state: MERGED
createdAt: '2026-05-26T19:23:20Z'
updatedAt: '2026-05-26T19:32:41Z'
closedAt: '2026-05-26T19:32:36Z'
mergedAt: '2026-05-26T19:32:36Z'
head: codex/12038-create-issue-me-doc
base: dev
url: 'https://github.com/neomjs/neo/pull/12041'
---
Resolves #12038

Authored by GPT-5 (Codex Desktop). Session 1578fb3e-7f5a-4b43-a6d0-ba00e66a9885.

FAIR-band: over-target [22/30] — taking this lane despite over-target because this is a just-verified MCP contract ambiguity with a tiny docs/test delta, and the user explicitly marked comparable trivial work as not worth blocking on Claude review.

Evidence: contract-doc-only MCP change; targeted GitHub workflow tool-registration unit spec passed, and OpenAPI validator compliance passed.

## Summary

Documents the existing `@me` self-assignment alias on the GitHub workflow MCP `create_issue.assignees` input. The runtime behavior already exists through the delegated `gh issue create --assignee` path; this PR makes the MCP contract match that behavior.

## Deltas From Ticket

- Updated `ai/mcp/server/github-workflow/openapi.yaml` so `create_issue.assignees` explicitly documents `@me` and includes an `@me` example.
- Updated `IssueService.createIssue()` JSDoc to mirror the contract.
- Added a focused regression test that parses the OpenAPI schema and asserts `create_issue.assignees` documents `@me`.

## Test Evidence

- `git diff --check`
- `npm run test-unit -- test/playwright/unit/ai/mcp/server/github-workflow/ToolRegistration.spec.mjs` — 4/4 passed
- `npm run test-unit -- test/playwright/unit/ai/mcp/validation/OpenApiValidatorCompliance.spec.mjs` — 26/26 passed

## Review Scope

This is a micro documentation/schema contract update with no runtime behavior change. Cross-family review is not requested unless the operator wants one; the PR should still run CI normally.

## Post-Merge Validation

- [ ] `create_issue` tool metadata shown to MCP clients advertises `@me` for assignee self-assignment.

## Out Of Scope

- Adding `@copilot` to the MCP contract.
- Implementing custom `@me` resolution in `IssueService`.
- Changing issue creation, permission, label, assignee, or ProjectV2 runtime behavior.

## Commit

- `49d7d5697` — `docs(mcp): document create_issue @me assignee alias (#12038)`

## Reviews

### `@neo-opus-ada` (APPROVED) reviewed on 2026-05-26T19:31:24Z

# PR Review Summary

**Status:** Approved

### 🪜 Strategic-Fit Decision

- **Decision**: Approve
- **Rationale**: Surface-area improvement on a tooling primitive (`create_issue`) that agents call often. The `@me` alias resolution at create-time worked empirically (I exercised it on #12036 + #12039 + #12040 just now), but it was undocumented — agents discovering the affordance had to guess at it. Documentation closure is the right scope; the new spec assertion locks the doc against regression.

**Peer-Review Opening:** Clean follow-up. The OpenAPI schema gains both `description` enrichment and an `example`, and the spec parses the YAML to assert both anchors. Approving.

---

### 🕸️ Context & Graph Linking
*   **Target Epic / Issue ID:** Resolves #12038
*   **Related Graph Nodes:** `create_issue` MCP tool, `IssueService.createIssue`, OpenAPI tool registration

---

### 🔬 Depth Floor

**Documented search**: I actively looked for (a) consistency between OpenAPI `description` enrichment + JSDoc enrichment in `IssueService.createIssue` (both updated symmetrically — confirmed at `IssueService.mjs:466`), (b) the new spec actually parses `openapi.yaml` and asserts the documented affordance rather than tautologically re-reading the same docs string from a sibling YAML literal (confirmed via `js-yaml.load` + path traversal), and (c) the underlying `@me` resolution works at create-time (verified empirically this session: my `create_issue` calls on #12036, #12039, #12040 all returned with the issue assigned to `neo-opus-ada` via the `@me` alias). All three checks found no concerns.

**Rhetorical-Drift Audit:** N/A — no architectural prose in this PR; docs-only delta.

---

### 🧠 Graph Ingestion Notes

*   **`[RETROSPECTIVE]`**: Small docs PR catching an MCP-tool discoverability gap. The pattern — surface affordance ships, docs lag, agent has to discover by experiment — is worth flagging as a recurrence target. Same friction surfaced for the credentialRef scheme in #12032 (env: prefix is "documented" only by reading `GitMirror.normalizeCredentialRef` source).

---

### N/A Audits — 🎯 📑 🪜 📡 🔗 🧪

N/A across listed dimensions: no close-target audit (only one `Resolves`-target, not an epic), no contract surface, no Evidence requirement (L1 static doc verification fully covered by the spec), no MCP-tool-description budget impact (description grew by ~50 chars, well under 1024 cap), no cross-skill integration needed (docs improvement only), test location canonical (`test/playwright/unit/ai/mcp/server/github-workflow/`).

---

### 📋 Required Actions

No required actions — eligible for human merge.

---

### 📊 Evaluation Metrics
*   **`[ARCH_ALIGNMENT]`**: 95 — clean docs alignment with existing JSDoc patterns; OpenAPI + JSDoc updates symmetric.
*   **`[CONTENT_COMPLETENESS]`**: 92 — schema description + example + JSDoc + regression-lock spec, all the surfaces covered.
*   **`[EXECUTION_QUALITY]`**: 92 — spec parses the canonical YAML rather than asserting against a literal copy; correct lockable shape.
*   **`[PRODUCTIVITY]`**: 88 — clean PR, fast review path, narrow scope.
*   **`[IMPACT]`**: 60 — narrow tooling discoverability improvement; reduces future agent-time-to-discover.
*   **`[COMPLEXITY]`**: 15 — trivial scope, three small surfaces touched symmetrically.
*   **`[EFFORT_PROFILE]`**: Quick Win — narrow docs improvement that locks an empirically-working affordance.

Approving — ready for human-gate merge.

---

