docs: replace the markdown bug template with GitHub issue forms (#1894)

* docs: replace the markdown bug template with issue forms (#1844)

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) <noreply@anthropic.com>

* docs: address Copilot review on the issue forms (#1844)

- 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.

* 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) <noreply@anthropic.com>

* docs: clarify the protocol-era prompt on the bug form (#1844)

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) <noreply@anthropic.com>

* docs: stop describing the feature form as sharing the bug form's fields (#1844)

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) <noreply@anthropic.com>

* feat: declare v2 statically on the feature form (#1844)

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) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

.github/ISSUE_TEMPLATE/1-bug_report.yml

@@ -0,0 +1,163 @@
+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 current v2 line requires Node >=
+        22.19.0; the deprecated v1 line has its own, older floor.
+      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 you connected with (auto / legacy / modern), 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

.github/ISSUE_TEMPLATE/2-feature_request.yml

@@ -0,0 +1,88 @@
+name: Feature request
+description: Suggest an improvement to the Inspector
+# `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:
+      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

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,73 +0,0 @@
----
-name: Bug report
-about: Report something broken in the Inspector
-title: ""
-labels: ""
-assignees: ""
----
-
-<!--
-Issues are how work reaches the Inspector — we accept issues, not pull
-requests. See CONTRIBUTORS.md for the full policy.
-
-Just tick the version below — a maintainer applies the `v1` / `v2` label
-during triage (most reporters can't set labels themselves). When in doubt,
-it's v2.
--->
-
-**Which version?**
-
-- [ ] v2 — current, published as `@modelcontextprotocol/inspector@latest`
-- [ ] v1 — deprecated, `@v1-latest` (security and bug fixes only)
-
-**Inspector version**
-
-<!-- e.g. 2.0.0 — the version you actually ran, not "latest" -->
-
-**Which client?**
-
-- [ ] Web
-- [ ] CLI
-- [ ] TUI
-- [ ] All / shared core
-
-**What happened**
-
-<!-- The actual behavior you observed. -->
-
-**What you expected instead**
-
-**Steps to reproduce**
-
-1.
-2.
-3.
-
-<!--
-If it depends on a particular MCP server, say which one and how it's
-configured — transport (stdio / streamable HTTP / SSE), protocol era
-(legacy / modern), and whether OAuth is involved.
--->
-
-**Environment**
-
-- OS:
-- Node version:
-- Browser (web client only):
-- MCP server under inspection:
-
-**Logs, errors, or screenshots**
-
-<!--
-Console output, the Inspector's Protocol or Network tab, or a screenshot.
-Redact tokens and secrets first.
--->
-
-**Already prototyped a fix?**
-
-<!--
-Please don't attach a diff or open a PR. Share the *prompt* you used to
-produce the change, plus what you verified — we'll reproduce it through our
-own workflow so it lands with the right conventions, tests, and coverage.
-See CONTRIBUTORS.md → "If you've already fixed it locally".
--->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,57 @@
+# Issue chooser configuration.
+#
+# 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
+# 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.

.github/pull_request_template.md

@@ -11,20 +11,20 @@
 
   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. 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.

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.** 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 #<ISSUE_NUMBER>` (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

CONTRIBUTING.md

@@ -62,6 +62,18 @@ 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 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
+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

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.