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

Option 2: Using uvx (Faster, Isolated)

First install uv if you don't have it:

Then use uvx (no separate installation needed):

Development Install

For local development or contributing:

1. Clone the repository:

2. Install in development mode:

3. For development with testing tools:

⚙️ Configuration

Claude Code (CLI)

Option 1: Using pip (Simplest)

Option 2: Using uvx (Requires uv installation)

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

Option 3: Local Development Setup

If you cloned the repository for development:

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

Option 2: Using uvx (Requires uv installed)

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

For local development:

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

Replace

🚀 Usage

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

Verify It's Working

Check server connection:

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:

📊 Project Structure

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