Astro MCP

Um servidor modular que fornece acesso unificado a múltiplos conjuntos de dados astronômicos, incluindo serviços astroquery e fontes de dados do DESI.

GitHub
5

Documentação

Astro MCP - Acesso Agêntico a Dados Astronômicos

Um servidor modular de Model Context Protocol (MCP) que fornece acesso unificado a múltiplos conjuntos de dados astronômicos através de uma arquitetura limpa e extensível.

Visão

Este servidor MCP visa transformar a astronomia de big data de um problema de engenharia de software em uma conversa em linguagem natural. Em vez de passar meses aprendendo APIs do astroquery, pesquisadores simplesmente pedem o que precisam e recebem produtos de dados limpos e processados, prontos para análise.

Um especialista resolve a complexidade uma vez; milhares de cientistas se beneficiam para sempre. Um estudante com pouca experiência em programação agora pode realizar a mesma análise multi-levantamento que um astrônomo especialista usando apenas linguagem natural e um assistente de IA.

Isto não é apenas sobre astronomia—é um modelo para democratizar toda a ciência. Todo campo tem pesquisadores brilhantes gastando 80% do seu tempo com manipulação de dados em vez de descoberta. Ao remover esse gargalo, aceleramos o ritmo do progresso científico em si.

O resultado: cientistas de IA que podem acessar e cruzar dados de dezenas de levantamentos astronômicos sem esforço, permitindo descobertas que teriam exigido meses de preparação há apenas alguns anos.

Configuração Rápida para Cursor & Claude Desktop

1. Clone e Configure o Ambiente

# Clone the repository
git clone https://github.com/SandyYuan/astro_mcp.git
cd astro_mcp

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

# Install dependencies
pip install -r requirements.txt

# Install astronomical libraries for full functionality
pip install sparclclient datalab astropy astroquery

2. Teste o Servidor

# Test basic functionality
python test_server.py

# Test with a simple query (optional)
python -c "
import asyncio
from server import astro_server
async def test():
    result = astro_server.get_global_statistics()
    print('✅ Server working:', result['total_files'], 'files in registry')
    services = astro_server.list_astroquery_services()
    print(f'✅ Astroquery: {len(services)} services discovered')
asyncio.run(test())
"

3. Configure para o Cursor

Adicione esta configuração às configurações MCP do seu Cursor:

{
  "mcpServers": {
    "astro-mcp": {
      "command": "/path/to/conda/envs/mcp/bin/python",
      "args": ["/path/to/astro_mcp/server.py"],
      "cwd": "/path/to/astro_mcp",
      "env": {}
    }
  }
}

Para encontrar o caminho do Python do conda:

conda activate mcp
which python
# Copy this path for the "command" field above

4. Configure para o Claude Desktop

Edite o arquivo de configuração MCP do seu Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "astro-mcp": {
      "command": "/path/to/conda/envs/mcp/bin/python",
      "args": ["/path/to/astro_mcp/server.py"],
      "cwd": "/path/to/astro_mcp",
      "env": {}
    }
  }
}

5. Reinicie e Teste

  1. Reinicie o Cursor/Claude Desktop para carregar o novo servidor MCP
  2. Teste com uma consulta como:
    • "Busque galáxias próximas a RA=10.68, Dec=41.27"
    • "Obtenha as coordenadas de Betelgeuse no SIMBAD"
    • "Encontre 10 galáxias BOSS em torno de z=0.5 e salve como FITS"
    • "Liste os serviços astroquery disponíveis"

6. Solução de Problemas

O servidor não inicia:

# Check Python environment
conda activate mcp
python --version  # Should be 3.11+

# 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 aponta para o ambiente conda
  • Certifique-se de que o diretório de trabalho (cwd) aponta para a pasta astro_mcp
  • Verifique se todas as dependências estão instaladas no ambiente correto

Dados astronômicos ausentes:

# Install optional dependencies for full functionality
conda activate mcp
pip install sparclclient datalab astropy astroquery h5py

Exemplos de Uso com Cursor/Claude Desktop

Uma vez configurado, você pode fazer perguntas em linguagem natural sobre dados astronômicos:

Buscas Básicas

  • "Encontre galáxias próximas a RA=150.5, Dec=2.2 dentro de 0.1 graus"
  • "Busque quasares com redshift entre 2 e 3"
  • "Obtenha as coordenadas exatas de Betelgeuse no SIMBAD"
  • "Encontre 10 galáxias BOSS em torno de redshift 0.5"

