# 1. Clone the repo
git clone https://github.com/Simonc44/OmniMCP.git
cd OmniMCP

# 2. Install dependencies (Python 3.10+ required)
pip install -r requirements.txt

# 3. Edit your config
notepad mcp_router_config.json   # Windows
# or: nano mcp_router_config.json

# 4. Run it
python router.py --config mcp_router_config.json

OmniMCP/
├── router.py                  #  Core gateway — routing, healing, hot-reload, hooks
├── mock_server.py             #  Lightweight mock MCP server for testing
├── run_integration_test.py    #  Full integration test suite (async, healing, hot-reload)
├── mcp_router_config.json     #   Production config — your real MCP servers go here
├── test_config.json           #  Test config — uses mock_server.py instances
├── requirements.txt           #  Dependencies: mcp, pydantic, jsonschema, anyio
├── docs/                      #  Architecture diagrams and assets
├── .github/
│   ├── workflows/ci.yml       #  GitHub Actions CI pipeline
│   └── ISSUE_TEMPLATE/        #  Bug report & feature request templates
├── CHANGELOG.md               #  Version history
├── CONTRIBUTING.md            #  Contribution guide
└── LICENSE                    #   MIT License

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx" }
    },
    "reddit": {
      "command": "python",
      "args": ["C:/path/to/reddit/server.py"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_CLIENT_SECRET": "your_secret",
        "REDDIT_USER_AGENT": "OmniMCP/1.0"
      }
    },
    "trend-mining": {
      "command": "python",
      "args": ["-m", "trend_mining.server"],
      "env": { "PLAYWRIGHT_HEADLESS": "true" }
    }
  }
}

python run_integration_test.py

{
  "mcpServers": {
    "omni-mcp": {
      "command": "python",
      "args": [
        "C:/path/to/OmniMCP/router.py",
        "--config",
        "C:/path/to/OmniMCP/mcp_router_config.json"
      ]
    }
  }
}

# Register a custom request hook (e.g. inject auth)
@gateway.hook_system.register_request_hook
async def inject_auth(server_name: str, tool_name: str, arguments: dict) -> dict:
    if server_name == "my-api":
        arguments["api_key"] = os.environ["MY_SECRET_KEY"]
    return arguments

# Register a custom response hook (e.g. redact PII)
@gateway.hook_system.register_response_hook
async def redact_pii(server_name, tool_name, result):
    # process result.content here
    return result

┌──────────────────────────────────────────────────────┐
│              Claude Desktop / Cursor                  │
└──────────────────────┬───────────────────────────────┘
                       │ stdio (single MCP connection)
┌──────────────────────▼───────────────────────────────┐
│                  OmniMCP Router                       │
│  ┌─────────────────────────────────────────────────┐ │
│  │  Hook System │  Schema Validator  │   Profiler   │ │
│  └─────────────────────────────────────────────────┘ │
│  ┌──────────────┐ ┌──────────────┐ ┌────────────┐   │
│  │SubServer A   │ │SubServer B   │ │SubServer C │   │
│  │ connected  │ │ reconnecting│ │ connected│   │
│  │Auto-Healing  │ │Backoff: 4s   │ │            │   │
│  └──────────────┘ └──────────────┘ └────────────┘   │
└──────────────────────────────────────────────────────┘