ALMA_MCP

Servidor ALMA MCP - Acesso a Dados Astronômicos via Linguagem Natural

Um servidor Model Context Protocol (MCP) que fornece acesso abrangente ao arquivo do ALMA (Atacama Large Millimeter/submillimeter Array) por meio de uma arquitetura limpa e extensível.

Visão

Este servidor MCP transforma consultas ao arquivo do ALMA de um problema de engenharia de software em uma conversa em linguagem natural. Em vez de aprender a sintaxe TAP/ADQL e as APIs do arquivo, os pesquisadores simplesmente pedem o que precisam e obtêm resultados limpos e prontos para análise.

O resultado: assistentes de IA que podem pesquisar dados do ALMA de forma integrada por alvo, posição, frequência, resolução ou qualquer critério personalizado

---

Configuração Rápida para o Claude Desktop

1. Clone/Copie e Configure o Ambiente

IMPORTANTE: Altere os caminhos abaixo de acordo com SUA localização de instalação!

# Clone the repository (or copy the ALMA_MCP folder)
git clone https://github.com/adamzacharia/ALMA_MCP.git
cd ALMA_MCP

# Create a dedicated conda environment with Python 3.11+
conda create -n alma_mcp python=3.11
conda activate alma_mcp

# Install dependencies
pip install -r requirements.txt

# Install astronomical libraries for full functionality
pip install fastmcp alminer pyvo astroquery astropy pandas

Alternativa: Usando venv em vez de conda:

# Navigate to the ALMA_MCP folder
cd path/to/ALMA_MCP

# Create a dedicated venv environment
python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # Mac/Linux

# Install dependencies
pip install -r requirements.txt

2. Teste o Servidor

# Test basic functionality
python test_server.py

# Quick test (optional)
python -c "
from server import get_alma_info, ALMINER_AVAILABLE, PYVO_AVAILABLE
print(' Server loads successfully')
print(f' alminer available: {ALMINER_AVAILABLE}')
print(f' pyvo available: {PYVO_AVAILABLE}')
"

3. Configure o Claude Desktop

Encontre e edite o arquivo de configuração MCP do Claude Desktop:

1. Navegue até a pasta AppData do seu Claude Desktop:

   • Windows: Abra o Explorador de Arquivos e vá para %APPDATA%\Claude\
   • macOS: ~/Library/Application Support/Claude/

2. adicione o 'claude_desktop_config.json' ou adicione o conteúdo abaixo ao seu arquivo 'config.json'

3. Adicione a seguinte configuração ao arquivo:

IMPORTANTE: Altere o caminho abaixo de acordo com SUA localização de instalação!

{
  "mcpServers": {
    "alma": {
      "command": "python",
      "args": ["c:/Users/Asus/Desktop/Quasar-main/ALMA_MCP/server.py"]
    }
  }
}

Nota: Use barras normais / nos caminhos mesmo no Windows.

Usando um Ambiente Personalizado (Conda ou venv)

Se você instalou as dependências em um ambiente conda ou venv, você DEVE especificar o caminho completo para o executável Python desse ambiente. Caso contrário, o sistema não encontrará os pacotes instalados!

Para ambiente Conda:

{
  "mcpServers": {
    "alma": {
      "command": "C:/Users/YourName/anaconda3/envs/alma_mcp/python.exe",
      "args": ["c:/path/to/ALMA_MCP/server.py"],
      "cwd": "c:/path/to/ALMA_MCP",
      "env": {}
    }
  }
}

Para encontrar o caminho do Python do seu ambiente conda, execute:

conda activate alma_mcp
where python    # Windows
which python    # Mac/Linux

Para venv:

{
  "mcpServers": {
    "alma": {
      "command": "c:/path/to/ALMA_MCP/venv/Scripts/python.exe",
      "args": ["c:/path/to/ALMA_MCP/server.py"],
      "cwd": "c:/path/to/ALMA_MCP",
      "env": {}
    }
  }
}

