MCP Web Search Server

A Model Context Protocol (MCP) server that provides web search capabilities using DuckDuckGo for OpenCode integration.

Overview

This project implements an MCP server that allows OpenCode to perform web searches. The server uses DuckDuckGo as the search provider and provides both MCP tool integration and a fallback command-line interface for testing.

Features

• Web Search: Perform searches using DuckDuckGo
• MCP Integration: Full MCP server implementation with FastMCP
• Health Checks: Built-in health monitoring
• Error Handling: Comprehensive error handling and logging
• Docker Support: Containerized deployment
• Fallback Mode: Command-line testing when dependencies are unavailable

Installation

Prerequisites

• Python 3.8+
• pip
• Docker (optional)

Install Dependencies

pip install -r requirements.txt

Docker Installation

Using Docker Compose (recommended):

docker compose build
docker compose up -d

Or manually:

docker build -t web-search-server .
docker run -p 127.0.0.1:8000:8000 web-search-server

Configure OpenCode

Add the MCP server configuration to your OpenCode config file. See OpenCode MCP Server Configuration for details.

Create or edit ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "web-search": {
      "type": "remote",
      "url": "http://localhost:8000",
      "enabled": true
    }
  }
}

Usage

MCP Server Mode (with FastMCP)

When FastMCP is available, the server runs as a full MCP server:

python src/server.py

Command-Line Testing Mode

Without FastMCP or when testing:

# Health check
python src/server.py

# Search query
python src/server.py "your search query here"

API

Tools

web_search(query: str, max_results: int = 10) -> str

Performs a web search and returns results in JSON format.

Parameters:

• query: Search query string
• max_results: Maximum number of results (1-50, default: 10)

Returns: JSON string with search results

search_health() -> str

Checks the health status of the search service.

Returns: JSON string with health status

Response Format

Search results:

{
  "query": "search term",
  "results": [
    {
      "title": "Result Title",
      "url": "https://example.com",
      "snippet": "Result description..."
    }
  ],
  "count": 1
}

Health check:

{
  "status": "healthy",
  "message": "Web search service is operational",
  "test_query_successful": true
}

Development

Project Structure

src/
├── __init__.py
└── server.py            # Main MCP server implementation
tests/
├── test_server.py       # Unit tests
└── test_integration.py  # Integration/E2E tests
requirements.txt         # Python dependencies
Dockerfile               # Docker configuration
docker-compose.yml       # Docker Compose configuration
AGENTS.md                # Agent guidelines
project.md               # Project documentation
architecture.md          # Architecture documentation with diagrams

Testing

Run unit tests:

python -m pytest tests/test_server.py -v

Run integration tests (requires server running):

docker compose up -d
python -m pytest tests/test_integration.py -v

Run all tests:

python -m pytest tests/ -v

Error Handling

The server gracefully handles:

• Missing dependencies (fallback mode)
• Network errors
• Invalid search queries
• Parsing errors

Configuration

No configuration files are currently required. The server uses DuckDuckGo's HTML search endpoint with default settings.

OpenCode Integration

To use this MCP server with OpenCode, add the following configuration to your ~/.config/opencode/opencode.json:

{
  "mcp": {
    "web-search": {
      "type": "remote",
      "url": "http://localhost:8000",
      "enabled": true
    }
  }
}

This enables the web_search tool in OpenCode for performing web searches via DuckDuckGo.

License

MIT License - see LICENSE file for details.

Contributing

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