🌐 Nexus MCP Server

The Hybrid Search & Retrieval Engine for AI Agents.

Nexus is a local Model Context Protocol (MCP) server that combines the best features of Exa (semantic web search) and Ref (documentation-optimized reading). It provides your AI agent (Claude, Cursor, etc.) with the ability to search the web and extract surgical, token-efficient context from documentation without requiring external API keys.

✨ Features

1. Hybrid Search (nexus_search)

Nexus understands that searching for news is different from searching for API docs.

• General Mode: Performs broad web searches (like Exa) to find articles, news, and general information.

• Docs Mode: Automatically filters results to prioritize technical domains (readthedocs, github, stackoverflow, official documentation).

2. Intelligent Reading (nexus_read)

Nexus doesn't just dump HTML into your context window. It parses content based on intent.

• General Focus: Cleans articles, removing ads, navigation bars, and fluff. Perfect for reading news or blog posts.

• Code Focus: Aggressively strips conversational text, retaining only Headers, Code Blocks, and Tables. This mimics ref.tools, ensuring your model gets pure syntax without the noise.

• Auto-Detect: Automatically switches to "Code Focus" when visiting technical sites like GitHub or API references.

3. Privacy & Cost

• No API Keys Required: Uses DuckDuckGo for search and standard HTTP requests for retrieval.

• Runs Locally: Your data stays on your machine until the cleaned context is sent to the LLM.

🛠️ Installation

Prerequisites

• Python 3.10+

Quick Install

Option 1: Using pip (Simplest - Works Everywhere)

# Install directly from GitHub
pip install git+https://github.com/rcdelacruz/nexus-mcp.git

Option 2: Using uvx (Faster, Isolated)

First install uv if you don't have it:

# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Then use uvx (no separate installation needed):

uvx --from git+https://github.com/rcdelacruz/nexus-mcp.git nexus-mcp

Development Install

For local development or contributing:

1. Clone the repository:

git clone https://github.com/rcdelacruz/nexus-mcp.git
cd nexus-mcp

2. Install in development mode:

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package in editable mode
pip install -e .

3. For development with testing tools:

pip install -e ".[dev]"

⚙️ Configuration

Claude Code (CLI)

Option 1: Using pip (Simplest)

# First install the package
pip install git+https://github.com/rcdelacruz/nexus-mcp.git

# Add the server globally (available in all projects)
claude mcp add nexus --transport stdio --scope user -- nexus-mcp

# Verify installation
claude mcp list        # Should show: ✓ Connected

Option 2: Using uvx (Requires uv installation)

Make sure you have uv installed first (see Installation section above), then:

# Add the server globally (available in all projects)
claude mcp add nexus --transport stdio --scope user -- \
  uvx --from git+https://github.com/rcdelacruz/nexus-mcp.git nexus-mcp

# Verify installation
claude mcp list        # Should show: ✓ Connected

Option 3: Local Development Setup

If you cloned the repository for development:

# Navigate to nexus-mcp directory
cd /path/to/nexus-mcp

# Install dependencies first
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Add the server to Claude Code (project scope)
claude mcp add nexus --scope project -- \
  $(pwd)/.venv/bin/python $(pwd)/nexus_server.py

# Verify installation
claude mcp list

Configuration Scopes:

• --scope user - Available across all projects (recommended for GitHub install)

• --scope project - Creates .mcp.json (shareable via git)

• --scope local - Personal config in ~/.claude.json

Check server status:

claude mcp list        # Should show: nexus - ✓ Connected
/mcp                   # In conversation: shows available tools

Claude Desktop / Cursor

Config Location:

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Option 1: Using pip (Simplest)

First install: pip install git+https://github.com/rcdelacruz/nexus-mcp.git

Then add to config:

{
  "mcpServers": {
    "nexus": {
      "command": "nexus-mcp"
    }
  }
}

Option 2: Using uvx (Requires uv installed)

Make sure uv is installed first (see Installation section), then add to config:

{
  "mcpServers": {
    "nexus": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/rcdelacruz/nexus-mcp.git",
        "nexus-mcp"
      ]
    }
  }
}

For local development:

If you cloned the repo and installed with pip install -e .:

{
  "mcpServers": {
    "nexus": {
      "command": "/ABSOLUTE/PATH/TO/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/nexus_server.py"]
    }
  }
}

Replace /ABSOLUTE/PATH/TO/ with the actual path to your clone.

🚀 Usage

Once connected, simply prompt Claude naturally. Nexus handles the tool selection.

Verify It's Working

Check server connection:

claude mcp list
# Should show: nexus - ✓ Connected

# In a Claude Code conversation:
/mcp
# Should show nexus with 2 tools available

See VERIFICATION.md for detailed testing instructions.

Scenario 1: Technical Research (Ref Emulation)

User: "How do I use asyncio.gather in Python? Check the docs."

• Nexus Action:

  1. Search: nexus_search(query="python asyncio gather", mode="docs")

  2. Read: nexus_read(url="docs.python.org/...", focus="code")

• Result: The AI receives only the function signature and code examples, saving context window space.

Scenario 2: General Research (Exa Emulation)

User: "Search for the latest updates on the NVIDIA Blackwell chip."

• Nexus Action:

  1. Search: nexus_search(query="NVIDIA Blackwell updates", mode="general")

  2. Read: nexus_read(url="techcrunch.com/...", focus="general")

• Result: The AI reads a clean, ad-free summary of the news article.

🧠 Architecture

Nexus is built on the Model Context Protocol using the FastMCP Python SDK.

Production Features

✅ Comprehensive Error Handling - All edge cases covered with graceful fallbacks

✅ Input Validation - URL format, parameter bounds, and mode validation

✅ Proper Logging - Structured logging instead of print statements

✅ Configurable Limits - Timeouts, content length, and result counts

✅ 85% Test Coverage - 19 comprehensive unit tests

✅ Type Hints - Full type annotations for better IDE support

✅ Dependency Management - Modern pyproject.toml configuration

🧪 Testing

Run the test suite:

# Activate virtual environment
source .venv/bin/activate

# Run all tests with coverage
pytest

# Run specific test file
pytest tests/test_nexus_server.py -v

# Run manual integration test
python test_manual.py

📊 Project Structure

nexus-mcp/
├── nexus_server.py      # Main MCP server implementation
├── tests/               # Comprehensive test suite
│   ├── __init__.py
│   └── test_nexus_server.py
├── test_manual.py       # Manual integration testing
├── pyproject.toml       # Project configuration & dependencies
├── LICENSE              # MIT License
├── README.md            # This file
└── .gitignore          # Git ignore rules

🤝 Contributing

Contributions are welcome! Please ensure:

• All tests pass (pytest)

• Code coverage remains above 80%

• Follow existing code style and patterns

• Add tests for new features

📄 License

MIT License - See LICENSE file for details. Free to use and modify.