Hub-Equity MCP

Fundamentos de XBRL da SEC e europeu (ESEF) em um único vocabulário de conceitos, cada valor com seu arquivamento e a tag do emissor, alterações e reafirmações silenciosas rastreadas. Servidor stdio somente leitura, Python.

GitHubExperimente este MCPPatrocinado

Documentação

hub-equity-mcp

Dados financeiros XBRL padronizados para agentes de LLM. Um servidor Model Context Protocol (MCP) que expõe fatos financeiros normalizados de arquivamentos da SEC (EDGAR) dos EUA e ESEF europeus para Claude Desktop, Cursor e qualquer cliente compatível com MCP.

O Hub-Equity serve arquivamentos padronizados ESEF europeus juntamente com dados da SEC dos EUA por meio de um vocabulário consistente de conceitos de hub, para que um agente possa solicitar REVENUE ou TOTAL_ASSETS e obter um valor comparável e vinculado à fonte independentemente de o emissor arquivar na SEC ou sob o ESEF.

Maturidade. A API REST pública por trás deste conector opera em produção e alimenta o chat do próprio Hub-Equity. O pacote segue o Versionamento Semântico; ele mantém o classificador Beta enquanto sua base de instalação é jovem.

Por quê

Um vocabulário para dois regimes. Conceitos us-gaap da SEC e ifrs-full do ESEF são mapeados para um único conjunto padronizado de códigos de hub, de modo que a comparação entre emissores e entre taxonomias funcione imediatamente.
Todo número é vinculado à fonte. Os fatos carregam seu arquivamento, período e proveniência, para que um agente possa citar em vez de adivinhar.
Ciente de reafirmações. Emendas explícitas e reafirmações silenciosas (um valor que um arquivamento posterior reimprimiu de forma diferente, sem emenda registrada), cada alteração com o arquivamento que a realizou.
Somente leitura e mundo fechado. Cada ferramenta anuncia readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false conforme a especificação MCP, para que os clientes possam raciocinar sobre segurança e cache sem introspecção.
Sem credenciais de banco de dados. O pacote publicado fala apenas com a API REST pública (https://api.hub-equity.com) via HTTPS. Ele nunca envia nem exige uma chave de banco de dados.

Instalação

pipx run hub-equity-mcp

pipx run (ou uvx hub-equity-mcp) baixa e inicia o servidor em um ambiente isolado; pip install hub-equity-mcp também funciona. Requer Python 3.12 ou mais recente.

Autenticação e acesso

O servidor fala apenas com a API REST pública, que precisa de uma chave hubq_ (variável de ambiente HUBEQUITY_API_KEY).

Chave gratuita. Crie uma conta e uma chave em um minuto em https://hub-equity.com/settings/api-keys. Oferece o conjunto básico de ferramentas (busca de entidades, fatos normalizados, séries temporais, segmentos, triagem, nota de qualidade de dados, conversão de câmbio e muito mais).
Plano pago. Desbloqueia as ferramentas premium (diferenças de reafirmação, árvores de cálculo, comparação entre períodos, comparação entre emissores, verificações de validação, conceitos de extensão) e aumenta o limite de taxa. Veja a tabela abaixo.

O pacote publicado nunca acessa o banco de dados diretamente, apenas a API REST.

Configure seu cliente

Claude Desktop

Adicione a claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "hub-equity": {
      "command": "pipx",
      "args": ["run", "hub-equity-mcp"],
      "env": {
        "HUBEQUITY_API_KEY": "INSERT_YOUR_API_KEY"
      }
    }
  }
}

Sem HUBEQUITY_API_KEY, cada chamada de ferramenta responde HUBEQUITY_API_KEY is not set com o link para uma chave gratuita.

Cursor

Adicione a .cursor/mcp.json (raiz do projeto) ou às configurações globais do MCP do Cursor:

{
  "mcpServers": {
    "hub-equity": {
      "command": "pipx",
      "args": ["run", "hub-equity-mcp"],
      "env": {
        "HUBEQUITY_API_KEY": "INSERT_YOUR_API_KEY"
      }
    }
  }
}

