From 73d7439320a77bca7556171d8ddfe103874db7cd Mon Sep 17 00:00:00 2001 From: cliffhall Date: Sat, 27 Jun 2026 18:47:51 -0400 Subject: [PATCH] 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 aeec0408..81f28bae 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 00000000..eebc6298 --- /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.