GetBirthChart MCP

@getbirthchart/mcp

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

Requisitos

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

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

Início rápido

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

{
  "mcpServers": {
    "getbirthchart": {
      "command": "npx",
      "args": ["-y", "@getbirthchart/mcp"],
      "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 do opcional unknown_time.

Ferramenta	Propósito	Hora exata obrigatória?	Comportamento com hora desconhecida
calculate_birth_chart	Fatos completos do mapa natal	Não	Omite Ascendente e casas; preserva a incerteza.
get_planet_positions	Posições planetárias	Não	Preserva a incerteza do mapa.
get_big_three	Sol, Lua e Ascendente	Não	Não adivinha o Ascendente.
get_moon_sign	Signo lunar e certeza	Não	Retorna ambiguidade quando o backend não consegue estabelecer um único signo.
get_rising_sign	Ascendente	Sim	Retorna birth_time_required.
calculate_aspects	Aspectos natais	Não	Retorna apenas fatos de propriedade do backend.
calculate_synastry	Relações entre mapas para person_a e person_b	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 assume meio-dia ou meia-noite e nunca adivinha casas, Ascendente ou 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"
}

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 de 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.

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 de forma privada 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.

Links

• Hub do desenvolvedor
• Repositório GitHub
• Pacote npm

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 nem do fluxo de CI.