From c6cccec4e9651bf43c5635a87de8f0a600f30c8f Mon Sep 17 00:00:00 2001 From: Adam Jones Date: Sat, 23 Aug 2025 07:04:42 +0000 Subject: [PATCH 1/3] refactor(CONTRIBUTING.md): streamline contribution guidelines and improve clarity --- CONTRIBUTING.md | 106 ++++++++---------------------------------------- 1 file changed, 17 insertions(+), 89 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 28cba5a6e8..1dfbc4bc0e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,105 +1,33 @@ # Contributing to MCP Servers -Thank you for your interest in contributing to the Model Context Protocol (MCP) servers! This document provides guidelines and instructions for contributing. +Thanks for your interest in contributing! Here's how you can help make this repo better. -## Types of Contributions +We accept changes through [the standard GitHub flow model](https://docs.github.com/en/get-started/using-github/github-flow). -### 1. New Servers +## Server Listings -The repository contains reference implementations, as well as a list of community servers. -We generally don't accept new servers into the repository. We do accept pull requests to the [README.md](./README.md) -adding a reference to your servers. +We welcome PRs that add links to your servers in the [README.md](./README.md)! -Please keep lists in alphabetical order to minimize merge conflicts when adding new items. +## Server Implementations -- Check the [modelcontextprotocol.io](https://modelcontextprotocol.io) documentation -- Ensure your server doesn't duplicate existing functionality -- Consider whether your server would be generally useful to others -- Follow [security best practices](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations) from the MCP documentation -- Create a PR adding a link to your server to the [README.md](./README.md). +We welcome: +- **Bug fixes** — Help us squash those pesky bugs. +- **Ergonomic improvements** — Making servers easier to use for humans and agents. -### 2. Improvements to Existing Servers -Enhancements to existing servers are welcome! This includes: +We're more selective about: +- **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! We think a diverse ecosystem of servers is beneficial for everyone, and would love to link to your improved server in our README. -- Bug fixes -- Performance improvements -- New features -- Security enhancements +We don't accept: +- **New server implementations** — We encourage you to publish them yourself, and link to them from the README. -### 3. Documentation -Documentation improvements are always welcome: +## Documentation -- Fixing typos or unclear instructions -- Adding examples -- Improving setup instructions -- Adding troubleshooting guides +Improvements to existing documentation is welcome - although generally we'd prefer ergonomic improvements than documenting pain points if possible! -## Getting Started - -1. Fork the repository -2. Clone your fork: - ```bash - git clone https://github.com/your-username/servers.git - ``` -3. Add the upstream remote: - ```bash - git remote add upstream https://github.com/modelcontextprotocol/servers.git - ``` -4. Create a branch: - ```bash - git checkout -b my-feature - ``` - -## Development Guidelines - -### Code Style -- Follow the existing code style in the repository -- Include appropriate type definitions -- Add comments for complex logic - -### Documentation -- Include a detailed README.md in your server directory -- Document all configuration options -- Provide setup instructions -- Include usage examples - -### Security -- Follow security best practices -- Implement proper input validation -- Handle errors appropriately -- Document security considerations - -## Submitting Changes - -1. Commit your changes: - ```bash - git add . - git commit -m "Description of changes" - ``` -2. Push to your fork: - ```bash - git push origin my-feature - ``` -3. Create a Pull Request through GitHub - -### Pull Request Guidelines - -- Thoroughly test your changes -- Fill out the pull request template completely -- Link any related issues -- Provide clear description of changes -- Include any necessary documentation updates -- Add screenshots for UI changes -- List any breaking changes +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 -- Participate in [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions) -- Follow the [Code of Conduct](CODE_OF_CONDUCT.md) - -## Questions? - -- Check the [documentation](https://modelcontextprotocol.io) -- Ask in GitHub Discussions +[Learn how the MCP community communicates](https://modelcontextprotocol.io/community/communication). -Thank you for contributing to MCP Servers! +Thank you for helping make MCP servers better for everyone! \ No newline at end of file From 414f98c35ed7e513480fe2fd0a999bb784b2bcd0 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Mon, 25 Aug 2025 17:42:12 +0000 Subject: [PATCH 2/3] Apply review feedback: improve language accessibility and add MCP protocol features guidance - Replace 'Ergonomic improvements' with 'Usability improvements' for better accessibility - Add guidance encouraging enhancements that demonstrate underutilized MCP protocol features Co-authored-by: adam jones --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1dfbc4bc0e..4f47551c93 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,10 +12,11 @@ We welcome PRs that add links to your servers in the [README.md](./README.md)! We welcome: - **Bug fixes** — Help us squash those pesky bugs. -- **Ergonomic improvements** — Making servers easier to use for humans and agents. +- **Usability improvements** — Making servers easier to use for humans and agents. We're more selective about: - **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! We think a diverse ecosystem of servers is beneficial for everyone, and would love to link to your improved server in our README. +- **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. We don't accept: - **New server implementations** — We encourage you to publish them yourself, and link to them from the README. From 9b6892dc9abc045471b2df8773c69fdb8abb2828 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Mon, 25 Aug 2025 17:45:48 +0000 Subject: [PATCH 3/3] Reorganize CONTRIBUTING.md: move MCP protocol features to 'we welcome' section and rename to 'other new features' Co-authored-by: adam jones --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f47551c93..7a10a22f93 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,10 +13,10 @@ We welcome PRs that add links to your servers in the [README.md](./README.md)! 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. We're more selective about: -- **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! We think a diverse ecosystem of servers is beneficial for everyone, and would love to link to your improved server in our README. -- **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. +- **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! We think a diverse ecosystem of servers is beneficial for everyone, and would love to link to your improved server in our README. We don't accept: - **New server implementations** — We encourage you to publish them yourself, and link to them from the README.