Skip to content

Commit 5cc00e7

Browse files
committed
docs: add SEP scenario review guidance to AGENTS.md
1 parent cb0f4c3 commit 5cc00e7

1 file changed

Lines changed: 13 additions & 0 deletions

File tree

AGENTS.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,13 +53,26 @@ Keep scenarios separate when they're genuinely independent features or when they
5353
- **Optimize for Ctrl+F on the slug.** Repetitive check blocks are fine — easier to find the failing one than to unwind a clever helper.
5454
- Reuse `ConformanceCheck` and other types from `src/types.ts` rather than defining parallel shapes.
5555
- Include `specReferences` pointing to the relevant spec section.
56+
- **Severity follows the spec keyword:** MUST / MUST NOT → `FAILURE`; SHOULD / SHOULD NOT → `WARNING`. (CI treats WARNING as a failure, so Tier-1 SDKs still need to satisfy SHOULDs — see #245.)
5657

5758
## Descriptions and wording
5859

5960
Be precise about what's **required** vs **optional**. A scenario description that tests optional behavior should make that clear — e.g. "Tests that a client _that wants a refresh token_ handles offline_access scope…" not "Tests that a client handles offline_access scope…". Don't accidentally promote a MAY/SHOULD to a MUST in the prose.
6061

6162
When in doubt about spec details (OAuth parameters, audiences, grant types), check the actual spec in `modelcontextprotocol` rather than guessing.
6263

64+
## Reviewing PRs
65+
66+
For any PR that adds a scenario or check, verify there is a **negative test** — a passing run against the everything-server proves the check doesn't false-positive, but not that it catches anything. The repo has infrastructure for this: a deliberately-broken implementation in `examples/{clients,servers}/typescript/` plus a vitest case asserting the check emits `FAILURE`/`WARNING` against it (see `src/scenarios/client/auth/index.test.ts` `describe('Negative tests')` for the pattern). Prefer that over a manual-run screenshot in the PR body.
67+
68+
### SEP scenarios
69+
70+
Verify requirement levels against the SEP's **spec diff** — the change to `docs/specification/draft/` in the SEP's PR — not the SEP markdown summary or the conformance PR's description. The keyword that governs check severity is the one in the spec text; a bullet under a "Servers SHOULD…" sentence is SHOULD-level even if the SEP's title says "standardize."
71+
72+
```sh
73+
gh api "repos/modelcontextprotocol/modelcontextprotocol/contents/docs/specification/draft/<path>?ref=<sep-branch>" --jq '.content' | base64 -d
74+
```
75+
6376
## Examples: prove it passes and fails
6477

6578
A new scenario should come with:

0 commit comments

Comments
 (0)