CelestialMCP

CelestialMCP

Um servidor Model Context Protocol (MCP) projetado para assistentes de IA como o Claude. Ele fornece ferramentas para acessar dados astronômicos, como posições de objetos celestes, horários de nascer/ocaso, visibilidade e informações de catálogo.

Visão Geral

O CelestialMCP é construído com o mcp-framework e utiliza a biblioteca astronomy-engine para fornecer cálculos astronômicos precisos. Ele oferece várias ferramentas para determinar posições de objetos celestes, calcular seus horários de nascer e ocaso e listar objetos disponíveis de catálogos de estrelas e objetos de céu profundo.

Recursos

• Dados Celestes em Tempo Real: Acesse dados astronômicos atuais para uma variedade de objetos.
• Detalhes Abrangentes do Objeto: Recupere coordenadas equatoriais e horizontais (altitude/azimute), status de visibilidade, horários de nascer/trânsito/ocaso.
• Dados Especializados: Para objetos relevantes, obtenha distância (objetos do sistema solar), iluminação de fase (Lua e planetas) e próximas fases lunares (Lua).
• Catálogos Extensos: Utiliza catálogos locais para:
  • Objetos do sistema solar (Sol, Lua, planetas).
  • Estrelas (por exemplo, do banco de dados HYG).
  • Objetos de Céu Profundo (DSOs) incluindo objetos Messier, NGC e IC.
• Observador Configurável: Todos os cálculos são baseados em uma localização de observador pré-configurada (padrão: Vancouver, Canadá) e no horário atual do sistema.
• Atualizações Fáceis de Catálogo: Inclui um script para baixar e atualizar catálogos astronômicos abrangentes.

Ferramentas

O servidor fornece três ferramentas principais para a IA usar:

1. getCelestialDetails: Recupera informações astronômicas detalhadas para um objeto celeste específico.
2. listCelestialObjects: Lista objetos celestes disponíveis conhecidos pelo sistema, filtráveis por categoria.
3. getStarHoppingPath: Calcula um caminho de "star hopping" (salto de estrela) de uma estrela inicial brilhante até um objeto celeste alvo.

Configuração e Instalação

Pré-requisitos

• Node.js (versão >=18.19.0, conforme especificado em package.json)
• npm (geralmente vem com Node.js)

Passos

1. Clone o repositório (se ainda não o fez):

   git clone https://github.com/Rkm1999/CelestialMCP
   cd CelestialMCP
   

2. Instale as dependências:

   npm install
   

3. Baixe os Catálogos Astronômicos: Este passo é crucial para acessar uma ampla gama de estrelas e objetos de céu profundo.

   npm run fetch-catalogs
   

   Este script baixa o banco de dados de estrelas HYG e o catálogo de objetos de céu profundo OpenNGC (New General Catalogue) para o diretório data/. Se esses arquivos não forem baixados, o aplicativo tentará usar sample_stars.csv e sample_dso.csv do diretório data/ se presentes. Se nenhum arquivo de catálogo for encontrado, os respectivos catálogos ficarão vazios.

4. Compile o projeto: Isso compila o código TypeScript para JavaScript.

   npm run build
   

5. Inicie o servidor:

   npm start
   

   O servidor MCP iniciará e as ferramentas ficarão disponíveis para um assistente de IA conectado.

Usando com o Claude Desktop

Para usar o CelestialMCP com o Claude Desktop para desenvolvimento local, adicione a seguinte configuração ao seu arquivo de configuração do Claude Desktop:

# Install dependencies
npm install

# Fetch star and deep sky object catalogs (IMPORTANT!)
npm run fetch-catalogs

# Build the project
npm run build

# Start the server
npm start

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

