modelcontextprotocol/inspector
Watch
1
0
Fork
You've already forked inspector
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

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

Browse source 
* 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>
This commit is contained in:
Cliff Hall 2026-08-01 19:50:49 -04:00 • committed by GitHub
commit 0742f78357
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 326 additions and 77 deletions
Download patch file Download diff file Expand all files Collapse all files

163
.github/ISSUE_TEMPLATE/1-bug_report.yml vendored Normal file
View file

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

88
.github/ISSUE_TEMPLATE/2-feature_request.yml vendored Normal file
View file

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

73
.github/ISSUE_TEMPLATE/bug_report.md vendored
View file

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

57
.github/ISSUE_TEMPLATE/config.yml vendored Normal file
View file

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

6
.github/pull_request_template.md vendored
View file

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

2
AGENTS.md
View file

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

12
CONTRIBUTING.md
View file

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

2
SECURITY.md
View file

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