Skip to content

Commit ef9808f

Browse files
authored
Merge pull request #5249 from modelcontextprotocol/v2/chore/5243-release-v2.1.0
Release v2.1.0: merge v2/main into main
2 parents 51b6382 + d131a87 commit ef9808f

50 files changed

Lines changed: 3456 additions & 534 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/settings.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"hooks": {
3+
"SessionStart": [
4+
{
5+
"hooks": [
6+
{
7+
"type": "command",
8+
"command": "node \"$CLAUDE_PROJECT_DIR/scripts/session-instructions-check.mjs\"",
9+
"timeout": 30
10+
}
11+
]
12+
}
13+
]
14+
}
15+
}

‎.claude/skills/board-ops/SKILL.md‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,10 +53,12 @@ every time**:
5353
# The board's fields, once per session. Refuses to go on from a failed call.
5454
FIELDS=$(gh project field-list 43 --owner modelcontextprotocol --format json) || FIELDS=
5555
# opt <Field> <Option name> → the option's current id, or nothing.
56+
# The arguments reach jq through --args, never as shell positional parameters:
57+
# Claude Code rewrites those in a skill invoked with arguments (#5160).
5658
opt() {
57-
jq -r --arg f "$1" --arg o "$2" \
58-
'.fields[] | select(.name == $f) | .options[] | select(.name == $o) | .id' \
59-
<<<"$FIELDS"
59+
jq -r '$ARGS.positional as [$f, $o]
60+
| .fields[] | select(.name == $f) | .options[] | select(.name == $o) | .id' \
61+
--args "$@" <<<"$FIELDS"
6062
}
6163

6264
STATUS_OPT=$(opt Status "Todo")
@@ -252,6 +254,13 @@ id, `[GHSA-xxxx-yyyy-zzzz]`, because a real issue would disclose it before a fix
252254
exists. No summary goes in the title until the advisory is published. What goes on the card, and when it moves, is the
253255
`/security-advisory` flow; these are only the mechanics.
254256

257+
An advisory can also have a **follow-up card**, titled
258+
`[GHSA-xxxx-yyyy-zzzz follow-up]`, for work its fix leaves open. The recipes
259+
below handle it with one change: put `[$GHSA follow-up]` wherever they have
260+
`[$GHSA]`, both in the lookup's `--arg p` and in `item-create`'s `--title`.
261+
The advisory card's own lookup matches up to the closing bracket, so it never
262+
finds the follow-up.
263+
255264
⚠️ **A draft card has no repository and no issue number**, so the issue-side
256265
lookup above cannot find one. Look it up by its **bracketed GHSA id** in the
257266
full listing, checked for truncation, then feed that item id to `item-edit` or