Variáveis de ambiente

HUBEQUITY_API_KEY (obrigatório): uma chave hubq_. Uma chave gratuita abre as ferramentas básicas; um plano pago abre as ferramentas premium e o limite de taxa mais alto.
HUBEQUITY_API_URL (opcional): o padrão é https://api.hub-equity.com. https:// é aplicado sempre que uma chave está definida (o servidor se recusa a enviar a chave Bearer em texto simples para um host não loopback).

Capacidades

Tipo	O quê
Ferramentas	Ferramentas somente leitura: descoberta, fatos, séries temporais, segmentos, verificações forenses (tabela abaixo)
Recursos	Catálogo do hub, esquema de demonstrações, catálogo de níveis, guias de uso, instantâneo de cobertura
Prompts	Modelos analíticos (lista abaixo)
API de conclusão	Autocompletar `{hub_code}`

Ferramentas

O catálogo de níveis legível por máquina é servido como um recurso (hub-equity://catalog/tool-tiers). As ferramentas gratuitas cobrem descoberta e identidade; as ferramentas Pro, disponíveis em todos os planos pagos (Builder, Team, Enterprise), adicionam profundidade forense (árvores de cálculo, diferenças de reafirmação em emendas e reafirmações silenciosas, comparação entre períodos, comparação entre emissores, resultados de validação, conceitos de extensão). O nível de uma ferramenta espelha o endpoint REST que ela chama: o endpoint de toda ferramenta Pro exige o escopo facts.premium no lado do servidor, e os limites gratuitos (get_fact_decomposition profundidade 1 sem componentes de roll-up ou fatias dimensionais, screen_companies 20 resultados sem o filtro de qualidade, get_segments eixos sem membros, roll_up_metric o valor sem sua regra) são aplicados pela API, não apenas por este pacote.

Ferramenta	Nível	O que faz
`find_entity(query)`	Gratuita	Busca por nome, ticker ou CIK. Retorna o `entity_id` que outras ferramentas precisam.
`get_fact(entity_id, hub_concept_code, fiscal_year, fiscal_period_type?)`	Gratuita	Um valor normalizado mais sua fonte de arquivamento.
`get_fact_decomposition(entity_id, fiscal_year, hub_concept_code? or qname?, depth?)`	Gratuita (profundidade 1, somente linkbase) / Pro (profundidade 2-3)	Roll-up do hub, filhos do linkbase de cálculo XBRL e detalhamento dimensional. Gratuita: a camada de linkbase, sem os componentes de roll-up e as fatias dimensionais.
`search_concept(query)`	Gratuita	Resolve um código de hub a partir de um rótulo ou código parcial.
`list_hubs(category?, include_non_primary?, limit?)`	Gratuita	Enumera o catálogo padronizado do hub por categoria.
`get_entity_profile(entity_id)`	Gratuita	Setor, auditor, funcionários, fim do ano fiscal, arquivamentos recentes.
`get_metric_history(entity_id, hub_concept_code, n_years?)`	Gratuita	Série temporal de N anos com crescimento YoY e CAGR.
`get_segments(entity_id, hub_concept_code, fiscal_year)`	Gratuita (limitada)	Detalhamento dimensional de eixo/membro (segmento, geografia). Gratuita: os eixos sem seus membros; Pro: todos os membros.
`get_amendments(entity_id, fiscal_year?)`	Gratuita	Resumo de reafirmação 10-K/A: cada emenda, suas alterações por conceito (50 por emenda).
`get_silent_restatements(entity_id, fiscal_year?)`	Gratuita	Reafirmações silenciosas: valores que um arquivamento posterior reimprimiu de forma diferente em suas colunas comparativas, sem emenda registrada, agrupados pelo arquivamento que os revelou (50 alterações por arquivamento).
`compare_entities(entity_ids, hub_concept_codes, fiscal_year)`	Pro (até 10x10)	Matriz de comparação entre emissores em um período, alinhada ao ano calendário. Aceita UUIDs, tickers ou `TICKER.MIC`.
`roll_up_metric(entity_id, hub_concept_code, fiscal_year)`	Gratuita (limitada)	Calcula um valor a partir de filhos assinados quando não está diretamente marcado. Gratuita: o valor; Pro: a regra e as contribuições assinadas por trás dele.
`convert_currency(amount, from_currency, to_currency, date?, rate_type?)`	Gratuita	Conversão de câmbio com taxa de referência do BCE (fechamento, média YTD, média do ano anterior).
`screen_companies(country?, sector?, min_revenue?, ..., sort_by?, limit?)`	Gratuita (limite 20, sem filtro de qualidade) / Pro (maior)	Filtra o universo de emissores por metadados, receita, auditoria e qualidade de dados.
`get_amendment_diff(entity_id, fiscal_year?, hub_concept_code?, min_diff_pct?, kind_filter?)`	Pro	Diferenças 10-K/A por conceito: materialidade, filtros de tipo e conceito, rótulo, delta absoluto, ambos os arquivamentos como fontes.
`get_silent_restatement_diff(entity_id, fiscal_year?, hub_concept_code?, min_diff_pct?, kind_filter?)`	Pro	A mesma diferença nas reafirmações silenciosas.
`get_calculation_tree(filing_id, link_role?)`	Pro	Linkbase de cálculo do arquivamento: cada total e seus componentes, sinal declarado ao lado do sinal que os valores arquivados suportam.
`compare_filings(entity_id, fiscal_year_a, fiscal_year_b, hub_concept_codes?)`	Pro	Comparação entre períodos da mesma entidade com sinalizações de novo / removido / inversão de sinal / reafirmação.
`get_extension_concepts(entity_id, status_filter?, limit?)`	Pro	Qnames específicos do emissor declarados fora das taxonomias padrão.
`get_data_quality_grade(entity_id)`	Gratuita	Nota de A+ a D (ou nenhuma), os dois portões e contagens por trás dela, atualidade, divisão direto-vs-derivado.
`get_validation_results(filing_id?, entity_id?, fiscal_year?, status_filter?)`	Pro	Verificações contábeis XBRL e do linkbase de cálculo.

Recursos

URI	Tipo	Propósito
`hub-equity://catalog/hubs`	json	Catálogo completo padronizado do hub com rótulos EN/FR e categoria.
`hub-equity://catalog/categories`	json	Contagens do hub por categoria.
`hub-equity://catalog/tool-tiers`	markdown	Catálogo de ferramentas Gratuitas vs Pro e condições de acesso.
`hub-equity://schema/financial-statements`	markdown	Estrutura de demonstrações e regras de leitura.
`hub-equity://catalog/hub/{hub_code}`	template	Entrada de catálogo encaminhada para um hub.
`hub-equity://entity/{entity_id}/profile`	template	Instantâneo completo da entidade.
`hub-equity://prompts/best-practices`	markdown	Orientação de prompt de sistema para integrações de cliente. Carregue antes de chamar qualquer ferramenta.
`hub-equity://prompts/tool-usage-examples`	markdown	Exemplos few-shot por ferramenta (bons e anti-padrões).
`hub-equity://prompts/data-coverage`	json	Instantâneo ao vivo do conjunto de dados (contagens de emissores e arquivamentos, fontes, taxonomias, intervalo de anos fiscais). Cache de 24h.

Prompts

Oito modelos analíticos: peer_comparison, quality_of_earnings, restatement_audit, sector_overview, valuation_screen, goodwill_impairment_risk, working_capital_diagnostic, cash_flow_consistency.

Para desenvolvedores de clientes

Antes de chamar qualquer ferramenta, busque hub-equity://prompts/best-practices e injete o markdown no seu prompt de sistema. Isso faz seu cliente seguir as mesmas regras de roteamento de ferramentas, citação de fontes e fidelidade numérica do chat do próprio Hub-Equity.

# Pseudo-code for a typical MCP client integration
session = mcp.connect("hub-equity-mcp")
best_practices = session.read_resource("hub-equity://prompts/best-practices")
system_prompt = "You are an assistant ...\n\n" + best_practices
# now call session.call_tool("find_entity", {"query": "AAPL"}) etc.

Limites de taxa

Modo	Limite	Notas
Chave gratuita	120 solicitações / minuto	Ferramentas básicas.
Chave Builder	300 solicitações / minuto	Ferramentas premium desbloqueadas.
Chave Team	600 solicitações / minuto	Ferramentas premium desbloqueadas.
Chave Enterprise	1 000 solicitações / minuto	Negociável.

O bucket é por chave de API.

Em um 429 por minuto, o cliente tenta novamente com backoff exponencial (até 3 vezes) antes de levantar RateLimitExceeded. Uma cota diária ou mensal esgotada é levantada imediatamente, com a mensagem da API.

Solução de problemas

Sintoma	Causa	Correção
`429 Too Many Requests` / `RateLimitExceeded`	Limite de taxa atingido (120/min com chave gratuita, 300 a 1 000/min com chave paga)	Mude para um plano pago ou reduza a dispersão de chamadas de ferramentas. O cliente já faz backoff até 3 vezes.
`HUBEQUITY_API_KEY is not set` em toda chamada de ferramenta	Sem chave no bloco `env` do cliente	Defina `HUBEQUITY_API_KEY`; uma chave gratuita leva um minuto em https://hub-equity.com/settings/api-keys.
`HubEquityRestError: HTTP 401`	Uma chave `hubq_` inválida, expirada ou revogada (`INVALID_API_KEY`)	Crie uma nova chave em https://hub-equity.com/settings/api-keys.
`HubEquityRestError: HTTP 403`	O workspace da chave está no plano gratuito e a chamada precisa de uma ferramenta Pro, ou um limite gratuito (`depth > 1`, `limit > 20`, `min_quality_grade`)	Faça upgrade do plano ou permaneça dentro dos limites gratuitos.
`RateLimitExceeded` cujo corpo carrega `DAILY_QUOTA_EXCEEDED` / `MONTHLY_QUOTA_EXCEEDED`	A cota de volume do workspace está esgotada (Gratuito 200 por dia / 5 000 por mês, Builder 50 000, Team 500 000 por mês); levantada imediatamente, sem nova tentativa	Aguarde `resets_on` ou faça upgrade do plano.
Erros de conexão ou tempo limite	Problema de rede ao acessar `api.hub-equity.com`, ou um `HUBEQUITY_API_URL` incorreto	Verifique a conectividade; confirme que `HUBEQUITY_API_URL` (se definido) aponta para um host `https://` acessível.
`ValueError: HUBEQUITY_API_URL must use https://`	Uma chave está definida, mas a URL é `http://` simples em um host não loopback	Use `https://` ou desdefina `HUBEQUITY_API_URL` para voltar à API padrão.
O servidor não aparece no Claude Desktop ou Cursor	Erro de JSON na configuração, ou `pipx` não está no PATH do cliente	Valide o JSON; use o caminho absoluto de `pipx` (ou `uvx`) se o cliente não conseguir resolvê-lo.

Execute localmente

python -m hub_equity_mcp.server

Ou conduza-o interativamente com o inspetor MCP:

npx @modelcontextprotocol/inspector python -m hub_equity_mcp.server

O inspetor lista todas as ferramentas, recursos e prompts e permite chamar cada um deles.

Desenvolvimento

pip install -e '.[dev]'
pytest tests/

Os testes são herméticos: os testes de ferramentas simulam a API REST com respx, então nenhum backend ao vivo é necessário.

Licença

Apache-2.0. Veja LICENSE e NOTICE. Este conector é um cliente aberto para a API REST pública do Hub-Equity; o acesso a dados premium permanece controlado por chave de API, plano e limites de taxa no lado do serviço.