Acesso Multi-Levantamento

  • "Consulte o VizieR para catálogos estelares na região de Orion"
  • "Busque galáxias no SDSS e salve em formato FITS"
  • "Obtenha informações de objetos em múltiplos bancos de dados astronômicos"
  • "Liste todos os serviços astroquery disponíveis para estudos de galáxias"

Análise de Dados Espectrais

  • "Obtenha o espectro do objeto DESI com ID 1270d3c4-9d36-11ee-94ad-525400ad1336"
  • "Mostre-me informações espectrais detalhadas do quasar mais brilhante que você encontrar"
  • "Encontre um espectro de galáxia e analise seu redshift"

Gerenciamento e Conversão de Arquivos

  • "Liste todos os arquivos de dados astronômicos salvos"
  • "Converta meu catálogo de galáxias para formato FITS"
  • "Pré-visualize a estrutura dos resultados de busca mais recentes"
  • "Mostre estatísticas de armazenamento dos dados baixados"

Consultas Avançadas

  • "Encontre galáxias de alto redshift (z > 1.5) e salve seus espectros"
  • "Busque objetos no campo COSMOS e analise seus tipos"
  • "Cruze dados DESI e SDSS para a mesma região do céu"

O servidor irá automaticamente:

  • Executar consultas apropriadas em múltiplos levantamentos
  • Salvar resultados com nomes de arquivo descritivos e metadados
  • Lidar com conversões de coordenadas e cálculos astronômicos
  • Converter dados para formatos padrão (CSV, FITS) conforme necessário

Arquitetura

astro_mcp/
├── server.py                    # Main MCP server entry point
├── data_sources/               # Modular data source implementations
│   ├── __init__.py
│   ├── base.py                # Base class for all data sources
│   ├── desi.py                # DESI survey data access
│   ├── astroquery_universal.py # Universal astroquery wrapper
│   └── astroquery_metadata.py  # Service metadata and capabilities
├── data_io/                   # File handling and conversion
│   ├── __init__.py
│   ├── preview.py             # Data preview and structure analysis
│   └── fits_converter.py      # FITS format conversion
├── tests/                     # Test suite
├── examples/                  # Usage examples
└── requirements.txt           # Project dependencies

Recursos

🔭 Acesso Universal a Dados Astronômicos

  • DESI: Instrumento Espectroscópico de Energia Escura via SPARCL e Data Lab
  • Astroquery: Acesso automático a mais de 40 serviços astronômicos (SIMBAD, VizieR, SDSS, Gaia, etc.)
  • Auto-descoberta: Detecta e configura automaticamente os serviços astroquery disponíveis
  • Interface unificada: Mesma API para todas as fontes de dados

📁 Gerenciamento Inteligente de Arquivos

  • Salvamento automático de dados com nomes de arquivo descritivos
  • Registro e organização de arquivos entre fontes
  • Rastreamento abrangente de metadados com proveniência
  • Pré-visualização inteligente de arquivos com exemplos de carregamento
  • Conversão para formato FITS para compatibilidade astronômica

🔍 Recursos Poderosos de Busca

  • Buscas baseadas em coordenadas (ponto, cone, caixa) em todos os levantamentos
  • Filtragem por tipo de objeto e redshift
  • Consultas SQL com indexação espacial (Q3C)
  • Interpretação de consultas em linguagem natural
  • Correlação de dados entre levantamentos

📊 Ferramentas de Análise e Conversão de Dados

  • Recuperação e análise de dados espectrais
  • Conversão automática para FITS de catálogos, espectros e imagens
  • Inspeção e pré-visualização de estrutura de arquivos
  • Estatísticas e gerenciamento de armazenamento
  • Arquitetura de ferramentas extensível para análises personalizadas

🤖 Interface Otimizada para IA

  • Pré-processamento e validação de parâmetros
  • Tratamento inteligente de erros com sugestões úteis
  • Detecção e conversão automática de formatos
  • Metadados consistentes em todas as fontes de dados

Instalação

Início Rápido: Para integração com Cursor & Claude Desktop, veja a seção Configuração Rápida acima.

Instalação Manual