‎.claude/skills/issue-triage/SKILL.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -676,7 +676,9 @@ What the queries account for:
676676
- **Advisory drafts are carved out by type, title and board together.** A
677677
private security advisory is tracked by a draft card titled
678678
`[GHSA-xxxx-yyyy-zzzz]`, the one exception to "no draft cards", added with
679-
the `security-advisory` flow (#4870). Counting them would pin the non-Issue
679+
the `security-advisory` flow (#4870). The same flow adds an advisory's
680+
follow-up card, `[GHSA-xxxx-yyyy-zzzz follow-up]`, which the prefix check
681+
exempts in the same way. Counting them would pin the non-Issue
680682
check permanently above zero, and a check that never prints `0` stops being
681683
read. The exemption is `DraftIssue` **and** the `[GHSA-` prefix, nothing
682684
broader: a draft titled anything else is still reported (by title, since a

‎.claude/skills/pr-flow/SKILL.md‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -40,12 +40,11 @@ gh issue edit <N> --repo modelcontextprotocol/servers --add-assignee @me
4040
## 2. Branch
4141

4242
`v2/<type>/<N>-<slug>`, cut from **`origin/v2/main`** into a **new git
43-
worktree**, never by switching branches in the primary checkout. Several agent
44-
sessions work this repo on one machine at once and share the primary checkout:
45-
a `git switch` there moves the branch out from under every other session using
46-
it, and carries one task's uncommitted edits, `dist/` output and
47-
`node_modules` into another's. A worktree per issue gives each task its own
48-
tree and leaves the primary checkout alone.
43+
worktree**, never by switching branches in the primary checkout. The rule, and
44+
the check that this session's own instructions are current, is `AGENTS.md`
45+
**Issue-driven work style** (all work in a worktree freshly cut from
46+
`origin/v2/main`). If that check, or the `SessionStart` hook, said `STALE`,
47+
stop here: a fresh branch does not refresh the rules this session loaded.
4948

5049
Run it from the primary checkout. The worktree is a **sibling** directory named
5150
for the checkout plus the issue number (`servers` → `../servers-4810`), never a

‎.claude/skills/project-structure/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ includes the tests) and `vitest.config.ts`.
2929
| Server | Layout | Where its features are registered |
3030
| --- | --- | --- |
3131
| `everything` | `index.ts` picks a transport from `argv`; `server/` holds the factory; `tools/`, `resources/`, `prompts/` hold one file per feature plus an `index.ts`; `transports/` holds one file per transport; `version.ts` reads the package version; `docs/` is shipped | Each feature file exports a `register…` function, wired into its area's `index.ts` (`registerTools`, `registerResources`, `registerPrompts`), which `server/index.ts` calls from `createServer()` |
32-
| `filesystem` | `index.ts` is the stdio entry point (argv → allowed directories, `main()`); `server.ts` exports `createServer(allowedDirectories)`; `lib.ts` holds the file operations and path validation, with the allow-list passed in rather than held globally; `path-utils.ts`, `path-validation.ts` and `roots-utils.ts` are focused helpers; `version.ts` reads the package version | Inline in `createServer()` in `server.ts`, with `server.registerTool(...)` |
32+
| `filesystem` | `index.ts` is the stdio entry point (argv → allowed directories, `main()`); `server.ts` exports `createServer(allowedDirectories)`; `lib.ts` holds the file operations and path validation, with the allow-list passed in rather than held globally; `path-utils.ts`, `path-validation.ts` and `roots-utils.ts` are focused helpers, and `pinned-directory.ts` runs the write operations inside their verified directory; `version.ts` reads the package version | Inline in `createServer()` in `server.ts`, with `server.registerTool(...)` |
3333
| `memory` | `index.ts` holds the `KnowledgeGraphManager`, `createServer(memoryFilePath)` and the stdio `main()`; `version.ts` reads the package version | Inline in `createServer()`; the resource and its subscription handlers are exported `register…` functions in the same file |
3434
| `sequentialthinking` | `index.ts` holds `createServer()` and the stdio `main()`; `lib.ts` holds `SequentialThinkingServer`, the logic; `version.ts` reads the package version | Inline in `createServer()` |
3535

‎.claude/skills/release/SKILL.md‎

Lines changed: 67 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,24 @@ Release whose commit is not on `main`.
1919
environment deployments are a maintainer's acts. So is merging any PR. Prepare,
2020
verify and recommend; do not perform those.
2121

22+
## 0. Check this session's instructions first
23+
24+
A release is the longest-running session and the costliest to get wrong, and
25+
it follows this skill and `AGENTS.md` exactly as they were when the session
26+
started. Before step 1, run the staleness check in `AGENTS.md`
27+
**Issue-driven work style** (all work in a worktree freshly cut from
28+
`origin/v2/main`), whatever the `SessionStart` hook printed: the hook ran when
29+
the session began, and this check runs now.
30+
31+
On `STALE`, or a `STALE` line from the `SessionStart` hook, **stop** and ask
32+
for a session started in a fresh worktree. The v2.0.0 release ran its first
33+
three steps on a `release` skill 447 commits out of date (#5167). Re-run the
34+
check after each preparation PR merges, since `v2/main` moves under the
35+
session, **from the session-start revision, not `HEAD`**: this flow moves
36+
between worktrees (step 4e moves the verification worktree onto a newer
37+
candidate), and a newer worktree's `HEAD` says nothing about the rules this
38+
session loaded. The hook prints that revision and the re-check command.
39+
2240
## The shape
2341

2442
One **release issue**, up to three **preparation PRs** on `v2/main`, one
@@ -174,23 +192,57 @@ ordinary PR first.
174192

175193
Then, on the PR:
176194

177-
1. **Tie it to the release issue with a comment**, `Part of #N`. The action
178-
rewrites the PR's body on every push to `v2/main`, so a `Closes` line there
179-
would not survive; this is the exception `AGENTS.md` names.
195+
1. **Link it to the release issue, and leave a comment.** The action rewrites
196+
the PR's body on every push to `v2/main`, so a `Closes` line there would
197+
not survive; this is the exception `AGENTS.md` names. The link lives
198+
outside the body, so make it now, with the `addCloseIssueReferences`
199+
mutation from `/pr-flow` (step 6), and read it back. On `v2/main` it closes
200+
nothing at merge. Then comment `Part of #N`, the textual record that every
201+
rewrite leaves alone:
202+
203+
```sh
204+
PR=<VERSION_PACKAGES_PR>
205+
gh pr comment "$PR" --repo modelcontextprotocol/servers --body "Part of #$N"
206+
```
180207
2. **Wait for its CI to pass.** The workflow token's push starts no workflow,
181-
so the Version Packages workflow dispatches the TypeScript and Python
182-
workflows on `changeset-release/v2/main` after each update. A PR does not
183-
list dispatched checks, so the result shows as two commit statuses,
184-
`TypeScript (dispatched)` and `Python (dispatched)`. Closing and reopening
185-
the PR does not start them (that fires `pull_request`; they run on `push`).
186-
If neither status appears, run them by hand:
187-
`gh workflow run typescript.yml --ref changeset-release/v2/main` (and
188-
`python.yml`).
208+
so the Version Packages workflow dispatches the TypeScript, Python, DCO and
209+
Everything diff workflows on `changeset-release/v2/main` after each update.
210+
A PR does not list dispatched checks, so the result shows as four commit
211+
statuses: `TypeScript (dispatched)`, `Python (dispatched)`,
212+
`DCO (dispatched)` and `Everything diff (dispatched)`. The PR may also
213+
list `DCO signoff` and the diff as pending or failed with no jobs: GitHub
214+
holds the token's `pull_request` runs (#5173), so read the statuses
215+
instead. Closing and reopening the PR does not start the CI workflows
216+
(that fires `pull_request`; they run on `push`). If a status does not
217+
appear, dispatch its workflow by hand:
218+
`gh workflow run typescript.yml --ref changeset-release/v2/main` (or
219+
`python.yml`, `dco.yml`, `everything-mcp-diff.yml`).
189220
3. **Read it**: each bump matches the semver policy in `RELEASING.md`, each
190221
`CHANGELOG.md` entry says what a user of the server needs to know, the
191222
consumed changeset files are deleted, and `package-lock.json` records the
192223
new versions.
193-
4. A maintainer merges it.
224+
4. **Put `Part of #N` as the body's first line, immediately before the
225+
merge**, once nothing else will land on `v2/main` first: any push there
226+
regenerates the body and drops the line.
227+
228+
```sh
229+
# Read the body first, and edit only on a successful, non-empty read: a
230+
# failed read must never replace the generated release notes with the
231+
# prefix alone.
232+
OLD=$(gh pr view "$PR" --repo modelcontextprotocol/servers --json body --jq .body) \
233+
&& [ -n "$OLD" ] \
234+
&& printf 'Part of #%s\n\n%s\n' "$N" "$OLD" \
235+
| gh pr edit "$PR" --repo modelcontextprotocol/servers --body-file - \
236+
|| echo "body read or edit FAILED — PR body left as it was" >&2
237+
```
238+
239+
5. A maintainer merges it, **first checking the line is still the body's
240+
first**. If a push regenerated the body in between, repeat step 4:
241+
242+
```sh
243+
gh pr view "$PR" --repo modelcontextprotocol/servers \
244+
--json body --jq '.body | split("\n")[0]' # must print: Part of #N
245+
```
194246

195247
### 2c. The Python version stamps: "Prepare Python Release"
196248

@@ -203,8 +255,9 @@ gh workflow run prepare-python-release.yml --repo modelcontextprotocol/servers \
203255

204256
It opens a PR that starts with `Closes #N`, on a branch named
205257
`v2/chore/<N>-python-calver-<date>`, labeled `v2`, and dispatches the
206-
TypeScript and Python workflows on that branch, as the Version Packages
207-
workflow does. Wait for its two `(dispatched)` statuses to pass, check that each stamped package really
258+
TypeScript, Python and DCO workflows on that branch, as the Version Packages
259+
workflow does (not the Everything diff, whose paths it never touches). Wait
260+
for its three `(dispatched)` statuses to pass, check that each stamped package really
208261
changed, and a maintainer merges it.
209262
No PR means no Python server has a shipped change since its last stamp.
210263

‎.claude/skills/security-advisory/SKILL.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -257,6 +257,52 @@ before anyone merges it.
257257
the advisory, so this card is the only place the rest of the team can see the
258258
work exists at all.
259259

260+
#### Work the fix leaves open: a follow-up card
261+
262+
A fix can leave part of the problem open: a platform the fix cannot reach yet,
263+
or a residual exposure that needs a larger change. That work cannot become a
264+
public issue before publication either, because describing it describes the
265+
vulnerability. Track it with a **second draft card**, the advisory's
266+
**follow-up card**, rather than widening the fix or leaving the gap in a PR
267+
body nobody will read again.
268+
269+
- **Title:** `[GHSA-xxxx-yyyy-zzzz follow-up]`, as opaque as the advisory's
270+
own card. The `[GHSA-` prefix keeps it inside the board audit's advisory
271+
exemption. The advisory card's lookup (`/board-ops`) matches
272+
`[GHSA-xxxx-yyyy-zzzz]` with its closing bracket, so it never finds the
273+
follow-up by mistake. A second follow-up for the same advisory is
274+
`[GHSA-xxxx-yyyy-zzzz follow-up 2]`.
275+
- **Body:** the same link-and-triage-only rule as step 1. Its lines, in order:
276+
- `**Advisory:** <html_url>` on the first line.
277+
- `Follow-up to the fix for this advisory. Convert to an issue only once the advisory is published.`
278+
- A link to the write-up.
279+
- The `Priority <level> (provisional, <YYYY-MM-DD>)` line.
280+
- **The write-up lives in the private fork**, where only the advisory's
281+
collaborators can read it. Draft it as the public issue it will become
282+
(problem, options, acceptance criteria), and post it as a `COMMENT` review on
283+
the fork's PR, since the fork refuses issue comments (see the API table).
284+
- **Status `Todo`** when a maintainer asked for the follow-up: the advisory is
285+
already accepted, and asking for the work approves it. Otherwise it goes in
286+
`Incoming`. Score its Priority with step 1's table, using the severity of the
287+
residual exposure rather than the advisory's.
288+
- **Say in the fix PR's body what the fix leaves open**, and link the
289+
follow-up. The advisory's text must say it too when it is published (step 5).
290+
291+
Create it with `/board-ops`'s draft-card recipe, using the follow-up title in
292+
place of `[$GHSA]`.
293+
294+
⚠️ **The follow-up card is the only exception beyond the advisory's own
295+
card.** Any other untracked work an advisory's review turns up falls into one
296+
of three cases:
297+
298+
- It is part of the fix.
299+
- It is a **separate vulnerability**, which goes through its own private
300+
advisory: this repository's for ours, or the SDK's advisory form for an
301+
SDK's (step 2). Publishing this advisory never makes another one safe to
302+
disclose.
303+
- It is non-security work outside the advisory's scope, which gets a public
304+
issue **after publication**, like any other finding.
305+
260306
### 5. Merge, release, publish (human only)
261307

262308
Publish **after** the fix has shipped in a release, never before: publishing
@@ -296,6 +342,12 @@ advisory is what users and advisory tooling (Dependabot, `npm audit`,
296342
added, and an unadded finder is simply never credited.
297343
- **A CVE**, if one is wanted: optional, and the advisory is the only place to
298344
request one.
345+
- **What the fix leaves open**, if the advisory has a follow-up card. Say which
346+
platforms or cases are still exposed, so a user who upgrades does not believe
347+
they are fully covered.
348+
- **The follow-up's write-up, copied out of the fork** before publishing. Once
349+
the advisory is published, don't count on the temporary fork, or on access to
350+
it, surviving.
299351

300352
### 6. After publication, convert the card into public tracking
301353

@@ -322,6 +374,20 @@ issues and two cards.
322374
**close** the issue: the work shipped before the issue existed.
323375
5. Move the card to **`Done`**, which is right here because the fix shipped.
324376

377+
**A follow-up card converts at the same time, but stays open**, because its
378+
work has not shipped:
379+
380+
1. Retitle it `[GHSA-xxxx-yyyy-zzzz follow-up] - <summary>`.
381+
2. Convert it.
382+
3. Replace the body's triage lines with the write-up copied out of the fork
383+
(step 5), linking the now-public advisory.
384+
4. Apply `/issue-create`'s labels. A card already past `Incoming` also takes
385+
the milestone the follow-up is planned for, not the one the fix shipped in.
386+
A card still in `Incoming` stays unmilestoned: once it is an issue the
387+
ordinary `Incoming` ⇔ no-milestone rule applies, and a maintainer approves
388+
it by assigning the milestone and moving it to `Todo`.
389+
5. Leave the issue open, and leave the card in the Status it had.
390+
325391
## API facts worth not re-deriving
326392

327393
| Thing | Fact |
@@ -333,6 +399,7 @@ issues and two cards.
333399
| Fork idempotency | Read `.private_fork` first; the POST creates, it does not probe |
334400
| Fork deletion | Needs the `delete_repo` OAuth scope, which a default `gh` token lacks |
335401
| Comments | **No API at all**, REST or GraphQL; UI-only |
402+
| Fork PR comments | Issue comments (`gh pr comment`, `issues/N/comments`) are refused and `…/comments/{id}/replies` returns `404`; reply in a thread with `POST pulls/N/comments -F in_reply_to=<id>`, and post a PR-level summary as a `COMMENT` review |
336403
| Credits | `credits_detailed` on the advisory; a private report carries the reporter's credit (`type` `reporter`, `state` `pending` or `accepted`) from submission |
337404
| Board writes | Not automatable from Actions: `GITHUB_TOKEN` cannot hold `organization projects: write` |
338405
| SDK routing | Both SDK repos have private vulnerability reporting enabled; use their advisory forms |

‎.claude/skills/security-advisory/evals/evals.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,5 +30,9 @@
3030
{
3131
"prompt": "Rename the local variable `tmp` to `buffer` in this snippet: `const tmp = 1; return tmp + 1;`",
3232
"expect": null
33+
},
34+
{
35+
"prompt": "The fix for a private advisory only covers Linux and macOS; Windows needs a bigger change. Where do I track the Windows work before the advisory is published?",
36+
"expect": "security-advisory"
3337
}
3438
]

0 commit comments

Comments
 (0)