github / github/github-mcp-server
projects_write: add iterations to an existing iteration field (currently impossible without wiping item assignments)
- 主要語言
- Go
- 星號
- 33k
- 分支
- 5k
- 平均合併
- 2 天 1 小時
- 30 天內合併 PR
- 52
描述
### Describe the feature or problem you’d like to solve
`projects_write` supports `create_iteration_field` (added in #2232, closing #1854), but there is **no way to add an iteration to an *existing* iteration field** — the single most common sprint operation ("add the next sprint").
Today, when an agent is asked to "add the next sprint to the Sprint field", the only iteration-related method available is `create_iteration_field`, so agents end up creating a duplicate field instead of appending to the existing one.
The underlying blocker is a public API asymmetry, which I verified empirically (2026-07-27):
1. **GraphQL**: the only way to modify iterations is `updateProjectV2Field` with `iterationConfiguration`, whose docs state *"provided values **overwrite** the existing configuration"*. Its `ProjectV2Iteration` input accepts only `{startDate, duration, title}` — **no `id`**, while the read-side type `ProjectV2IterationFieldIteration` does expose `id`.
2. **Consequence (tested on a disposable project)**: rebuilding the list with identical titles/dates regenerates **all** iteration ids (e.g. `18dd8506` → `3038b65f`), and **every item's iteration field value is silently cleared** — for completed and active iterations alike.
3. **REST**: the new `projectsV2` REST endpoints only allow *creating* fields (`POST .../fields`); `fields/{field_id}` has no PATCH/PUT, and the iteration items schema is `additionalProperties: false` with no `id` either.
4. **Precedent in the same mutation**: `ProjectV2SingleSelectFieldOptionInput` *does* have an optional `id`, documented as *"Include this to preserve the option's identity during updates, **preventing item field values from being cleared**"*. The GitHub web UI's internal endpoint uses exactly this pattern for iterations (existing entries carry `id`, new entries send `id: ""`). Iterations appear to be the one place this mechanism was left out of the public schema.
### Proposed solution
Two complementary parts:
1. **(Root fix, likely needs routing to the Projects/GraphQL team)** Add an optional `id: String` to the `ProjectV2Iteration` input, with the same preserve-identity semantics as `ProjectV2SingleSelectFieldOptionInput.id`. This would make read-modify-write appends safe for any API consumer, not just MCP.
2. **(This repo)** Add an `add_iteration` method to `projects_write` that appends an iteration to an existing iteration field (auto-computing the next start date from the last iteration when omitted). If/while the schema lacks `id`, the method could either (a) be gated with an explicit destructive warning, or (b) mitigate by snapshotting item assignments before the rewrite and re-assigning them to the regenerated ids afterwards.
This would benefit every team running sprint workflows through the MCP server: sprint planning is a recurring, high-frequency operation, and it is currently the one Projects v2 write that agents cannot perform safely at all.
### Example prompts or workflows (for tools/toolsets only)
- "Add the next sprint to the Sprint field in project 14"
- "Extend our Sprint iterations through the end of Q4, two weeks each"
- "Create 'Sprint 23' starting 2026-10-03 with a duration of 14 days"
- "Our sprints ran out — add six more iterations matching the current cadence"
- "Insert next sprint and move all unfinished items from the current one into it"
### Additional context
- Verification was done via schema introspection (`__type` on `ProjectV2Iteration`, `ProjectV2IterationFieldIteration`, `ProjectV2SingleSelectFieldOptionInput`) and a live experiment on a throwaway user project; happy to share the exact GraphQL calls and before/after output.
- Related: #1854 (closed by #2232, which covers field *creation* only).
- Public schema references (docs.github.com `schema.docs.graphql`): `input ProjectV2Iteration` (no id) vs `type ProjectV2IterationFieldIteration` (has id); `UpdateProjectV2FieldInput.iterationConfiguration` overwrite note; `ProjectV2SingleSelectFieldOptionInput.id` preserve-identity note.
貢獻指南
研究方向
Start at the projects_write implementation, especially the existing create_iteration_field path, and review how GraphQL ProjectV2Iteration updates are assembled. Compare the public input schema with the read-side iteration type and the single-select option identity behavior described in the issue. Done means an existing iteration field can safely receive appended iterations without losing item assignments, with the external API limitation and any destructive fallback explicitly handled.
由索引模型根據 Issue 內容生成。
評估
- 技術堆疊
- github, go, graphql
- 領域
- api, backend-api-design, tooling
- Issue 類型
- 功能
- 難度
- 5/5
- 預估耗時
- 一週以上
- 活躍度
- 活躍
- 描述清晰度
- 基本清楚
- 新手友好度
- 35/100