HKEx Filings

npx add-mcp 'https://hkex-listco-updates.ascent-partners.com/api/mcp'

HKEx Filing Scraper

Uma ferramenta Python de código aberto que coleta mais de 25 anos de arquivos regulatórios da Bolsa de Valores de Hong Kong (HKEx) e os ingere em qualquer combinação de nove bancos de dados — com extração de texto completo e tabelas, cobertura em nível de bloco, vinculação opcional de grafos e um servidor MCP somente leitura para que agentes de IA possam consultar o corpus ou o site ao vivo.

Ele fala diretamente com a API JSON não documentada da HKEx, o que é mais rápido e mais resiliente do que controlar um navegador.

Fornecedores e integrações

Bancos de dados — nove destinos de primeira classe, em ordem de popularidade documentada (veja a matriz de suporte):

• PostgreSQL — relacional de código aberto de nível de produção
• MySQL / MariaDB — servidores relacionais GPL, um driver
• SQLite — banco de dados de arquivo sem servidor, sem instalação necessária
• MongoDB — banco de dados de documentos
• Neo4j — banco de dados de grafos de propriedades
• ClickHouse — mecanismo de análise colunar
• DuckDB — mecanismo analítico em processo
• SurrealDB — banco de dados multimodelo de grafos + documentos

Clientes de IA — qualquer agente compatível com MCP; configuração pronta para Claude, ChatGPT, Cursor, VS Code/Copilot, Gemini CLI, opencode, Manus e Perplexity.

Disponível em — PyPI · Glama · MCP Registry · gateway hospedado.

Duas maneiras de usar

	Gateway MCP hospedado	Pipeline local
O quê	Um endpoint público para o qual você aponta um agente de IA	O CLI hkex-scraper
Configuração	Nenhuma — cole uma URL	pip install + uma variável de ambiente
Dados	Ao vivo da HKEx, nada armazenado	Armazenados no(s) seu(s) banco(s) de dados
Documentação	Gateway MCP ao vivo · Suporte a agentes de IA	Começando

Use o gateway MCP hospedado

POST, HTTP Streamable, sem chave de API:

https://hkex-listco-updates.ascent-partners.com/api/mcp

Quatro ferramentas somente leitura: get_server_info, search_filings (uma janela de no máximo 31 dias, com filtros opcionais de código de ação, título, tipo de documento, categoria e nome da ação), list_filing_facets (navegue pelo que uma janela contém) e get_filing (baixa um documento e extrai seu texto e tabelas).

Aponte um cliente para ele — por exemplo, opencode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "hkex-live": {
      "type": "remote",
      "url": "https://hkex-listco-updates.ascent-partners.com/api/mcp"
    }
  }
}

Depois pergunte:

Use hkex-live to list the filings published between 2026-09-01 and 2026-09-18,
then summarise the interim report.

A configuração pronta para Claude, ChatGPT, Cursor, VS Code/Copilot, Gemini CLI, opencode, Manus e Perplexity está em Suporte a agentes de IA — e para um corpus armazenado, o servidor MCP stdio expõe um catálogo de ferramentas mais amplo e é publicado no Glama. O gateway está listado no MCP Registry oficial como io.github.simonplmak-cloud/hkex-filings.

Destaque no Glama — o servidor MCP stdio somente leitura também é publicado no Glama, onde o Glama escaneia o servidor construído e avalia a qualidade das definições de ferramentas (atualmente 4,7/5).

Início rápido (local)

pip install hkex-filing-scraper        # core; SQLite needs no server
pip install "hkex-filing-scraper[all]" # Excel + dotenv + every driver + the MCP server
cp .env.example .env                   # then set DATABASE_TARGET (below)
hkex-scraper --metadata-only --limit 100

Extras opcionais: excel, postgres, mysql, duckdb, mongodb, clickhouse, neo4j, mcp, pdf, all, dev.

DATABASE_TARGET é uma lista ordenada e separada por vírgulas de IDs de destino; a ordem decide qual destino atende às leituras. Para começar sem servidor:

DATABASE_TARGET=sqlite
SQLITE_PATH=hkex.db

hkex-scraper executa o pipeline completo (metadados + documentos + grafo); hkex-scraper --full-history cobre tudo desde abril de 1999. O esquema é criado automaticamente. Opções completas de instalação e configurações por destino estão em Começando.

Suporte a bancos de dados

Cada destino é um destino de primeira classe; as linhas estão em ordem de popularidade documentada. A matriz completa — licenças, diferenças de capacidade, notas por mecanismo — está em Destinos de banco de dados.

