adawalli/nexus

**AI integration without the complexity**
_Intelligent AI model search and discovery with zero-install simplicity_
Quick Start • Features • Documentation • Contributing
---
What is Nexus?
Nexus is a **Model Context Protocol (MCP) server** that provides AI-powered search functionality through the OpenRouter API. It integrates with MCP-compatible clients including Claude Desktop and Cursor, providing search capabilities via multiple model families including Perplexity Sonar (real-time web search) and Grok 4 (training-data knowledge).
Key Characteristics
- **Zero-install deployment**: Executable via bunx (or npx) with no build requirements
- **OpenRouter integration**: Multiple AI models including Perplexity Sonar (web search) and Grok 4 (training data)
- **MCP protocol compliance**: Implements standard MCP tool and resource interfaces
- **Production architecture**: Includes request caching, deduplication, retry logic, and error handling
- **Type-safe implementation**: Full TypeScript coverage with strict type checking
Features
Deployment
- Bunx/NPX-based execution with zero local installation
- Cross-platform compatibility (macOS, Linux, Windows)
- Bun 1.0+ or Node.js 18+ runtime requirement
- Automated version updates via npm registry
Search Capabilities
- **Multiple model tiers** with different capabilities:
- sonar - Fast Q&A, real-time web search (30s timeout, standard tier)
- sonar-pro - Multi-step queries, real-time web search (60s timeout, premium tier)
- sonar-reasoning-pro - Chain-of-thought reasoning, real-time web search (120s timeout, premium tier)
- sonar-deep-research - Exhaustive research reports, real-time web search (300s timeout, premium tier)
- grok-4 - Training-data knowledge, no real-time search (60s timeout, premium tier)
- Real-time web search with current information (Perplexity models)
- Training-data knowledge responses (Grok 4)
- Structured citation extraction from responses
- Configurable model parameters (temperature, max tokens, timeout override)
Architecture
- Comprehensive error handling with typed error classes
- Request caching with configurable TTL
- Request deduplication for concurrent identical queries
- Automatic retry logic with exponential backoff
- Winston-based structured logging
- TypeScript strict mode implementation with full type coverage
Quick Start
Prerequisites
- Bun 1.0+ (recommended) or Node.js 18+
- OpenRouter API key (register at openrouter.ai)
Quick Install
Execute the server without local installation:
The server starts and listens for MCP client connections via STDIO transport.
Testing the Installation
Alternative: Local Development Installation
For local development or customization:
1. Clone the repository:
2. Install dependencies:
3. Build the server:
4. Configure your OpenRouter API key:
5. Test the server:
Integration with MCP Clients
Bunx-Based Integration (Recommended)
Configure MCP clients to execute the server via bunx:
Claude Code
Configuration in ~/.claude/mcp_settings.json:
Restart Claude Code after configuration changes.
Cursor
Add server configuration in Cursor's MCP settings:
- **Name**: nexus
- **Command**: bunx
- **Args**: ["nexus-mcp"]
- **Environment Variables**: OPENROUTER_API_KEY=your-api-key-here
Restart Cursor after configuration changes.
Generic MCP Client Configuration
Standard MCP client connection parameters:
- **Transport**: stdio
- **Command**: bunx
- **Args**: ["nexus-mcp"]
- **Environment**: OPENROUTER_API_KEY=your-api-key-here
Alternative: npx or Local Installation
If you don't have Bun installed, use npx in place of bunx in any of the configurations above.
For a local installation (after following the local development setup):
Usage
Once integrated, you can use the search tool in your MCP client:
Basic Search