OpenGathyr

# OpenGathyr <img src="logo.svg" alt="OpenGathyr Logo" align="right" width="200" /> An open-source Model Context Protocol (MCP) server powered by RSS feeds. [](https://opensource.org/licenses/MIT) [](CONTRIBUTING.md) ## What is OpenGathyr? OpenGathyr transforms how you manage content feeds by providing a centralized hub that collects, processes, and distributes RSS/Atom feeds. Unlike traditional aggregators, OpenGathyr functions as a complete Model Context Protocol (MCP) server for your feed ecosystem. ### Key Features - **MCP Tools Integration**: Expose RSS feed functionality through standardized Model Context Protocol tools - **Automated Feed Refreshing**: Configurable periodic fetching of RSS feeds to ensure fresh content - **Content Search**: Search across all RSS feeds with a unified query interface - **Feed Management**: Add, remove, and list RSS feeds dynamically - **Environment Configuration**: Easy setup using environment variables for feed sources and settings - **Docker Ready**: Containerized deployment support for both local and production environments - **Modular Architecture**: Cleanly separated components for easier maintenance and extensibility ## Getting Started ### Prerequisites - Node.js 22.x or higher - npm 7.x or higher - Docker (optional, for containerized deployment) ### Installation 1. Clone the repository: ```bash git clone https://github.com/yourusername/opengathyr.git cd opengathyr ``` 2. Install dependencies: ```bash npm install ``` 3. Create a `.env` file with your configuration (see Configuration section) 4. Build the project: ```bash npm run build ``` 5. Start the server: ```bash npm start ``` For development with auto-reload: ```bash npm run dev ``` ### Docker Deployment To run the server in a Docker container: ```bash # Build the Docker image docker build -t opengathyr . # Run the container docker run -it opengathyr ``` ## Configuration The server can be configured using environment variables: - `MCP_SERVER_NAME`: Name of the MCP server - `MCP_SERVER_VERSION`: Version of the MCP server - `RSS_FEED_URL_1`, `RSS_FEED_URL_2`, etc.: Individual RSS feed URLs (one URL per variable) - `RSS_REFRESH_INTERVAL`: Refresh interval in milliseconds (default: 300000 = 5 minutes) - `RSS_MAX_ITEMS`: Maximum number of items to keep per feed (default: 20) ### Example .env file ``` MCP_SERVER_NAME=opengathyr MCP_SERVER_VERSION=1.0.0 # RSS Feed URLs - one per line RSS_FEED_URL_1=https://news.google.com/rss RSS_FEED_URL_2=https://example.com/feed.xml RSS_FEED_URL_3=https://another-site.org/rss RSS_REFRESH_INTERVAL=300000 RSS_MAX_ITEMS=20 ``` ## Available MCP Tools ### get-feed Retrieves the content from a specific feed. **Parameters:** - `feedName`: Name of the feed to retrieve ### search-feeds Searches across all configured feeds for matching content. **Parameters:** - `query`: Search term to look for in feed titles and content ### list-feeds Lists all currently configured feeds and their details. **Parameters:** None ### add-feed Adds a new RSS feed to be monitored. **Parameters:** - `name`: Identifier for the feed - `url`: URL of the RSS feed - `refreshInterval` (optional): Refresh interval in milliseconds - `maxItems` (optional): Maximum number of items to keep ### remove-feed Removes an RSS feed from monitoring. **Parameters:** - `feedName`: Name of the feed to remove ## Using with VS Code ### GitHub Copilot Integration To use OpenGathyr with GitHub Copilot in VS Code, you need to configure it as an MCP server in your Copilot settings. #### Setup Steps 1. **Build the MCP Server:** ```bash npm run build ``` 2. **Configure Copilot MCP Settings:** Create or edit your Copilot configuration file. The location depends on your VS Code setup: - **Windows:** `%APPDATA%\Code\User\globalStorage\github.copilot-chat\mcpServers.json` - **macOS:** `~/Library/Application Support/Code/User/globalStorage/github.copilot-chat/mcpServers.json` - **Linux:** `~/.config/Code/User/globalStorage/github.copilot-chat/mcpServers.json` Add your OpenGathyr server configuration: ```json { "mcpServers": { "opengathyr": { "command": "node", "args": ["dist/index.js"], "cwd": "a:\\OpenGathyr", "env": { "MCP_SERVER_NAME": "opengathyr", "MCP_SERVER_VERSION": "1.0.0", "RSS_FEED_URL_1": "https://news.google.com/rss", "RSS_FEED_URL_2": "https://feeds.bbci.co.uk/news/rss.xml", "RSS_REFRESH_INTERVAL": "300000", "RSS_MAX_ITEMS": "20" } } } } ``` 3. **Restart VS Code** to apply the configuration changes. 4. **Verify Connection:** Open GitHub Copilot Chat and try using the RSS feed tools: ```text @opengathyr list-feeds @opengathyr get-feed news @opengathyr search-feeds "technology" ``` #### Available Commands in Copilot Chat Once configured, you can use these commands in GitHub Copilot Chat: - **`@opengathyr list-feeds`** - Lists all configured RSS feeds - **`@opengathyr get-feed <feedName>`** - Gets content from a specific feed - **`@opengathyr search-feeds <query>`** - Searches across all feeds - **`@opengathyr add-feed <name> <url>`** - Adds a new RSS feed - **`@opengathyr remove-feed <feedName>`** - Removes a feed #### Example Usage ```text User: @opengathyr search-feeds "artificial intelligence" Copilot: I'll search for AI-related content across your RSS feeds... User: @opengathyr get-feed tech-news Copilot: Here's the latest content from the tech-news feed... ``` ### Alternative: Direct MCP Client Usage OpenGathyr includes a simple MCP client (`src/client/mcp-client.ts`) that can be used to interact with the MCP server for testing purposes. ### Running the Client Ensure the MCP server is not already running on the same port, then execute the client with: ```bash npm run client ``` ### How It Works The client: 1. Spawns a new instance of the MCP server as a child process 2. Sends a request to the `list-feeds` tool 3. Displays the formatted response 4. Automatically terminates the server after receiving the response ### Modifying the Client You can easily modify the client to test other MCP tools: ```javascript // Change the request to use a different tool const request = { jsonrpc: '2.0', id: 1, method: 'tool', params: { name: 'get-feed', // Change to any of the available tools params: { feedName: 'example-feed' // Add required parameters for the tool } } }; ``` Available tools you can test: - `list-feeds`: Lists all configured feeds (no parameters needed) - `get-feed`: Gets content from a specific feed (requires `feedName` parameter) - `search-feeds`: Searches across feeds (requires `query` parameter) - `add-feed`: Adds a new feed (requires `name` and `url` parameters) - `remove-feed`: Removes a feed (requires `feedName` parameter) Example for searching feeds: ```javascript const request = { jsonrpc: '2.0', id: 1, method: 'tool', params: { name: 'search-feeds', params: { query: 'technology' } } }; ``` ## Use Cases - **AI Assistants**: Integrate with LLM assistants via the Model Context Protocol to provide current news and information - **Content Aggregation**: Centralize multiple RSS feeds into a single accessible interface - **News Monitoring**: Track specific topics across multiple sources using the search functionality - **Headless CMS Integration**: Feed dynamic content into websites and applications - **Research Tools**: Collect and analyze content from multiple sources with a standardized API ## Contributing Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details. ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.