Simple MCP Tool Server

Simple MCP Tool Server

Um servidor MCP simples que expõe uma ferramenta de busca de sites usando transporte SSE.

Requisitos

• Python 3.10 ou superior (testado no Python 3.13)

Instalação

# Create a virtual environment
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate

# Install the package and dependencies
pip install -r requirements.txt

Documentação do SDK Python do MCP

A documentação do SDK Python do MCP foi dividida em arquivos menores e organizada no diretório docs/. Essa estrutura facilita a navegação e o entendimento do SDK por agentes de IA. A documentação cobre:

• Conceitos principais (servidores, recursos, ferramentas, etc.)
• Execução de servidores MCP em diferentes modos
• Exemplos e uso avançado
• E muito mais!

Uso

O pacote fornece uma interface de linha de comando (CLI) com vários comandos para gerenciar o servidor MCP:

Iniciando o servidor

Inicie o servidor na porta padrão (7000) ou especifique uma porta personalizada:

# Using default port (7000)
python -m mcp_simple_tool start

# Using custom port
python -m mcp_simple_tool start --port 8000

Gerenciando o servidor

# Check if server is running
python -m mcp_simple_tool check [--port PORT]

# Stop the server
python -m mcp_simple_tool stop [--port PORT]

# Restart the server (stop and start)
python -m mcp_simple_tool restart [--port PORT]

O comando de reinicialização irá:

1. Parar qualquer servidor existente na porta especificada
2. Iniciar um novo servidor em segundo plano
3. Aguardar até que o servidor esteja responsivo
4. Registrar a saída no arquivo server.log

Referência rápida da CLI

Comando	Finalidade
start	Iniciar o servidor
stop	Parar o servidor
check	Verificação de integridade
restart	Parar e iniciar

Ferramentas do Servidor

O servidor expõe as seguintes ferramentas:

• fetch: Buscador HTTP remoto – forneça uma URL absoluta; retorna o texto da página.

  • url: A URL do site a ser buscado (obrigatório)

• search_docs: Busca semântica na documentação do SDK; retorna os trechos mais relevantes.

  • query: Frase de busca ou pergunta (obrigatório)
  • k: Número de correspondências principais a retornar (opcional, padrão = 3)

• get_content: Obtém o arquivo local completo para qualquer correspondência retornada por search_docs.

  • file: Caminho relativo à documentação (obrigatório)

Configuração de Desenvolvimento

Para desenvolvimento, instale ferramentas adicionais:

pip install -e .
pip install -r requirements.txt

Use o Makefile para tarefas comuns:

# Format code
make fmt

# Run linters
make lint

# Run tests
make test

A suíte de testes possui um tempo limite de 20 segundos embutido para todos os testes, a fim de evitar travamentos, especialmente com endpoints SSE. Para testes individuais, um tempo limite mais rigoroso pode ser especificado usando o decorador @pytest.mark.timeout(seconds).

Índice de Busca Semântica

Para a ferramenta search_docs, você pode construir ou reconstruir manualmente o índice vetorial:

# Build or rebuild the semantic search index
python scripts/build_doc_index.py

O índice é construído automaticamente no primeiro uso da ferramenta, caso não exista.

Arquitetura do Projeto

mcp_simple_tool/
    __init__.py          # Package initialization
    __main__.py          # Entry point when run as module
    cli.py               # Command-line interface
    server/              # Server implementation
        __init__.py      # Server package initialization
        app.py           # ASGI application setup
        config.py        # Configuration settings
        handlers.py      # Tool implementations
        http.py          # HTTP utilities
    semantic_search/     # Semantic search functionality
        __init__.py      # Package initialization
        indexing.py      # Build and persist vector store
        search.py        # Load index and query helpers

Uso com o Cursor

Este servidor MCP pode ser usado com o Cursor como cliente. Para a configuração:

1. Execute o servidor em um terminal:

source venv/bin/activate
python -m mcp_simple_tool start
# or use the restart command
python -m mcp_simple_tool restart

2. Configure o Cursor criando um arquivo .cursor/mcp.json:

{
  "mcpServers": {
    "website-fetcher-sse": {
      "url": "http://localhost:7000/sse"
    }
  }
}

3. Mencione o servidor em seus prompts ao usar o Cursor