diff --git a/.github/ISSUE_TEMPLATE/1-bug_report.yml b/.github/ISSUE_TEMPLATE/1-bug_report.yml new file mode 100644 index 0000000000..752ceb698c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/1-bug_report.yml @@ -0,0 +1,204 @@ +# Bug report form (GitHub issue forms schema). +# +# Requires the facts triage needs before anything else: which server, its +# version, how it was run, the transport, the protocol era the client speaks, +# and the client itself. The server dropdown is how triage picks the +# `server-` scope label; `labels:` below is static, so it cannot apply +# that label itself. `bug` is the type label and `v2` the version label: this +# repository has no v1 line, so every issue is a v2 issue (AGENTS.md). +# +# GitHub serves issue forms from the default branch (`main`), so a change here +# goes live at the next milestone merge from `v2/main`, not when it merges. +name: Bug report +description: Report something broken in one of the reference servers +labels: ["bug", "v2"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting a bug. **Issues are how work reaches these servers.** + + This repository accepts **issues, not pull requests**: design and + implementation are done by the maintainers through a prompt-driven + workflow ([`CONTRIBUTING.md`](https://github.com/modelcontextprotocol/servers/blob/main/CONTRIBUTING.md)). + So if you have already prototyped a fix locally, **the prompt you used + is worth more to us than a diff**. There is a field for it at the bottom + of this form. + + > 🔒 **Do not report security vulnerabilities here.** Use the + > [private advisory form](https://github.com/modelcontextprotocol/servers/security/advisories/new) + > instead. + + - type: dropdown + id: server + attributes: + label: Which server? + description: > + The servers in this repository. A server you found in the MCP Server + Registry or elsewhere is maintained by its own authors; report its bugs + to them. + options: + - everything (@modelcontextprotocol/server-everything) + - filesystem (@modelcontextprotocol/server-filesystem) + - memory (@modelcontextprotocol/server-memory) + - sequentialthinking (@modelcontextprotocol/server-sequential-thinking) + - fetch (mcp-server-fetch) + - git (mcp-server-git) + - time (mcp-server-time) + - More than one server + - The repository itself (CI, docs, templates, release tooling) + validations: + required: true + + - type: input + id: server-version + attributes: + label: Server version + description: > + The version you actually ran, not "latest". For an unreleased build, + give the commit. For a repository-level report, write n/a. + placeholder: "1.0.0 (npm) or 2026.8.1 (PyPI)" + validations: + required: true + + - type: dropdown + id: install + attributes: + label: How did you run the server? + options: + - npx (npm package) + - uvx or pip (PyPI package) + - Docker image + - From a clone of this repository + - Other (say which below) + - Not applicable (a repository-level report) + validations: + required: true + + - type: dropdown + id: transport + attributes: + label: Transport + description: > + Every server speaks stdio. Only `everything` also serves Streamable HTTP + and the deprecated HTTP+SSE transport. + options: + - stdio + - Streamable HTTP + - HTTP+SSE (deprecated) + - Not sure + - Not applicable (a repository-level report) + validations: + required: true + + - type: dropdown + id: spec-era + attributes: + label: Protocol era + description: > + Which revision of the MCP specification the client spoke. Modern is + 2026-07-28, the stateless revision: there is no `initialize` handshake, + and the protocol version travels with each request. Legacy is + 2025-11-25 or earlier, where the version is agreed in `initialize`. + The client's logs, or the MCP Inspector, show which one was used. + options: + - Modern (2026-07-28) + - Legacy (2025-11-25 or earlier) + - Not sure + - Not applicable (a repository-level report) + validations: + required: true + + - type: input + id: client + attributes: + label: MCP client and version + description: > + The client that talked to the server, with its version. For a + repository-level report, write n/a. + placeholder: "Claude Desktop 1.2.3, MCP Inspector 2.0.0, a custom SDK client" + validations: + required: true + + - type: input + id: environment + attributes: + label: Operating system and runtime + description: Your OS, plus `node --version` or `python --version` as applicable. + placeholder: "macOS 15.5, Node v22.19.0" + validations: + required: false + + - type: textarea + id: config + attributes: + label: Server configuration + description: > + The command, arguments and environment variables the client launched the + server with (for example, the `mcpServers` entry). Redact tokens, + secrets and private paths. + validations: + required: false + + - type: textarea + id: repro + attributes: + label: Steps to reproduce + description: > + Numbered steps from a fresh start of the server, including the tool, + resource or prompt you called and its arguments. + placeholder: | + 1. Start the server with the configuration above + 2. Call `read_text_file` with `{"path": "/allowed/dir/link"}` + 3. ... + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What you expected to happen. + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual behavior + description: What happened instead. + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Logs or error output + description: > + The server's stderr, the client's MCP log, or the error the tool + returned. Redact tokens and secrets first. + render: text + validations: + required: false + + - type: textarea + id: prompt + attributes: + label: Already prototyped a fix? + description: > + Please don't attach a diff or open a pull request. Share the **exact + prompt(s)** you used to produce the change, the behavior before and + after, and how you verified it. We reproduce it through our own + workflow so it lands with the right conventions, tests and coverage. + validations: + required: false + + - type: checkboxes + id: acknowledgements + attributes: + label: Before you submit + options: + - label: I searched existing issues and this is not a duplicate. + required: true + - label: This is not a security vulnerability report (those go through the private advisory form). + required: true diff --git a/.github/ISSUE_TEMPLATE/2-feature_request.yml b/.github/ISSUE_TEMPLATE/2-feature_request.yml new file mode 100644 index 0000000000..32ca5fe830 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/2-feature_request.yml @@ -0,0 +1,135 @@ +# Feature request form (GitHub issue forms schema). +# +# Asks for the server and a problem statement first, since the servers are +# reference implementations and a feature is judged by what it demonstrates +# about the protocol (CONTRIBUTING.md, "What we act on"). The server dropdown is +# how triage picks the `server-` scope label; `labels:` below is static. +# `enhancement` is the type label and `v2` the version label: this repository +# has no v1 line, so every issue is a v2 issue (AGENTS.md). +# +# GitHub serves issue forms from the default branch (`main`), so a change here +# goes live at the next milestone merge from `v2/main`, not when it merges. +name: Feature request +description: Suggest an improvement to one of the reference servers +labels: ["enhancement", "v2"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting an improvement. + + **Maintainers do the implementation here**: this repository accepts + **issues, not pull requests** + ([`CONTRIBUTING.md`](https://github.com/modelcontextprotocol/servers/blob/main/CONTRIBUTING.md)). + That makes a sharply stated **problem** the most valuable thing you can + give us. It is what we design against, and it survives after a specific + solution turns out not to fit. + + These servers are **reference implementations**. We favor changes that + show how a part of the protocol is meant to be used (Resources, Prompts + and Roots as well as Tools) and are selective about other new features. + + > **New servers are not accepted here.** To publish or list a server, + > use the [MCP Server Registry](https://github.com/modelcontextprotocol/registry). + + - type: dropdown + id: server + attributes: + label: Which server? + options: + - everything (@modelcontextprotocol/server-everything) + - filesystem (@modelcontextprotocol/server-filesystem) + - memory (@modelcontextprotocol/server-memory) + - sequentialthinking (@modelcontextprotocol/server-sequential-thinking) + - fetch (mcp-server-fetch) + - git (mcp-server-git) + - time (mcp-server-time) + - More than one server + - The repository itself (CI, docs, templates, release tooling) + validations: + required: true + + - type: dropdown + id: spec-era + attributes: + label: Protocol era + description: > + Which revision of the MCP specification the request concerns. Modern is + 2026-07-28, the stateless revision; legacy is 2025-11-25 or earlier. + options: + - Modern (2026-07-28) + - Legacy (2025-11-25 or earlier) + - Both, or not era-specific + - Not sure + validations: + required: true + + - type: input + id: client + attributes: + label: MCP client + description: The client you use the server with, if it matters to the request. + placeholder: "Claude Desktop, MCP Inspector, a custom SDK client" + validations: + required: false + + - type: textarea + id: problem + attributes: + label: The problem + description: > + What are you trying to do, and what makes it hard or impossible today? + Describe the situation, not the feature, including how often you hit it + and what you do instead right now. + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Solution you have in mind (optional) + description: > + If you have a concrete idea, describe it here. It's fine to leave this + blank; the problem above is the part we need. + validations: + required: false + + - type: textarea + id: protocol + attributes: + label: Which MCP feature does it demonstrate? (optional) + description: > + If the change would show off a part of the protocol (a resource + template, a prompt, Roots, elicitation, and so on), say which, with a + link to the specification section if you have one. + validations: + required: false + + - type: textarea + id: alternatives + attributes: + label: Alternatives or workarounds you have tried + validations: + required: false + + - type: textarea + id: prompt + attributes: + label: Already built it locally? + description: > + Please don't attach a diff or open a pull request. Share the **exact + prompt(s)** you used, the result, and how you verified it. We reproduce + the work through our own workflow so it lands with the right + conventions, tests and coverage. + validations: + required: false + + - type: checkboxes + id: acknowledgements + attributes: + label: Before you submit + options: + - label: I searched existing issues and this is not a duplicate. + required: true + - label: This is a request for this repository or one of its servers, not a new server, the MCP specification or an SDK. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000000..e05ce1099f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,58 @@ +# Issue chooser configuration (GitHub issue template config schema). +# +# Blank issues are disabled so every report lands in a form: the bug form +# requires the facts triage needs first (server, version, transport, protocol +# era, client), and the feature form requires the server and a problem +# statement. +# +# Security reports are deliberately a *contact link* rather than a form: a form +# would still open a public issue, which is exactly what a vulnerability report +# must not do. The link leaves the issue flow and opens the private advisory +# form; private vulnerability reporting is enabled on this repository. +# +# New servers and server listings are also contact links, to the MCP Server +# Registry, because this repository accepts neither (CONTRIBUTING.md). +# +# GitHub reads this file from the default branch (`main`), so a change here +# goes live at the next milestone merge from `v2/main`, not when it merges. +blank_issues_enabled: false +contact_links: + - name: "🔒 Security vulnerability: report privately" + url: https://github.com/modelcontextprotocol/servers/security/advisories/new + about: > + Never report a vulnerability in a public issue. Private vulnerability + reporting is enabled on this repository, and this link opens the advisory + form. A vulnerability in an MCP SDK goes to that SDK's repository instead. + + - name: "📦 New server, or listing a server: use the MCP Server Registry" + url: https://github.com/modelcontextprotocol/registry + about: > + This repository does not accept new server implementations or server + listings. Publish your server to the Registry to make it discoverable; + browse published servers at https://registry.modelcontextprotocol.io/. + + - name: '🤝 Contribution policy: why there is no "New pull request"' + url: https://github.com/modelcontextprotocol/servers/blob/main/CONTRIBUTING.md + about: > + This repository accepts issues, not pull requests; maintainers do the + implementation. If you already built a change locally, open an issue and + share the prompt you used rather than a diff. + + - name: "📐 MCP specification: protocol questions and proposals" + url: https://github.com/modelcontextprotocol/modelcontextprotocol/issues + about: > + If the behavior you're reporting is defined by the protocol rather than by + one of these servers, file it against the specification repository. + + - name: "🧰 MCP SDKs: TypeScript and Python" + url: https://github.com/modelcontextprotocol + about: > + The servers are built on the TypeScript and Python SDKs. If a bug + reproduces against the SDK directly, outside these servers, file it in + that SDK's repository. + + - name: "💬 Questions and community" + url: https://modelcontextprotocol.io/community/communication + about: > + Usage questions and discussion: the MCP Contributor Discord and the other + community channels, and how each is used. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index dd93c47980..90f4c2921e 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,44 +1,6 @@ - - -## Description - -## Publishing Your Server - -**Note: We are no longer accepting PRs to add servers to the README.** Instead, please publish your server to the [MCP Server Registry](https://github.com/modelcontextprotocol/registry) to make it discoverable to the MCP ecosystem. - -To publish your server, follow the [quickstart guide](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/quickstart.mdx). You can browse published servers at [https://registry.modelcontextprotocol.io/](https://registry.modelcontextprotocol.io/). - -## Server Details - -- Server: -- Changes to: - -## Motivation and Context - - -## How Has This Been Tested? - - -## Breaking Changes - - -## Types of changes - -- [ ] Bug fix (non-breaking change which fixes an issue) -- [ ] New feature (non-breaking change which adds functionality) -- [ ] Breaking change (fix or feature that would cause existing functionality to change) -- [ ] Documentation update - -## Checklist - -- [ ] I have read the [MCP Protocol Documentation](https://modelcontextprotocol.io) -- [ ] My changes follows MCP security best practices -- [ ] I have updated the server's README accordingly -- [ ] I have tested this with an LLM client -- [ ] My code follows the repository's style guidelines -- [ ] New and existing tests pass locally -- [ ] I have added appropriate error handling -- [ ] I have documented all environment variables and configuration options - -## Additional context - +> **Heads up:** this repository accepts **issues, not pull requests**, from +> anyone but the repository maintainers. Please read +> [`CONTRIBUTING.md`](https://github.com/modelcontextprotocol/servers/blob/main/CONTRIBUTING.md) before continuing. If you're not a +> maintainer, open an issue (and share the prompt you used, if you've already +> built the change) rather than this PR. To make a server discoverable, publish +> it to the [MCP Server Registry](https://github.com/modelcontextprotocol/registry). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8ce9a21dd6..dcb466b864 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,40 +1,168 @@ # Contributing to MCP Servers -Thanks for your interest in contributing! Here's how you can help make this repo better. - -We accept changes through [the standard GitHub flow model](https://docs.github.com/en/get-started/using-github/github-flow). - -## Server Listings - -The README no longer contains a list of third-party MCP servers — that list has been retired in favor of the [MCP Server Registry](https://github.com/modelcontextprotocol/registry). To make your server discoverable, follow the [quickstart guide](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/quickstart.mdx) to publish it there. - -You can browse published servers at [https://registry.modelcontextprotocol.io/](https://registry.modelcontextprotocol.io/). - -## Server Implementations - -We welcome: -- **Bug fixes** — Help us squash those pesky bugs. -- **Usability improvements** — Making servers easier to use for humans and agents. -- **Enhancements that demonstrate MCP protocol features** — We encourage contributions that help reference servers better illustrate underutilized aspects of the MCP protocol beyond just Tools, such as Resources, Prompts, or Roots. For example, adding Roots support to filesystem-server helps showcase this important but lesser-known feature. +Thank you for your interest in improving the MCP reference servers. Contributors +are genuinely valued, and this document explains how to get your input into a +form the maintainers can act on quickly and consistently. + +## TL;DR + +**We accept issues, not pull requests.** Design and implementation are done by +the repository maintainers. If you've already built a fix or feature locally, +share **the prompt you used** to produce it, not the source code. This applies +to everyone outside the repository maintainers, including organization members +who happen to have write access to this repository. + +## Why this policy exists + +The reference servers are developed with an AI-assisted, prompt-driven workflow +built around shared conventions and strict gates (see [`AGENTS.md`](./AGENTS.md)): +seven independently published packages in two languages, each with its own +tests, type checks, lint and release steps, all tracked on one project board. + +A diff written outside that workflow has to be reverse-engineered to fit those +conventions, tests and gates, and it is often faster to re-derive the change than +to adapt the patch. Many outside pull requests also race each other for the same +bug. A well-formed issue captures your **intent**, and the **prompt** behind a +local change lets us reproduce the work inside our own workflow, with the quality +bar already built in. + +This policy is about efficiency, not gatekeeping. Your bug reports, ideas and +prompts directly shape what gets built. + +## Who opens pull requests + +Pull requests against this repository are opened by the **repository +maintainers** only. That includes organization members with write access: being +able to push a branch here is not the same as being asked to. The constraint is +the workflow described above, not permissions. + +If you're not a repository maintainer, open a **detailed issue** instead and a +maintainer will pick it up. A pull request from anyone else is closed with a +pointer back to this document; if it held a fix worth keeping, a maintainer files +an issue for it first, so the work is not lost. + +**Every pull request references an issue**, including the maintainers' own. Work +is tracked on the project board through issues, so a PR without one is invisible +to the board. That is why a well-formed issue is the useful contribution here, +and why writing one is never wasted effort. + +## How to report a bug or request a feature + +Open a well-formed issue. [**New issue**](https://github.com/modelcontextprotocol/servers/issues/new/choose) +offers a **Bug report** and a **Feature request** form, and both start by asking +which server the issue is about. The bug form also asks for the server version, +how you ran it, the transport, the protocol era your client speaks and the client +you used, because those are the facts triage needs first. + +GitHub serves the issue chooser from the repository's **default branch** +(`main`), and development happens on `v2/main`, which reaches `main` at milestone +releases. So a change to the forms goes live at the next milestone merge, not +when it merges into `v2/main`. + +The chooser also links to the private security-advisory form and to the MCP +Server Registry. **Never report a security vulnerability in a public issue**; use +[the private advisory form](https://github.com/modelcontextprotocol/servers/security/advisories/new) +instead. + +### What we act on + +The servers here are **reference implementations**, meant to show how each part +of the protocol is used, not general-purpose products. Issues are most likely to +be picked up when they ask for: + +- **Bug fixes.** +- **Usability improvements**: making the servers easier to use for humans and + agents. +- **Enhancements that demonstrate MCP protocol features.** We especially want the + reference servers to illustrate underused parts of the protocol beyond Tools, + such as Resources, Prompts or Roots. For example, adding Roots support to the + filesystem server showcases an important but lesser-known feature. We're more selective about: -- **Other new features** — Especially if they're not crucial to the server's core purpose or are highly opinionated. The existing servers are reference servers meant to inspire the community. If you need specific features, we encourage you to build enhanced versions and publish them to the [MCP Server Registry](https://github.com/modelcontextprotocol/registry)! We think a diverse ecosystem of servers is beneficial for everyone. - -We don't accept: -- **New server implementations** — We encourage you to publish them to the [MCP Server Registry](https://github.com/modelcontextprotocol/registry) instead. - -## Testing - -When adding or configuring tests for servers implemented in TypeScript, use **vitest** as the test framework. Vitest provides better ESM support, faster test execution, and a more modern testing experience. - -## Documentation -Improvements to existing documentation is welcome - although generally we'd prefer ergonomic improvements than documenting pain points if possible! +- **Other new features**, especially ones that are not central to a server's + purpose or are highly opinionated. If you need a specific feature, we encourage + you to build an enhanced version and publish it to the + [MCP Server Registry](https://github.com/modelcontextprotocol/registry). A + diverse ecosystem of servers is good for everyone. +- **Wholly new documentation**, especially if it is not vendor neutral (for + example, how to run a particular server with a particular client). + Improvements to existing documentation are welcome, though we generally prefer + fixing the rough edge to documenting it. -We're more selective about adding wholly new documentation, especially in ways that aren't vendor neutral (e.g. how to run a particular server with a particular client). - -## Community - -[Learn how the MCP community communicates](https://modelcontextprotocol.io/community/communication). +We don't accept: -Thank you for helping make MCP servers better for everyone! \ No newline at end of file +- **New server implementations.** Publish them to the + [MCP Server Registry](https://github.com/modelcontextprotocol/registry) + instead. +- **Server listings.** The README's list of third-party servers has been retired + in favor of the Registry. To make your server discoverable, follow the + Registry's [quickstart guide](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/quickstart.mdx). + You can browse published servers at + [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/). + +## 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. +- **The behavior before and after** your change. +- **How you verified it**: the steps you ran, the tests you added, what you + observed, and the MCP client you tried it with. + +We'll reproduce the change through our workflow so it lands with the right +conventions, tests and coverage. + +## What makes a good issue + +A great issue gives us everything we need to act without a round-trip: + +- **The server** it concerns (`everything`, `filesystem`, `memory`, + `sequentialthinking`, `fetch`, `git` or `time`), and its version. +- **A clear reproduction or use case**: exact steps to reproduce a bug, or a + concrete description of the problem a feature would solve. +- **Expected and actual behavior**: what you expected, and what you saw instead. +- **The client and environment**: the MCP client and its version, the protocol + era it speaks, the transport, how you ran the server (`npx`, `uvx`, Docker, from + source), your OS, and the relevant configuration with secrets redacted. +- **The exact prompt text**, if you generated a local change. + +If you're unsure how to scope something, open the issue anyway and say so. We'll +help shape it. + +## Want to work on the servers with us? + +The issues-only policy is about how **unsolicited patches** are handled; it is not +a closed door. If you'd like to contribute at a deeper level, in general or in a +specific area, we'd like to hear from you. See +[how the MCP community communicates](https://modelcontextprotocol.io/community/communication) +for the Contributor Discord, the community calls, and how each channel is used. +From there we can scope a piece of work with you and supervise it through our +workflow. + +All participation is governed by the [Code of Conduct](./CODE_OF_CONDUCT.md). + +## For maintainers + +The rules for maintainers and the agents working for them are in +[`AGENTS.md`](./AGENTS.md), and the procedures are in the skills it indexes. Before +pushing, run `npm run format` at the repository root and then +**`npm run local:gate`**, which runs every check CI runs for both languages: +the repo-wide guards, each TypeScript server's `validate` (format check, lint +where a warning fails like an error, typecheck, build, tests), each Python +server's `validate:py` chain, the skills validator, and a boot smoke of every +server. [`docs/quality-gate.md`](./docs/quality-gate.md) describes each stage. +While iterating, `npm run validate -w src/` checks a single TypeScript +server and `npm run validate:py -- ` a single Python one; neither +replaces the gate. + +A pull request that changes what a TypeScript server publishes also carries a +**changeset** (`npm run changeset`), which is how that server's next version +and its CHANGELOG entry are decided; [`.changeset/README.md`](./.changeset/README.md) +says when one is needed and which bump to pick. The Python servers are versioned +by date instead. [`RELEASING.md`](./RELEASING.md) describes both, and how a +release is published. + +Thank you for helping make the MCP servers better for everyone!