diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..f6d5e1a8 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,39 @@ + + +## Description + +## Server Details + +- Server: +- Changes to: + +## Motivation and Context + + +## How Has This Been Tested? + + +## Breaking Changes + + +## Types of changes + +- [ ] New MCP Server +- [ ] 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 server 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 + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..c76c0687 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,111 @@ +# 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. + +## Types of Contributions + +### 1. New Servers +Adding new servers is one of the most valuable ways to contribute. Before creating a new server: + +- 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 from the MCP documentation + +### 2. Improvements to Existing Servers +Enhancements to existing servers are welcome! This includes: + +- Bug fixes +- Performance improvements +- New features +- Documentation improvements +- Security enhancements + +### 3. Documentation +Documentation improvements are always welcome: + +- Fixing typos or unclear instructions +- Adding examples +- Improving setup instructions +- Adding troubleshooting guides + +## Getting Started + +1. Fork the repository +2. Clone your fork: + ```bash + git clone https://github.com/your-username/mcp-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 +- Use TypeScript for JavaScript/Node.js servers +- 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 + +### Testing +- Add appropriate tests for new functionality +- Ensure existing tests pass +- Test your changes thoroughly + +### 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 + +- 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 + +## Review Process + +1. Maintainers will review your PR +2. Address any requested changes +3. Once approved, your PR will be merged + +## Community + +- Participate in [GitHub Discussions](https://github.com/modelcontextprotocol/servers/discussions) +- Follow the [Code of Conduct](CODE_OF_CONDUCT.md) + +## Questions? + +- Check the [documentation](https://modelcontextprotocol.io) +- Ask in GitHub Discussions + +Thank you for contributing to MCP Servers! \ No newline at end of file diff --git a/README.md b/README.md index 782a8278..dc5fc6e9 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,73 @@ # MCP servers ![NPM Version](https://img.shields.io/npm/v/%40modelcontextprotocol%2Fexample-servers) -Example servers for the Model Context Protocol, to demonstrate the kinds of things you can do! +[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) -## Getting started +A collection of reference implementations and community-contributed servers for the Model Context Protocol (MCP). This repository showcases the versatility and extensibility of MCP, demonstrating how it can be used to give Large Language Models (LLMs) secure, controlled access to external tools and data sources. -Install from npm: +## 🌟 Featured Servers -```sh +- **[Filesystem](src/filesystem)** - Secure file operations with configurable access controls +- **[GitHub](src/github)** - Repository management, file operations, and GitHub API integration +- **[Google Drive](src/gdrive)** - File access and search capabilities for Google Drive +- **[PostgreSQL](src/postgres)** - Read-only database access with schema inspection +- **[Slack](src/slack)** - Channel management and messaging capabilities +- **[Memory](src/memory)** - Knowledge graph-based persistent memory system +- **[Puppeteer](src/puppeteer)** - Browser automation and web scraping +- **[Brave Search](src/brave-search)** - Web and local search using Brave's API +- **[Google Maps](src/google-maps)** - Location services, directions, and place details + +## 🚀 Getting Started + +### Installation + +```bash +# Install all servers globally npm install -g @modelcontextprotocol/servers + +# Or install individual servers +npm install -g @modelcontextprotocol/server-github +npm install -g @modelcontextprotocol/server-filesystem +# etc... ``` -Then, the servers will be globally available on your PATH: +### Usage + +Each server can be run directly from the command line: -```sh -mcp-server-everything -mcp-server-postgres -# ... +```bash +mcp-server-github +mcp-server-filesystem ~/allowed/path +mcp-server-postgres "postgresql://localhost/mydb" ``` -Each server will operate differently. See the READMEs within [src](src/) for more information. \ No newline at end of file +## 🛠️ Creating Your Own Server + +Interested in creating your own MCP server? Visit the official documentation at [modelcontextprotocol.io/introduction](https://modelcontextprotocol.io/introduction) for comprehensive guides, best practices, and technical details on implementing MCP servers. + +## 🤝 Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for information about contributing to the MCP servers repository. + +## 🔒 Security + +See [SECURITY.md](SECURITY.md) for reporting security vulnerabilities. + +## 📜 License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## 💬 Community + +- [Discord](https://discord.gg/modelcontextprotocol) +- [GitHub Discussions](https://github.com/modelcontextprotocol/servers/discussions) + +## ⭐ Support + +If you find MCP servers useful, please consider: +- Starring the repository +- Contributing new servers or improvements +- Sharing your experience with the community + +--- + +Managed by Anthropic, but built together with the community. The Model Context Protocol is open source and we encourage everyone to contribute their own servers and improvements!