4. Reinicie e Teste

1. Feche o Claude Desktop completamente (clique com o botão direito na bandeja do sistema → Sair)
2. Verifique o Gerenciador de Tarefas - Se o Claude ainda estiver em execução em segundo plano, encerre a tarefa
3. Reabra o Claude Desktop
4. Teste com uma consulta como:
   • "Pesquise no ALMA observações de M87"
   • "Encontre dados ALMA de alta resolução com resolução inferior a 0.5 segundos de arco"
   • "Quais são as bandas de frequência do ALMA?"

5. Solução de Problemas

O servidor não inicia:

# Check Python environment
python --version  # Should be 3.10+

# Test server manually
python server.py
# Should start without errors

Problemas de conexão MCP:

• Verifique se o caminho do Python na sua configuração está correto
• Certifique-se de que todas as dependências estão instaladas
• Verifique se server.py existe no caminho especificado

Dependências ausentes:

pip install fastmcp alminer pyvo astroquery astropy pandas

---

Exemplos de Uso

Depois de configurado, você pode fazer perguntas em linguagem natural sobre dados do ALMA:

Pesquisas Básicas

• "Encontre observações de Orion KL"
• "Pesquise no ALMA por M87 dentro de 1 minuto de arco"
• "Quais dados ALMA existem para NGC 1234?"

Pesquisas por Posição

• "Pesquise no ALMA em RA=83.6, Dec=-5.4"
• "Encontre observações perto do Centro Galáctico"
• "Busca cônica nas coordenadas 150.5, 2.2 com raio de 5 minutos de arco"

Pesquisas por Frequência

• "Encontre dados ALMA entre 230 e 250 GHz"
• "Pesquise observações da Banda 6"
• "Quais observações cobrem a linha CO(2-1) em 230.5 GHz?"

Pesquisas por Resolução

• "Encontre dados de alta resolução com resolução inferior a 0.1 segundos de arco"
• "Pesquise observações ALMA com resolução melhor que 0.5 arcsec"

Pesquisas por Proposta/PI

• "Encontre propostas ALMA de Adele Plunket"
• "Obtenha dados da proposta 2023.1.00001.S"
• "Pesquise propostas de evolução de galáxias"

Cobertura de Linhas Espectrais

• "Alguma observação de M87 cobre a linha CO(2-1)?"
• "Verifique se os dados de Orion cobrem HCN(1-0) em 88.6 GHz"
• "Encontre observações que cobrem 115 GHz para uma fonte em z=0.5"

Consultas SQL Personalizadas

• "Execute este SQL: SELECT target_name, band_list FROM ivoa.obscore WHERE target_name LIKE '%M87%'"
• "Consulte o ALMA por todas as observações da Banda 7 de 2023"

Informações do ALMA

• "Quais são as bandas de frequência do ALMA?"
• "Liste linhas espectrais comuns na faixa de mm"
• "Quais categorias científicas o ALMA suporta?"

---

Pesquisas por Bibliografia e Publicações

• "Encontre observações ALMA publicadas na Nature"
• "Pesquise dados usados em artigos de Smith publicados em 2023"
• "Quais dados ALMA têm o bibcode 2017ApJ...834..140R"

Pesquisas por Palavras-chave Científicas

• "Encontre todas as observações ALMA marcadas com 'Quasars'"
• "Pesquise observações de Galáxias Sub-mm (SMG)"
• "Quais observações são categorizadas sob 'Núcleos Ativos de Galáxias'?"

Pesquisas por Tipo de Dado

• "Encontre todos os cubos espectrais de M87"
• "Pesquise imagens de contínuo marcadas com Exoplanetas"
• "Mostre-me observações de linhas espectrais na Banda 6"

Pesquisas por Resumo

• "Encontre propostas que mencionem buracos negros em seus resumos"
• "Pesquise observações de propostas sobre formação estelar"
• "Quais propostas mencionam o fundo cósmico de micro-ondas?"

