This is a Java/Spring Boot implementation of the MCP WebSearch server with the same features as the Node.js version.

• ✅ MCP Server Implementation using Spring AI MCP SDK
• ✅ Web Search Tools:
  • DuckDuckGo as primary search provider
  • Brave Search as automatic fallback
  • Intelligent query enhancement with preferred sites
  • Rate limiting and suspension management
• ✅ Content Fetching Tool: Extract and parse web page content
• ✅ Dual Transport Support: stdio and HTTP/HTTPS
• ✅ Automatic HTTPS Detection: Enables SSL when certificates are found in ./certs/
• ✅ Debug Mode: Comprehensive logging for troubleshooting
• ✅ Preferred Sites: Auto-enhance queries with relevant site: operators

• Java 21 or higher
• Maven 3.8+

java/
├── pom.xml                           # Maven configuration
├── src/
│   ├── main/
│   │   ├── java/com/xtivia/mcp/websearch/
│   │   │   ├── McpWebSearchApplication.java       # Main application
│   │   │   ├── config/
│   │   │   │   └── WebSearchProperties.java       # Configuration properties
│   │   │   ├── model/
│   │   │   │   ├── SearchResult.java              # Search result model
│   │   │   │   ├── SearchResponse.java            # Search response model
│   │   │   │   ├── FetchResult.java               # Fetch result model
│   │   │   │   └── PreferredSite.java             # Preferred site model
│   │   │   ├── provider/
│   │   │   │   ├── SearchProvider.java            # Provider interface
│   │   │   │   ├── DuckDuckGoProvider.java        # DuckDuckGo implementation
│   │   │   │   └── BraveProvider.java             # Brave Search implementation
│   │   │   ├── service/
│   │   │   │   ├── PreferredSitesManager.java     # Site preferences
│   │   │   │   ├── RequestManager.java            # Rate limiting
│   │   │   │   └── ContentFetchService.java       # Content fetching
│   │   │   ├── tool/
│   │   │   │   ├── WebSearchTool.java             # Search MCP tool
│   │   │   │   └── ContentFetchTool.java          # Fetch MCP tool
│   │   │   └── util/
│   │   │       ├── KeywordExtractor.java          # Keyword extraction
│   │   │       └── SummaryGenerator.java          # Summary generation
│   │   └── resources/
│   │       ├── application.yml                    # Spring configuration
│   │       └── preferred_sites.json               # Site preferences
│   └── test/
│       └── java/com/xtivia/mcp/websearch/
│           └── McpWebSearchApplicationTests.java

Edit src/main/resources/application.yml:

websearch:
  provider: duckduckgo                 # duckduckgo or brave
  max-concurrent-requests: 4
  rate-limit: 10
  rate-limit-window-seconds: 60
  search-results-count: 10
  search-result-max-length: 400
  fetch-result-max-length: 5000
  debug: false

cd java
mvn clean package

java -jar target/mcp-websearch-1.0.0.jar --stdio

java -jar target/mcp-websearch-1.0.0.jar
# Or specify custom port
java -jar target/mcp-websearch-1.0.0.jar --port=8080

The application automatically detects SSL certificates and enables HTTPS if:

1. A certs/ folder exists in the working directory
2. Both cert.pem and key.pem files are present in the folder
3. The certificate files are readable and not empty

If certificates are found, the server will start in HTTPS mode automatically. Otherwise, it falls back to HTTP mode.

Generate self-signed certificates (for development):

On Linux/Mac:

./generate-certs.sh

On Windows:

openssl req -x509 -newkey rsa:4096 -keyout certs/key.pem -out certs/cert.pem -days 365 -nodes

The server will display which mode it's running in at startup:

• 🔒 HTTPS Secure Mode (when certificates are found)
• 🌐 HTTP Mode (when no certificates are detected)

java -jar target/mcp-websearch-1.0.0.jar --debug

Intelligent web search with DuckDuckGo (primary) and Brave (fallback).

Parameters:

• query (string, required): Search query
• maxResults (integer, optional): Max results (default: 10, max: 50)
• dateFilter (string, optional): Date filter (d=day, w=week, m=month, y=year)

Returns:

{
  "query": "search term",
  "totalResults": 10,
  "searchProvider": "DuckDuckGo",
  "results": [
    {
      "title": "Result Title",
      "url": "https://example.com",
      "keywords": ["keyword1", "keyword2"],
      "summary": "Intelligent summary of the result..."
    }
  ]
}

Fetch and extract content from a URL.

Parameters:

• url (string, required): URL to fetch

Returns:

{
  "url": "https://example.com",
  "title": "Page Title",
  "content": "Extracted content...",
  "summary": "Intelligent summary...",
  "keywords": ["keyword1", "keyword2"],
  "metadata": {
    "domain": "example.com",
    "contentType": "text/html",
    "contentLength": 1234,
    "lastModified": "2025-01-01T00:00:00Z"
  }
}

• Primary: DuckDuckGo HTML search
• Automatic fallback to Brave Search when DuckDuckGo is rate limited
• Exponential backoff suspension system (20min → 40min → 80min → max 120min)
• Automatic recovery when DuckDuckGo becomes available

Automatically enhances queries with site: operators based on keywords:

• Programming queries → Stack Overflow, GitHub, MDN
• Package/module queries → npmjs.com
• Tutorial queries → Medium, YouTube
• Definition queries → Wikipedia

• Minimum 2-second delay between requests
• Maximum 10 requests per minute
• Rotating user agents
• Random jitter to appear human-like

• Smart HTML parsing with Jsoup
• Removes navigation, ads, and clutter
• Extracts main content intelligently
• Generates summaries from key paragraphs
• Extracts relevant keywords

• Spring Boot 3.4.1: Application framework
• Spring AI MCP: Model Context Protocol SDK
• Spring WebFlux: Reactive HTTP client
• Jsoup 1.18.1: HTML parsing
• Jackson: JSON processing
• Lombok: Boilerplate reduction

cd java
mvn test

The project includes spring-boot-devtools for automatic restart during development.

Enable debug mode to see detailed logs:

java -jar target/mcp-websearch-1.0.0.jar --debug

Add to your Claude Desktop config:

stdio mode:

{
  "mcpServers": {
    "websearch": {
      "command": "java",
      "args": [
        "-jar",
        "/path/to/mcp-websearch-1.0.0.jar",
        "--stdio"
      ]
    }
  }
}

HTTP mode:

{
  "mcpServers": {
    "websearch": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

HTTPS mode (when certificates are detected):

{
  "mcpServers": {
    "websearch": {
      "url": "https://localhost:3000/mcp"
    }
  }
}

MIT

Contributions welcome! Please feel free to submit a Pull Request.