MCP Search Engine Gateway

Overview

This Java-based server component adheres to the Model Context Protocol (MCP) specification. It serves as an abstraction layer built atop the robust Apache Lucene search library, providing streamlined document manipulation and sophisticated querying capabilities. Leveraging the Spring Boot framework ensures rapid deployment and maintenance.

Core Functionality

• Protocol Alignment: Full adherence to MCP mandates.

• Indexing Core: Leverages Apache Lucene for persistent, high-speed full-text indexing and searching.

• Web Interface: Exposes all functionalities via a standardized REST API structure.

• Data Lifecycle Operations:

  • Register/Update: Methods to ingest new records or modify existing indexed entries.

  • Retire: Facilities for purging specific documents from the index.

  • Enumeration: Retrieve subsets of indexed items.

• Advanced Search Capabilities:

  • Allows formulation of intricate queries leveraging Lucene's domain-specific query language.

  • Supports pre-query filtering based on associated document metadata attributes.

• Health Check: Endpoint for verifying operational status.

• Platform: Developed using the Spring Boot ecosystem for ease of bootstrapping.

• Containerization: Includes necessary configurations for deployment via Docker.

Navigational Structure

• Overview

• Core Functionality

• Deployment Guide

  • Prerequisites

  • Acquisition

  • Execution Methods

• Interaction

  • Service Endpoints

  • Usage Samples

• Customization

• Licensing

Deployment Guide

Prerequisites

• JVM: Runtime Environment version 11 or newer is required.

• Build Tool: Apache Maven, version 3.6.0 minimum.

• Virtualization: Docker must be installed for containerized operations.

Acquisition

1. Source Code Retrieval:

   git clone [https://github.com/your-username/mcp-lucene-server.git](https://github.com/your-username/mcp-lucene-server.git) cd mcp-lucene-server

   (Substitute your-username appropriately)

2. Project Compilation:

   mvn clean install

Execution Methods

Native Execution (No Container)

1. Launch Application: Execute the compiled artifact: bash java -jar target/mcp-lucene-server-0.0.1-SNAPSHOT.jar

2. The service defaults to listening on TCP port 8080.

Containerized Execution (Docker)

1. Verify Docker Installation: Confirm Docker daemon is operational.

2. Image Construction: From the project root, build the image: bash docker build -t mcp-lucene-server .

3. Container Initialization: Start the service instance: bash docker run -p 8080:8080 mcp-lucene-server This maps host port 8080 to the container's internal port 8080.

MCP Shim for Claude Desktop

This repository includes auxiliary code (mcp-shim/) designed to bridge the server's HTTP interfaces into the native MCP tool structure utilized by Claude Desktop, communicating over STDIO.

Prerequisites

• Java 17 or newer
• Node.js version 18 or higher
• Maven 3.6+

1) Initiate the Backend Service

mvn spring-boot:run

Access point will be established at http://localhost:8080/mcp/v1.

2) Execute the MCP Bridge Process

cd mcp-shim
npm install
# Standard operation: JSON output supported
LUCENE_BASE_URL=http://localhost:8080/mcp/v1 npm start
# Fallback for clients that fail JSON rendering, forcing plain text output
MCP_FORCE_TEXT=1 LUCENE_BASE_URL=http://localhost:8080/mcp/v1 npm start

3) Configure Claude Desktop Integration

Modify ~/.claude/mcp/config.json:

{
  "mcpServers": {
    "lucene": {
      "command": "/opt/homebrew/bin/node",
      "args": [".../MCP-Lucene-Server/mcp-shim/server.js"],
      "env": {
        "LUCENE_BASE_URL": "http://localhost:8080/mcp/v1",
        "MCP_FORCE_TEXT": "1"
      }
    }
  }
}

Alternatively, utilize the provided wrapper script to direct shim diagnostics to /tmp/mcp-lucene-shim.stderr.log:

cat > .../MCP-Lucene-Server/mcp-shim/run-shim.sh <<'SH'
#!/usr/bin/env bash
set -euo pipefail
export LUCENE_BASE_URL="${LUCENE_BASE_URL:-http://localhost:8080/mcp/v1}"
exec node .../MCP-Lucene-Server/mcp-shim/server.js \
  2> /tmp/mcp-lucene-shim.stderr.log
SH
chmod +x .../MCP-Lucene-Server/mcp-shim/run-shim.sh

Then update ~/.claude/mcp/config.json to reference the wrapper:

{
  "mcpServers": {
    "lucene": {
      "command": ".../MCP-Lucene-Server/mcp-shim/run-shim.sh",
      "env": {
        "LUCENE_BASE_URL": "http://localhost:8080/mcp/v1",
        "MCP_FORCE_TEXT": "1"
      }
    }
  }
}

4) Exposed Tools

• lucene_status: Retrieves operational metrics.
• lucene_upsert: Ingests or modifies document payloads.
• lucene_query: Executes complex search requests (metadata filtering supported).
• lucene_delete: Removes entries based on unique identifiers.
• lucene_list: Fetches indexed records with pagination controls.

5) Example Interactions for Claude Desktop

• Query the system state using lucene_status.
• Fetch initial data via lucene_list with parameters: { "limit": 10, "offset": 0 }.
• Register a new item with lucene_upsert: {"documents":[{"id":"doc-1","text":"initial indexed content","metadata":{"lang":"en"}}]}.
• Execute a focused search using lucene_query: {"queries":[{"query":"indexed content","top_k":5}]}.
• Purge data using lucene_delete: { "ids": ["doc-1"] }.

6) Debugging Common Issues

• Confirm HTTP connectivity via curl:

