GetBirthChart MCP

Servidor MCP oficial para cálculos estruturados de mapa astral, posição planetária, Big Three, signo lunar, signo ascendente, aspecto e sinastria via GetBirthChart.

GitHub

Documentação

@getbirthchart/mcp

Servidor MCP oficial 0.2.0 para cálculos astrológicos do GetBirthChart. Ele fornece a clientes de IA compatíveis com MCP acesso a cálculos estruturados por meio da API pública do GetBirthChart; não contém nem reimplementa o motor de astrologia.

Requisitos

Node.js 20 ou mais recente
Uma chave de API de desenvolvedor do GetBirthChart

Crie uma chave em getbirthchart.com/developers. Mantenha-a privada e não faça commit de configuração do host MCP contendo a chave real.

Início rápido

O pacote executa via MCP stdio e pode ser iniciado com npx:

{
  "mcpServers": {
    "getbirthchart": {
      "command": "npx",
      "args": ["-y", "@getbirthchart/mcp@0.2.0"],
      "env": {
        "GETBIRTHCHART_API_KEY": "gbc_live_your_key_here"
      }
    }
  }
}

Esta é a configuração padrão baseada em comandos para hosts que suportam servidores MCP stdio. Use a documentação atual do seu cliente para a localização exata do arquivo de configuração ou da interface; este repositório foi testado em protocolo com o cliente oficial MCP TypeScript, não com clientes específicos de fornecedores.

Variáveis de ambiente

Variável	Obrigatória	Descrição
`GETBIRTHCHART_API_KEY`	Sim	Chave de API de desenvolvedor do lado do servidor.
`GETBIRTHCHART_API_BASE_URL`	Não	Substituição da URL base da API HTTPS para desenvolvimento/testes. HTTP é aceito apenas para localhost.

A chave é lida na inicialização, nunca aceita como argumento de ferramenta e nunca gravada em stdout, logs, recursos ou resultados de ferramentas.

Ferramentas disponíveis

Todas as ferramentas são somente leitura e retornam fatos de cálculo estruturados. As entradas usam campos estritos: date, opcionais time e place, obrigatórios latitude, longitude e timezone, além de opcionais unknown_time e configurações de cálculo documentadas abaixo.

Ferramenta	Entrada	Saída	Hora exata obrigatória?	Comportamento com hora desconhecida
`calculate_birth_chart`	`birthData`	Mapa natal mapeado	Não	Omite Ascendente e casas; preserva a incerteza.
`get_planet_positions`	`birthData`	Posições planetárias	Não	Preserva a incerteza do mapa.
`get_big_three`	`birthData`	Sol, Lua e Ascendente opcional	Não	Não adivinha o Ascendente.
`get_moon_sign`	`birthData`	Signo lunar e incerteza	Não	Retorna ambiguidade quando o backend não consegue estabelecer um único signo.
`get_rising_sign`	`birthData`	Signo ascendente	Sim	Retorna `birth_time_required`.
`calculate_aspects`	`birthData`	Aspectos natais	Não	Retorna apenas fatos de propriedade do backend.
`calculate_synastry`	`person_a`, `person_b`, campos de relacionamento	Aspectos e resumos de sinastria	Por pessoa	Preserva os limites de hora desconhecida de cada pessoa.

A API pública atual não geocodifica place; forneça latitude, longitude e um fuso horário IANA mesmo quando um rótulo de local for incluído. O servidor MCP nunca inventa uma hora de nascimento. O backend pode usar meia-noite local como âncora de cálculo rotulada para uma avaliação de hora desconhecida, mas nunca apresenta essa âncora como a hora de nascimento da pessoa e nunca adivinha casas, o Ascendente ou um signo lunar ambíguo.

Exemplo de entrada:

{
  "date": "1990-01-15",
  "time": "12:00",
  "place": "New York, NY",
  "latitude": 40.7128,
  "longitude": -74.006,
  "timezone": "America/New_York"
}

Hora desconhecida:

{
  "date": "1990-01-15",
  "unknown_time": true,
  "latitude": 40.7128,
  "longitude": -74.006,
  "timezone": "America/New_York"
}

Opções de cálculo