Destino	Modelo	Licença	Extra	Upsert idempotente
postgres	relacional	PostgreSQL License	postgres	ON CONFLICT DO UPDATE
mysql / mariadb	relacional	GPLv2	mysql	ON DUPLICATE KEY UPDATE
sqlite	relacional	Domínio público	—	ON CONFLICT DO UPDATE
mongodb	documento	SSPL¹	mongodb	update_one(upsert=True)
neo4j	grafo	GPLv3 (Community)	neo4j	MERGE
clickhouse	colunar	Apache-2.0	clickhouse	ReplacingMergeTree + leitura-merge
duckdb	relacional	MIT	duckdb	ON CONFLICT DO UPDATE
surrealdb	grafo + documento	BSL 1.1¹	—	UPSERT / RELATE

¹ Código-fonte disponível, não aprovado pela OSI — exceções rotuladas conforme ADR 0003.

IDs de destino válidos, em ordem documentada: postgres, mysql, sqlite, mongodb, mariadb, neo4j, clickhouse, duckdb, surrealdb. Defina uma variável e a mesma execução alimenta todos os destinos:

# Order sets read precedence.
DATABASE_TARGET=postgres,sqlite
POSTGRES_DSN=postgresql://user:password@localhost:5432/hkex
SQLITE_PATH=hkex.db

Como funciona

flowchart LR
    A[HKEx JSON API] --> B[Phase 1: metadata]
    B --> C[Canonical record]
    C --> D{DATABASE_TARGET}
    D --> E[(PostgreSQL)]
    D --> F[(MySQL / MariaDB)]
    D --> G[(SQLite)]
    D --> H[(MongoDB)]
    D --> I[(Neo4j)]
    D --> J[(ClickHouse)]
    D --> K[(DuckDB)]
    D --> L[(SurrealDB)]
    B --> M[Graph linking]
    M --> D
    B --> N[Phase 2: download and extract]
    N --> C

• Fase 1 coleta metadados de arquivos por meio de uma sessão JSF, dividindo o intervalo em blocos mensais e deduplicando em um MD5 de 16 caracteres filingId.
• Fase 2 baixa o documento PDF/HTML/Excel de cada arquivo, extrai texto e tabelas para Markdown e grava o payload.
• Vinculação de grafo (opcional) grava arestas has_filing e references_filing quando COMPANY_TABLE está definido.
• Isolamento de falhas — uma falha em um destino é registrada e contada, mas nunca bloqueia outro; a execução sai com código não zero se qualquer destino configurado falhar.

Mais detalhes: Arquitetura · ADR 0002.

Recursos

• Coleta rápida via API — API JSON direta da HKEx; sem navegador ou Selenium.
• Histórico completo — todos os arquivos de abril de 1999 até hoje, com verificações de cobertura em nível de bloco.
• Processamento de documentos — texto de PDF/HTML/Excel e tabelas estruturadas, extraídos para Markdown.
• Multi-destino — qualquer combinação ordenada de nove bancos de dados, cada um com upserts idempotentes nativos.
• Pronto para IA — um gateway MCP ao vivo hospedado mais um servidor MCP stdio local.
• Retomável e observável — agrupamento, downloads paralelos, detecção de trabalhos travados, contadores por destino e --coverage-report / --parity-report / --verify.
• Dependências opcionais — o núcleo é requests + beautifulsoup4; drivers e extração de documentos são extras com fallbacks graciosos.

Documentação

• Começando · Configuração · CLI
• Destinos de banco de dados (matriz) — PostgreSQL, MySQL/MariaDB, SQLite, MongoDB, Neo4j, ClickHouse, DuckDB, SurrealDB
• Gateway MCP ao vivo · Suporte a agentes de IA · Servidor MCP
• Arquitetura · Solução de problemas · Testes
• Roteiro · Registro de mitigação de riscos · Atualização
• Novidades · Lançamentos · Legal e Termos de Uso · Changelog
• Site de documentação: https://hkex-listco-updates.ascent-partners.com/ · Experimente localmente (examples/)

Desenvolvimento

pip install -e ".[dev,all]"
ruff check           # lint (py310, line-length 100)
ruff format --check  # formatting
pytest               # unit tests (no DB or network required)

Os testes são testes de unidade puros; testes de contrato SQLite e DuckDB são executados em processo, e testes de integração que precisam de um servidor são ignorados, a menos que esse destino esteja configurado. Veja Testes.

Contribuindo

Veja CONTRIBUTING.md; relate problemas de segurança conforme SECURITY.md. Ideias e perguntas são bem-vindas em Discussões.

Se isso economizar seu tempo, uma estrela ajuda outras pessoas a encontrá-lo.

Licença

MIT — veja LICENSE. Isso cobre apenas o código deste projeto; dependências opcionais têm suas próprias licenças, notavelmente o extra pdf (PyMuPDF / pymupdf4llm), que é AGPL-3.0 e deliberadamente excluído de .[all]. Veja docs/legal.md.

Dados e Termos de Uso: esta é uma ferramenta de pesquisa para a API JSON não documentada da HKEx, e não é afiliada ou endossada pela HKEx. A redistribuição comercial de dados da HKEx pode exigir um feed licenciado da HKEx; veja docs/legal.md.