Skip to content

Commit 8821de3

Browse files
cliffhallclaude
andcommitted
docs: issues-not-PRs contribution model, issue forms, backlog plan
Outside pull requests are turned off, as in the Inspector (decided on #4861). CONTRIBUTING.md, AGENTS.md's Contributing section, the PR template's banner, and the fetch and time READMEs now say so. Add bug and feature issue forms with a server dropdown, a protocol-era field and a client field, and a config.yml that disables blank issues and routes security reports to the private advisory form and new servers to the MCP Server Registry. docs/contribution-model.md records the plan for the open outside-PR backlog (classify, harvest into issues, close with a canned comment, verify), which #4868's triage pass carries out. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 9b734b9 commit 8821de3

9 files changed

Lines changed: 809 additions & 49 deletions

File tree

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
# Bug report form (GitHub issue forms schema).
2+
#
3+
# Requires the facts triage needs before anything else: which server, its
4+
# version, how it was run, the transport, the protocol era the client speaks,
5+
# and the client itself. The server dropdown is how triage picks the
6+
# `server-<name>` scope label; `labels:` below is static, so it cannot apply
7+
# that label itself. `bug` is the type label and `v2` the version label: this
8+
# repository has no v1 line, so every issue is a v2 issue (AGENTS.md).
9+
#
10+
# GitHub serves issue forms from the default branch (`main`), so a change here
11+
# goes live at the next milestone merge from `v2/main`, not when it merges.
12+
name: Bug report
13+
description: Report something broken in one of the reference servers
14+
labels: ["bug", "v2"]
15+
body:
16+
- type: markdown
17+
attributes:
18+
value: |
19+
Thanks for reporting a bug. **Issues are how work reaches these servers.**
20+
21+
This repository accepts **issues, not pull requests**: design and
22+
implementation are done by the maintainers through a prompt-driven
23+
workflow ([`CONTRIBUTING.md`](https://github.com/modelcontextprotocol/servers/blob/main/CONTRIBUTING.md)).
24+
So if you have already prototyped a fix locally, **the prompt you used
25+
is worth more to us than a diff**. There is a field for it at the bottom
26+
of this form.
27+
28+
> 🔒 **Do not report security vulnerabilities here.** Use the
29+
> [private advisory form](https://github.com/modelcontextprotocol/servers/security/advisories/new)
30+
> instead.
31+
32+
- type: dropdown
33+
id: server
34+
attributes:
35+
label: Which server?
36+
description: >
37+
The servers in this repository. A server you found in the MCP Server
38+
Registry or elsewhere is maintained by its own authors; report its bugs
39+
to them.
40+
options:
41+
- everything (@modelcontextprotocol/server-everything)
42+
- filesystem (@modelcontextprotocol/server-filesystem)
43+
- memory (@modelcontextprotocol/server-memory)
44+
- sequentialthinking (@modelcontextprotocol/server-sequential-thinking)
45+
- fetch (mcp-server-fetch)
46+
- git (mcp-server-git)
47+
- time (mcp-server-time)
48+
- More than one, or the repository itself
49+
validations:
50+
required: true
51+
52+
- type: input
53+
id: server-version
54+
attributes:
55+
label: Server version
56+
description: >
57+
The version you actually ran, not "latest". For an unreleased build,
58+
give the commit.
59+
placeholder: "0.6.3"
60+
validations:
61+
required: true
62+
63+
- type: dropdown
64+
id: install
65+
attributes:
66+
label: How did you run the server?
67+
options:
68+
- npx (npm package)
69+
- uvx or pip (PyPI package)
70+
- Docker image
71+
- From a clone of this repository
72+
- Other (say which below)
73+
validations:
74+
required: true
75+
76+
- type: dropdown
77+
id: transport
78+
attributes:
79+
label: Transport
80+
description: >
81+
Every server speaks stdio. Only `everything` also serves Streamable HTTP
82+
and the deprecated HTTP+SSE transport.
83+
options:
84+
- stdio
85+
- Streamable HTTP
86+
- HTTP+SSE (deprecated)
87+
- Not sure
88+
validations:
89+
required: true
90+
91+
- type: dropdown
92+
id: spec-era
93+
attributes:
94+
label: Protocol era
95+
description: >
96+
Which revision of the MCP specification the client negotiated. Modern
97+
is 2026-07-28, the stateless revision with no `initialize` handshake.
98+
Legacy is 2025-11-25 or earlier. The client's logs, or the MCP
99+
Inspector, show the negotiated version.
100+
options:
101+
- Modern (2026-07-28)
102+
- Legacy (2025-11-25 or earlier)
103+
- Not sure
104+
validations:
105+
required: true
106+
107+
- type: input
108+
id: client
109+
attributes:
110+
label: MCP client and version
111+
description: The client that talked to the server, with its version.
112+
placeholder: "Claude Desktop 1.2.3, MCP Inspector 2.0.0, a custom SDK client"
113+
validations:
114+
required: true
115+
116+
- type: input
117+
id: environment
118+
attributes:
119+
label: Operating system and runtime
120+
description: Your OS, plus `node --version` or `python --version` as applicable.
121+
placeholder: "macOS 15.5, Node v22.19.0"
122+
validations:
123+
required: false
124+
125+
- type: textarea
126+
id: config
127+
attributes:
128+
label: Server configuration
129+
description: >
130+
The command, arguments and environment variables the client launched the
131+
server with (for example, the `mcpServers` entry). Redact tokens,
132+
secrets and private paths.
133+
validations:
134+
required: false
135+
136+
- type: textarea
137+
id: repro
138+
attributes:
139+
label: Steps to reproduce
140+
description: >
141+
Numbered steps from a fresh start of the server, including the tool,
142+
resource or prompt you called and its arguments.
143+
placeholder: |
144+
1. Start the server with the configuration above
145+
2. Call `read_text_file` with `{"path": "/allowed/dir/link"}`
146+
3. ...
147+
validations:
148+
required: true
149+
150+
- type: textarea
151+
id: expected
152+
attributes:
153+
label: Expected behavior
154+
description: What you expected to happen.
155+
validations:
156+
required: true
157+
158+
- type: textarea
159+
id: actual
160+
attributes:
161+
label: Actual behavior
162+
description: What happened instead.
163+
validations:
164+
required: true
165+
166+
- type: textarea
167+
id: logs
168+
attributes:
169+
label: Logs or error output
170+
description: >
171+
The server's stderr, the client's MCP log, or the error the tool
172+
returned. Redact tokens and secrets first.
173+
render: text
174+
validations:
175+
required: false
176+
177+
- type: textarea
178+
id: prompt
179+
attributes:
180+
label: Already prototyped a fix?
181+
description: >
182+
Please don't attach a diff or open a pull request. Share the **exact
183+
prompt(s)** you used to produce the change, the behavior before and
184+
after, and how you verified it. We reproduce it through our own
185+
workflow so it lands with the right conventions, tests and coverage.
186+
validations:
187+
required: false
188+
189+
- type: checkboxes
190+
id: acknowledgements
191+
attributes:
192+
label: Before you submit
193+
options:
194+
- label: I searched existing issues and this is not a duplicate.
195+
required: true
196+
- label: This is not a security vulnerability report (those go through the private advisory form).
197+
required: true
Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Feature request form (GitHub issue forms schema).
2+
#
3+
# Asks for the server and a problem statement first, since the servers are
4+
# reference implementations and a feature is judged by what it demonstrates
5+
# about the protocol (CONTRIBUTING.md, "What we act on"). The server dropdown is
6+
# how triage picks the `server-<name>` scope label; `labels:` below is static.
7+
# `enhancement` is the type label and `v2` the version label: this repository
8+
# has no v1 line, so every issue is a v2 issue (AGENTS.md).
9+
#
10+
# GitHub serves issue forms from the default branch (`main`), so a change here
11+
# goes live at the next milestone merge from `v2/main`, not when it merges.
12+
name: Feature request
13+
description: Suggest an improvement to one of the reference servers
14+
labels: ["enhancement", "v2"]
15+
body:
16+
- type: markdown
17+
attributes:
18+
value: |
19+
Thanks for suggesting an improvement.
20+
21+
**Maintainers do the implementation here**: this repository accepts
22+
**issues, not pull requests**
23+
([`CONTRIBUTING.md`](https://github.com/modelcontextprotocol/servers/blob/main/CONTRIBUTING.md)).
24+
That makes a sharply stated **problem** the most valuable thing you can
25+
give us. It is what we design against, and it survives after a specific
26+
solution turns out not to fit.
27+
28+
These servers are **reference implementations**. We favor changes that
29+
show how a part of the protocol is meant to be used (Resources, Prompts
30+
and Roots as well as Tools) and are selective about other new features.
31+
32+
> **New servers are not accepted here.** To publish or list a server,
33+
> use the [MCP Server Registry](https://github.com/modelcontextprotocol/registry).
34+
35+
- type: dropdown
36+
id: server
37+
attributes:
38+
label: Which server?
39+
options:
40+
- everything (@modelcontextprotocol/server-everything)
41+
- filesystem (@modelcontextprotocol/server-filesystem)
42+
- memory (@modelcontextprotocol/server-memory)
43+
- sequentialthinking (@modelcontextprotocol/server-sequential-thinking)
44+
- fetch (mcp-server-fetch)
45+
- git (mcp-server-git)
46+
- time (mcp-server-time)
47+
- More than one, or the repository itself
48+
validations:
49+
required: true
50+
51+
- type: dropdown
52+
id: spec-era
53+
attributes:
54+
label: Protocol era
55+
description: >
56+
Which revision of the MCP specification the request concerns. Modern is
57+
2026-07-28, the stateless revision; legacy is 2025-11-25 or earlier.
58+
options:
59+
- Modern (2026-07-28)
60+
- Legacy (2025-11-25 or earlier)
61+
- Both, or not era-specific
62+
- Not sure
63+
validations:
64+
required: true
65+
66+
- type: input
67+
id: client
68+
attributes:
69+
label: MCP client
70+
description: The client you use the server with, if it matters to the request.
71+
placeholder: "Claude Desktop, MCP Inspector, a custom SDK client"
72+
validations:
73+
required: false
74+
75+
- type: textarea
76+
id: problem
77+
attributes:
78+
label: The problem
79+
description: >
80+
What are you trying to do, and what makes it hard or impossible today?
81+
Describe the situation, not the feature, including how often you hit it
82+
and what you do instead right now.
83+
validations:
84+
required: true
85+
86+
- type: textarea
87+
id: solution
88+
attributes:
89+
label: Solution you have in mind (optional)
90+
description: >
91+
If you have a concrete idea, describe it here. It's fine to leave this
92+
blank; the problem above is the part we need.
93+
validations:
94+
required: false
95+
96+
- type: textarea
97+
id: protocol
98+
attributes:
99+
label: Which MCP feature does it demonstrate? (optional)
100+
description: >
101+
If the change would show off a part of the protocol (a resource
102+
template, a prompt, Roots, elicitation, and so on), say which, with a
103+
link to the specification section if you have one.
104+
validations:
105+
required: false
106+
107+
- type: textarea
108+
id: alternatives
109+
attributes:
110+
label: Alternatives or workarounds you have tried
111+
validations:
112+
required: false
113+
114+
- type: textarea
115+
id: prompt
116+
attributes:
117+
label: Already built it locally?
118+
description: >
119+
Please don't attach a diff or open a pull request. Share the **exact
120+
prompt(s)** you used, the result, and how you verified it. We reproduce
121+
the work through our own workflow so it lands with the right
122+
conventions, tests and coverage.
123+
validations:
124+
required: false
125+
126+
- type: checkboxes
127+
id: acknowledgements
128+
attributes:
129+
label: Before you submit
130+
options:
131+
- label: I searched existing issues and this is not a duplicate.
132+
required: true
133+
- label: This is a request for one of the servers in this repository, not a new server, the MCP specification or an SDK.
134+
required: true

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Issue chooser configuration (GitHub issue template config schema).
2+
#
3+
# Blank issues are disabled so every report lands in a form: the bug form
4+
# requires the facts triage needs first (server, version, transport, protocol
5+
# era, client), and the feature form requires the server and a problem
6+
# statement.
7+
#
8+
# Security reports are deliberately a *contact link* rather than a form: a form
9+
# would still open a public issue, which is exactly what a vulnerability report
10+
# must not do. The link leaves the issue flow and opens the private advisory
11+
# form; private vulnerability reporting is enabled on this repository.
12+
#
13+
# New servers and server listings are also contact links, to the MCP Server
14+
# Registry, because this repository accepts neither (CONTRIBUTING.md).
15+
#
16+
# GitHub reads this file from the default branch (`main`), so a change here
17+
# goes live at the next milestone merge from `v2/main`, not when it merges.
18+
blank_issues_enabled: false
19+
contact_links:
20+
- name: "🔒 Security vulnerability: report privately"
21+
url: https://github.com/modelcontextprotocol/servers/security/advisories/new
22+
about: >
23+
Never report a vulnerability in a public issue. Private vulnerability
24+
reporting is enabled on this repository, and this link opens the advisory
25+
form. A vulnerability in an MCP SDK goes to that SDK's repository instead.
26+
27+
- name: "📦 New server, or listing a server: use the MCP Server Registry"
28+
url: https://github.com/modelcontextprotocol/registry
29+
about: >
30+
This repository does not accept new server implementations or server
31+
listings. Publish your server to the Registry to make it discoverable;
32+
browse published servers at https://registry.modelcontextprotocol.io/.
33+
34+
- name: '🤝 Contribution policy: why there is no "New pull request"'
35+
url: https://github.com/modelcontextprotocol/servers/blob/main/CONTRIBUTING.md
36+
about: >
37+
This repository accepts issues, not pull requests; maintainers do the
38+
implementation. If you already built a change locally, open an issue and
39+
share the prompt you used rather than a diff.
40+
41+
- name: "📐 MCP specification: protocol questions and proposals"
42+
url: https://github.com/modelcontextprotocol/modelcontextprotocol/issues
43+
about: >
44+
If the behavior you're reporting is defined by the protocol rather than by
45+
one of these servers, file it against the specification repository.
46+
47+
- name: "🧰 MCP SDKs: TypeScript and Python"
48+
url: https://github.com/modelcontextprotocol
49+
about: >
50+
The servers are built on the TypeScript and Python SDKs. If a bug
51+
reproduces against the SDK directly, outside these servers, file it in
52+
that SDK's repository.
53+
54+
- name: "💬 Questions and community"
55+
url: https://modelcontextprotocol.io/community/communication
56+
about: >
57+
Usage questions and discussion: the MCP Contributor Discord and the other
58+
community channels, and how each is used.

0 commit comments

Comments
 (0)