OmniWire MCP Server ⚡️

OmniWire-MCP is a production-ready, fault-tolerant news aggregation server built on the Model Context Protocol (MCP). It bridges the gap between AI models and real-time information by providing a unified interface for consuming RSS, Atom, JSON, and HTML feeds.

Designed for resilience, it features a Sentinel Service with Circuit Breakers to handle failing sources gracefully and a Universal Parser that automatically adapts to different content formats.

✨ Features

• Universal Parsing: Automatically detects and parses RSS, Atom, JSON, and HTML content.
• Sentinel Architecture: Intelligent Circuit Breakers monitor source health, preventing cascading failures.
• Dynamic Configuration: Hot-reload sources via remote JSON config (RSS_FEEDS) or fallback to local defaults.
• Data Normalization: Transforms diverse feed formats into a standardized NewsItem schema.
• AI-Native: Exposes specialized Tools and Prompts optimized for LLM consumption.
• Zero-Config Deployment: Runs instantly via npx or Docker.

🚀 Quick Start

Using npx (Global)

Prerequisite: The package must be published to NPM or installed globally.

npx omniwire-mcp

Local Testing (Without Publishing)

If you are developing locally and want to test the npx command:

1. Link the package globally:

   cd OmniWire-MCP
   npm link

2. Run with npx:

   npx omniwire-mcp

Custom Configuration

You can configure the server in two ways:

1. Remote URL: Provide a URL to a JSON configuration file.

   RSS_FEEDS="https://raw.githubusercontent.com/furkankoykiran/OmniWire-MCP/refs/heads/main/src/config/defaults/feeds.json" npx omniwire-mcp

2. Direct JSON: Pass the configuration JSON directly as a string.

   RSS_FEEDS='{"sources": [...]}' npx omniwire-mcp

📦 Installation & Publishing

Publish to NPM (Recommended)

To make npx omniwire-mcp available to everyone:

1. Login to NPM:

   npm login

2. Publish the package:

   npm publish --access public

Option 1: Docker (Cloud/Production)

The server is Docker-ready for easy deployment.

# Build the image
docker build -t omniwire-mcp .

# Run with custom config
docker run -e RSS_FEEDS="https://raw.githubusercontent.com/furkankoykiran/OmniWire-MCP/refs/heads/main/src/config/defaults/feeds.json" omniwire-mcp

Option 2: Local Development

1. Clone the repository:

   git clone https://github.com/furkankoykiran/OmniWire-MCP.git
   cd OmniWire-MCP

2. Install dependencies and build:

   npm install
   npm run build

3. Run the server:

   npm start

🔌 MCP Configuration

Add OmniWire to your MCP client configuration (e.g., claude_desktop_config.json or mcp_config.json).

Standard Configuration (npx)

{
  "mcpServers": {
    "omniwire": {
      "command": "npx",
      "args": [
        "-y",
        "@furkankoykiran/omniwire-mcp"
      ],
      "env": {
        "RSS_FEEDS": "https://raw.githubusercontent.com/furkankoykiran/OmniWire-MCP/refs/heads/main/src/config/defaults/feeds.json",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Docker Configuration

{
  "mcpServers": {
    "omniwire": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "RSS_FEEDS",
        "omniwire-mcp"
      ],
      "env": {
        "RSS_FEEDS": "https://raw.githubusercontent.com/furkankoykiran/OmniWire-MCP/refs/heads/main/src/config/defaults/feeds.json"
      }
    }
  }
}

🛠 Capabilities

Tools

| Tool | Description | Arguments | |------|-------------|-----------| | fetch-news | Smat fetcher with Sentinel protection | filter (string), sourceId (string), limit (number) | | check-health | Diagnostic report for sources | sourceId (optional) | | refresh-config | Force reload of remote config | None | | reset-source | Manually reset a circuit breaker | sourceId (string) |

Resources

| URI | Description | |-----|-------------| | news://all | Aggregated feed from all healthy sources | | news://source/{id} | Live feed from a specific source | | health://sources | Real-time system health report | | config://current | View active configuration |

Prompts

| Prompt | Application | |--------|-------------| | summarize-news | "Give me a digest of topic X" (Uses fetch-news) | | analyze-sources | "Diagnose my feed health" (Uses check-health) |

⚙️ Configuration Schema

The configuration JSON file should match the following schema:

{
  "sources": [
    {
      "id": "tech-crunch",
      "name": "TechCrunch",
      "url": "https://techcrunch.com/feed/",
      "type": "rss",
      "enabled": true
    }
  ],
  "configPollIntervalMs": 60000,
  "requestTimeoutMs": 10000,
  "sentinel": {
    "failureThreshold": 3,
    "recoveryTimeoutMs": 60000
  }
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on how to set up your development environment and submit Pull Requests.

📄 License

This project is licensed under the MIT License.