Nexus

🚀 🔍 Nexus MCP Server

Nexus is a production-ready Model Context Protocol (MCP) server that seamlessly integrates AI-powered web search into your development environment. With just one command, you can obtain intelligent search results with proper citations in Claude Desktop, Cursor, or any MCP-compatible client.

🚀 Quick Start

Prerequisites

• Node.js 16 or higher
• An OpenRouter API key (get one at OpenRouter)

Zero-Config Installation

No build steps, no dependencies, no setup required:

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

# Run the server instantly
npx nexus-mcp

The server is now running and ready for MCP client connections.

Testing the NPX Installation

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

# Test the version
npx nexus-mcp --version

# Run with your API key
OPENROUTER_API_KEY=your-key npx 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

2. Install dependencies:

npm install

3. Build the server:

npm run build

4. 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

5. Test the server:

npm start

Integration with MCP Clients

🚀 Quick Setup with NPX (Recommended)

The easiest way to integrate with any MCP client is using NPX:

Claude Code

Add this server to your Claude Code MCP settings:

1. Open your MCP settings file (usually ~/.claude/mcp_settings.json)
2. Add the server configuration using NPX:

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

3. Restart Claude Code

Cursor

Configure the server in Cursor's MCP settings:

1. Open Cursor settings and navigate to MCP servers
2. Add a new server with:
   • Name: nexus
   • Command: npx
   • Args: ["nexus-mcp"]
   • Environment Variables:
     • OPENROUTER_API_KEY: your-api-key-here
3. Restart Cursor

Other MCP Clients

For any MCP-compatible client, use these connection details:

• Transport: stdio
• Command: npx
• Args: ["nexus-mcp"]
• Environment Variables: OPENROUTER_API_KEY=your-api-key-here

Alternative: Local Installation

If you prefer using a local installation (after following the local development setup):

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

✨ Features

🚀 Zero-Install Simplicity

• Ready in 30 seconds with npx
• No dependencies or build steps
• Cross-platform compatibility
• Always up-to-date

🧠 AI-Powered Intelligence

• Perplexity Sonar model integration
• Real-time web content search
• Context-aware result ranking
• Multiple model options

📚 Professional Quality

• Source citations and metadata
• Comprehensive error handling
• Production-grade reliability
• TypeScript implementation

🔧 Developer Experience

• MCP protocol compliance
• Extensive documentation
• Configurable parameters
• Community support

💻 Usage Examples

Basic Usage

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

Advanced Usage

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

Available Tools - search

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

Parameters:

• query (required): Search query (1 - 2000 characters)
• model (optional): Perplexity model to use (default: "perplexity/sonar")
• maxTokens (optional): Maximum response tokens (1 - 4000, default: 1000)
• temperature (optional): Response randomness (0 - 2, default: 0.7)

Example Response:

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
- Sources: 5 found

📚 Documentation

🔧 Technical Details

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

NPX-Specific Issues

• "npx: command not found":
  • Ensure Node.js 16+ 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
• NPX takes a long time to start:
  • This is normal on first run as NPX downloads the package
  • 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 Node.js 16+ 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

# Development with hot reload
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

💰 API Credits and Costs

This server uses OpenRouter's API, which charges based on token usage:

• Perplexity Sonar models: Check current pricing at OpenRouter Models
• Usage monitoring: Track consumption through the OpenRouter dashboard
• Cost control: Set usage limits in your OpenRouter account
• Optimization: Nexus includes built - in rate limiting and intelligent caching

🤝 Contributing

We welcome contributions from developers of all experience levels!

🚀 Get Started

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

🐛 Report Issues

• Bug Reports
• Feature Requests
• Ask Questions

💬 Join Community

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

🌟 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

📄 License

MIT License - see LICENSE file for details.