As ferramentas natais aceitam as opções principais expostas gbc-astro 1.13.0 house_system, node_type, aspect_preset, custom_aspect_rules, additional_points, fold, zodiac e ayanamsa. Omita-as para os padrões compatíveis com legado: Tropical, Placidus, Nodo Verdadeiro, Aspectos Padrão, Quíron ativado e Lilith desativado. Cálculos siderais exigem um ayanamsa nomeado; Lahiri é a escolha de produto recomendada. Aspectos personalizados exigem custom_aspect_rules e cada regra usa type, exact_angle e orb.

A implementação expõe os sistemas de casas relevantes ao produto do núcleo (placidus, whole_sign, equal) além dos sistemas registrados do motor, Nodo Médio, aspectos natais Padrão/Estendido/Personalizado, Lilith Média/Verdadeira, solicitações de Vértice e Parte da Fortuna, e ayanamsas siderais nomeados. O contrato MCP não adiciona lógica de cálculo ou interpretação. Composto e Davison são operações do núcleo/SDK, mas não são ferramentas MCP nesta versão.

A sinastria aceita um node_type em nível de relacionamento para que ambos os mapas usem uma única convenção de nodo, além de opcionais relationship_type, topic e target_instant. O servidor preserva metadados de resposta e campos aditivos do esquema 1.x. Uma resposta HTTP natal pode omitir calculationHash; isso é válido e nunca é obrigatório. O servidor preserva um hash de cálculo v2: retornado sem alterá-lo ou truncá-lo. A compatibilidade principal é o esquema natal 1.9.0 e o esquema de sinastria 1.5.0.

Recursos

getbirthchart://methodology — convenções de cálculo e limites de hora desconhecida.
getbirthchart://data-sources — efemérides, fuso horário e proveniência de entrada de local.
getbirthchart://engine-info — metadados do provedor e da API pública.

Referências web autoritativas: Metodologia e Fontes de Dados.

Erros

Falhas de ferramentas usam dados estruturados error com um code seguro legível por máquina, mensagem, retryable e retry_after opcional. Códigos comuns incluem validation_error, authentication_required, birth_time_required, location_not_found, ambiguous_location, rate_limit_exceeded, timeout e internal_error.

Solução de problemas

Chave de API ausente: defina GETBIRTHCHART_API_KEY no ambiente do servidor do host MCP; nunca é um argumento de ferramenta.
Erros de autenticação ou limite de taxa: use o erro estruturado code e retry_after quando presentes. Não coloque a chave em uma chamada de ferramenta ou log do cliente.
Validação de hora desconhecida: omita time quando unknown_time for true; o servidor não substituirá por meio-dia nem inventará um signo ascendente.
Validação de local: inclua latitude, longitude numéricos WGS84 e um timezone IANA; place é apenas um rótulo e não é geocodificado aqui.
Desenvolvimento local: use GETBIRTHCHART_API_BASE_URL apenas com HTTPS, ou HTTP em localhost. Nunca envie uma chave de produção para um host não confiável.

Privacidade e segurança

Os dados de nascimento são passados apenas para a API pública configurada para o cálculo solicitado. Este pacote não persiste, armazena em cache nem registra entradas de nascimento, e não possui análises ou telemetria. A substituição opcional da URL base altera o limite de confiança; não envie uma chave de produção para um host não confiável.

Relate problemas de segurança em particular pelo processo em SECURITY.md. Não inclua chaves de API em relatórios de bugs.

Desenvolvimento

npm install
npm run lint
npm run typecheck
npm test
npm run build

Os testes usam clientes simulados e não chamam a API de produção. Para executar o servidor compilado localmente, defina GETBIRTHCHART_API_KEY e execute node dist/cli.js; o tráfego normal do protocolo permanece no stdout, enquanto falhas de inicialização são gravadas no stderr.

Metadados do registro MCP

Os metadados do registro são preparados em server.json com o nome do servidor io.github.getbirthchart-com/getbirthchart-mcp. Publique o pacote npm primeiro, depois autentique-se com a ferramenta oficial mcp-publisher e publique os metadados. O envio ao registro não faz parte intencionalmente do build do pacote ou do fluxo de CI.