🌐 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+
• uv (Recommended) or pip

Quick Install (Recommended)

Install directly from GitHub - no cloning needed:

# Using uvx (no installation, runs on-demand)
uvx --from git+https://github.com/rcdelacruz/nexus-mcp.git nexus-mcp

# Or install with pip
pip install git+https://github.com/rcdelacruz/nexus-mcp.git

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)

Quick Setup (Recommended - Install from GitHub):

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

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

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

Recommended: Install from GitHub with uvx

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

Alternative: Using local installation

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

{
  "mcpServers": {
    "nexus": {
      "command": "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.

Component	Technology	Purpose
MCP Framework	FastMCP	Server implementation and tool registration
Search Backend	DDGS (DuckDuckGo)	Free web search without API keys
HTTP Client	httpx	Async HTTP requests with timeout handling
HTML Parsing	BeautifulSoup4	Intelligent content extraction
Doc Detection	Heuristic URL matching	Auto-detection of technical sites

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.