{
  "mcpServers": {
    "mcp-hkexnews": {
      "command": "uvx",
      "args": ["agentladle-mcp-hkexnews"]
    }
  }
}

pip install agentladle-mcp-hkexnews

{
  "mcpServers": {
    "mcp-hkexnews": {
      "command": "agentladle-mcp-hkexnews"
    }
  }
}

git clone https://github.com/agentladle/mcp-hkexnews.git

{
  "mcpServers": {
    "mcp-hkexnews": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-hkexnews", "agentladle-mcp-hkexnews"]
    }
  }
}

HKEXnews API                      Local Files (~/.agentladle/mcp-hkexnews/data/)
──────────────                    ──────────────────────────────
activestock_sehk_e.json  ──→     companies.json               (stock_code→stockId mapping)
ListOfSecurities.xlsx      ──→         │
tierone/tiertwo JSON       ──→     tiers.json                   (headline category mapping)
                                     │
titleSearchServlet.do    ──→        pdf/{LOCAL_KEY}/            (Tool 2: primary PDF/HTML + manifest)
                                     │
PyMuPDF parsing          ──→        json/*.json                 (Tool 3: parse, page-split)
                                     │
Local TF search          ──→        search results              (Tool 4: keyword search)
Page range read          ──→        page content                (Tool 5: read pages)

paths:
  data_dir: "~/.agentladle/mcp-hkexnews/data"
  pdf_dir: "~/.agentladle/mcp-hkexnews/data/pdf"
  json_dir: "~/.agentladle/mcp-hkexnews/data/json"

download:
  delay_between_requests: 0.3
  min_file_size: 500
  list_row_range: 100
  list_max_pages: 5

company:
  cache_ttl_days: 7

tiers:
  cache_ttl_days: 7

~/.agentladle/mcp-hkexnews/
├── config.yaml                        # Configuration (auto-created)
└── data/
    ├── companies.json                 # stock_code→stockId mapping (auto-downloaded & cached)
    ├── tiers.json                     # HKEX headline category mapping (auto-downloaded & cached)
    ├── pdf/                           # Downloaded announcement bundles
    │   ├── 00700_13500_2026-03-15_a1b2c3d4/
    │   │   ├── primary.pdf
    │   │   └── manifest.json
    │   └── ...
    └── json/                          # Parsed page-split JSON
        ├── 00700_13500_2026-03-15_a1b2c3d4.json
        └── ...

User: "Search 00700 inside information for buyback"

1. keyword_search(local_key="00700_50100_2026-07-09_a1b2c3d4", keywords=["buyback", "repurchase"])
   → Returns page snippets matching the keywords immediately.

User: "What did Tencent announce in its latest inside information?"

1. list_hkexnews_announcements(stock_code="00700", category="Inside Information", limit=3)
   → Returns local_key / release_date / title.

2. keyword_search(local_key="...", keywords=["inside information"])
   → Error: File not found.

3. download_hkexnews_announcement(stock_code="00700", local_key="...")
   → Downloads PDF to ~/.agentladle/mcp-hkexnews/data/pdf/

4. parse_hkexnews_announcement(local_key="...")
   → Parses into JSON.

5. keyword_search(local_key="...", keywords=["inside information"])
   → Retries search and returns data.

src/mcp_hkexnews/
├── __init__.py
├── server.py                 # MCP Server entry point
├── config.py                 # Config loading (~/.agentladle/mcp-hkexnews/config.yaml, singleton cached)
├── models.py                 # Data models
├── categories.py             # Announcement category blacklist
├── response.py               # Unified JSON responses
├── instances.py              # Service singletons
├── tools/
│   ├── list_announcements.py # Tool 1: list_hkexnews_announcements
│   ├── download.py           # Tool 2: download_hkexnews_announcement
│   ├── parse.py              # Tool 3: parse_hkexnews_announcement
│   ├── search.py             # Tool 4: keyword_search
│   ├── page.py               # Tool 5: get_announcement_pages
│   └── lookup.py             # Tool 6: lookup_stock_code
└── services/
    ├── company.py            # HKEX activestock + ListOfSecurities + stock_code→stockId
    ├── tiers.py              # HKEX tierone/tiertwo category cache
    ├── downloader.py         # HKEXnews titleSearch + PDF download
    ├── parser.py             # PDF/HTML→JSON parsing (PyMuPDF)
    ├── searcher.py           # Local JSON search + TF scoring
    └── keys.py               # local_key helpers