Asterwise

Astrologia védica e ocidental para agentes de IA: mapas astrais, dasha, compatibilidade, panchanga, numerologia, tarô.

Documentação

Servidor MCP Asterwise

Cálculos de astrologia e adivinhação como ferramentas MCP. 103 ferramentas cobrindo astrologia védica e ocidental, numerologia, tarô, cristais, sonhos, mapas natais, Dasha, compatibilidade e Panchanga, com interpretações que seguem o método clássico de Jyotish. Cada posição é verificada contra uma execução independente do Swiss Ephemeris (asterwise.com/proof) e conferida com o NASA JPL Horizons, com mediana de 0,046 segundos de arco em 80 posições (asterwise.com/accuracy).

Início Rápido (2 minutos)

Veja primeiro: demonstração de 46 segundos do Claude Desktop lançando um mapa através deste servidor, e a verificação cruzada independente do Swiss Ephemeris.

Obtenha sua chave de API

Cadastre-se gratuitamente em asterwise.com/dashboard: 500 chamadas/mês no nível Sandbox. Sem cartão de crédito. Sem limite de tempo.

Conecte ao Claude Desktop

Adicione ao ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "asterwise": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.asterwise.com/mcp"
      ],
      "env": {
        "MCP_HEADER_AUTHORIZATION": "Bearer your-api-key-here"
      }
    }
  }
}

Conecte ao Cursor

Adicione ao .cursor/mcp.json no seu projeto:

