diff --git a/.github/ISSUE_TEMPLATE/1-bug_report.yml b/.github/ISSUE_TEMPLATE/1-bug_report.yml new file mode 100644 index 000000000..e46c78906 --- /dev/null +++ b/.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 diff --git a/.github/ISSUE_TEMPLATE/2-feature_request.yml b/.github/ISSUE_TEMPLATE/2-feature_request.yml new file mode 100644 index 000000000..a5d3fefcb --- /dev/null +++ b/.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 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..f2dddef16 --- /dev/null +++ b/.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. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 029906dbf..5ce2a7ee1 100644 --- a/.github/pull_request_template.md +++ b/.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. diff --git a/AGENTS.md b/AGENTS.md index f94fd60c6..52ea3571f 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.** 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. ## Project Status and Direction diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index df3bda452..1976d078e 100644 --- a/CONTRIBUTING.md +++ b/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 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.