# Clone the repository
git clone https://github.com/SandyYuan/astro_mcp.git
cd astro_mcp

# Create and activate environment
conda create -n mcp python=3.11
conda activate mcp

# Install core dependencies
pip install -r requirements.txt

# Install astronomical libraries
pip install sparclclient datalab astropy astroquery

# Optional: Install development dependencies
pip install pytest coverage

Verifique a Instalação

# Test the server components
python test_server.py

# Check available astroquery services
python -c "
import asyncio
from server import astro_server

async def show_services():
    services = astro_server.list_astroquery_services()
    print(f'✅ Discovered {len(services)} astroquery services')
    for service in services[:5]:  # Show first 5
        print(f'  - {service["full_name"]} ({service["service"]})')

asyncio.run(show_services())
"

Início Rápido

1. Inicie o Servidor MCP

python server.py

2. Ferramentas Disponíveis

O servidor fornece estas ferramentas principais:

Acesso a Dados:

  • search_objects - Encontre objetos astronômicos (DESI)
  • astroquery_query - Consultas universais em mais de 40 serviços astronômicos
  • get_spectrum_by_id - Recupere dados espectrais detalhados (DESI)

Descoberta de Serviços:

  • list_astroquery_services - Mostre todos os bancos de dados astronômicos disponíveis
  • get_astroquery_service_details - Informações detalhadas de serviços
  • search_astroquery_services - Encontre serviços por critérios

Gerenciamento de Arquivos:

  • preview_data - Inspecione arquivos salvos com análise de estrutura
  • list_files - Gerencie dados salvos de todas as fontes
  • file_statistics - Informações de uso de armazenamento e organização
  • convert_to_fits - Converta dados para formato FITS

3. Exemplo de Uso

# Get object coordinates from SIMBAD
astroquery_query(
    service_name="simbad",
    object_name="Betelgeuse"
)

# Search SDSS for galaxies with SQL
astroquery_query(
    service_name="sdss",
    query_type="query_sql",
    sql="SELECT TOP 10 ra, dec, z FROM SpecObj WHERE class='GALAXY' AND z BETWEEN 0.1 AND 0.3"
)

# Search VizieR catalogs
astroquery_query(
    service_name="vizier",
    ra=10.68,
    dec=41.27,
    radius=0.1
)

# Convert results to FITS
convert_to_fits(
    identifier="search_results.csv",
    data_type="catalog"
)

Fontes de Dados

DESI (Instrumento Espectroscópico de Energia Escura)

Status: ✅ Totalmente Implementado

  • Acesso SPARCL: Recuperação completa de dados espectrais
  • SQL do Data Lab: Consultas rápidas de catálogo (tabela sparcl.main)
  • Cobertura: DESI EDR (~1.8M) e DR1 (~18M+ espectros)
  • Comprimento de onda: 360-980 nm, Resolução: R ~ 2000-5500

Acesso Universal Astroquery

Status: ✅ Totalmente Implementado

Principais Serviços Disponíveis:

  • SIMBAD: Identificação de objetos e dados básicos
  • VizieR: Catálogos e levantamentos astronômicos
  • SDSS: Dados e espectros do Sloan Digital Sky Survey
  • Gaia: Dados astrométricos e fotométricos
  • MAST: Arquivos do Hubble, JWST e outros telescópios espaciais
  • IRSA: Arquivos infravermelhos e submilimétricos
  • ESASky: Dados astronômicos de múltiplas missões
  • E mais de 30 serviços...

Capacidades:

  • Descoberta e configuração automática de serviços
  • Detecção inteligente de tipo de consulta
  • Pré-processamento e validação de parâmetros
  • Tratamento unificado de erros e geração de ajuda

Dependências Necessárias:

pip install astroquery astropy

Estendendo a Arquitetura

Adicionando uma Nova Fonte de Dados

  1. Crie a classe da fonte de dados:
# data_sources/my_survey.py
from .base import BaseDataSource

class MySurveyDataSource(BaseDataSource):
    def __init__(self, base_dir=None):
        super().__init__(base_dir=base_dir, source_name="my_survey")
        # Initialize survey-specific clients
    
    def search_objects(self, **kwargs):
        # Implement survey-specific search
        pass
  1. Atualize o servidor principal:
# server.py
from data_sources import MySurveyDataSource

