Haruspex

Obter pontuação de ações (ex.: /score NVDA)

GitHub

Experimente este MCPPatrocinado

Documentação

haruspex-skills

Um servidor MCP para análise de ações, além de Skills da Anthropic que se baseiam nele — com tecnologia Haruspex.

Este repositório contém duas coisas:

Um servidor MCP — @haruspex-guru/mcp-server, um servidor Model Context Protocol que expõe a API de análise de ações da Haruspex como ferramentas (get_stock_score, get_stock_score_history, get_batch_scores, search_stocks, get_stock_news). Seu código-fonte e Dockerfile estão em mcp-server/, e é publicado no npm como @haruspex-guru/mcp-server.
Um conjunto de Anthropic Agent Skills (em skills/) que constroem fluxos de trabalho estruturados de negociação — leituras de ticker único, varreduras de watchlist, verificações de tese, uma variante em japonês — sobre esse servidor MCP.

Servidor MCP

O servidor MCP está em mcp-server/ e é publicado como @haruspex-guru/mcp-server. Ele fala o Model Context Protocol via stdio e expõe cinco ferramentas:

Ferramenta	Finalidade
`get_stock_score`	Pontuação Haruspex mais recente (0-100) para um ticker, com perspectiva, sinal, detalhamento dimensional e URL compartilhável.
`get_stock_score_history`	Pontuações históricas diárias para um ticker.
`get_batch_scores`	Pontuações para até 50 tickers em uma única chamada (watchlists).
`search_stocks`	Encontre tickers por símbolo ou nome da empresa.
`get_stock_news`	Artigos de notícias recentes para um ticker.

Execute diretamente:

npx -y @haruspex-guru/mcp-server

Compile a partir do código-fonte (Docker):

docker build -t haruspex-mcp mcp-server/   # or build from repo root: docker build -t haruspex-mcp .

O servidor lê HARUSPEX_API_KEY em tempo de execução para dados ao vivo; obtenha uma chave em https://haruspex.guru/settings. As Skills da Anthropic abaixo dependem deste servidor MCP para seus dados — sem ele instalado, as skills detectam isso, exibem instruções de instalação e param; elas nunca fabricarão análises.

Skills neste repositório

Skill	Finalidade
`haruspex-stock-analyst`	Análise fundamental + sinais de ticker único. O padrão para qualquer pergunta "e sobre [TICKER]?".
`haruspex-watchlist-review`	Revisão em lote de uma watchlist com vários tickers. Tabelas classificadas, maiores movimentações, sinalizadores dimensionais.
`haruspex-thesis-tracker`	Mapeia uma tese de investimento declarada para as dimensões relevantes da Haruspex e informa se os dados ainda estão alinhados.
`haruspex-stock-analyst-ja`	Versão em japonês do analista principal, para traders que trabalham em japonês em ações listadas nos EUA (NYSE/NASDAQ).

Cada skill é uma pasta contendo um SKILL.md com frontmatter YAML, um reference.md para documentação mais aprofundada e um examples.md com diálogos de exemplo completos usando dados reais capturados.

Matriz de suporte por superfície

Superfície	Skills	MCP	Status
Claude Code (terminal CLI)	✅ filesystem `~/.claude/skills/`	✅ `claude mcp add-json`	Totalmente testado
Claude.ai web (navegador)	✅ upload de ZIP via Configurações → Personalizar → Skills	✅ via Conectores	Suportado
Claude API (SDK)	✅ agrupar na solicitação	✅ passar configuração do servidor	Consulte a documentação da Anthropic
Claude Desktop app	❌ skills instaláveis pelo usuário não suportadas a partir da v0.1.0	✅ `claude_desktop_config.json`	MCP funciona; skills não (use Claude Code em vez disso)
Cursor / Windsurf	❌ Anthropic Agent Skills não suportadas nativamente	✅ MCP funciona	Somente MCP; sem runtime de skills

Início rápido — Claude Code (recomendado)

Este é o caminho que testamos.

Instale as skills. A partir deste repositório:

