mirasurf/tarzi-search-mcp

Tarzi Search MCP Server

A Model Context Protocol (MCP) server that provides AI agents with powerful web search and content fetching capabilities through the tarzi library.

Features

• HTML Conversion: Convert HTML content to markdown, JSON, YAML formats
• Web Page Fetching: Retrieve web content with multiple modes (plain HTTP, headless browser, headed browser)
• Web Search: Search across multiple engines (Google, Bing, DuckDuckGo, Brave, Baidu)
• Combined Search & Fetch: Search for results and automatically fetch full content
• Flexible Configuration: All settings exposed as tool parameters (no config files)
• Browser Support: Full Firefox + geckodriver integration for JavaScript-heavy sites

Architecture

This server follows the MCP specification and exposes:

• Tools: Convert, fetch, search, and search-and-fetch functions
• Resources: Server status and help documentation
• Configuration: All options available as parameters per request

Available Tools

1. convert_html

Converts HTML content to various formats.

Parameters:

• input_html (required): HTML content to convert
• output_format: "markdown" (default), "json", "yaml", "html"

2. fetch_web_page

Fetches content from web pages with configurable options.

Parameters:

• url (required): URL to fetch
• mode: "plain_request" (default), "browser_headless", "browser_head"
• output_format: "markdown" (default), "html", "json", "yaml"
• proxy: HTTP proxy URL (optional)
• timeout: Request timeout in seconds (default: 30)
• user_agent: Custom user agent string (optional)

3. search_web

Performs web searches using various search engines.

Parameters:

• query (required): Search query
• engine: "bing" (default), "google", "duckduckgo", "brave", "baidu"
• mode: "webquery" (default), "apiquery"
• limit: Maximum results (default: 10)
• output_format: "json" (default), "yaml"
• api_key: API key for engines requiring authentication (optional)
• proxy: HTTP proxy URL (optional)
• timeout: Request timeout in seconds (default: 30)

4. search_and_fetch

Combines search and content fetching.

Parameters:

• query (required): Search query
• search_engine: "bing" (default), "google", "duckduckgo", "brave", "baidu"
• search_mode: "webquery" (default), "apiquery"
• fetch_mode: "plain_request" (default), "browser_headless", "browser_head"
• limit: Number of results to fetch content for (default: 5)
• output_format: "markdown" (default), "html", "json", "yaml"
• api_key: API key for search engines (optional)
• proxy: HTTP proxy URL (optional)
• timeout: Request timeout in seconds (default: 30)
• user_agent: Custom user agent string (optional)

Available Resources

tarzi://status

Returns server status, capabilities, and supported options.

tarzi://help

Returns comprehensive help documentation.

Installation

Option 1: Docker (Recommended)

# Build the Docker image
docker build -t tarzi-mcp-server .

# Run with stdio transport
docker run -i tarzi-mcp-server

# Run with environment variables for proxy/API keys
docker run -e HTTP_PROXY=http://proxy:8080 -e API_KEY=your-key -i tarzi-mcp-server

Option 2: Local Installation

# Install dependencies
pip install -r requirements.txt

# Install the package
pip install -e .

# Run the server
python server.py

Option 3: Claude Desktop Integration

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "tarzi-search": {
      "command": "python",
      "args": ["/path/to/mcp/server.py"]
    }
  }
}

Docker Image Details

The Docker image provides:

• Base: Ubuntu 24.04
• Python: 3.10+
• Browser: Firefox with geckodriver
• Display: Xvfb for headless operation
• Security: Runs as non-root user
• Size: Optimized with multi-stage build

Configuration

All configuration is done through tool parameters. No configuration files are needed. This provides maximum flexibility for AI agents to configure each request independently.

Common Configuration Options

• Proxy Support: Set proxy parameter for HTTP/HTTPS proxies
• Timeouts: Configure timeout for request limits
• User Agents: Custom user_agent strings for requests
• API Keys: Provide api_key for search engines requiring authentication
• Output Formats: Choose between JSON, YAML, Markdown, HTML formats

Search Engines

Fetch Modes

Examples

HTML Conversion

{
  "tool": "convert_html",
  "parameters": {
    "input_html": "<h1>Hello</h1><p>World</p>",
    "output_format": "markdown"
  }
}

Web Search

{
  "tool": "search_web",
  "parameters": {
    "query": "machine learning tutorials",
    "engine": "google",
    "limit": 5,
    "output_format": "json"
  }
}

Fetch Web Page

{
  "tool": "fetch_web_page",
  "parameters": {
    "url": "https://example.com",
    "mode": "browser_headless",
    "output_format": "markdown"
  }
}

Search and Fetch

{
  "tool": "search_and_fetch",
  "parameters": {
    "query": "Python web scraping guide",
    "search_engine": "duckduckgo",
    "fetch_mode": "browser_headless",
    "limit": 3,
    "output_format": "markdown"
  }
}

Development

Running Tests

pytest tests/

Code Quality

black .
ruff check .
mypy .

Building Docker Image

docker build -t tarzi-mcp-server .

Troubleshooting

Common Issues

1. Tarzi not available: Install with pip install tarzi>=0.0.11
2. Browser errors: Ensure Firefox and geckodriver are installed
3. Permission errors: Check Docker user permissions
4. Network timeouts: Increase timeout parameters or check connectivity

Browser Mode Requirements

For browser_headless and browser_head modes:

• Firefox must be installed
• geckodriver must be in PATH
• X11 display available (provided by Xvfb in Docker)

License

Apache-2.0 License - see the main tarzi.rs repository for details.

Contributing

This MCP server is part of the tarzi.rs project. Please refer to the main repository for contribution guidelines.

Support

For issues and support:

• GitHub Issues
• Documentation
• MCP Specification