nexus

<!-- markdownlint-disable MD033 MD041 -->

<div align="center">

🔍 Nexus MCP Server

AI integration without the complexity

 !NPM Downloads    


_Intelligent AI model search and discovery with zero-install simplicity_

Quick Start • Features • Documentation • Contributing

</div>

---

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:

# Set your OpenRouter API key
export OPENROUTER_API_KEY=your-api-key-here

# Run the server via bunx (recommended)
bunx nexus-mcp

# Or via npx
npx nexus-mcp

The server starts and listens for MCP client connections via STDIO transport.

Testing the Installation

# Test the CLI help
bunx nexus-mcp --help

# Test the version
bunx nexus-mcp --version

# Run with your API key
OPENROUTER_API_KEY=your-key bunx nexus-mcp

Alternative: Local Development Installation

For local development or customization:

1. Clone the repository:

git clone https://github.com/adawalli/nexus.git
cd nexus

1. Install dependencies:

bun install

1. Build the server:

bun run build

1. Configure your OpenRouter API key:

# Copy the example environment file
cp .env.example .env

# Edit .env and add your actual API key
# OPENROUTER_API_KEY=your-api-key-here

1. Test the server:

bun run start

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:

{
  "mcpServers": {
    "nexus": {
      "command": "bunx",
      "args": ["nexus-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

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):

{
  "mcpServers": {
    "nexus": {
      "command": "bun",
      "args": ["run", "/path/to/nexus-mcp/dist/cli.js"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Usage

Once integrated, you can use the search tool in your MCP client:

Basic Search

Use the search tool to find information about "latest developments in AI"

Advanced Search with Parameters

Search for "climate change solutions" using:
- Model: sonar-pro
- Max tokens: 2000
- Temperature: 0.3

Using Different Models

# Fast Q&A with real-time web search (default)
Search for "latest news" with model: sonar

# Deep research with comprehensive analysis
Search for "AI safety research" with model: sonar-deep-research

# Knowledge from training data (no web search)
Search for "explain quantum computing" with model: grok-4

Available Tools

search

The main search tool that provides AI-powered search capabilities.

Parameters:

• query (required): Search query (1-2000 characters)
• model (optional): Model to use (default: sonar)
• sonar - Fast Q&A with real-time web search (30s timeout)
• sonar-pro - Multi-step queries with real-time web search (60s timeout, premium)
• sonar-reasoning-pro - Chain-of-thought reasoning with real-time web search (120s timeout, premium)
• sonar-deep-research - Exhaustive research reports with real-time web search (300s timeout, premium)
• grok-4 - Training-data knowledge, no real-time search (60s timeout, premium)
• maxTokens (optional): Maximum response tokens (1-4000, default: 1000)
• temperature (optional): Response randomness (0-2, default: 0.3)
• timeout (optional): Override default timeout in milliseconds (5000-600000)

Example Response (Perplexity model):

Based on current information, here are the latest developments in AI...

[Detailed AI-generated response with current information]

---
**Search Metadata:**
- Model: perplexity/sonar
- Response time: 1250ms
- Tokens used: 850
- Timeout: 30000ms
- Search type: realtime
- Sources: 5 found

Example Response (Grok 4 model):

Quantum computing is a type of computation that harnesses quantum mechanics...

[Response based on training data knowledge]

---
**Search Metadata:**
- Model: x-ai/grok-4
- Response time: 3500ms
- Tokens used: 650
- Timeout: 60000ms
- Search type: training-data
- Cost tier: premium

Configuration

Environment Variables

• OPENROUTER_API_KEY (required): Your OpenRouter API key
• NODE_ENV (optional): Environment setting (development, production, test)
• LOG_LEVEL (optional): Logging level (debug, info, warn, error)

Advanced Configuration

The server supports additional configuration through environment variables:

• OPENROUTER_TIMEOUT_MS: Request timeout in milliseconds (default: 30000)
• OPENROUTER_MAX_RETRIES: Maximum retry attempts (default: 3)
• OPENROUTER_BASE_URL: Custom OpenRouter API base URL

Resources

The server provides a configuration status resource at config://status that shows:

• Server health status
• Configuration information (with masked API key)
• Search tool availability
• Server uptime and version

Troubleshooting

Bunx/NPX-Specific Issues

"bunx: command not found"

• Install Bun: curl -fsSL https://bun.sh/install | bash
• Or fall back to npx if you have Node.js 18+ installed

"npx: command not found"

• Ensure Node.js 18+ is installed: node --version
• Update npm: npm install -g npm@latest

"Cannot find package 'nexus-mcp'"

• The package may not be published yet. Use local installation instead
• Verify network connectivity for npm registry access

Slow startup on first run

• This is normal on first run as the package is downloaded
• Subsequent runs will be faster due to caching
• For faster startup, use local installation instead

"Permission denied" errors with npx

• Try: npx --yes nexus-mcp --stdio
• Or set npm permissions: npm config set user 0 && npm config set unsafe-perm true

Common Issues

"Search functionality is not available"

• Ensure OPENROUTER_API_KEY environment variable is set
• Verify your API key is valid at OpenRouter
• Check the server logs for initialization errors

"Authentication failed: Invalid API key"

• Double-check your API key format and validity
• Ensure the key has sufficient credits/permissions
• Test the key directly at OpenRouter dashboard

"Rate limit exceeded"

• Wait for the rate limit to reset (usually 1 minute)
• Consider upgrading your OpenRouter plan for higher limits
• Monitor usage in your OpenRouter dashboard

Connection timeouts

• Check your internet connection
• The server will automatically retry failed requests
• Increase timeout if needed: OPENROUTER_TIMEOUT_MS=60000

MCP client can't connect to server

• Verify your MCP configuration uses the correct command and arguments
• Check that Bun 1.0+ or Node.js 18+ is available in your MCP client's environment
• Ensure the API key is properly set in the environment variables

Debug Logging

Enable debug logging by:

For local development: Add LOG_LEVEL=debug to your .env file

For MCP clients: Add LOG_LEVEL: "debug" to the env section of your MCP configuration

This will provide detailed information about:

• Configuration loading
• API requests and responses
• Error details and stack traces
• Performance metrics

Testing Connection

You can test if the server is working by checking the configuration status resource in your MCP client, or by running a simple search query.

Development

For developers working on this server:

# Development with hot reload
bun run dev

# Run tests
bun run test

# Run tests with coverage
bun run test:coverage

# Lint code
bun run lint

# Format code
bun run format

API Costs

OpenRouter charges for API usage based on token consumption:

• Pricing: See current rates at OpenRouter Models
• Monitoring: Usage tracking available in OpenRouter dashboard
• Limits: Configure spending limits in OpenRouter account settings
• Optimization: Server implements response caching and request deduplication to minimize redundant API calls

📚 Documentation

<div align="center">

| 📖 Guide | 🔗 Link | 📝 Description | | ------------------- | ------------------------------------------- | -------------------------------- | | Quick Start | Getting Started | Zero-install setup in 30 seconds | | API Reference | MCP Tools | Complete command reference | | Configuration | Environment Setup | Advanced configuration options | | Contributing | Contributing Guide | Join our open source community | | Troubleshooting | Common Issues | Solutions to common problems |

</div>

🤝 Contributing

We welcome contributions from developers of all experience levels!

<table> <tr> <td width="33%">

🚀 Get Started

• Fork the repository
• Read our Contributing Guide
• Check out good first issues

</td> <td width="33%">

🐛 Report Issues

• Bug Reports
• Feature Requests
• Ask Questions

</td> <td width="33%">

💬 Join Community

• GitHub Discussions
• Code of Conduct
• Roadmap & Project Board

</td> </tr> </table>

🌟 Recognition

Contributors are recognized in our:

• Contributors list
• Release notes for significant contributions
• Community spotlights and testimonials

🔗 Related Projects

• Model Context Protocol - The standard we implement
• OpenRouter - Our AI model provider
• Claude Desktop - Primary MCP client
• Cursor - AI-powered code editor with MCP support

📞 Support & Community

<div align="center">

| 💬 Need Help? | 🔗 Resource | | -------------------- | ---------------------------------------------------------------------------------------------------- | | Quick Questions | GitHub Discussions | | Bug Reports | GitHub Issues | | Documentation | OpenRouter Docs • MCP Specification | | Feature Requests | Enhancement Proposals |

</div>

📄 License

MIT License - see LICENSE file for details.

---

<div align="center">

Made with ❤️ by the open source community

⭐ Star us on GitHub • 📦 View on NPM • 📚 Read the Docs

_Nexus: AI integration without the complexity_


</div>