git clone https://github.com/Haruspex-guru/haruspex-skills.git
mkdir -p ~/.claude/skills
cp -r haruspex-skills/skills/* ~/.claude/skills/

Registre o servidor MCP no escopo do usuário (funciona em qualquer projeto):

claude mcp add-json --scope user haruspex '{
  "command": "npx",
  "args": ["-y", "@haruspex-guru/mcp-server"],
  "env": { "HARUSPEX_API_KEY": "hrspx_demo_public_REPLACE_ME" }
}'

Substitua hrspx_demo_public_REPLACE_ME pela sua chave real de https://haruspex.guru.

Verifique:

claude mcp list           # haruspex should show ✓ Connected

Depois, em uma sessão do Claude Code:

/mcp                      # browse Haruspex tools
/skills                   # see all 4 haruspex skills (✔ on)

Experimente uma consulta:
```
What do you think about NVDA?
```
A skill haruspex-stock-analyst é acionada automaticamente, chama as ferramentas MCP e retorna análise estruturada com uma URL de compartilhamento verificável.

Início rápido — Claude.ai (web)

Ative a execução de código no Claude.ai se ainda não tiver feito (Configurações → Capacidades).
Empacote cada skill como um ZIP. A partir deste repositório:
```
cd skills
for d in */; do (cd "$d" && zip -r "../${d%/}.zip" .); done
```
Gera 4 ZIPs no diretório skills/.
Envie cada ZIP: claude.ai → Configurações → Personalizar → Skills → "+" → Enviar uma skill. Repita para todas as quatro.
Configure @haruspex-guru/mcp-server via Conectores (a interface de Conectores é separada da configuração local do Desktop). Use sua chave de API Haruspex.
Experimente uma consulta em qualquer chat: "O que você acha da NVDA?"

Atenção: skills enviadas ao claude.ai estão sujeitas às diretrizes de revisão da Anthropic para conteúdo de terceiros. "Instale apenas skills de fontes confiáveis" se aplica — as skills da Haruspex não executam código arbitrário, mas os usuários ainda devem revisar os arquivos SKILL.md antes de instalar.

Início rápido — Claude API / SDK

A API Claude suporta Agent Skills programaticamente. Agrupe os diretórios de skills com sua solicitação e passe a configuração do servidor MCP junto. Consulte a documentação oficial da API de Skills da Anthropic para a sintaxe atual.

Claude Desktop — limitação atual

O aplicativo nativo Claude Desktop não carrega skills de sistema de arquivos instaláveis pelo usuário a partir da v0.1.0 deste repositório (abril de 2026). O runtime de skills do Desktop atualmente só exibe um conjunto integrado (docx, pdf, pptx, etc.).

O lado do servidor MCP funciona no Claude Desktop — veja shared/MCP_SETUP.md para configuração do claude_desktop_config.json. Mas sem um runtime de skills, você ficaria chamando ferramentas MCP de forma livre, em vez de obter o fluxo de trabalho estruturado que essas skills impõem.

Para usuários do Desktop hoje: instale o Claude Code e use-o a partir do seu terminal, ou use o claude.ai web com o fluxo de upload de ZIP acima. A Anthropic pode adicionar suporte a skills de sistema de arquivos ao Desktop posteriormente; este repositório será atualizado quando isso acontecer.

Pré-requisitos

Uma chave de API Haruspex — cadastre-se em https://haruspex.guru. Nunca envie sua chave de API para um repositório.
Um dos: Claude Code, Claude.ai web ou a API Claude.
Node.js 18+ se você estiver executando @haruspex-guru/mcp-server via npx.

Detalhes completos de configuração do MCP por superfície estão em shared/MCP_SETUP.md.

Conformidade e aviso legal

Estas skills produzem análise, não aconselhamento. Cada skill é codificada com regras de conformidade que proíbem recomendações diretas de compra/venda/manutenção, previsões de preço, dimensionamento de posição e especificações de stop-loss/take-profit. Cada saída de skill inclui o rodapé de aviso legal canônico.

A linguagem completa do aviso legal e a justificativa por trás de cada regra de conformidade estão em shared/DISCLAIMER.md. Trate esse arquivo e as seções "Regras de conformidade (NUNCA VIOLAR)" de cada SKILL.md como essenciais.

Nada neste repositório é aconselhamento de investimento. As pontuações Haruspex são sinais quantitativos derivados de dados públicos, fornecidos apenas para fins informativos.

Dimensões de tópico

A pontuação Haruspex é um composto de dimensões de tópico (por exemplo, competitors, earnings, supplychain, us_china_official). Descrições em linguagem simples de todas as 16 estão em shared/DIMENSIONS.md. A metodologia de pontuação em si é proprietária e intencionalmente não documentada aqui.

Contribuindo

Veja CONTRIBUTING.md. A versão resumida:

Abra uma issue antes de abrir um PR para mudanças não triviais.
Execute bash scripts/validate-skills.sh antes de enviar.
Os exemplos devem usar dados reais capturados da API ao vivo. Fabricação será rejeitada.
A linguagem de conformidade é inegociável.

Consultas de avaliação

eval/queries/ contém cerca de 20 consultas de teste de acionamento por skill (metade deve acionar, metade não deve, com casos de ambiguidade entre skills). Use-as ao revisar o campo description de qualquer skill. Veja eval/README.md para o procedimento de avaliação manual.

Licença

MIT. O servidor MCP e as skills (instruções e exemplos neste repositório) são licenciados sob MIT. O algoritmo de pontuação Haruspex e os dados subjacentes são proprietários; o acesso é regido pelos Termos de Serviço da API Haruspex. Veja NOTICE para a declaração completa de escopo.

De onde isso veio

Construído para a comunidade Haruspex, inspirado em padrões que vimos funcionar em fluxos de trabalho reais de traders. Submissões ao catálogo oficial anthropics/skills seguirão assim que as skills tiverem uma forma estável aqui.