{
  "mcpServers": {
    "asterwise": {
      "url": "https://mcp.asterwise.com/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

Teste a conexão

curl https://mcp.asterwise.com/health

Autenticação

Três métodos suportados:

Método 1 — Chave de API (início rápido)
Envie sua chave de API Asterwise (começa com aw_) como Authorization: Bearer <api-key> ou como um cabeçalho X-API-Key: <api-key>. Ambos são equivalentes; use o que seu cliente MCP puder configurar.

Método 2 — OAuth 2.1 (produção)
Troque sua chave de API por um token de curta duração:

curl -X POST https://mcp.asterwise.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your-api-key",
    "client_secret": "your-api-key"
  }'

Retorna: {"access_token": "...", "expires_in": 3600, ...}

Use o token: Authorization: Bearer <access_token>

Tokens de acesso são JWTs HS256 sem estado. A chave de API é transportada dentro do token criptografada com uma chave derivada de JWT_SECRET; apenas um hash SHA-256 da chave aparece na declaração sub. Mantenha JWT_SECRET privado.

Método 3 — Código de autorização OAuth 2.1 para clientes MCP (Claude, Cursor, VS Code, Smithery)
Clientes MCP autenticam um usuário através do fluxo padrão de código de autorização com PKCE (S256). A descoberta está em /.well-known/oauth-authorization-server. Duas formas de o cliente se identificar são suportadas:

Documentos de Metadados de ID do Cliente (especificação MCP atual, preferida): use uma URL HTTPS como client_id. A URL deve servir um documento JSON cujo client_id seja igual à URL, com client_name, redirect_uris e token_endpoint_auth_method: "none". Esses clientes são públicos: sem segredo, apenas PKCE, concessões authorization_code e refresh_token, tokens de atualização rotacionam a cada uso. URIs de redirecionamento devem ser https, ou http em localhost / 127.0.0.1 / [::1] (porta ignorada, conforme RFC 8252). Um documento de referência que você pode copiar: https://asterwise.com/public/oauth/example-client.json.
Registro Dinâmico de Cliente (POST /oauth/register, descontinuado na especificação MCP, mas ainda suportado): retorna um client_id e client_secret; o segredo é exigido em /oauth/token.

O servidor busca documentos de metadados com proteções SSRF (apenas endereços públicos, sem redirecionamentos, 64 KB, 10 s) e os armazena em cache pelo Cache-Control: max-age do documento (60 s a 24 h, padrão 1 h). A página de consentimento mostra o host que publicou o documento.

Configuração

Copie .env.example para .env e defina pelo menos:

Variável	Obrigatória	Descrição
`ASTERWISE_API_BASE_URL`	Sim	URL base da API Asterwise (ex.: `https://api.asterwise.com`).
`JWT_SECRET`	Para `/oauth/token`	Pelo menos 32 caracteres; usado para assinar tokens de acesso.
`MCP_SERVER_HOST` / `MCP_SERVER_PORT`	Não	Endereço de bind e porta para o servidor HTTP MCP.
`LOG_LEVEL`	Não	`INFO` padrão.
`MCP_OAUTH_SECRET`	Para OAuth	Compartilhada com asterwise-api; verifica tokens de acesso emitidos pelo seu `/v1/oauth/token`.
`INTERNAL_API_TOKEN`	Para registro de cliente OAuth	Compartilhada com asterwise-api; usada ao encaminhar registro dinâmico de cliente.
`FRONTEND_URL`	Para `/authorize`	Para onde o navegador é enviado para login e consentimento (ex.: `https://asterwise.com`).
`OPENAI_APPS_CHALLENGE_TOKEN`	Não	Servida em `/.well-known/openai-apps-challenge` para verificação de diretório.

Ferramentas (103 no total)

O servidor MCP expõe 103 ferramentas organizadas por módulo Python. A categorização reflete a organização do código; as ferramentas podem atender a múltiplas tradições (ex.: compatibilidade inclui tanto os métodos Dashakoot em sânscrito quanto Porutham em tâmil).

western — 16 ferramentas (mapa, trânsitos, retornos, progressões)
natal — 13 ferramentas (mapa, árvores dasha, sistemas de ascendente)
numerology — 11 ferramentas (perfil, compatibilidade, caminho de vida)
tarot — 9 ferramentas (tiragens, disposições, referências de naipes)
vedic_reference — 8 ferramentas (nakshatra, natureza dos planetas, ayanamsha, referência clássica)
numerology_gaps — 7 ferramentas (expressão, impulso da alma, personalidade, maturidade, equilíbrio, kármico, ciclos pessoais)
panchanga — 6 ferramentas (panchanga, choghadiya, rahu kaal, hora)
crystals — 5 ferramentas (lista, por planeta, recomendações, individual)
dasha — 5 ferramentas (vimshottari, ashtottari, yogini, char, trânsitos)
matchmaking — 5 ferramentas (dashakoot, porutham, thirumana, papasamyam, compatibilidade)
horoscope — 4 ferramentas (diário/semanal/mensal/anual)
yoga_dosha — 4 ferramentas (yogas, doshas, sade sati, pitra dosha)
angel_numbers — 3 ferramentas (hoje, pessoal, consulta)
varshaphal — 3 ferramentas (mapa anual, saham, harsha bala)
dreams — 2 ferramentas (símbolos, individual)
panchanga_ext — 2 ferramentas (calendário, festivais, tâmil)

Para a lista completa de ferramentas, veja docs.asterwise.com ou o endpoint de listagem de ferramentas do servidor MCP.

Executar localmente

python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
export ASTERWISE_API_BASE_URL=https://api.asterwise.com
export JWT_SECRET="$(python -c 'import secrets; print(secrets.token_hex(32))')"
uvicorn server:app --host 0.0.0.0 --port 8080

uvicorn server:app é o mesmo ponto de entrada que o Dockerfile e o railway.toml de produção usam, então o middleware de autenticação, as rotas OAuth e o /health estão todos presentes localmente. As dependências de runtime estão fixadas em requirements.txt; requirements-dev.txt adiciona as ferramentas de teste.

Testes

pytest

A cobertura é aplicada em 78% para módulos principais (auth, client, errors, logging_config, models, runtime, server); os módulos de ferramentas são excluídos do limite (veja .coveragerc).

Status

https://status.asterwise.com

Licença

MIT. Veja LICENSE. Relatórios de segurança: veja SECURITY.md.