# MCPNyx

**MCPNyx** is an advanced MCP (Model Context Protocol) proxy server designed for the Nyx extension. It allows you to run multiple **MCP stdio-based** and **SSE-based** servers and expose them through a single unified SSE/HTTP/WebSocket endpoint. This enables Nyx and other MCP-compatible tools to connect to multiple remote MCP servers and tools via a single proxy.

## Features

- 🔄 **Multiple Transport Protocols**: stdio, SSE, WebSocket, Streamable HTTP
- 🌐 **Unified Proxy**: Aggregate multiple MCP servers behind a single endpoint
- 🔌 **Flexible Routing**: Route requests to different MCP servers based on configuration
- 📡 **Real-time Communication**: SSE and WebSocket support for live updates
- ��️ **Stateful & Stateless Modes**: Choose between session-based or stateless operation
- 🎯 **Nyx Integration**: Optimized for use with the Nyx browser extension

## Installation & Usage

### Option 1: Run with npx (No Installation)

Run MCPNyx directly without installing:

```bash
npx -y @alsania-io/mcpnyx@latest --config path/to/config.json
```

### Option 2: Global Installation

Install MCPNyx globally to use the `mcpnyx` or `nyxmcp` commands:

```bash
# Install globally
npm install -g @alsania-io/mcpnyx

# Run with mcpnyx command
mcpnyx --config path/to/config.json

# Or use the nyxmcp alias
nyxmcp --config path/to/config.json
```

### CLI Options

- `--config, -c <path>`: **(required)** Path to a JSON configuration file (see below)
- `--port <number>`: Port to run the proxy server on (default: `3055`)
- `--baseUrl <url>`: Base URL for SSE clients (default: `http://localhost:<port>`)
- `--ssePath <path>`: Path for SSE subscriptions (default: `/sse`)
- `--messagePath <path>`: Path for SSE messages (default: `/message`)
- `--logLevel <info|none>`: Set logging level (default: `info`)
- `--outputTransport stdio | sse | ws | streamableHttp`: Output MCP transport (default: `sse` with `--stdio` or `--config`, `stdio` with `--sse` or `--streamableHttp`)
- `--streamableHttpPath "/mcp"`: Path for Streamable HTTP (default: `/mcp`)
- `--stateful`: Run StreamableHttp in stateful mode
- `--sessionTimeout 60000`: Session timeout in milliseconds (stateful StreamableHttp modes only)
- `--header "x-user-id: 123"`: Add one or more custom headers

## Configuration

Create a JSON configuration file to define your MCP servers:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-database", "postgresql://..."]
    },
    "remote-sse": {
      "url": "https://remote-mcp-server.example.com/sse",
      "transport": "sse"
    }
  }
}
```

## Endpoints

Once running, MCPNyx exposes the following endpoints:

- **SSE endpoint**: `http://localhost:<port>/sse`
- **POST messages**: `http://localhost:<port>/message`
- **Streamable HTTP endpoint**: `http://localhost:<port>/mcp`
- **WebSocket endpoint**: `ws://localhost:<port>/message`

(You can customize the paths with `--ssePath`, `--messagePath`, and `--streamableHttpPath`.)

## Example Usage

### Basic Configuration

1. **Create a config file** (e.g., `nyx-config.json`):

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
    },
    "alsaniamcp": {
      "command": "npx",
      "args": ["-y", "@alsania-io/mcp@latest", "server", "start", "-c", "/home/user/.mcp/config.json"]
    }
  }
}
```

2. **Run MCPNyx**:

```bash
npx -y @alsania-io/mcpnyx@latest --config nyx-config.json --port 3055
```

### Advanced Usage

#### stdio → SSE

Convert a stdio MCP server to SSE:

```bash
npx -y @alsania-io/mcpnyx --stdio "npx -y @modelcontextprotocol/server-filesystem /" \
                          --port 3055 --baseUrl http://localhost:3055
```

#### SSE → stdio

Convert an SSE MCP server to stdio:

```bash
npx -y @alsania-io/mcpnyx --sse "https://remote-mcp-server.example.com/sse"
```

#### Config → Streamable HTTP (Stateful)

Run multiple servers with stateful Streamable HTTP:

```bash
npx -y @alsania-io/mcpnyx --config ./config.json \
                          --outputTransport streamableHttp \
                          --port 3055 \
                          --stateful \
                          --sessionTimeout 300000
```

## Why MCP?

[Model Context Protocol](https://spec.modelcontextprotocol.io/) standardizes how AI tools exchange data. If your MCP server only speaks stdio, MCPNyx exposes an SSE/HTTP/WebSocket interface so remote clients (like the Nyx extension, MCP Inspector, or Claude Desktop) can connect without extra server changes. It also allows you to aggregate multiple MCP servers behind a single endpoint.

## Advanced Features

MCPNyx is designed with modularity and flexibility in mind:

- ✅ Supports both stdio and SSE MCP servers in one config
- ✅ Automatically derives the JSON-RPC version from incoming requests
- ✅ Package information (name and version) is retransmitted where possible
- ✅ Stdio-to-SSE mode uses standard logs; SSE-to-stdio mode logs via stderr
- ✅ SSE-to-SSE mode provides automatic reconnection with exponential backoff
- ✅ Health endpoints can be added for monitoring
- ✅ CORS support for cross-origin requests
- ✅ Custom headers for authentication and routing

## Integration with Nyx

MCPNyx is optimized for use with the **Nyx browser extension**, providing:

- 🎯 **Seamless MCP Integration**: Connect Nyx to multiple MCP servers
- 🔄 **Real-time Updates**: SSE support for live tool and resource updates
- 🛡️ **Secure Communication**: Support for authentication headers
- 📊 **Session Management**: Stateful mode for persistent connections

## Development

### Building from Source

```bash
# Clone the repository
git clone https://github.com/alsania-io/mcpnyx.git
cd mcpnyx

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start -- --config ./config.json
```

### Development Mode

```bash
npm run dev -- --config ./config.json
```

## Troubleshooting

### Port Already in Use

If port 3055 is already in use, specify a different port:

```bash
npx -y @alsania-io/mcpnyx --config config.json --port 3007
```

### Connection Issues

- Ensure your MCP servers are properly configured in the config file
- Check that stdio commands are executable and have correct paths
- Verify SSE URLs are accessible and return proper SSE responses
- Check firewall settings if connecting to remote servers

### Logging

Enable detailed logging:

```bash
npx -y @alsania-io/mcpnyx --config config.json --logLevel info
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE file for details

## Links

- **Homepage**: [alsania-io.com](https://alsania-io.com)
- **Repository**: [github.com/alsania-io/mcpnyx](https://github.com/alsania-io/mcpnyx)
- **Issues**: [github.com/alsania-io/mcpnyx/issues](https://github.com/alsania-io/mcpnyx/issues)
- **MCP Specification**: [modelcontextprotocol.io](https://modelcontextprotocol.io/)

## Acknowledgments

MCPNyx is part of the **Alsania I/O** ecosystem, built with the Alsania soverign vision and purpose in mind. It is designed for the Nyx extension.

---

**Aligned with the Alsania AI Protocol v1.0**  
_Imagined by Sigma. Powered by Echo._