Skip to content

Commit b3be65b

Browse files
cliffhallclaude
andauthored
docs: add CONTRIBUTORS.md issues-only policy (closes #1517) (#1604)
* 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) <[email protected]> * 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) <[email protected]> * 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) <[email protected]> * docs: add version-board/label table to CONTRIBUTORS.md (closes #1595) Completes requirement #2 of #1517: a table mapping each active version to its base branch, project board, and version label, plus a "Label by version" note mirroring AGENTS.md. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01S3fTN8H3R8YV4yUGvZjYnX * docs: drop v1.5 from CONTRIBUTORS.md, invite deeper contribution (#1517) Review feedback on PR #1604: - Remove the v1.5 row/bullet from the version table — v1.5 was an internal intermediate branch that external contributors never saw, so surfacing it in an outward-facing doc is noise. The table is now v1 / v2 only. - Add a "Want to work on the Inspector with us?" section pointing at the MCP Contributor Discord (#inspector-dev) and the community calls, framing the issues-only rule as being about unsolicited patches rather than a closed door, with supervised work as the path toward maintainership. - Link that section from "Why this policy exists", and add the same Discord pointer to the PR template. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01Txmv2qqv3yeKgRzoqXytzD * docs: drop project-board links from CONTRIBUTORS.md (#1517) The org project boards aren't visible to anyone outside the organization, so linking them in an outward-facing doc points contributors at a 404. The version table is now base branch + label only, and the PR template names the version labels instead of "the appropriate version board". Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01Txmv2qqv3yeKgRzoqXytzD * docs: v1 takes security fixes only (#1517) Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01Txmv2qqv3yeKgRzoqXytzD * docs: use post-runbook branch names (v1/main, main) (#1517) This doc will be read after the branch runbook completes, when v1 lives on v1/main and v2 is the default main. Update the version table, the label-by- version line, and the PR template's label hint + CONTRIBUTORS.md links accordingly. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01Txmv2qqv3yeKgRzoqXytzD --------- Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
1 parent 7784553 commit b3be65b

3 files changed

Lines changed: 157 additions & 0 deletions

File tree

‎.github/pull_request_template.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<!--
2+
⚠️ Before you open this pull request, please read our contribution policy.
3+
4+
We accept ISSUES, NOT PULL REQUESTS from external contributors.
5+
6+
Design and implementation are done by the maintainers through a
7+
prompt-driven workflow (see AGENTS.md). External source PRs will not be
8+
merged — they have to be reverse-engineered to fit our component/theme
9+
conventions and coverage gates, so it's faster for us to re-derive the
10+
change from your intent.
11+
12+
If you've found a bug or want a feature:
13+
→ Open an issue instead, labeled for the version you're targeting
14+
(`v1` for `v1/main`, `v2` for `main`).
15+
16+
If you've already built the change locally:
17+
→ Open an issue and share the PROMPT(S) you used to generate it, not a
18+
diff. We'll reproduce it through our own workflow.
19+
20+
Full policy: https://github.com/modelcontextprotocol/inspector/blob/main/CONTRIBUTORS.md
21+
22+
Maintainers: delete this template body and describe your change normally.
23+
-->
24+
25+
> **Heads up:** this repository accepts **issues, not pull requests** from
26+
> external contributors. Please read [`CONTRIBUTORS.md`](../blob/main/CONTRIBUTORS.md)
27+
> before continuing. If you're an external contributor, open an issue (and
28+
> share the prompt you used, if you've already built the change) rather than
29+
> this PR.
30+
>
31+
> Want to work on the Inspector with us directly? Come say hello in
32+
> **`#inspector-dev`** on the
33+
> [MCP Contributor Discord](https://discord.gg/6CSzBmMkjX) — we're happy to
34+
> scope work with you.

‎AGENTS.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,13 @@ After installing, `npm run build` builds all clients. The launcher scripts (`npm
102102
- v2 - https://github.com/orgs/modelcontextprotocol/projects/28 (active board — all current work goes here)
103103
- v1 - https://github.com/orgs/modelcontextprotocol/projects/11 (existing inspector version, no new activity except security and bug fixes)
104104

105+
## Contributing
106+
107+
External contributions are accepted as **issues, not pull requests** —
108+
maintainers handle design and implementation through a prompt-driven workflow.
109+
If you've already built a change locally, share the **prompt** you used, not a
110+
diff. See [`CONTRIBUTORS.md`](./CONTRIBUTORS.md) for the full policy.
111+
105112
## Project Status and Direction
106113
* The main branch currently contains the legacy version of the Inspector, which we are accepting bug fixes and minor improvement PRs for.
107114

‎CONTRIBUTORS.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Contributing to MCP Inspector
2+
3+
Thank you for your interest in improving the MCP Inspector. Contributors are
4+
genuinely valued — the goal of this document is to channel your input into a
5+
form we can act on quickly and consistently.
6+
7+
## TL;DR
8+
9+
**We accept issues, not pull requests.** Design and implementation are done by
10+
the maintainers. If you've already built a fix or feature locally, share **the
11+
prompt you used** to produce it — not the source code.
12+
13+
## Why this policy exists
14+
15+
The Inspector v2 is developed with an AI-assisted, prompt-driven workflow built
16+
around a consistent architecture, a shared design system, and strict testing
17+
gates (see [`AGENTS.md`](./AGENTS.md)). Every component follows the same
18+
conventions: "dumb" components that take data and callbacks as props, Mantine
19+
for all UI, theme variants instead of ad-hoc CSS, and a uniform per-file
20+
coverage gate of ≥ 90% on lines, statements, functions, and branches.
21+
22+
Accepting raw source PRs creates friction: a diff written outside this pipeline
23+
has to be reverse-engineered to fit our component/theme conventions, coverage
24+
gates, and review process — often it's faster to re-derive the change than to
25+
adapt the patch. Capturing your **intent** (a well-formed issue) or the
26+
**prompt** that generated your local change lets us reproduce the work inside
27+
our own workflow and standards, with the quality bar already baked in.
28+
29+
This policy is about efficiency, not gatekeeping. Your ideas, bug reports, and
30+
prompts directly shape what gets built. And if you'd like to contribute more
31+
than an issue, see
32+
[Want to work on the Inspector with us?](#want-to-work-on-the-inspector-with-us)
33+
below — we'd rather bring you into the workflow than turn you away.
34+
35+
## How to contribute a bug report or feature request
36+
37+
Open a well-formed issue describing the bug or the feature you have in mind.
38+
A great issue gives us everything we need to act on it without a round-trip —
39+
see [What makes a good issue or prompt submission](#what-makes-a-good-issue-or-prompt-submission)
40+
below. That's the whole process: you describe the intent, we handle the design
41+
and implementation.
42+
43+
### Which version and label?
44+
45+
The Inspector is maintained across two versions, each with its own base branch
46+
and version label. File your issue against the version your report or request
47+
targets:
48+
49+
| Version | Base branch | Label |
50+
| ------- | ----------- | ----- |
51+
| v1 | `v1/main` | `v1` |
52+
| v2 | `main` | `v2` |
53+
54+
- **v1** (`v1/main`) is the legacy Inspector — it takes **security fixes
55+
only**.
56+
- **v2** (`main`) is where all current work happens — when in doubt, target v2.
57+
58+
**Label by version.** Every issue (and the PRs maintainers open for it) must
59+
carry the label matching the target branch — `v1` for `v1/main` and `v2` for
60+
`main`. This mirrors the "Label by version" convention documented in
61+
[`AGENTS.md`](./AGENTS.md).
62+
63+
## If you've already fixed it locally
64+
65+
Please don't send a diff or open a pull request. Instead, open an issue that
66+
includes:
67+
68+
- **The prompt(s) you used** to generate the change — the exact text, so we can
69+
reproduce it through our own workflow.
70+
- **A description of the behavior before and after** your change.
71+
- **How you verified it** (steps you ran, tests you added, what you observed).
72+
73+
We'll reproduce the change through our pipeline so it lands with the right
74+
conventions, tests, and coverage.
75+
76+
## What makes a good issue or prompt submission
77+
78+
A great submission gives us everything we need to act without a round-trip:
79+
80+
- **Clear reproduction or use case** — exact steps to reproduce a bug, or a
81+
concrete description of the feature and the problem it solves.
82+
- **Expected vs. actual behavior** — what you saw, and what you expected
83+
instead.
84+
- **Affected client** — which incarnation is involved: **Web**, **TUI**, or
85+
**CLI** (or "all" / "core" if it's shared logic).
86+
- **Environment details** when relevant — OS, Node version, the MCP server you
87+
were inspecting, and any relevant config.
88+
- **The exact prompt text**, if you generated a local change and want us to
89+
reproduce it.
90+
91+
## Want to work on the Inspector with us?
92+
93+
The issues-only policy is about how **unsolicited patches** are handled — it is
94+
not a closed door. If you want to contribute at a deeper level, either in
95+
general or in a specific area, we'd genuinely like to hear from you:
96+
97+
- **Join the [MCP Contributor Discord](https://discord.gg/6CSzBmMkjX)** and say
98+
hello in **`#inspector-dev`**. That's where day-to-day Inspector development
99+
is discussed and the fastest way to reach the maintainers.
100+
- **Attend the community calls** at
101+
[meet.modelcontextprotocol.io](https://meet.modelcontextprotocol.io/) — see
102+
[Contributor Communication](https://modelcontextprotocol.io/community/communication)
103+
for the full set of channels and how they're used.
104+
105+
From there we can scope a piece of work with you and supervise it through our
106+
workflow — which is also the path toward becoming a maintainer. What we want to
107+
avoid is drive-by diffs that have to be reverse-engineered into our pipeline;
108+
what we want to encourage is sustained, coordinated contribution.
109+
110+
All participation is governed by the MCP
111+
[Code of Conduct](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/CODE_OF_CONDUCT.md).
112+
113+
## Questions
114+
115+
If you're unsure how to scope something, open the issue anyway and say so —
116+
we'll help shape it. Thanks for helping make the Inspector better.

0 commit comments

Comments
 (0)