Servidor MCP de Surf

Servidor MCP para personas que navegan por Waves y la web.

Diagrama

Related MCP server: BC Water Tides MCP Server

Demostración en vídeo

https://github.com/user-attachments/assets/0a4453e2-66df-4bf5-8366-8538cda366ed

Características

• Obtenga información sobre mareas para cualquier ubicación utilizando latitud y longitud

• Soporte para consultas de mareas específicas de la fecha

• Datos detallados de mareas, incluidas mareas altas y bajas e información de la estación

• Manejo automático de zona horaria (UTC)

Prerrequisitos

• Python 3.x

• Clave API de Storm Glass

Cómo obtener su clave API de Storm Glass

1. Visita Storm Glass

2. Haga clic en "Probar gratis" o "Iniciar sesión" para crear una cuenta.

3. Una vez registrado, recibirás tu clave API

Nota sobre los límites de uso de la API:

• Nivel gratuito: 10 solicitudes por día

• Planes de pago disponibles:

  • Pequeño: 500 solicitudes/día (19€/mes)

  • Mediano: 5000 solicitudes/día (49€/mes)

  • Grande: 25.000 solicitudes/día (129 €/mes)

  • Empresa: Planes personalizados disponibles

Elige un plan según tus necesidades de uso. El plan gratuito es ideal para pruebas y uso personal.

Instalación

1. Clonar el repositorio:

git clone https://github.com/ravinahp/surf-mcp.git
cd surf-mcp

2. Instalar dependencias usando uv:

uv sync

Nota: Usamos uv en lugar de pip ya que el proyecto usa pyproject.toml para la gestión de dependencias.

Configurar como servidor MCP

Para agregar esta herramienta como servidor MCP, deberá modificar el archivo de configuración de su escritorio Claude. Esta configuración incluye su clave API de Storm Glass, por lo que no necesitará configurarla por separado.

La ubicación del archivo de configuración depende de su sistema operativo:

• MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json

• Ventanas: %APPDATA%/Claude/claude_desktop_config.json

Agregue la siguiente configuración a su archivo JSON:

{
    "surf-mcp": {
        "command": "uv",
        "args": [
            "--directory",
            "/Users/YOUR_USERNAME/Code/surf-mcp",
            "run",
            "surf-mcp"
        ],
        "env": {
            "STORMGLASS_API_KEY": "your_api_key_here"
        }
    }
}

⚠️ IMPORTANTE:

1. Reemplace YOUR_USERNAME con su nombre de usuario actual del sistema

2. Reemplace your_api_key_here con su clave API de Storm Glass real

3. Asegúrese de que la ruta del directorio coincida con su instalación local

Despliegue

Edificio

Para preparar el paquete:

1. Sincronizar dependencias y actualizar el archivo de bloqueo:

uv sync

2. Paquete de compilación:

uv build

Esto creará distribuciones en el directorio dist/ .

Depuración

Dado que los servidores MCP se ejecutan en stdio, la depuración puede ser complicada. Para una experiencia óptima, recomendamos usar el Inspector MCP.

Puede iniciar el Inspector MCP con este comando:

npx @modelcontextprotocol/inspector uv --directory /path/to/surf-mcp run surf-mcp

Al iniciarse, el Inspector mostrará una URL a la que podrá acceder en su navegador para comenzar a depurar.

El Inspector proporciona:

• Monitoreo de solicitudes y respuestas en tiempo real

• Validación de entrada/salida

• Seguimiento de errores

• Métricas de rendimiento

Uso

El servicio proporciona una herramienta FastMCP para obtener información sobre las mareas:

@mcp.tool()
async def get_tides(latitude: float, longitude: float, date: str) -> str:
    """Get tide information for a specific location and date."""

Parámetros:

• latitude : valor flotante que representa la latitud de la ubicación

• longitude : valor flotante que representa la longitud de la ubicación

• date : cadena de fecha en formato AAAA-MM-DD

Ejemplo de respuesta:

Tide Times:
Time: 2024-01-20T00:30:00+00:00 (UTC)
Type: HIGH tide
Height: 1.52m

Time: 2024-01-20T06:45:00+00:00 (UTC)
Type: LOW tide
Height: 0.25m

Station Information:
Name: Sample Station
Distance: 20.5km from requested location

Casos de uso

Ejemplo n.° 1: Encontrar el mejor momento para surfear

Puedes usar esta herramienta para determinar el mejor momento para surfear en tu playa favorita y la estación más cercana. Generalmente, las mejores condiciones para surfear se dan durante la marea alta, unas dos horas antes de la pleamar.

Ejemplo de mensaje para Claude:

Nota: Las condiciones óptimas de marea pueden variar según la geografía y el tipo de rompiente de cada playa. Esta herramienta también proporciona información sobre la distancia entre estaciones, que debe considerarse junto con la información sobre mareas. (Por ejemplo, una mayor distancia entre estaciones implica una mayor probabilidad de inexactitud; también puede preguntarle a Claude si se lo solicita).

Manejo de errores

El servicio incluye un manejo robusto de errores para:

• Errores en las solicitudes de API

• Coordenadas no válidas

• Claves API faltantes o no válidas

• Tiempos de espera de la red