From e67ff3180d33017aba9e51ed2513c1efbf09f030 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Sat, 1 Aug 2026 16:25:21 -0400 Subject: [PATCH 1/6] docs: replace the markdown bug template with issue forms (#1844) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Issues are the only intake channel now that external pull requests are off (#1820), so the chooser is where the contribution policy has to be stated — GitHub gives a would-be contributor no explanation when the "New pull request" button isn't there. The one existing template was a legacy **markdown** template, whose fields are prose headings a reporter can delete or ignore. Most reports still arrive missing the client and the transport, which are the two facts that decide where to look. Issue forms enforce them: this replaces `bug_report.md` with `1-bug_report.yml`, where client (web/cli/tui/core), version line (v1/v2), Inspector version, Node version, transport, MCP server, repro, expected, and actual are all `validations.required`. It auto-labels `bug`, and its intro says maintainers implement the fix, so a prompt plus screenshots beats a diff — with a field for exactly that. Adds `2-feature_request.yml` (auto-labels `enhancement`), which puts the problem statement first and marks the solution optional, since the problem is what survives when a specific solution turns out not to fit. Neither form applies a `v1`/`v2` label: GitHub can't map a form answer to a label, so the version line is a required dropdown and a maintainer still labels at triage. v1 takes security fixes only, so routing that answer early is the point. `config.yml` disables blank issues and carries the contact links. **There is deliberately no security *template*** — a template still opens a public issue, which is precisely what a vulnerability report must not do. The redirect is a contact link straight to the private advisory form (`/security/advisories/new`, verified enabled on this repo) plus one to `SECURITY.md`, which covers the v1 line too. The remaining links deflect the recurring misfiled classes: the specification repo and the TypeScript SDK for reports that aren't about this tool, the docs site, the contribution policy, and `#inspector-dev`. Also fixes three links the #1884 rename left dangling — `SECURITY.md` and the PR template still pointed at `CONTRIBUTORS.md`, which no longer exists on this branch. A policy nobody can open is the same as no policy. Validated against GitHub's issue-forms schema (unique ids, allowed `type`s, `markdown` blocks carrying no `id`/`validations`, `checkboxes` marking `required` per option rather than under `validations`). Claude-Session: https://claude.ai/code/session_01YAt8rqxysNbhYWLhoRm3fU Co-authored-by: Claude Opus 5 (1M context) --- .github/ISSUE_TEMPLATE/1-bug_report.yml | 161 +++++++++++++++++++ .github/ISSUE_TEMPLATE/2-feature_request.yml | 84 ++++++++++ .github/ISSUE_TEMPLATE/bug_report.md | 73 --------- .github/ISSUE_TEMPLATE/config.yml | 56 +++++++ .github/pull_request_template.md | 4 +- AGENTS.md | 2 + CONTRIBUTING.md | 8 + SECURITY.md | 2 +- 8 files changed, 314 insertions(+), 76 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/1-bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/2-feature_request.yml delete mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml diff --git a/.github/ISSUE_TEMPLATE/1-bug_report.yml b/.github/ISSUE_TEMPLATE/1-bug_report.yml new file mode 100644 index 000000000..310c80faf --- /dev/null +++ b/.github/ISSUE_TEMPLATE/1-bug_report.yml @@ -0,0 +1,161 @@ +name: Bug report +description: Report something broken in the Inspector (web, CLI, or TUI) +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting a bug — **issues are how work reaches the Inspector.** + + This repository accepts **issues, not pull requests**: design and + implementation are done by the maintainers through a prompt-driven + workflow ([`CONTRIBUTING.md`](https://github.com/modelcontextprotocol/inspector/blob/main/CONTRIBUTING.md)). + So if you have already prototyped a fix locally, **the prompt you used + plus screenshots is worth more to us than a diff** — there is a field + for it at the bottom of this form. + + > 🔒 **Do not report security vulnerabilities here.** Use the + > [private advisory process](https://github.com/modelcontextprotocol/inspector/security/advisories/new) + > instead — see [`SECURITY.md`](https://github.com/modelcontextprotocol/inspector/blob/main/SECURITY.md). + + - type: dropdown + id: version-line + attributes: + label: Which version line? + description: > + v2 is the current Inspector. v1 is deprecated and takes **security + fixes only**, so a v1 bug report gets a different answer. When in + doubt, it's v2. + options: + - v2 — current (`@modelcontextprotocol/inspector@latest`) + - v1 — deprecated (`@v1-latest`, security fixes only) + validations: + required: true + + - type: dropdown + id: client + attributes: + label: Which client? + description: The Inspector ships three clients from one package. + options: + - Web + - CLI + - TUI + - All / shared core + validations: + required: true + + - type: input + id: inspector-version + attributes: + label: Inspector version + description: The version you actually ran, not "latest". + placeholder: "2.0.0" + validations: + required: true + + - type: input + id: node-version + attributes: + label: Node version + description: Output of `node --version`. The Inspector requires Node >= 22.19.0. + placeholder: "v22.19.0" + validations: + required: true + + - type: input + id: os + attributes: + label: Operating system (and browser, for the web client) + placeholder: "macOS 15.5, Chrome 140" + validations: + required: false + + - type: dropdown + id: transport + attributes: + label: Transport + description: How the Inspector was connected to the MCP server under inspection. + options: + - stdio + - Streamable HTTP + - SSE (legacy) + - Not applicable / never connected + validations: + required: true + + - type: textarea + id: mcp-server + attributes: + label: MCP server under inspection + description: > + Which server, and how it is configured — the command or URL, the + protocol era (legacy / modern) if you selected one, and whether OAuth + is involved. Redact tokens and secrets. + placeholder: | + Server: @modelcontextprotocol/server-everything (npx) + Protocol era: modern + OAuth: no + validations: + required: true + + - type: textarea + id: repro + attributes: + label: Steps to reproduce + description: Numbered steps, starting from a fresh launch of the Inspector. + placeholder: | + 1. Run `npx @modelcontextprotocol/inspector` + 2. Add the server above and connect + 3. Open the Tools tab and call `echo` + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What you expected to happen. + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual behavior + description: What happened instead. + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Logs, errors, or screenshots + description: > + Console output, the Inspector's Protocol or Network tab, or a + screenshot. Redact tokens and secrets first. Screenshots can be pasted + directly into this field. + validations: + required: false + + - type: textarea + id: prompt + attributes: + label: Already prototyped a fix? + description: > + Please don't attach a diff or open a pull request — share the **exact + prompt(s)** you used to produce the change, plus what you verified and + any before/after screenshots. We reproduce it through our own workflow + so it lands with the right conventions, tests, and coverage. + validations: + required: false + + - type: checkboxes + id: acknowledgements + attributes: + label: Before you submit + options: + - label: I searched existing issues and this is not a duplicate. + required: true + - label: This is not a security vulnerability report (those go through the private advisory process). + required: true diff --git a/.github/ISSUE_TEMPLATE/2-feature_request.yml b/.github/ISSUE_TEMPLATE/2-feature_request.yml new file mode 100644 index 000000000..33421d9ea --- /dev/null +++ b/.github/ISSUE_TEMPLATE/2-feature_request.yml @@ -0,0 +1,84 @@ +name: Feature request +description: Suggest an improvement to the Inspector +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting an improvement. + + **Maintainers do the implementation here** — this repository accepts + **issues, not pull requests** + ([`CONTRIBUTING.md`](https://github.com/modelcontextprotocol/inspector/blob/main/CONTRIBUTING.md)). + That makes a sharply-stated **problem** the most valuable thing you can + give us: it is what we design against, and it survives after a specific + solution turns out not to fit. + + So please describe the problem first, and treat the solution section as + one possible answer rather than the request itself. + + > **This form targets v2.** The v1 line is deprecated and takes + > **security fixes only** — it does not take new features. + + - type: dropdown + id: client + attributes: + label: Which client? + options: + - Web + - CLI + - TUI + - All / shared core + - Not sure + validations: + required: true + + - type: textarea + id: problem + attributes: + label: The problem + description: > + What are you trying to do, and what makes it hard or impossible today? + Describe the situation, not the feature — including how often you hit + it and what you do instead right now. + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Solution you have in mind (optional) + description: > + If you have a concrete idea, describe it here. It's fine to leave this + blank — the problem above is the part we need. + validations: + required: false + + - type: textarea + id: alternatives + attributes: + label: Alternatives or workarounds you have tried + validations: + required: false + + - type: textarea + id: prompt + attributes: + label: Already built it locally? + description: > + Please don't attach a diff or open a pull request — share the **exact + prompt(s)** you used, plus screenshots of the result. We reproduce the + work through our own workflow so it lands with the right conventions, + tests, and coverage. + validations: + required: false + + - type: checkboxes + id: acknowledgements + attributes: + label: Before you submit + options: + - label: I searched existing issues and this is not a duplicate. + required: true + - label: This is a request for the Inspector itself, not for the MCP specification or an SDK. + required: true diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index a038f0661..000000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -name: Bug report -about: Report something broken in the Inspector -title: "" -labels: "" -assignees: "" ---- - - - -**Which version?** - -- [ ] v2 — current, published as `@modelcontextprotocol/inspector@latest` -- [ ] v1 — deprecated, `@v1-latest` (security and bug fixes only) - -**Inspector version** - - - -**Which client?** - -- [ ] Web -- [ ] CLI -- [ ] TUI -- [ ] All / shared core - -**What happened** - - - -**What you expected instead** - -**Steps to reproduce** - -1. -2. -3. - - - -**Environment** - -- OS: -- Node version: -- Browser (web client only): -- MCP server under inspection: - -**Logs, errors, or screenshots** - - - -**Already prototyped a fix?** - - diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..bc6be6fda --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,56 @@ +# Issue chooser configuration. +# +# Blank issues are disabled so every report lands in a form with the fields +# triage actually needs (client, version line, transport). +# +# Security reports are deliberately a *contact link* rather than a template: +# a template would still open a public issue, which is exactly what a +# vulnerability report must not do. These links leave GitHub's issue flow and +# go straight to the private advisory form. See SECURITY.md. +blank_issues_enabled: false +contact_links: + - name: 🔒 Security vulnerability (v1 or v2) — report privately + url: https://github.com/modelcontextprotocol/inspector/security/advisories/new + about: > + Never report a vulnerability in a public issue. Private vulnerability + reporting is enabled on this repository — this link opens the advisory + form, which is the fastest route to a maintainer. v1 is deprecated and + takes security fixes only, so this is the channel for a v1 security + issue. + + - name: 📜 Security policy (supported versions, what to include) + url: https://github.com/modelcontextprotocol/inspector/blob/main/SECURITY.md + about: > + Which versions are supported, how reports are handled, and what to + include in one. + + - name: 🤝 Contribution policy — why there is no "New pull request" + url: https://github.com/modelcontextprotocol/inspector/blob/main/CONTRIBUTING.md + about: > + This repository accepts issues, not pull requests — maintainers do the + implementation. If you already built a change locally, open an issue and + share the prompt you used rather than a diff. + + - name: 📖 MCP documentation + url: https://modelcontextprotocol.io + about: > + Guides and reference for the Model Context Protocol itself. Start here + for "how does MCP work" questions. + + - name: 📐 MCP specification — protocol questions and proposals + url: https://github.com/modelcontextprotocol/modelcontextprotocol/issues + about: > + If the behavior you're reporting is defined by the protocol rather than + by this tool, file it against the specification repository instead. + + - name: 🧰 MCP TypeScript SDK + url: https://github.com/modelcontextprotocol/typescript-sdk/issues + about: > + The Inspector is built on the TypeScript SDK. If the bug reproduces + against the SDK directly (outside the Inspector), file it there. + + - name: 💬 MCP Contributor Discord (#inspector-dev) + url: https://discord.gg/6CSzBmMkjX + about: > + Questions, usage help, and day-to-day Inspector development discussion. + Also where to say hello if you'd like to work on the Inspector with us. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 029906dbf..253b77740 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -17,14 +17,14 @@ → Open an issue and share the PROMPT(S) you used to generate it, not a diff. We'll reproduce it through our own workflow. - Full policy: ../CONTRIBUTORS.md (relative to this template — the file lives + Full policy: ../CONTRIBUTING.md (relative to this template — the file lives at the repository root, on whatever branch you're reading). Maintainers: delete this template body and describe your change normally. --> > **Heads up:** this repository accepts **issues, not pull requests** from -> external contributors. Please read [`CONTRIBUTORS.md`](../CONTRIBUTORS.md) +> external contributors. Please read [`CONTRIBUTING.md`](../CONTRIBUTING.md) > before continuing. If you're an external contributor, open an issue (and > share the prompt you used, if you've already built the change) rather than > this PR. diff --git a/AGENTS.md b/AGENTS.md index f94fd60c6..ac4600050 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -120,6 +120,8 @@ If you've already built a change locally, share the **prompt** you used and scre **This applies to org members with write access too, not just outside contributors.** Having permission to push a branch is not authorization to open a PR. Pull requests against this repo are opened by the **repo maintainers** only. Anyone else — including organization members whose write access makes it technically possible — opens a **detailed issue** instead, and a maintainer takes it from there. A detailed issue means: the problem, how to reproduce it, the behavior you expected, and — if you've already prototyped a fix — the prompt you used and any screenshots, rather than a diff. +**Issues are filed through the forms in [`.github/ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE) — blank issues are disabled.** There are two forms, **Bug report** (`1-bug_report.yml`, auto-labels `bug`) and **Feature request** (`2-feature_request.yml`, auto-labels `enhancement`); `config.yml` holds the chooser's contact links. Neither form applies a `v1`/`v2` label — the version line is a required *dropdown*, since GitHub can't map a form answer to a label, so a maintainer still applies the version label at triage per [Label by version](#issue-driven-work-style). **There is deliberately no security template**: a vulnerability report must not open a public issue, so the chooser routes it to the private advisory form as a contact link instead (see [`SECURITY.md`](./SECURITY.md)). When adding or changing a form, validate it against GitHub's issue-forms schema (`markdown` blocks take no `id` and no `validations`; `checkboxes` mark `required` per option, not under `validations`). + **Every PR must reference an issue. No exceptions, regardless of who opens it.** The PR body's first line is `Closes #` (see the [Issue-driven Work Style](#issue-driven-work-style) rules below). A PR with no linked issue has no board card, so the work is invisible to the project board and untracked — if you're about to open one and there's no issue yet, create the issue first. This holds for a maintainer's own one-line fix as much as for a feature. ## Project Status and Direction diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index df3bda452..a44d51813 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,6 +62,14 @@ see [What makes a good issue or prompt submission](#what-makes-a-good-issue-or-p below. That's the whole process: you describe the intent, we handle the design and implementation. +[**New issue**](https://github.com/modelcontextprotocol/inspector/issues/new/choose) +offers a **Bug report** and a **Feature request** form. Blank issues are +disabled, so pick one of the two — the required fields (which client, which +version line, which transport) are exactly the facts triage needs first. The +same chooser links out to the private security-advisory process, to this +policy, and to the specification and SDK repositories for reports that aren't +about the Inspector itself. + ### Which version and label? The Inspector is maintained across two versions, each with its own base branch diff --git a/SECURITY.md b/SECURITY.md index 3e26f2162..f0ec359ff 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -38,7 +38,7 @@ Please **do not** report security vulnerabilities through public GitHub issues, or pull requests. Note that this repository does not accept pull requests from outside contributors -(see [CONTRIBUTORS.md](./CONTRIBUTORS.md)) — **this does not apply to security +(see [CONTRIBUTING.md](./CONTRIBUTING.md)) — **this does not apply to security reports**, which should always go through the advisory process above rather than any public channel. From 4d32c2de46aae468cd060ecef5a83325517f1fa1 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Sat, 1 Aug 2026 16:37:25 -0400 Subject: [PATCH 2/6] docs: address Copilot review on the issue forms (#1844) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - PR template said `v2` targets `main`; the v2 base branch is `v2/main`. Correct on its face, and the one line in that template a reader acts on. - Scoped the Node floor on the bug form to v2, since the form serves both lines and v1's floor is older — reading `>= 22.19.0` as universal would make a legitimate v1 report look out of support. - Both the CONTRIBUTING.md paragraph and the AGENTS.md section now say the chooser is served from the **default branch**, so neither claims a form added on `v2/main` is live before the milestone merge. --- .github/ISSUE_TEMPLATE/1-bug_report.yml | 4 +++- .github/pull_request_template.md | 2 +- AGENTS.md | 2 +- CONTRIBUTING.md | 5 ++++- 4 files changed, 9 insertions(+), 4 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/1-bug_report.yml b/.github/ISSUE_TEMPLATE/1-bug_report.yml index 310c80faf..fe3b55b42 100644 --- a/.github/ISSUE_TEMPLATE/1-bug_report.yml +++ b/.github/ISSUE_TEMPLATE/1-bug_report.yml @@ -58,7 +58,9 @@ body: id: node-version attributes: label: Node version - description: Output of `node --version`. The Inspector requires Node >= 22.19.0. + description: > + Output of `node --version`. The current v2 line requires Node >= + 22.19.0; the deprecated v1 line has its own, older floor. placeholder: "v22.19.0" validations: required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 253b77740..5ce2a7ee1 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -11,7 +11,7 @@ If you've found a bug or want a feature: → Open an issue instead, labeled for the version you're targeting - (`v1` for `v1/main`, `v2` for `main`). + (`v1` for `v1/main`, `v2` for `v2/main`). If you've already built the change locally: → Open an issue and share the PROMPT(S) you used to generate it, not a diff --git a/AGENTS.md b/AGENTS.md index ac4600050..38caff2c8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -120,7 +120,7 @@ If you've already built a change locally, share the **prompt** you used and scre **This applies to org members with write access too, not just outside contributors.** Having permission to push a branch is not authorization to open a PR. Pull requests against this repo are opened by the **repo maintainers** only. Anyone else — including organization members whose write access makes it technically possible — opens a **detailed issue** instead, and a maintainer takes it from there. A detailed issue means: the problem, how to reproduce it, the behavior you expected, and — if you've already prototyped a fix — the prompt you used and any screenshots, rather than a diff. -**Issues are filed through the forms in [`.github/ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE) — blank issues are disabled.** There are two forms, **Bug report** (`1-bug_report.yml`, auto-labels `bug`) and **Feature request** (`2-feature_request.yml`, auto-labels `enhancement`); `config.yml` holds the chooser's contact links. Neither form applies a `v1`/`v2` label — the version line is a required *dropdown*, since GitHub can't map a form answer to a label, so a maintainer still applies the version label at triage per [Label by version](#issue-driven-work-style). **There is deliberately no security template**: a vulnerability report must not open a public issue, so the chooser routes it to the private advisory form as a contact link instead (see [`SECURITY.md`](./SECURITY.md)). When adding or changing a form, validate it against GitHub's issue-forms schema (`markdown` blocks take no `id` and no `validations`; `checkboxes` mark `required` per option, not under `validations`). +**Issues are filed through the forms in [`.github/ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE) — blank issues are disabled.** GitHub serves the chooser from the **default branch** only, so a form edited here on `v2/main` has no effect on the live chooser until the next milestone merge into `main` — and it cannot be previewed before then, which is why the schema notes below matter. There are two forms, **Bug report** (`1-bug_report.yml`, auto-labels `bug`) and **Feature request** (`2-feature_request.yml`, auto-labels `enhancement`); `config.yml` holds the chooser's contact links. Neither form applies a `v1`/`v2` label — the version line is a required *dropdown*, since GitHub can't map a form answer to a label, so a maintainer still applies the version label at triage per [Label by version](#issue-driven-work-style). **There is deliberately no security template**: a vulnerability report must not open a public issue, so the chooser routes it to the private advisory form as a contact link instead (see [`SECURITY.md`](./SECURITY.md)). When adding or changing a form, validate it against GitHub's issue-forms schema (`markdown` blocks take no `id` and no `validations`; `checkboxes` mark `required` per option, not under `validations`). **Every PR must reference an issue. No exceptions, regardless of who opens it.** The PR body's first line is `Closes #` (see the [Issue-driven Work Style](#issue-driven-work-style) rules below). A PR with no linked issue has no board card, so the work is invisible to the project board and untracked — if you're about to open one and there's no issue yet, create the issue first. This holds for a maintainer's own one-line fix as much as for a feature. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a44d51813..52f5fbe80 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -65,7 +65,10 @@ and implementation. [**New issue**](https://github.com/modelcontextprotocol/inspector/issues/new/choose) offers a **Bug report** and a **Feature request** form. Blank issues are disabled, so pick one of the two — the required fields (which client, which -version line, which transport) are exactly the facts triage needs first. The +version line, which transport) are exactly the facts triage needs first. +(GitHub serves the chooser from the repository's **default branch**, so what +you see when filing is whatever has reached `main`; a form added on `v2/main` +appears at the next milestone merge.) The same chooser links out to the private security-advisory process, to this policy, and to the specification and SDK repositories for reports that aren't about the Inspector itself. From 88f098f751e7d764d2abe0b4be4d6cbdd27c59d4 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Sat, 1 Aug 2026 16:41:00 -0400 Subject: [PATCH 3/6] docs: re-wrap the CONTRIBUTING chooser paragraph (#1844) Round-2 Copilot nit: the previous wrap left a dangling "The" at end of line, splitting a phrase mid-sentence in the raw markdown. Claude-Session: https://claude.ai/code/session_01YAt8rqxysNbhYWLhoRm3fU Co-authored-by: Claude Opus 5 (1M context) --- CONTRIBUTING.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 52f5fbe80..5698b3890 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -68,10 +68,9 @@ disabled, so pick one of the two — the required fields (which client, which version line, which transport) are exactly the facts triage needs first. (GitHub serves the chooser from the repository's **default branch**, so what you see when filing is whatever has reached `main`; a form added on `v2/main` -appears at the next milestone merge.) The -same chooser links out to the private security-advisory process, to this -policy, and to the specification and SDK repositories for reports that aren't -about the Inspector itself. +appears at the next milestone merge.) The same chooser links out to the private +security-advisory process, to this policy, and to the specification and SDK +repositories for reports that aren't about the Inspector itself. ### Which version and label? From 20c51277921dc4f0a7a2a00687a947029ae63815 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Sat, 1 Aug 2026 16:45:02 -0400 Subject: [PATCH 4/6] docs: clarify the protocol-era prompt on the bug form (#1844) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round-3 Copilot nit. "the protocol era (legacy / modern) if you selected one" reads as referring to a field on this form, which has none — the era is selected on the *connection*, in the Inspector's server settings. Reworded to "the protocol era you connected with (auto / legacy / modern)", which also picks up `auto`, the default the previous list omitted. Claude-Session: https://claude.ai/code/session_01YAt8rqxysNbhYWLhoRm3fU Co-authored-by: Claude Opus 5 (1M context) --- .github/ISSUE_TEMPLATE/1-bug_report.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/1-bug_report.yml b/.github/ISSUE_TEMPLATE/1-bug_report.yml index fe3b55b42..e46c78906 100644 --- a/.github/ISSUE_TEMPLATE/1-bug_report.yml +++ b/.github/ISSUE_TEMPLATE/1-bug_report.yml @@ -92,8 +92,8 @@ body: label: MCP server under inspection description: > Which server, and how it is configured — the command or URL, the - protocol era (legacy / modern) if you selected one, and whether OAuth - is involved. Redact tokens and secrets. + protocol era you connected with (auto / legacy / modern), and whether + OAuth is involved. Redact tokens and secrets. placeholder: | Server: @modelcontextprotocol/server-everything (npx) Protocol era: modern From a2ba194b578a47adf315cd3e65251e71f236fb76 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Sat, 1 Aug 2026 16:49:28 -0400 Subject: [PATCH 5/6] docs: stop describing the feature form as sharing the bug form's fields (#1844) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round-4 Copilot nits, and it was right three times over — I had described "client, version line, transport" as the required set for *both* forms in CONTRIBUTING.md, AGENTS.md, and the config.yml header. The feature form has neither a version-line dropdown nor a transport field, and cannot have the first: v1 takes security fixes only, so a feature request is v2 by construction. Each of the three now distinguishes the two forms rather than generalizing from the bug form. Claude-Session: https://claude.ai/code/session_01YAt8rqxysNbhYWLhoRm3fU Co-authored-by: Claude Opus 5 (1M context) --- .github/ISSUE_TEMPLATE/config.yml | 5 +++-- AGENTS.md | 2 +- CONTRIBUTING.md | 6 ++++-- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index bc6be6fda..f2dddef16 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,7 +1,8 @@ # Issue chooser configuration. # -# Blank issues are disabled so every report lands in a form with the fields -# triage actually needs (client, version line, transport). +# Blank issues are disabled so every report lands in a form. The bug form +# requires the facts triage needs first (client, version line, transport); the +# feature form requires the client and a problem statement, and is v2-only. # # Security reports are deliberately a *contact link* rather than a template: # a template would still open a public issue, which is exactly what a diff --git a/AGENTS.md b/AGENTS.md index 38caff2c8..6042cd160 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -120,7 +120,7 @@ If you've already built a change locally, share the **prompt** you used and scre **This applies to org members with write access too, not just outside contributors.** Having permission to push a branch is not authorization to open a PR. Pull requests against this repo are opened by the **repo maintainers** only. Anyone else — including organization members whose write access makes it technically possible — opens a **detailed issue** instead, and a maintainer takes it from there. A detailed issue means: the problem, how to reproduce it, the behavior you expected, and — if you've already prototyped a fix — the prompt you used and any screenshots, rather than a diff. -**Issues are filed through the forms in [`.github/ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE) — blank issues are disabled.** GitHub serves the chooser from the **default branch** only, so a form edited here on `v2/main` has no effect on the live chooser until the next milestone merge into `main` — and it cannot be previewed before then, which is why the schema notes below matter. There are two forms, **Bug report** (`1-bug_report.yml`, auto-labels `bug`) and **Feature request** (`2-feature_request.yml`, auto-labels `enhancement`); `config.yml` holds the chooser's contact links. Neither form applies a `v1`/`v2` label — the version line is a required *dropdown*, since GitHub can't map a form answer to a label, so a maintainer still applies the version label at triage per [Label by version](#issue-driven-work-style). **There is deliberately no security template**: a vulnerability report must not open a public issue, so the chooser routes it to the private advisory form as a contact link instead (see [`SECURITY.md`](./SECURITY.md)). When adding or changing a form, validate it against GitHub's issue-forms schema (`markdown` blocks take no `id` and no `validations`; `checkboxes` mark `required` per option, not under `validations`). +**Issues are filed through the forms in [`.github/ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE) — blank issues are disabled.** GitHub serves the chooser from the **default branch** only, so a form edited here on `v2/main` has no effect on the live chooser until the next milestone merge into `main` — and it cannot be previewed before then, which is why the schema notes below matter. There are two forms, **Bug report** (`1-bug_report.yml`, auto-labels `bug`) and **Feature request** (`2-feature_request.yml`, auto-labels `enhancement`); `config.yml` holds the chooser's contact links. Neither form applies a `v1`/`v2` label, because GitHub can't map a form answer to a label — `labels:` is static. The **bug** form therefore carries a required version-line *dropdown* and a maintainer applies the matching label at triage per [Label by version](#issue-driven-work-style); the **feature** form has no such dropdown, since v1 takes security fixes only and cannot receive a feature, so it states up front that it targets v2 and is always labeled `v2`. **There is deliberately no security template**: a vulnerability report must not open a public issue, so the chooser routes it to the private advisory form as a contact link instead (see [`SECURITY.md`](./SECURITY.md)). When adding or changing a form, validate it against GitHub's issue-forms schema (`markdown` blocks take no `id` and no `validations`; `checkboxes` mark `required` per option, not under `validations`). **Every PR must reference an issue. No exceptions, regardless of who opens it.** The PR body's first line is `Closes #` (see the [Issue-driven Work Style](#issue-driven-work-style) rules below). A PR with no linked issue has no board card, so the work is invisible to the project board and untracked — if you're about to open one and there's no issue yet, create the issue first. This holds for a maintainer's own one-line fix as much as for a feature. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5698b3890..1976d078e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,8 +64,10 @@ and implementation. [**New issue**](https://github.com/modelcontextprotocol/inspector/issues/new/choose) offers a **Bug report** and a **Feature request** form. Blank issues are -disabled, so pick one of the two — the required fields (which client, which -version line, which transport) are exactly the facts triage needs first. +disabled, so pick one of the two. The bug form requires the facts triage needs +first — which client, which version line, which transport; the feature form +asks for the client and the problem you are trying to solve, and targets v2 +only. (GitHub serves the chooser from the repository's **default branch**, so what you see when filing is whatever has reached `main`; a form added on `v2/main` appears at the next milestone merge.) The same chooser links out to the private From a9c7687474610fbd73cbe152c0a531a009917b87 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Sat, 1 Aug 2026 16:52:28 -0400 Subject: [PATCH 6/6] feat: declare v2 statically on the feature form (#1844) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round-5 Copilot nit caught a real contradiction: the AGENTS.md paragraph said no form can apply a version label, then asserted the feature form "is always labeled v2". Both halves can't be true. Resolved in the direction that makes the claim true rather than softer. A form's `labels:` is static, which is only an obstacle when the value depends on a reporter's answer — and for the feature form it doesn't: v1 takes security fixes only, so a feature request is v2 by construction. So it now declares `["enhancement", "v2"]` outright, which also satisfies AGENTS.md's label-at-create-time rule without a triage step. The bug form still can't, and shouldn't: its version line is genuinely the reporter's to answer. Claude-Session: https://claude.ai/code/session_01YAt8rqxysNbhYWLhoRm3fU Co-authored-by: Claude Opus 5 (1M context) --- .github/ISSUE_TEMPLATE/2-feature_request.yml | 6 +++++- AGENTS.md | 2 +- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/2-feature_request.yml b/.github/ISSUE_TEMPLATE/2-feature_request.yml index 33421d9ea..a5d3fefcb 100644 --- a/.github/ISSUE_TEMPLATE/2-feature_request.yml +++ b/.github/ISSUE_TEMPLATE/2-feature_request.yml @@ -1,6 +1,10 @@ name: Feature request description: Suggest an improvement to the Inspector -labels: ["enhancement"] +# `v2` is safe to declare statically here: v1 takes security fixes only and +# cannot receive a feature, so a feature request is v2 by construction. The bug +# form can't do this — its version line is a reporter's answer, and `labels:` +# is static. +labels: ["enhancement", "v2"] body: - type: markdown attributes: diff --git a/AGENTS.md b/AGENTS.md index 6042cd160..52ea3571f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -120,7 +120,7 @@ If you've already built a change locally, share the **prompt** you used and scre **This applies to org members with write access too, not just outside contributors.** Having permission to push a branch is not authorization to open a PR. Pull requests against this repo are opened by the **repo maintainers** only. Anyone else — including organization members whose write access makes it technically possible — opens a **detailed issue** instead, and a maintainer takes it from there. A detailed issue means: the problem, how to reproduce it, the behavior you expected, and — if you've already prototyped a fix — the prompt you used and any screenshots, rather than a diff. -**Issues are filed through the forms in [`.github/ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE) — blank issues are disabled.** GitHub serves the chooser from the **default branch** only, so a form edited here on `v2/main` has no effect on the live chooser until the next milestone merge into `main` — and it cannot be previewed before then, which is why the schema notes below matter. There are two forms, **Bug report** (`1-bug_report.yml`, auto-labels `bug`) and **Feature request** (`2-feature_request.yml`, auto-labels `enhancement`); `config.yml` holds the chooser's contact links. Neither form applies a `v1`/`v2` label, because GitHub can't map a form answer to a label — `labels:` is static. The **bug** form therefore carries a required version-line *dropdown* and a maintainer applies the matching label at triage per [Label by version](#issue-driven-work-style); the **feature** form has no such dropdown, since v1 takes security fixes only and cannot receive a feature, so it states up front that it targets v2 and is always labeled `v2`. **There is deliberately no security template**: a vulnerability report must not open a public issue, so the chooser routes it to the private advisory form as a contact link instead (see [`SECURITY.md`](./SECURITY.md)). When adding or changing a form, validate it against GitHub's issue-forms schema (`markdown` blocks take no `id` and no `validations`; `checkboxes` mark `required` per option, not under `validations`). +**Issues are filed through the forms in [`.github/ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE) — blank issues are disabled.** GitHub serves the chooser from the **default branch** only, so a form edited here on `v2/main` has no effect on the live chooser until the next milestone merge into `main` — and it cannot be previewed before then, which is why the schema notes below matter. There are two forms, **Bug report** (`1-bug_report.yml`, auto-labels `bug`) and **Feature request** (`2-feature_request.yml`, auto-labels `enhancement` **and `v2`**); `config.yml` holds the chooser's contact links. A form's `labels:` is **static** — GitHub cannot map a reporter's answer to a label — which splits the two cases: the **bug** form could target either line, so it carries a required version-line *dropdown* and a maintainer applies the matching label at triage per [Label by version](#issue-driven-work-style); the **feature** form is v2 by construction (v1 takes security fixes only and cannot receive a feature), so it needs no dropdown and declares `v2` statically. If v1 ever reopens to features, that static label is what has to change. **There is deliberately no security template**: a vulnerability report must not open a public issue, so the chooser routes it to the private advisory form as a contact link instead (see [`SECURITY.md`](./SECURITY.md)). When adding or changing a form, validate it against GitHub's issue-forms schema (`markdown` blocks take no `id` and no `validations`; `checkboxes` mark `required` per option, not under `validations`). **Every PR must reference an issue. No exceptions, regardless of who opens it.** The PR body's first line is `Closes #` (see the [Issue-driven Work Style](#issue-driven-work-style) rules below). A PR with no linked issue has no board card, so the work is invisible to the project board and untracked — if you're about to open one and there's no issue yet, create the issue first. This holds for a maintainer's own one-line fix as much as for a feature.