# freeWeb MCP Server

A lightweight MCP (Model Context Protocol) server providing web search and page content extraction tools powered by DuckDuckGo.

## Tools

- **`web_search`** - Search the web using DuckDuckGo, returning title, URL, and snippet for each result.
- **`web_visit`** - Visit a URL and extract its page content in various formats (markdown, plain text, rich text).

## Quick Start

### 1. Create the conda environment

```bash
conda create -n mcp python=3.12
conda activate mcp
pip install -r requirements.txt
```

### 2. Run the server

```bash
python main.py              # HTTP mode on http://127.0.0.1:8101/mcp
python main.py --stdio      # Stdio mode (for MCP clients)
```

### 3. Run tests

```bash
python test_server.py
```

## Browser-based MCP Clients

MCP 2.x returns a plain Starlette app with no built-in CORS handling. When connecting from a browser-based MCP client (e.g., at `http://127.0.0.1:8080`), add [`CORSMiddleware`](https://starlette-admin.github.io/docs/middleware/#corsmiddleware):

```python
from starlette.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://127.0.0.1:8080"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
    expose_headers=["Mcp-Session-Id", "Mcp-Protocol-Version"],
)
```

The SDK intentionally provides no opinionated middleware — auth, rate limiting, and CORS are left to the user.

## Project Structure

```
freeWeb/
├── main.py              # Server entry point (HTTP + stdio modes)
├── test_server.py       # Test suite (run with: python test_server.py)
└── tools/
    ├── __init__.py
    ├── search.py        # web_search tool
    └── visit.py         # web_visit tool
```

## MCP Client Configuration

### Stdio transport

```json
{
  "mcpServers": {
    "freeWeb": {
      "command": "conda",
      "args": ["run", "-n", "mcp", "python", "/path/to/freeWeb/main.py", "--stdio"]
    }
  }
}
```

### HTTP transport (browser clients)

Connect your browser-based MCP client to `http://127.0.0.1:8101/mcp` with CORS configured as shown above.

## Requirements

See [`requirements.txt`](requirements.txt). Test uses `starlette` (TestClient), which is a transitive dependency of `mcp`.

| Package | Version |
|---------|---------|
| mcp | 2.0.0 |
| ddgs | 9.14.4 |