class AstroMCPServer:
    def __init__(self, base_dir=None):
        # ... existing code ...
        self.my_survey = MySurveyDataSource(base_dir=base_dir)

Adicionando Novos Serviços Astroquery

A integração astroquery descobre automaticamente novos serviços. Para adicionar metadados personalizados:

# data_sources/astroquery_metadata.py
ASTROQUERY_SERVICE_INFO = {
    "my_service": {
        "full_name": "My Custom Service",
        "description": "Custom astronomical database",
        "data_types": ["catalogs", "images"],
        "wavelength_coverage": "optical",
        "object_types": ["stars", "galaxies"],
        "requires_auth": False,
        "example_queries": [
            {
                "description": "Search by object name",
                "query": "astroquery_query(service_name='my_service', object_name='M31')"
            }
        ]
    }
}

Organização de Arquivos

Os arquivos são organizados automaticamente por fonte de dados com metadados abrangentes:

~/astro_mcp_data/
├── file_registry.json           # Global file registry with metadata
├── desi/                        # DESI-specific files
│   ├── desi_search_*.json      # Search results
│   ├── spectrum_*.json         # Spectral data
│   └── *.fits                  # FITS conversions
└── astroquery/                 # Astroquery results
    ├── astroquery_simbad_*.csv # SIMBAD queries
    ├── astroquery_sdss_*.csv   # SDSS results
    ├── astroquery_vizier_*.csv # VizieR catalogs
    └── *.fits                  # FITS conversions

Desenvolvimento

Benefícios da Estrutura do Projeto

  • Modularidade: Fácil adicionar novos levantamentos e ferramentas de análise
  • Acesso Universal: Interface única para mais de 40 bancos de dados astronômicos
  • Separação de Preocupações: Acesso a dados, E/S e análise são separados
  • Testabilidade: Cada módulo pode ser testado independentemente
  • Escalabilidade: Arquitetura limpa suporta crescimento ilimitado

Testes

# Run all tests
pytest

# Test specific modules
pytest tests/test_desi.py
pytest tests/test_astroquery.py

# Test with coverage
pytest --cov=data_sources tests/

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade (git checkout -b feature/new-capability)
  3. Adicione sua fonte de dados ou ferramenta seguindo os padrões existentes
  4. Escreva testes para a nova funcionalidade
  5. Atualize a documentação e os exemplos
  6. Envie um pull request

Dependências

Requisitos Principais

  • mcp>=1.0.0 - Estrutura do Model Context Protocol
  • pandas>=2.0.0 - Manipulação de dados
  • numpy>=1.24.0 - Computação numérica

Bibliotecas Astronômicas

  • astroquery>=0.4.6 - Acesso universal a bancos de dados astronômicos
  • astropy>=5.0.0 - Arquivos FITS e cálculos astronômicos
  • sparclclient>=1.0.0 - Acesso DESI SPARCL
  • datalab>=2.20.0 - Consultas NOAO Data Lab

Recursos Opcionais

  • h5py>=3.8.0 - Suporte a arquivos HDF5
  • pytest>=7.0.0 - Estrutura de testes

Licença

[Especifique sua licença aqui]

Citação

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

@software{astro_mcp,
  title={Astro MCP: Universal Astronomical Data Access for AI Agents},
  author={[Your Name]},
  year={2024},
  url={[Repository URL]}
}

Suporte

Roteiro

Atual (v0.1.0)

  • ✅ Acesso a dados DESI via SPARCL e Data Lab
  • ✅ Integração universal astroquery (mais de 40 serviços)
  • ✅ Conversão automática para FITS de todos os tipos de dados
  • ✅ Gerenciamento inteligente de arquivos com metadados abrangentes
  • ✅ Interface de consulta em linguagem natural

Planejado (v0.2.0)

  • 🚧 Correspondência e correlação de objetos entre levantamentos
  • 🚧 Cálculos astronômicos avançados (distâncias, magnitudes)
  • 🚧 Análise de séries temporais para objetos variáveis
  • 🚧 Integração de ferramentas de visualização

Futuro (v0.3.0+)

  • 🔮 Integração de aprendizado de máquina para classificação de objetos
  • 🔮 Streaming de dados em tempo real de levantamentos
  • 🔮 Criação de pipelines de análise personalizados
  • 🔮 Ferramentas de correlação de dados multi-comprimento de onda