## EN
MCP Fast Server

An MCP (Model Context Protocol) server built with FastMCP that exposes two useful tools for agents/IDEs: web search via DuckDuckGo and readable content extraction from HTML pages.

## Overview

- **search(query, max_results=5)**: searches the web and returns titles, links, and snippets.
- **fetch_content(url, timeout_seconds=15.0)**: fetches a URL and returns the main readable text (uses trafilatura; falls back to raw HTML if extraction fails).

Main implementation is in `src/mcp_fast_server/server.py` and the CLI is registered as `mcp-fast-server` via `pyproject.toml`.

## Requirements

- Python >= 3.10
- [uv](https://github.com/astral-sh/uv) installed (recommended for dependency management and execution)

## Installation (with uv)

```bash
uv sync
```

This will install the dependencies defined in `pyproject.toml` (fastmcp, httpx, duckduckgo-search, trafilatura) into an isolated environment.

## How to run

### Direct (CLI)

```bash
uv run mcp-fast-server
```

This starts the MCP server over stdio and waits for a client to connect.

#### HTTP/Streamable HTTP and SSE

The server also supports modern HTTP transport (streamable-http) and legacy SSE.

- Streamable HTTP (recommended):

```bash
uv run mcp-fast-server --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp
```

- HTTP (alias compatible with streamable-http on recent versions):

```bash
uv run mcp-fast-server --transport http --host 127.0.0.1 --port 8000 --path /mcp
```

- SSE (legacy):

```bash
uv run mcp-fast-server --transport sse --host 127.0.0.1 --port 8000 --path /mcp/sse
```

You can also set options via environment variables: `MCP_TRANSPORT`, `MCP_HOST`, `MCP_PORT`, `MCP_PATH`.

### Integrating with an MCP client

Configure your MCP client to launch the command above via stdio. Example for the MCP Inspector:

```json
{
  "mcpServers": {
    "mcp-fast-server": {
      "command": "uv",
      "args": ["run", "mcp-fast-server"]
    }
  }
}
```

In the Inspector, select the "mcp-fast-server", connect, and try the tools.

#### Client over HTTP/Streamable HTTP

Example configuration for clients that support HTTP/Streamable HTTP:

```json
{
  "mcpServers": {
    "mcp-fast-server-http": {
      "url": "http://127.0.0.1:8000/mcp",
      "transport": "http"
    }
  }
}
```

Or using the explicit alias "streamable-http":

```json
{
  "mcpServers": {
    "mcp-fast-server-stream": {
      "url": "http://127.0.0.1:8000/mcp",
      "transport": "streamable-http"
    }
  }
}
```

#### Client over SSE (legacy)

```json
{
  "mcpServers": {
    "mcp-fast-server-sse": {
      "url": "http://127.0.0.1:8000/mcp/sse",
      "transport": "sse"
    }
  }
}
```

## Tools (API)

- **search**
  - **Parameters**:
    - `query` (str): search term
    - `max_results` (int, default 5): maximum number of results
  - **Returns**: `List[Dict]` with keys `title`, `href`, `body`, `source`

- **fetch_content**
  - **Parameters**:
    - `url` (str): URL to fetch
    - `timeout_seconds` (float, default 15.0): HTTP timeout
  - **Returns**: `str` with the extracted main text; raw HTML if extraction fails.

## Quick examples

- Calling `search` with `query="Model Context Protocol"` returns up to 5 DuckDuckGo results with title/link/snippet.
- Calling `fetch_content` with `url="https://example.com"` returns the main textual content of the page.

## Project structure

```
src/
  mcp_fast_server/
    __init__.py
    server.py        # defines the tools and the entrypoint
pyproject.toml       # project metadata and mcp-fast-server script
README.md
README.en.md
```

## Development

Open `src/mcp_fast_server/server.py` and edit/add tools decorated with `@mcp.tool()`.

To run during development:

```bash
uv run mcp-fast-server
```

Add new dependencies in `pyproject.toml` and sync with:

```bash
uv sync
```

## Build & distribution (optional)

You can build artifacts (wheel/sdist) with:

```bash
uv build
```

Artifacts will be placed in `dist/`.

## Notes & limitations

- Search uses DuckDuckGo via `duckduckgo-search`; follow ToS and access policies.
- Content extraction uses `trafilatura` and may not work perfectly on all pages.
- `fetch_content` follows redirects and raises for non‑successful HTTP responses.

## License

Set the project license here (e.g., MIT, Apache-2.0). Update `pyproject.toml` accordingly if needed.



## PT BR
MCP Fast Server · [English README](README.en.md)

Servidor MCP (Model Context Protocol) construído com FastMCP que expõe duas ferramentas úteis para agentes/IDE: pesquisa na web via DuckDuckGo e extração de conteúdo limpo de páginas HTML.

## Visão geral

- **search(query, max_results=5)**: busca na web e retorna títulos, links e trechos.
- **fetch_content(url, timeout_seconds=15.0)**: baixa uma URL e retorna o texto principal legível (usa trafilatura; caso falhe, retorna o HTML bruto).

Implementação principal em `src/mcp_fast_server/server.py` e CLI registrada como `mcp-fast-server` via `pyproject.toml`.

## Requisitos

- Python >= 3.10
- [uv](https://github.com/astral-sh/uv) instalado (recomendado para gerenciar dependências e execução)

## Instalação e setup (com uv)

```bash
# Dentro do diretório do projeto
uv sync
```

Isso instalará as dependências definidas em `pyproject.toml` (fastmcp, httpx, duckduckgo-search, trafilatura) em um ambiente isolado.

## Como executar

### Execução direta (CLI)

```bash
uv run mcp-fast-server
```

Isso inicia o servidor MCP via stdio, aguardando um cliente conectar.

#### HTTP/Streamable HTTP e SSE

O servidor também suporta transporte HTTP moderno (streamable-http) e SSE.

- Streamable HTTP (recomendado):

```bash
uv run mcp-fast-server --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp
```

- HTTP (alias compatível com streamable-http nas versões recentes):

```bash
uv run mcp-fast-server --transport http --host 127.0.0.1 --port 8000 --path /mcp
```

- SSE (legado):

```bash
uv run mcp-fast-server --transport sse --host 127.0.0.1 --port 8000 --path /mcp/sse
```

As opções também podem ser passadas por variáveis de ambiente: `MCP_TRANSPORT`, `MCP_HOST`, `MCP_PORT`, `MCP_PATH`.

### Integração com um cliente MCP

Configure seu cliente MCP para iniciar o comando acima via stdio. Exemplo com o MCP Inspector:

```json
{
  "mcpServers": {
    "mcp-fast-server": {
      "command": "uv",
      "args": ["run", "mcp-fast-server"]
    }
  }
}
```

No Inspector, selecione o servidor "mcp-fast-server", conecte e teste as ferramentas.

#### Cliente via HTTP/Streamable HTTP

Exemplo de configuração para clientes que suportam HTTP/Streamable HTTP:

```json
{
  "mcpServers": {
    "mcp-fast-server-http": {
      "url": "http://127.0.0.1:8000/mcp",
      "transport": "http"
    }
  }
}
```

Ou usando o alias explícito "streamable-http":

```json
{
  "mcpServers": {
    "mcp-fast-server-stream": {
      "url": "http://127.0.0.1:8000/mcp",
      "transport": "streamable-http"
    }
  }
}
```

#### Cliente via SSE (legado)

```json
{
  "mcpServers": {
    "mcp-fast-server-sse": {
      "url": "http://127.0.0.1:8000/mcp/sse",
      "transport": "sse"
    }
  }
}
```

## Ferramentas (API)

- **search**
  - **Parâmetros**:
    - `query` (str): termo de busca
    - `max_results` (int, padrão 5): máximo de resultados
  - **Retorno**: `List[Dict]` com chaves `title`, `href`, `body`, `source`

- **fetch_content**
  - **Parâmetros**:
    - `url` (str): URL a ser baixada
    - `timeout_seconds` (float, padrão 15.0): timeout HTTP
  - **Retorno**: `str` com o texto principal extraído. Se a extração falhar, retorna o HTML.

## Exemplos rápidos

- Chamar `search` com `query="Model Context Protocol"` retorna até 5 resultados do DuckDuckGo com título/link/trecho.
- Chamar `fetch_content` com `url="https://example.com"` retorna o corpo textual principal da página.

## Estrutura do projeto

```
src/
  mcp_fast_server/
    __init__.py
    server.py        # define as ferramentas e o entrypoint
pyproject.toml       # metadata do projeto e script mcp-fast-server
README.md
```

## Desenvolvimento

Abra `src/mcp_fast_server/server.py` e edite/adicione ferramentas decoradas com `@mcp.tool()`.

Para executar durante o desenvolvimento:

```bash
uv run mcp-fast-server
```

Dependências novas podem ser adicionadas ao `pyproject.toml` e sincronizadas com:

```bash
uv sync
```

## Build e distribuição (opcional)

Você pode gerar artefatos (wheel/sdist) do projeto com:

```bash
uv build
```

Os artefatos serão colocados em `dist/`.

## Notas e limitações

- A busca usa DuckDuckGo via `duckduckgo-search`; respeite termos de uso e políticas de acesso.
- A extração de conteúdo usa `trafilatura` e pode não funcionar perfeitamente para todas as páginas.
- `fetch_content` segue redirecionamentos e lança erro para respostas HTTP não bem-sucedidas.

## Licença

Defina a licença do projeto e adicione aqui (ex.: MIT, Apache-2.0). Atualize também o `pyproject.toml` se necessário.