Avalanche.org

avalanche-org-mcp-server

Um servidor Model Context Protocol (MCP) mínimo que encapsula os endpoints de camadas de mapa da Avalanche.org Public API. Ele permite que LLMs consultem classificações de perigo de avalanche por localização, recuperem GeoJSON bruto de previsões e consultem condições históricas.

Recursos

• Consulta de perigo por lat/lon — encontre a zona de avalanche para qualquer ponto e obtenha sua classificação de perigo atual
• Consulta de perigo histórico — igual ao anterior, mas para uma data passada específica
• GeoJSON bruto de camadas de mapa — FeatureCollection completa para todos os centros de avalanche, ou limitada a um centro específico

Dados provenientes da Avalanche.org Public API. Consulte a documentação da API para detalhes.

Início Rápido

Claude Desktop (npx — recomendado)

Adicione isto à configuração do seu Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

{
  "mcpServers": {
    "avalanche-org": {
      "command": "npx",
      "args": ["-y", "avalanche-org-mcp-server"]
    }
  }
}

Nenhuma instalação necessária. O Claude baixará e executará automaticamente.

Instalação global via npm

npm install -g avalanche-org-mcp-server

{
  "mcpServers": {
    "avalanche-org": {
      "command": "avalanche-org-mcp-server"
    }
  }
}

Docker

docker pull ghcr.io/haydenwade/avalanche-org-mcp-server:latest

{
  "mcpServers": {
    "avalanche-org": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/haydenwade/avalanche-org-mcp-server:latest"]
    }
  }
}

A partir do código-fonte

git clone https://github.com/haydenwade/avalanche-org-mcp-server.git
cd avalanche-org-mcp-server
npm install
npm run build

{
  "mcpServers": {
    "avalanche-org": {
      "command": "node",
      "args": ["/absolute/path/to/avalanche-org-mcp-server/dist/src/index.js"]
    }
  }
}

Ferramentas

avalanche_danger_rating_by_point

Obtenha a classificação atual de perigo de avalanche para um ponto lat/lon. Retorna a zona em que o ponto se encontra, ou a zona mais próxima se preferNearest for verdadeiro.

Exemplo de entrada:

{ "lat": 40.5763, "lon": -111.7522, "preferNearest": true, "centerId": "UAC" }

{
  "match": "inside_zone",
  "distance_km": 0,
  "distance_miles": 0,
  "zone": {
    "id": "zone-1",
    "name": "Salt Lake",
    "state": "UT"
  },
  "center": {
    "id": "UAC",
    "name": "Utah Avalanche Center",
    "timezone": "America/Denver",
    "link": "https://utahavalanchecenter.org"
  },
  "danger": {
    "level": 3,
    "label": "Considerable",
    "color": "#f1a302"
  },
  "travel_advice": "Dangerous avalanche conditions. Careful snowpack evaluation, cautious route-finding and conservative decision-making essential.",
  "forecast_url": "https://utahavalanchecenter.org/forecast/salt-lake",
  "validity": {
    "start_date": "2026-03-22",
    "end_date": "2026-03-23"
  },
  "warning": null
}

historic_avalanche_danger_rating_by_point

Igual ao anterior, mas para uma data histórica específica. Retorna todos os mesmos campos, além de day.

Exemplo de entrada:

{ "lat": 40.5763, "lon": -111.7522, "day": "2025-02-24", "preferNearest": true }

{
  "match": "inside_zone",
  "distance_km": 0,
  "distance_miles": 0,
  "zone": { "id": "zone-1", "name": "Salt Lake", "state": "UT" },
  "center": { "id": "UAC", "name": "Utah Avalanche Center", "..." : "..." },
  "danger": { "level": 3, "label": "Considerable", "color": "#f1a302" },
  "travel_advice": "Dangerous avalanche conditions. ...",
  "forecast_url": "https://utahavalanchecenter.org/forecast/salt-lake",
  "validity": { "start_date": "2025-02-24", "end_date": "2025-02-25" },
  "warning": null,
  "day": "2025-02-24"
}

raw_map_layer

Retorna a FeatureCollection GeoJSON bruta da camada de mapa da Avalanche.org para todos os centros de avalanche.

{
  "geojson": {
    "type": "FeatureCollection",
    "features": [ "... full GeoJSON features ..." ]
  }
}

raw_map_layer_by_avalanche_center

Retorna a FeatureCollection GeoJSON bruta da camada de mapa para um único centro de avalanche.

{
  "geojson": {
    "type": "FeatureCollection",
    "features": [ "... full GeoJSON features ..." ]
  }
}

Desenvolvimento

Requer Node.js >= 18.

npm install
npm run build
npm test

Para testar interativamente as ferramentas com o MCP Inspector:

npx @modelcontextprotocol/inspector node dist/src/index.js

Estrutura do projeto

src/
  index.ts          # Entry point — server setup + stdio transport
  tools.ts          # Tool registration
  constants.ts      # API URLs and timeouts
  types.ts          # GeoJSON type definitions
  api/
    mapLayer.ts     # Map-layer fetch + GeoJSON normalization
  lib/
    geometry.ts     # Point-in-polygon, haversine distance, bounds
    dangerLookup.ts # Danger rating lookup logic
    validation.ts   # Date and coordinate validation
test/
  *.test.ts         # Tests (node:test)

Contribuindo

1. Faça um fork do repositório
2. Crie um branch de funcionalidade (git checkout -b my-feature)
3. Faça suas alterações e adicione testes
4. Execute npm test para garantir que tudo passe
5. Abra um pull request

Licença

MIT