Pesquisas por Sensibilidade

• "Encontre observações com sensibilidade de contínuo melhor que 0.1 mJy/beam"
• "Pesquise observações ALMA profundas com sensibilidade inferior a 0.05 mJy"

Consultas em Lote de Múltiplas Fontes

• "Verifique se o ALMA observou M31, M51, M82 e NGC 1068"
• "Consulte o ALMA para estas fontes: Cen A, M83 e NGC 1234"

---

Uso com Outros LLMs e Frameworks

Integração com LangChain

Você pode usar este servidor MCP com LangChain usando o pacote langchain-mcp-adapters:

pip install langchain-mcp-adapters

from langchain_mcp_adapters.client import MCPClient
from langchain_openai import ChatOpenAI

# Connect to the MCP server
client = MCPClient(
    command="python",
    args=["path/to/ALMA_MCP/server.py"]
)

# Get tools from MCP server
tools = client.get_tools()

# Use with any LangChain-compatible LLM
llm = ChatOpenAI(model="gpt-4")
llm_with_tools = llm.bind_tools(tools)

LLMs de Código Aberto

Para LLMs de código aberto (Ollama, LMStudio, etc.), você pode:

1. Use clientes compatíveis com MCP: Alguns projetos de código aberto como MCP CLI suportam conectar servidores MCP a LLMs locais.

2. Chamada direta de funções: Importe as funções do servidor diretamente no seu código Python:

from server import search_alma_by_target, search_alma_by_position, get_alma_info

# Use tools directly
result = search_alma_by_target("M87", search_radius_arcmin=5.0)
print(result)

# Get ALMA reference info
info = get_alma_info()
print(info)

3. Crie uma API REST: Envolva as ferramentas MCP em um servidor FastAPI/Flask para qualquer LLM que suporte chamada de funções via HTTP.

---

Arquitetura

ALMA_MCP/
├── server.py           # Main MCP server with 16 tools
├── requirements.txt    # Python dependencies
├── test_server.py      # Test suite
└── README.md           # This file

---

Recursos

Acesso ao Arquivo do ALMA

• Pesquisa por Alvo: Resolva nomes de objetos via SIMBAD e pesquise no ALMA
• Pesquisa por Posição: Busca cônica por coordenadas RA/Dec
• Pesquisa por Proposta: Encontre por nome do PI, ID da proposta ou categoria científica
• Pesquisa por Frequência: Consulte por faixa de frequência (GHz)
• Pesquisa por Resolução: Filtre por resolução angular (arcsec)
• SQL Personalizado: Execute qualquer consulta ADQL contra o TAP do ALMA

Ferramentas de Consulta Principais (8 originais)

Ferramenta	Descrição
search_alma_by_target	Pesquisa por nome de objeto astronômico (resolução SIMBAD)
search_alma_by_position	Busca cônica por coordenadas RA/Dec
search_alma_by_proposal	Pesquisa por nome do PI ou ID da proposta
search_alma_by_frequency	Pesquisa por faixa de frequência (GHz)
search_alma_by_resolution	Pesquisa por resolução angular (arcsec)
check_alma_line_coverage	Verifica cobertura de linhas espectrais com redshift
get_alma_info	Referência de bandas, linhas e capacidades do ALMA
run_alma_tap_query	Consultas SQL/ADQL personalizadas contra o TAP

Ferramentas de Consulta Estendidas (8 novas - dos notebooks do ALMA)

Ferramenta	Descrição
search_alma_by_source_name	Pesquisa por nome de alvo especificado pelo PI (exato ou parcial)
search_alma_by_bibliography	Pesquisa por bibcode, periódico, autor ou ano de publicação
search_alma_by_member_ous	Pesquisa por identificador de conjunto de dados Member OUS
search_alma_by_data_type	Pesquisa por cubos (espectrais) vs imagens (contínuo)
search_alma_by_science_keyword	Pesquisa por palavras-chave científicas do ALMA
search_alma_by_abstract	Pesquisa de texto completo em resumos de propostas/publicações
search_alma_by_sensitivity	Pesquisa por sensibilidade de contínuo ou linha (mJy/beam)
query_alma_multiple_sources	Consulta em lote para múltiplas fontes de uma só vez

