-
Notifications
You must be signed in to change notification settings - Fork 871
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
new SQLite server for demo and Getting started guide. Added contribut…
…ing.md and pull_request_template.md
- Loading branch information
Showing
8 changed files
with
774 additions
and
254 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| <!-- Provide a brief description of your changes --> | ||
|
|
||
| ## Description | ||
|
|
||
| ## Server Details | ||
| <!-- If modifying an existing server or adding a new one, provide details --> | ||
| - Server: <!-- e.g., filesystem, github, new-server-name --> | ||
| - Changes to: <!-- e.g., tools, resources, prompts --> | ||
|
|
||
| ## Motivation and Context | ||
| <!-- Why is this change needed? What problem does it solve? --> | ||
|
|
||
| ## How Has This Been Tested? | ||
| <!-- Have you tested this with an LLM client? Which scenarios were tested? --> | ||
|
|
||
| ## Breaking Changes | ||
| <!-- Will users need to update their MCP client configurations? --> | ||
|
|
||
| ## Types of changes | ||
| <!-- What types of changes does your code introduce? Put an `x` in all the boxes that apply: --> | ||
| - [ ] 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 | ||
| <!-- Go over all the following points, and put an `x` in all the boxes that apply. --> | ||
| - [ ] 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 | ||
| <!-- Add any other context, implementation notes, or design decisions --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,21 +1,101 @@ | ||
| # Example MCP servers  | ||
| # Model Context Protocol (MCP) Servers | ||
|
|
||
| Example servers for the Model Context Protocol, to demonstrate the kinds of things you can do! | ||
|  | ||
| [](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 | ||
| npm install -g @modelcontextprotocol/example-servers | ||
| - **[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 example 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. | ||
| ## 🛠️ 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 | ||
|
|
||
| We welcome contributions from the community! Whether you're fixing bugs, adding features to existing servers, or creating entirely new ones, here's how to contribute: | ||
|
|
||
| 1. **Fork & Clone**: | ||
| ```bash | ||
| git clone https://github.com/your-username/mcp-servers.git | ||
| cd mcp-servers | ||
| ``` | ||
|
|
||
| 2. **Install Dependencies**: | ||
| ```bash | ||
| npm install | ||
| ``` | ||
|
|
||
| 3. **Create Your Server**: | ||
| - Add your server in `src/your-server-name/` | ||
| - Include a comprehensive README.md | ||
| - Follow the implementation guidelines from [modelcontextprotocol.io](https://modelcontextprotocol.io) | ||
|
|
||
| 4. **Build & Test**: | ||
| ```bash | ||
| npm run build | ||
| npm test | ||
| ``` | ||
|
|
||
| 5. **Submit a Pull Request**: | ||
| - Describe your changes in detail | ||
| - Reference any related issues | ||
| - Follow the existing code style | ||
|
|
||
| ## 🔒 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! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,62 +1,48 @@ | ||
| # Simple SQLite Notes Server | ||
| # SQLite MCP Server | ||
|
|
||
| A basic MCP server implementation that demonstrates note-taking functionality using the three core MCP primitives: Resources, Prompts, and Tools. | ||
| ## Overview | ||
| A Model Context Protocol (MCP) server implementation that provides database interaction and business intelligence capabilities through SQLite. This server enables running SQL queries, analyzing business data, and automatically generating business insight memos that can be enhanced with Claude's analysis when an Anthropic API key is provided. | ||
|
|
||
| ## Core Concepts | ||
| ## Components | ||
|
|
||
| ### Resources | ||
| Resources are how clients access data from the server. In this case, they're notes stored in SQLite. | ||
|
|
||
| ```python | ||
| # Access notes through a custom URI scheme | ||
| note:///example_note # Gets the content of 'example_note' | ||
| ``` | ||
| The server exposes a single dynamic resource: | ||
| - `memo://insights`: A continuously updated business insights memo that aggregates discovered insights during analysis | ||
| - Auto-updates as new insights are discovered via the append-insight tool | ||
| - Optional enhancement through Claude for professional formatting (requires Anthropic API key) | ||
|
|
||
| ### Prompts | ||
| Prompts allow generating text based on server state. Our server has a note summarization prompt that can be styled. | ||
|
|
||
| ```python | ||
| # Example prompt with style argument | ||
| { | ||
| "name": "summarize-notes", | ||
| "arguments": { | ||
| "style": "academic" # Can be any style descriptor | ||
| } | ||
| } | ||
| ``` | ||
| The server provides a demonstration prompt: | ||
| - `mcp-demo`: Interactive prompt that guides users through database operations | ||
| - Required argument: `topic` - The business domain to analyze | ||
| - Generates appropriate database schemas and sample data | ||
| - Guides users through analysis and insight generation | ||
| - Integrates with the business insights memo | ||
|
|
||
| ### Tools | ||
| Tools modify server state. We have a simple tool to add new notes. | ||
|
|
||
| ```python | ||
| # Adding a new note | ||
| { | ||
| "name": "add-note", | ||
| "arguments": { | ||
| "name": "my_note", | ||
| "content": "This is my note content" | ||
| } | ||
| } | ||
| ``` | ||
| The server offers six core tools: | ||
|
|
||
| ## Key Implementation Details | ||
|
|
||
| ### Handler Registration | ||
| All decorated handlers must be inside `__init__`: | ||
| ```python | ||
| def __init__(self): | ||
| super().__init__("sqlite") | ||
|
|
||
| @self.list_resources() | ||
| async def handle_list_resources(): | ||
| # Handler code here | ||
|
|
||
| @self.read_resource() | ||
| async def handle_read_resource(): | ||
| # Handler code here | ||
| ``` | ||
| #### Query Tools | ||
| - `read-query`: Execute SELECT queries on the database | ||
| - `write-query`: Execute INSERT, UPDATE, or DELETE queries | ||
| - `create-table`: Create new database tables | ||
|
|
||
| #### Schema Tools | ||
| - `list-tables`: Get a list of all tables in the database | ||
| - `describe-table`: View the schema of a specific table | ||
|
|
||
| ### Storage | ||
| - Uses SQLite for persistent storage | ||
| - Helper methods handle database operations | ||
| - Clients are notified of state changes | ||
| #### Analysis Tools | ||
| - `append-insight`: Add new business insights to the memo resource | ||
|
|
||
| ## Installation | ||
|
|
||
| ```bash | ||
| # Required: Python 3.10+ | ||
| python -m pip install mcp-sqlite-server | ||
|
|
||
| # Run with default settings | ||
| mcp-sqlite-server | ||
|
|
||
| # Run with custom database and Anthropic integration | ||
| mcp-sqlite-server --db-path ~/analysis.db --anthropic-key sk-xxx | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.