mcp_server by apossebon - MCP Server

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 installed (recommended for dependency management and execution)

Installation (with uv)

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)

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):

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):

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

SSE (legacy):

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:

{
  "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:

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

Or using the explicit alias "streamable-http":

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

Client over SSE (legacy)

{
  "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:

uv run mcp-fast-server

Add new dependencies in pyproject.toml and sync with:

uv sync

Build & distribution (optional)

You can build artifacts (wheel/sdist) with:

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 ·

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 instalado (recomendado para gerenciar dependências e execução)

Instalação e setup (com uv)

# 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)

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):

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):

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

SSE (legado):

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:

{
  "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:

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

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

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

Cliente via SSE (legado)

{
  "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:

uv run mcp-fast-server

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

uv sync

Build e distribuição (opcional)

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

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.