Suporte Multi-Backend

• alminer: Consultas ALMA avançadas com ferramentas de linhas espectrais
• pyvo: Acesso direto TAP/ADQL ao arquivo do ALMA
• astroquery: Resolução de nomes SIMBAD

---

Dependências

Requisitos Principais

fastmcp>=2.0.0      # MCP framework
pandas>=1.5.0       # Data manipulation

Bibliotecas Astronômicas

alminer>=0.2.0      # Advanced ALMA queries
pyvo>=1.4.0         # TAP/ADQL access
astroquery>=0.4.0   # SIMBAD, VizieR, etc.
astropy>=5.0.0      # Astronomical utilities

---

Roteiro

Atual (v1.0) ✅

• Pesquisa de nome de alvo ALMA com resolução SIMBAD
• Busca cônica baseada em posição
• Pesquisa por faixa de frequência
• Filtragem por resolução angular
• Pesquisa por proposta/PI
• Verificação de cobertura de linhas espectrais
• Consultas SQL/TAP personalizadas
• Informações do ALMA e referência de bandas
• Pesquisa por nome de fonte (nomes especificados pelo PI, exato/parcial)
• Pesquisa por bibliografia/publicação (bibcode, periódico, autor, ano)
• Pesquisa por ID Member OUS (identificador de conjunto de dados)
• Filtragem por tipo de dado (cubos vs imagens)
• Pesquisa por palavras-chave científicas com filtros
• Pesquisa de texto completo em resumos (proposta e publicação)
• Pesquisa baseada em sensibilidade (contínuo ou linha)
• Consultas em lote de múltiplas fontes

Planejado (v2.0)

• Integração com o arquivo do VLA
• Integração com o arquivo do GBT
• Cache de resultados para consultas mais rápidas
• Suporte a download de arquivos FITS
• Correspondência de objetos entre arquivos (ALMA + VLA + óptico)
• Ferramentas de visualização (mapas do céu, espectros)
• Fluxo de trabalho de download de dados

---

Movendo para um Local Independente

Esta pasta foi projetada para ser portátil. Para movê-la:

1. Copie a pasta inteira ALMA_MCP/ para o local desejado
2. Atualize o caminho em config.json
3. Reinicie o Claude Desktop

---

Contribuindo

1. Faça um fork do repositório
2. Crie um branch de recurso (git checkout -b feature/vla-support)
3. Adicione sua fonte de dados seguindo os padrões existentes
4. Escreva testes para a nova funcionalidade
5. Envie um pull request

Autores

• Adam Zacharia Anil - Desenvolvedor Principal
• Adele Plunkett - Consultora Científica

---

Agradecimentos

Agradecimentos especiais a:

• Adele Plunkett - Pela valiosa orientação e conselhos ao longo deste projeto
• NRAO (National Radio Astronomy Observatory) - Por apoiar a pesquisa astronômica e o acesso a dados
• Brian Mason - Pela experiência técnica e suporte
• Cosmic AI / Stella Offner - Pela inspiração em aplicar IA à pesquisa astronômica

---

Licença

Licença MIT - Consulte LICENSE para obter detalhes.

---

Citação

Se você usar este software em sua pesquisa, por favor cite:

@software{alma_mcp,
  title={ALMA MCP Server: Astronomical Data Access for AI Agents},
  author={Adam Zacharia Anil and Adele Plunkett},
  year={2025},
  url={https://github.com/adamzacharia/ALMA_MCP}
}

---

Suporte

• Issues: GitHub Issues
• Documentação: Este README e comentários de código inline
• Discussions: GitHub Discussions