Simple MCP Tool Server

Simple MCP Tool Server

Un servidor MCP simple que expone una herramienta de obtención de sitios web mediante transporte SSE.

Requisitos

• Python 3.10 o superior (probado en Python 3.13)

Instalación

# 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

Documentación del SDK de Python de MCP

La documentación del SDK de Python de MCP se ha dividido en archivos más pequeños y organizado en el directorio docs/. Esta estructura facilita que los agentes de IA naveguen y comprendan el SDK. La documentación cubre:

• Conceptos principales (servidores, recursos, herramientas, etc.)
• Ejecución de servidores MCP en diferentes modos
• Ejemplos y uso avanzado
• ¡Y más!

Uso

El paquete proporciona una interfaz de línea de comandos (CLI) con varios comandos para gestionar el servidor MCP:

Iniciar el servidor

Inicia el servidor en el puerto predeterminado (7000) o especifica un puerto personalizado:

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

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

Gestionar el 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]

El comando de reinicio:

1. Detiene cualquier servidor existente en el puerto especificado
2. Inicia un nuevo servidor en segundo plano
3. Espera hasta que el servidor responda
4. Registra la salida en server.log

Referencia rápida de la CLI

Comando	Propósito
start	Iniciar el servidor
stop	Detener el servidor
check	Comprobación de salud
restart	Detener e iniciar

Herramientas del servidor

El servidor expone las siguientes herramientas:

• fetch: Remoto Buscador HTTP – proporciona una URL absoluta; devuelve el texto de la página.

  • url: La URL del sitio web a buscar (obligatorio)

• search_docs: Búsqueda semántica en la documentación del SDK; devuelve los k mejores extractos.

  • query: Frase de búsqueda o pregunta (obligatorio)
  • k: Número de coincidencias principales a devolver (opcional, por defecto = 3)

• get_content: Obtén el archivo local completo de cualquier coincidencia devuelta por search_docs.

  • file: Ruta relativa a los documentos (obligatorio)

Configuración de desarrollo

Para el desarrollo, instala herramientas adicionales:

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

Usa el Makefile para tareas comunes:

# Format code
make fmt

# Run linters
make lint

# Run tests
make test

El conjunto de pruebas tiene un tiempo de espera integrado de 20 segundos para todas las pruebas para evitar bloqueos, especialmente con endpoints SSE. Para pruebas individuales, se puede especificar un tiempo de espera más estricto usando el decorador @pytest.mark.timeout(seconds).

Índice de búsqueda semántica

Para la herramienta search_docs, puedes construir o reconstruir manualmente el índice vectorial:

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

El índice se construye automáticamente en el primer uso de la herramienta si no existe.

Arquitectura del proyecto

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 con Cursor

Este servidor MCP se puede usar con Cursor como cliente. Para la configuración:

1. Ejecuta el servidor en una terminal:

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

2. Configura Cursor creando un archivo .cursor/mcp.json:

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

3. Menciona el servidor en tus indicaciones al usar Cursor