Which integrations are available for this server?

Enables natural language querying of Lucene/NRTSearch indexes through [GitHub Copilot](/mcp/servers/integrations/github-copilot) Chat, allowing AI-assisted search with support for Boolean, phrase, range, wildcard, and fuzzy queries.

NRTSearch MCP Server

Production-ready Model Context Protocol (MCP) server for Lucene/NRTSearch, with first-class support for AI assistants like GitHub Copilot and Claude.

Features

Exposes NRTSearch/Lucene search as a robust MCP server for AI tools
Accepts any Lucene query (Boolean, phrase, range, wildcard, fuzzy, etc.)
Structured logging, retries, and highlight support
Pure unit-testable search logic with full test coverage
Easy integration with GitHub Copilot, Claude Desktop, and other MCP clients
Modern Python packaging and configuration (Pydantic, pyproject.toml)

Quick Start

git clone https://github.com/tvergilio/nrtsearch-mcp-server.git cd nrtsearch-mcp-server ./quickstart.sh

This will:

Install all dependencies (including MCP SDK)
Start the server on the configured port

Usage

CLI / Manual

After installation, you can start the server with either:

# Using the Python module python -m nrtsearch_mcp.server # Or, if installed via pip/pipx, use the CLI entrypoint: nrtsearch-mcp

With GitHub Copilot (VS Code)

Install VS Code and GitHub Copilot
Add nrtsearch-mcp as a Model Context Provider in VS Code settings (see .vscode/settings.json)
Start the server (./quickstart.sh or nrtsearch-mcp)
Use Copilot Chat to query your Lucene indexes in natural language

Configuration

The server is configured via environment variables and/or a JSON config file. By default, it looks for:

NRTSEARCH_MCP_CONFIG env var (path to config)
./config.json in the current directory
~/nrtsearch-mcp-config.json in your home directory

Example config:

{ "nrtsearch_connection": { "host": "localhost", "port": 8000, "use_https": false }, "log_level": "INFO" }

Key environment variables:

LOG_LEVEL (default: INFO)
NRTSEARCH_MCP_CONFIG (optional config path)

API: Search Tool

The main tool is nrtsearch/search:

Parameters:

index (str): Index name (e.g. yelp_reviews_staging)
queryText (str): Full Lucene query (e.g. text:(irish AND pub AND (texas OR tx)))
topHits (int, default 10): Number of results (1-100)
retrieveFields (list, optional): Fields to return (default: ["text", "stars"])
highlight (bool, optional): Highlight matches

Returns:

List of hits: {score, stars, text}

Lucene Query Examples:

text:(irish AND pub AND (texas OR tx))
text:"great coffee"
stars:[4 TO 5] AND text:(vegan AND brunch)

Testing

Run all tests (unit, no server needed):

pytest -v

Tests cover:

Success, empty, and multiple hits
Error handling (HTTP, network, malformed, missing fields)
Retry logic
Highlight and custom fields
Input validation

Project Structure

nrtsearch-mcp-server/ ├── nrtsearch_mcp/ │ ├── server.py # Main MCP server and search logic │ ├── settings.py # Pydantic config │ └── ... ├── tests/ # Unit tests ├── quickstart.sh # One-step install & run ├── requirements.txt # Python dependencies ├── pyproject.toml # Packaging/metadata └── ...