airquality-tr-mcp

airquality-tr-mcp

Disponibiliza os dados oficiais da Rede Nacional de Monitoramento da Qualidade do Ar (UHKİA) da Turquia como um servidor MCP (Model Context Protocol); um assistente compatível com MCP, como o Claude Desktop, pode responder a perguntas em tempo real e históricas sobre a qualidade do ar para 81 províncias e mais de 365 estações na Turquia.

Versão estável atual: v1.1.0

Esta é uma integração não oficial. Não tem afiliação com o Ministério do Meio Ambiente, Urbanização e Mudanças Climáticas da República da Turquia e não é endossada por ele. É responsabilidade do usuário cumprir os termos de uso do portal de origem.

Fontes de dados

• Medições de qualidade do ar: UHKİA (sim.csb.gov.tr) — por meio de endpoints oficiais, não documentados, mas públicos. O servidor usa os valores de IQA (Índice de Qualidade do Ar), categoria e poluente dominante retornados pela fonte exatamente como estão; nenhum cálculo, média ou previsão própria é feito.
• Geocodificação: OpenStreetMap Nominatim (https://nominatim.openstreetmap.org/search) — usado apenas para converter um local fornecido em texto em latitude/longitude; não fornece dados de qualidade do ar e não requer chave de API. A entrada de coordenadas nunca chama este serviço.

Requisitos

• Python 3.11+
• uv

Instalação

Via PyPI (recomendado):

pip install airquality-tr-mcp
# veya
uvx airquality-tr-mcp

Instalação para desenvolvimento clonando o repositório:

cd airquality-tr-mcp
uv sync

Configuração do Claude Desktop / Codex (stdio)

Se instalado com o pacote PyPI:

{
  "mcpServers": {
    "airquality-tr": {
      "command": "uvx",
      "args": ["airquality-tr-mcp"]
    }
  }
}

Com instalação de desenvolvimento clonada do repositório:

{
  "mcpServers": {
    "airquality-tr": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/airquality-tr-mcp",
        "run",
        "python",
        "-m",
        "airquality_tr_mcp.server"
      ]
    }
  }
}

Execução como API REST

Também está disponível uma API REST independente que usa a mesma lógica de negócios do servidor MCP:

uv run airquality-tr-api
# veya
uv run uvicorn airquality_tr_mcp.api:app --reload

Por padrão, escuta em http://localhost:8000. Visite http://localhost:8000/docs para documentação interativa. Os endpoints mapeiam um a um com as ferramentas MCP (/stations, /air-quality, /nearest-air-quality, /station, /historical-data, /trend-summary, /compare-cities, /ranking, /detailed-ranking, /health-advisory, /alert) e retornam os mesmos corpos JSON em turco; a única diferença é que, em casos de erro (respostas com o campo hata preenchido), um código de status HTTP apropriado (400/404/409/429/502/504) é retornado.

Ferramentas

Ferramenta	Finalidade
ping	Verifica se o processo MCP está ativo
list_stations	Lista estações UHKİA ativas
get_air_quality	Resumo da província e detalhamento por estação
get_nearest_air_quality	Dados da estação oficial mais próxima por texto ou coordenadas
get_station_detail	Medição atual completa de uma única estação
get_historical_data	Resumos históricos diários
get_trend_summary	Tendência de 3/6 dias baseada em regras
compare_cities	Comparação compacta entre duas províncias
get_ranking	Classificação em nível de província
get_detailed_ranking	Classificação nacional em nível de estação
get_health_advisory	Recomendação de saúde para província baseada em regras
check_alert	Verificação de limites de IQA/poluente sob demanda

get_air_quality e get_nearest_air_quality servem a propósitos diferentes:

• get_air_quality — fornece o resumo de uma província e o detalhamento de todas as estações nela; o valor representativo no resumo da província é a estação com o pior (maior IQA) daquela província.
• get_nearest_air_quality — encontra a estação mais próxima de um local (texto ou coordenadas) com medição de IQA válida dentro do limite de referência de 75 km; não se preocupa com limites provinciais.
• get_health_advisory — gera uma recomendação determinística baseada em regras de acordo com o status representativo (pior estação) de uma província.
• get_ranking vs get_detailed_ranking — get_ranking fornece uma classificação rápida com um único valor representativo por província; get_detailed_ranking classifica os mesmos dados em nível de estação em todo o país, sem resumir por província.

Exemplos de chamadas

ping()

list_stations()
list_stations(province="İstanbul")
list_stations(province="Kadıköy")

get_air_quality(province="Ankara")
get_air_quality(province="İstanbul", district="Kadıköy")

get_station_detail(station="Ankara - Çankaya")
get_station_detail(station="a1b2c3d4-e5f6-7890-abcd-ef1234567890")

get_historical_data(province="İzmir", days=7)
get_historical_data(province="İstanbul", days=14, district="Kadıköy")

get_trend_summary(province="Bursa", days=3)
get_trend_summary(province="Bursa", days=6)

compare_cities(province1="İstanbul", province2="Ankara")

get_ranking(mode="worst", limit=10)
get_ranking(mode="best", limit=5)

get_detailed_ranking(mode="worst", limit=20)

get_health_advisory(province="Kocaeli")

check_alert(province="İstanbul", threshold=100)
check_alert(province="Ankara", threshold=50, pollutant="PM10")
check_alert(province="İzmir", threshold=40, pollutant="PM10", district="Konak")

Exemplos de get_nearest_air_quality

get_nearest_air_quality(location="Göbeklitepe, Şanlıurfa")
get_nearest_air_quality(latitude=37.2232, longitude=38.9224)

Privacidade, atribuição e limitações

• Consultas de localização por texto são enviadas ao OpenStreetMap Nominatim; a entrada de coordenadas ignora completamente essa transferência.
• As medições de qualidade do ar vêm da UHKİA.
• A distância é um cálculo local em linha reta (Haversine) — não é distância de estrada/rota.
• referans_hki não é uma previsão, interpolação ou média local; é o valor oficial da estação relevante na fonte.
• Uma medição com mais de duas horas é retornada mesmo assim, com um aviso claro.
• Este pacote é um software stdio local; não há serviço centralizado/hospedado na v1.
• O parâmetro location não tolera erros de digitação em província/distrito tão bem quanto get_air_quality (o Nominatim faz busca de texto livre, não correção fuzzy de província/distrito); se apenas a qualidade geral do ar de uma província/distrito for questionada, get_air_quality/list_stations devem ser preferidos.
• Nominatim/OpenStreetMap e UHKİA são dois serviços externos independentes e não relacionados.

Licença

Este projeto é licenciado sob a Licença MIT.