OmniWire

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.