Skip to content

Commit 5abed86

Browse files
authored
Merge pull request #4939 from modelcontextprotocol/v2/chore/4938-contribution-policy-to-main
chore: bring the contribution policy to main ahead of the v2.0.0 merge
2 parents f46d957 + a207787 commit 5abed86

5 files changed

Lines changed: 564 additions & 77 deletions

File tree

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
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 server
49+
- The repository itself (CI, docs, templates, release tooling)
50+
validations:
51+
required: true
52+
53+
- type: input
54+
id: server-version
55+
attributes:
56+
label: Server version
57+
description: >
58+
The version you actually ran, not "latest". For an unreleased build,
59+
give the commit. For a repository-level report, write n/a.
60+
placeholder: "1.0.0 (npm) or 2026.8.1 (PyPI)"
61+
validations:
62+
required: true
63+
64+
- type: dropdown
65+
id: install
66+
attributes:
67+
label: How did you run the server?
68+
options:
69+
- npx (npm package)
70+
- uvx or pip (PyPI package)
71+
- Docker image
72+
- From a clone of this repository
73+
- Other (say which below)
74+
- Not applicable (a repository-level report)
75+
validations:
76+
required: true
77+
78+
- type: dropdown
79+
id: transport
80+
attributes:
81+
label: Transport
82+
description: >
83+
Every server speaks stdio. Only `everything` also serves Streamable HTTP
84+
and the deprecated HTTP+SSE transport.
85+
options:
86+
- stdio
87+
- Streamable HTTP
88+
- HTTP+SSE (deprecated)
89+
- Not sure
90+
- Not applicable (a repository-level report)
91+
validations:
92+
required: true
93+
94+
- type: dropdown
95+
id: spec-era
96+
attributes:
97+
label: Protocol era
98+
description: >
99+
Which revision of the MCP specification the client spoke. Modern is
100+
2026-07-28, the stateless revision: there is no `initialize` handshake,
101+
and the protocol version travels with each request. Legacy is
102+
2025-11-25 or earlier, where the version is agreed in `initialize`.
103+
The client's logs, or the MCP Inspector, show which one was used.
104+
options:
105+
- Modern (2026-07-28)
106+
- Legacy (2025-11-25 or earlier)
107+
- Not sure
108+
- Not applicable (a repository-level report)
109+
validations:
110+
required: true
111+
112+
- type: input
113+
id: client
114+
attributes:
115+
label: MCP client and version
116+
description: >
117+
The client that talked to the server, with its version. For a
118+
repository-level report, write n/a.
119+
placeholder: "Claude Desktop 1.2.3, MCP Inspector 2.0.0, a custom SDK client"
120+
validations:
121+
required: true
122+
123+
- type: input
124+
id: environment
125+
attributes:
126+
label: Operating system and runtime
127+
description: Your OS, plus `node --version` or `python --version` as applicable.
128+
placeholder: "macOS 15.5, Node v22.19.0"
129+
validations:
130+
required: false
131+
132+
- type: textarea
133+
id: config
134+
attributes:
135+
label: Server configuration
136+
description: >
137+
The command, arguments and environment variables the client launched the
138+
server with (for example, the `mcpServers` entry). Redact tokens,
139+
secrets and private paths.
140+
validations:
141+
required: false
142+
143+
- type: textarea
144+
id: repro
145+
attributes:
146+
label: Steps to reproduce
147+
description: >
148+
Numbered steps from a fresh start of the server, including the tool,
149+
resource or prompt you called and its arguments.
150+
placeholder: |
151+
1. Start the server with the configuration above
152+
2. Call `read_text_file` with `{"path": "/allowed/dir/link"}`
153+
3. ...
154+
validations:
155+
required: true
156+
157+
- type: textarea
158+
id: expected
159+
attributes:
160+
label: Expected behavior
161+
description: What you expected to happen.
162+
validations:
163+
required: true
164+
165+
- type: textarea
166+
id: actual
167+
attributes:
168+
label: Actual behavior
169+
description: What happened instead.
170+
validations:
171+
required: true
172+
173+
- type: textarea
174+
id: logs
175+
attributes:
176+
label: Logs or error output
177+
description: >
178+
The server's stderr, the client's MCP log, or the error the tool
179+
returned. Redact tokens and secrets first.
180+
render: text
181+
validations:
182+
required: false
183+
184+
- type: textarea
185+
id: prompt
186+
attributes:
187+
label: Already prototyped a fix?
188+
description: >
189+
Please don't attach a diff or open a pull request. Share the **exact
190+
prompt(s)** you used to produce the change, the behavior before and
191+
after, and how you verified it. We reproduce it through our own
192+
workflow so it lands with the right conventions, tests and coverage.
193+
validations:
194+
required: false
195+
196+
- type: checkboxes
197+
id: acknowledgements
198+
attributes:
199+
label: Before you submit
200+
options:
201+
- label: I searched existing issues and this is not a duplicate.
202+
required: true
203+
- label: This is not a security vulnerability report (those go through the private advisory form).
204+
required: true
Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
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 server
48+
- The repository itself (CI, docs, templates, release tooling)
49+
validations:
50+
required: true
51+
52+
- type: dropdown
53+
id: spec-era
54+
attributes:
55+
label: Protocol era
56+
description: >
57+
Which revision of the MCP specification the request concerns. Modern is
58+
2026-07-28, the stateless revision; legacy is 2025-11-25 or earlier.
59+
options:
60+
- Modern (2026-07-28)
61+
- Legacy (2025-11-25 or earlier)
62+
- Both, or not era-specific
63+
- Not sure
64+
validations:
65+
required: true
66+
67+
- type: input
68+
id: client
69+
attributes:
70+
label: MCP client
71+
description: The client you use the server with, if it matters to the request.
72+
placeholder: "Claude Desktop, MCP Inspector, a custom SDK client"
73+
validations:
74+
required: false
75+
76+
- type: textarea
77+
id: problem
78+
attributes:
79+
label: The problem
80+
description: >
81+
What are you trying to do, and what makes it hard or impossible today?
82+
Describe the situation, not the feature, including how often you hit it
83+
and what you do instead right now.
84+
validations:
85+
required: true
86+
87+
- type: textarea
88+
id: solution
89+
attributes:
90+
label: Solution you have in mind (optional)
91+
description: >
92+
If you have a concrete idea, describe it here. It's fine to leave this
93+
blank; the problem above is the part we need.
94+
validations:
95+
required: false
96+
97+
- type: textarea
98+
id: protocol
99+
attributes:
100+
label: Which MCP feature does it demonstrate? (optional)
101+
description: >
102+
If the change would show off a part of the protocol (a resource
103+
template, a prompt, Roots, elicitation, and so on), say which, with a
104+
link to the specification section if you have one.
105+
validations:
106+
required: false
107+
108+
- type: textarea
109+
id: alternatives
110+
attributes:
111+
label: Alternatives or workarounds you have tried
112+
validations:
113+
required: false
114+
115+
- type: textarea
116+
id: prompt
117+
attributes:
118+
label: Already built it locally?
119+
description: >
120+
Please don't attach a diff or open a pull request. Share the **exact
121+
prompt(s)** you used, the result, and how you verified it. We reproduce
122+
the work through our own workflow so it lands with the right
123+
conventions, tests and coverage.
124+
validations:
125+
required: false
126+
127+
- type: checkboxes
128+
id: acknowledgements
129+
attributes:
130+
label: Before you submit
131+
options:
132+
- label: I searched existing issues and this is not a duplicate.
133+
required: true
134+
- label: This is a request for this repository or one of its servers, not a new server, the MCP specification or an SDK.
135+
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)