From 73d7439320a77bca7556171d8ddfe103874db7cd Mon Sep 17 00:00:00 2001 From: cliffhall Date: Sat, 27 Jun 2026 18:47:51 -0400 Subject: [PATCH 1/3] docs: add CONTRIBUTORS.md issues-only policy (#1517) Document the contribution policy: we accept issues, not pull requests. Maintainers handle design and implementation through a prompt-driven workflow. Contributors who have already built a change locally should share the prompt they used rather than a diff. Cross-reference the policy from AGENTS.md. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 7 +++++ CONTRIBUTORS.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 86 insertions(+) create mode 100644 CONTRIBUTORS.md diff --git a/AGENTS.md b/AGENTS.md index aeec0408b..81f28bae1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -73,6 +73,13 @@ After installing, `npm run build` builds all clients. The launcher scripts (`npm - v1.5 - https://github.com/orgs/modelcontextprotocol/projects/39 - v1 - https://github.com/orgs/modelcontextprotocol/projects/11 +## Contributing + +External contributions are accepted as **issues, not pull requests** — +maintainers handle design and implementation through a prompt-driven workflow. +If you've already built a change locally, share the **prompt** you used, not a +diff. See [`CONTRIBUTORS.md`](./CONTRIBUTORS.md) for the full policy. + ## Project Status and Direction * The main branch currently contains the legacy version of the Inspector, which we are accepting bug fixes and minor improvement PRs for. diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md new file mode 100644 index 000000000..eebc62983 --- /dev/null +++ b/CONTRIBUTORS.md @@ -0,0 +1,79 @@ +# Contributing to MCP Inspector + +Thank you for your interest in improving the MCP Inspector. Contributors are +genuinely valued — the goal of this document is to channel your input into a +form we can act on quickly and consistently. + +## TL;DR + +**We accept issues, not pull requests.** Design and implementation are done by +the maintainers. If you've already built a fix or feature locally, share **the +prompt you used** to produce it — not the source code. + +## Why this policy exists + +The Inspector v2 is developed with an AI-assisted, prompt-driven workflow built +around a consistent architecture, a shared design system, and strict testing +gates (see [`AGENTS.md`](./AGENTS.md)). Every component follows the same +conventions: "dumb" components that take data and callbacks as props, Mantine +for all UI, theme variants instead of ad-hoc CSS, and a uniform per-file +coverage gate of ≥ 90% on lines, statements, functions, and branches. + +Accepting raw source PRs creates friction: a diff written outside this pipeline +has to be reverse-engineered to fit our component/theme conventions, coverage +gates, and review process — often it's faster to re-derive the change than to +adapt the patch. Capturing your **intent** (a well-formed issue) or the +**prompt** that generated your local change lets us reproduce the work inside +our own workflow and standards, with the quality bar already baked in. + +This policy is about efficiency, not gatekeeping. Your ideas, bug reports, and +prompts directly shape what gets built. + +## How to contribute a bug report or feature request + +Open a well-scoped issue on the appropriate version board. The Inspector +maintains three lines of development, each with its own board and base branch: + +| Target | Board | Base branch | Label | +| --- | --- | --- | --- | +| v2 (current focus) | [v2 board](https://github.com/orgs/modelcontextprotocol/projects/28) | `v2/main` | `v2` | +| v1.5 | [v1.5 board](https://github.com/orgs/modelcontextprotocol/projects/39) | `v1.5/main` | `v1.5` | +| v1 (legacy) | [v1 board](https://github.com/orgs/modelcontextprotocol/projects/11) | `main` | `v1` | + +Most new work targets **v2** — open it on the v2 board and label it `v2`. Apply +the label that matches the target version (`v1` / `v1.5` / `v2`) so the issue +can be filtered correctly; see the "Label by version" convention in +[`AGENTS.md`](./AGENTS.md). + +## If you've already fixed it locally + +Please don't send a diff or open a pull request. Instead, open an issue that +includes: + +- **The prompt(s) you used** to generate the change — the exact text, so we can + reproduce it through our own workflow. +- **A description of the behavior before and after** your change. +- **How you verified it** (steps you ran, tests you added, what you observed). + +We'll reproduce the change through our pipeline so it lands with the right +conventions, tests, and coverage. + +## What makes a good issue or prompt submission + +A great submission gives us everything we need to act without a round-trip: + +- **Clear reproduction or use case** — exact steps to reproduce a bug, or a + concrete description of the feature and the problem it solves. +- **Expected vs. actual behavior** — what you saw, and what you expected + instead. +- **Affected client** — which incarnation is involved: **Web**, **TUI**, or + **CLI** (or "all" / "core" if it's shared logic). +- **Environment details** when relevant — OS, Node version, the MCP server you + were inspecting, and any relevant config. +- **The exact prompt text**, if you generated a local change and want us to + reproduce it. + +## Questions + +If you're unsure which board or label applies, open the issue on the v2 board +and say so — we'll route it. Thanks for helping make the Inspector better. From cc1e707ff05b8be0d3c26434180f9804dfe013b2 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Sat, 27 Jun 2026 18:49:27 -0400 Subject: [PATCH 2/3] docs: add PR template redirecting external authors to issues-only policy (#1517) GitHub auto-populates pull_request_template.md into every new PR body, so it steers would-be external PR authors to CONTRIBUTORS.md before they submit a diff. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/pull_request_template.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..3c8167a97 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,28 @@ + + +> **Heads up:** this repository accepts **issues, not pull requests** from +> external contributors. Please read [`CONTRIBUTORS.md`](../blob/v2/main/CONTRIBUTORS.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. From f7a746c3cd7d1ebd9d726e373d30b53794802d79 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Sat, 27 Jun 2026 19:45:08 -0400 Subject: [PATCH 3/3] docs: drop version-board details from CONTRIBUTORS.md (#1517) The policy takes effect after v2/main merges into main, leaving a single line of development. Tell contributors to open a well-formed issue rather than routing them to per-version project boards. Co-Authored-By: Claude Opus 4.8 (1M context) --- CONTRIBUTORS.md | 22 +++++++--------------- 1 file changed, 7 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index eebc62983..530455647 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -31,19 +31,11 @@ prompts directly shape what gets built. ## How to contribute a bug report or feature request -Open a well-scoped issue on the appropriate version board. The Inspector -maintains three lines of development, each with its own board and base branch: - -| Target | Board | Base branch | Label | -| --- | --- | --- | --- | -| v2 (current focus) | [v2 board](https://github.com/orgs/modelcontextprotocol/projects/28) | `v2/main` | `v2` | -| v1.5 | [v1.5 board](https://github.com/orgs/modelcontextprotocol/projects/39) | `v1.5/main` | `v1.5` | -| v1 (legacy) | [v1 board](https://github.com/orgs/modelcontextprotocol/projects/11) | `main` | `v1` | - -Most new work targets **v2** — open it on the v2 board and label it `v2`. Apply -the label that matches the target version (`v1` / `v1.5` / `v2`) so the issue -can be filtered correctly; see the "Label by version" convention in -[`AGENTS.md`](./AGENTS.md). +Open a well-formed issue describing the bug or the feature you have in mind. +A great issue gives us everything we need to act on it without a round-trip — +see [What makes a good issue or prompt submission](#what-makes-a-good-issue-or-prompt-submission) +below. That's the whole process: you describe the intent, we handle the design +and implementation. ## If you've already fixed it locally @@ -75,5 +67,5 @@ A great submission gives us everything we need to act without a round-trip: ## Questions -If you're unsure which board or label applies, open the issue on the v2 board -and say so — we'll route it. Thanks for helping make the Inspector better. +If you're unsure how to scope something, open the issue anyway and say so — +we'll help shape it. Thanks for helping make the Inspector better.