curl -i http://localhost:8080/mcp/v1/status

• If the LLM reports parsing errors, force the shim to use text-only output:

MCP_FORCE_TEXT=1 LUCENE_BASE_URL=http://localhost:8080/mcp/v1 npm start

• Inspect diagnostic output (if using wrapper):

tail -n +1 /tmp/mcp-lucene-shim.stderr.log

• Double-check that all file system paths specified in config.json are absolute and correctly referenced, followed by a restart of the Claude application.

Service Endpoints (Reference for cURL)

The gateway exposes the following HTTP interface methods:

• GET /mcp/v1/status

  • Reports the operational condition of the gateway.

• POST /mcp/v1/upsert

  • Handles the addition or modification of multiple document records.

  • Payload structure example:

    json { "documents": [ { "id": "record_A", "text": "Content for the first entry.", "metadata": { "classification": "example_set", "locale": "en_US" } } ] }

• POST /mcp/v1/query

  • Initiates a search against the Lucene index.

  • Payload structure example:

    json { "queries": [ { "query": "search term definition", "top_k": 15, "filter": { "locale": "en_US" } } ] }

  • Parameters:

    • query: The text string interpreted by Lucene.
    • top_k: (Optional) Maximum result count; defaults to 10 entries.
    • filter: (Optional) Key-value constraints applied to metadata fields.

• POST /mcp/v1/delete

  • Removes records identified by their unique identifiers.

  • Payload structure example:

    json { "ids": ["record_A", "record_B"] }

• GET /mcp/v1/list

  • Retrieves a paginated listing of indexed items.

  • Payload structure example:

    json { "limit": 25, "offset": 50 }

Usage Samples

Check Service Availability:

curl http://localhost:8080/mcp/v1/status

Register/Update Records:

curl -X POST -H 'Content-Type: application/json' -d '{
"documents": [
{
"id": "item_X",
"text": "Data point X content.",
"metadata": {"classification": "test", "locale": "en"}
}
]
}' http://localhost:8080/mcp/v1/upsert

Execute Search Operation:

curl -X POST -H 'Content-Type: application/json' -d '{
"queries": [
{
"query": "data point",
"top_k": 3,
"filter": {"locale": "en"}
}
]
}' http://localhost:8080/mcp/v1/query

Remove Entries:

curl -X POST -H 'Content-Type: application/json' -d '{
"ids": ["item_X"]
}' http://localhost:8080/mcp/v1/delete

List Records:

curl -X POST -H 'Content-Type: application/json' -d '{
"limit": 5
}' http://localhost:8080/mcp/v1/list

Customization

The operational parameters of this service are configured via standard Spring Boot property files. Key configurable settings include:

• server.port: Defines the network port the application binds to (default: 8080).

• lucene.index.path: Specifies the directory path for persistent storage of the Lucene index segments. Setting this to a dedicated, external location is strongly advised for production stability.

You may define these overrides in application.properties or application.yml located within the src/main/resources structure, or by supplying system environment variables.

Configuration File Snippet (application.properties):

server.port=8080 lucene.index.path=/mnt/persistent/lucene/data_store

Licensing

This software is distributed under the terms of the Apache License Version 2.0.

WIKIPEDIA: XMLHttpRequest (XHR) is an Application Programming Interface implemented as a JavaScript object, enabling the dispatch of HTTP requests from a web browser to a server endpoint. These methods permit asynchronous data exchange following initial page load, bypassing traditional full-page refreshes. XMLHttpRequest is fundamental to the concept of Asynchronous JavaScript and XML (Ajax).

== Genesis == The conceptual basis for XHR originated around 2000 within the development cycle of Microsoft Outlook. This idea was first actualized in Internet Explorer 5 (1999), although it utilized proprietary object instantiation syntax like ActiveXObject("Msxml2.XMLHTTP"). By the release of Internet Explorer 7 (2006), all dominant browser platforms natively supported the standardized XMLHttpRequest constructor.

The standardized XMLHttpRequest object has since become the universal interface across major browser engines, including Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Trajectory === The World Wide Web Consortium (W3C) released the initial Working Draft specification for the XMLHttpRequest object in April 2006. A subsequent Level 2 specification followed in February 2008, introducing enhancements such as progress monitoring, enabling cross-origin communication, and facilitating binary stream handling. By the close of 2011, Level 2 features were integrated back into the primary specification document. Development was subsequently transferred to the WHATWG, which currently maintains the active living standard documented using Web IDL.

== Functional Workflow == Typically, invoking a network transaction using XMLHttpRequest involves several sequential programming steps:

1. Instantiate the object via its constructor:
2. Invoke the open() method to declare the HTTP method, define the target URI, and set the operation mode (synchronous or asynchronous):
3. If utilizing asynchronous mode, register a callback function to process state change notifications:
4. Transmit the request payload (if any) using the send() method:
5. Monitor state transitions within the listener. Upon completion of response reception, the object enters state 4 ("done"), and the server's textual reply is accessible via the responseText attribute.

Beyond these core steps, XHR offers fine-grained control over transmission parameters. Request headers can be customized to convey server instructions. Data can be supplied for upload within the send() call. Responses can be automatically parsed from formats like JSON into native JavaScript objects or streamed incrementally rather than waiting for the totality of the payload. Furthermore, operations can be prematurely terminated or configured with a timeout threshold.

== Cross-Origin Communication Constraints ==

Early in the Web's expansion, security models imposed strict limitations preventing scripts loaded from one origin (domain/port/protocol) from initiating requests to a distinct origin, a restriction designed to mitigate various security vulnerabilities.