{ "mcpServers": { "CelestialMCP": { "command": "node", // Or your node executable path "args":["/absolute/path/to/your/CelestialMCP/project/dist/index.js"] // Replace with the actual absolute path } } }

Dados de Catálogo

O script npm run fetch-catalogs baixa:

• hygdata_v41.csv: O banco de dados de estrelas HYG (aprox. 120.000 estrelas).
• ngc.csv: O catálogo OpenNGC (aprox. 14.000 objetos de céu profundo).

Esses arquivos são armazenados no diretório data/. Se esses arquivos de catálogo primários não forem encontrados, o aplicativo tentará carregar sample_stars.csv e sample_dso.csv se existirem no diretório data/. Para dados abrangentes, é altamente recomendável executar npm run fetch-catalogs.

Uso das Ferramentas

Todos os cálculos astronômicos realizados por essas ferramentas usam a localização do observador pré-configurada (veja src/config.ts) e o horário atual do sistema quando a solicitação é feita.

1. getCelestialDetails

Propósito: Recupera dados astronômicos abrangentes para um objeto celeste específico. Isso inclui sua posição atual (coordenadas equatoriais e horizontais), visibilidade (por exemplo, acima/abaixo do horizonte, qualidade de visibilidade), horários de nascer/trânsito/ocaso para o dia atual e, para objetos relevantes, distância da Terra, fase de iluminação e próximas fases lunares (para a Lua).

Parâmetros:

• objectName (string): O nome ou identificador de catálogo do objeto celeste. A ferramenta pode resolver nomes comuns (por exemplo, "Andromeda Galaxy") para seus IDs de catálogo (por exemplo, "M31"). Exemplos: "Mars", "Sirius", "M42", "NGC 253", "Orion Nebula", "Moon", "Sun"

Exemplos de Prompts para Claude:

• "Obtenha detalhes de Júpiter a partir da localização configurada."
• "Quais são as coordenadas atuais da Lua?"
• "Fale sobre a estrela Vega, incluindo seus horários de nascer e ocaso para hoje."
• "A Galáxia do Rodamoinho (M51) está visível esta noite?"
• "Mostre-me informações sobre a posição atual do Sol e seus horários de nascer/ocaso."

2. listCelestialObjects

Propósito: Lista objetos celestes conhecidos pelo sistema, que podem então ser consultados usando getCelestialDetails. Os objetos podem ser filtrados por categoria. Isso ajuda a descobrir quais objetos estão disponíveis para consulta.

Parâmetros:

• category (string, opcional): Filtra a lista de objetos por uma categoria específica. Se omitido, o padrão é "all". As categorias válidas são:
  • planets: Objetos do Sistema Solar (Sol, Lua, Mercúrio, Vênus, Marte, Júpiter, Saturno, Urano, Netuno, Plutão).
  • stars: Estrelas nomeadas ou catalogadas.
  • messier: Objetos do catálogo Messier (por exemplo, M1, M31).
  • ic: Objetos do Index Catalogue (por exemplo, IC 434).
  • ngc: Objetos do New General Catalogue (por exemplo, NGC 7000).
  • dso: Todos os Objetos de Céu Profundo (combina Messier, IC, NGC e outros DSOs, como nebulosas ou galáxias nomeadas comuns que não estão nesses catálogos específicos, se disponíveis).
  • all: Todos os objetos disponíveis de todas as categorias (padrão).

Exemplos de Prompts para Claude:

• "Liste todos os objetos Messier disponíveis."
• "Sobre quais planetas posso obter informações?"
• "Mostre-me algumas estrelas brilhantes que posso consultar usando a categoria stars."
• "Liste todos os objetos NGC no catálogo."
• "Quais objetos de céu profundo (dso) estão disponíveis?"
• "Você pode listar todos os objetos conhecidos pelo sistema?"

3. getStarHoppingPath

Propósito: Calcula um caminho de "star hopping" (salto de estrela) de uma estrela inicial brilhante até um objeto celeste alvo. Cada salto está dentro do Campo de Visão (FOV) especificado. Esta ferramenta ajuda observadores a localizar manualmente objetos mais fracos "saltando" de uma estrela reconhecível para outra.

Parâmetros:

• targetObjectName (string): O nome ou identificador de catálogo do objeto celeste a ser encontrado. Exemplos: "M13", "Andromeda Galaxy", "Mars", "NGC 7000"
• fovDegrees (número, positivo): O Campo de Visão (FOV) do equipamento do usuário em graus (por exemplo, binóculos, ocular de telescópio). Exemplo: 5.0
• maxHopMagnitude (número, opcional, padrão: 8.0): A magnitude estelar máxima (mais fraca) para estrelas a serem incluídas no caminho de salto. Estrelas mais brilhantes têm valores de magnitude menores. Exemplo: 7.5
• initialSearchRadiusDegrees (número, positivo, opcional, padrão: 20.0): O raio angular (em graus) ao redor do objeto alvo para procurar uma estrela inicial brilhante adequada. Exemplo: 25.0
• startStarMagnitudeThreshold (número, opcional, padrão: 3.5): A magnitude máxima (mais fraca) para uma estrela ser considerada uma boa "estrela inicial" brilhante para a sequência de saltos. Exemplo: 4.0

Exemplos de Prompts para Claude:

• "Encontre um caminho de salto de estrela até M13 com um FOV de 5 graus."
• "Você pode me dar uma sequência de saltos de estrela até a Nebulosa do Anel (M57) usando um binóculo 8x50 (FOV em torno de 6 graus) e estrelas não mais fracas que magnitude 7?"
• "Preciso encontrar NGC 253. Meu telescópio tem um campo de visão de 1 grau. Encontre um caminho começando de uma estrela mais brilhante que magnitude 3, dentro de 20 graus do alvo."
• "Gere um guia de salto de estrela para a Galáxia do Sombrero, assumindo um FOV de 2 graus e magnitude máxima de salto de 8,5."

Estrutura do Projeto

CelestialMCP/
├── src/
│   ├── tools/                      # MCP Tools provided to the AI
│   │   ├── CelestialDetailsTool.ts   # Tool to get detailed info for an object
│   │   ├── ListCelestialObjectsTool.ts # Tool to list available objects
│   │   └── StarHoppingTool.ts        # Tool to calculate star hopping paths
│   ├── utils/                      # Utility functions
│   │   └── astronomy.ts            # Core astronomy calculations and catalog loading
│   ├── config.ts                   # Observer's location and atmospheric conditions configuration
│   └── index.ts                    # MCP Server entry point
├── scripts/
│   └── fetch-catalogs.js           # Script to download astronomical catalogs
├── data/                           # Directory for catalog data files (e.g., hygdata_v41.csv, ngc.csv)
│   ├── README.md                   # Information about data files
│   ├── sample_dso.csv            # Sample DSO data if full catalog isn't downloaded
│   └── sample_stars.csv          # Sample star data if full catalog isn't downloaded
├── package.json
└── tsconfig.json

Configuração Padrão

Por padrão, a localização do observador é definida como Vancouver, Canadá. Você pode alterar isso em src/config.ts: Esta configuração é usada para todos os cálculos, a menos que uma ferramenta especificamente permita substituí-la (as ferramentas atuais não permitem).

export const OBSERVER_CONFIG = {
  latitude: 49.2827,    // Observer latitude
  longitude: -123.1207, // Observer longitude
  altitude: 30,         // Observer altitude in meters
  temperature: 15,      // Default temperature in Celsius
  pressure: 1013.25     // Default pressure in hPa
};

Licença

MIT

Agradecimentos

• astronomy-engine para cálculos astronômicos principais
• mcp-framework para a implementação do servidor MCP
• Banco de dados HYG para dados de estrelas
• OpenNGC para dados de objetos de céu profundo