ah-disclosure-kit

# ah-disclosure-kit Related documents: [A0. Document Index](./docs/A0_DOC_INDEX.md) | [A1. Installation and Usage](./docs/A1_INSTALLATION_AND_USAGE.md) | [A2. Local Update](./docs/A2_UPDATE_LOCAL_INSTALL.md) | [A3. Workflow](./docs/A3_WORKFLOW.md) | [A4. MCP Tools](./docs/A4_MCP_TOOLS.md) | [B1. PDF Ingest](./docs/B1_PDF_INGEST.md) | [B2. Company Data](./docs/B2_COMPANY_DATA.md) | [B3. HKEX](./docs/B3_HKEX.md) | [B4. Prospectus](./docs/B4_PROSPECTUS.md) | [C1. Test Plan](./docs/C1_TEST_PLAN.md) | [D1. Development Plan](./docs/D1_DEVELOPMENT_PLAN_V1_0.md) | [Command Examples](./examples/A0_CLAUDE_CODE_COMMANDS.md) | [Changelog](./CHANGELOG.md) `ah-disclosure-kit` is a local Python + MCP toolkit for A-share and H-share disclosure documents. It is used for querying non-trading company information, downloading original announcement PDFs, parsing PDFs, building local search indexes, and providing traceable evidence packets for AI-assisted financial analysis. **A/H-share disclosure documents, HKEXnews/CNINFO PDF ingest, local search, and MCP toolkit for AI-assisted financial analysis.** This tool is not a trading system or a real-time market data system. It does not cover real-time market data, K-lines, trading interfaces, technical indicators, short-term sentiment, or timing signals. English keywords: `A-share`, `H-share`, `HKEXnews`, `CNINFO`, `prospectus`, `annual report`, `PDF ingest`, `local search`, `MCP server`, `EvidencePacket` ## 1. One-sentence introduction Turn scattered A-share, H-share, and prospectus disclosure documents into a local evidence workspace suitable for tools like `Claude Code`, `Codex`, and `Kimi Code`. ## 2. Problems it solves - Public websites provide downloadable files, but it's difficult to precipitate these files into searchable, reusable, and traceable local assets. - Common financial analysis issues, such as revenue recognition, stock incentives, IPO financing, and major investors, often require navigating multiple PDFs. - Directly providing large models with entire annual reports or prospectuses is costly in terms of tokens and does not facilitate stable citation of page numbers and evidence sources. ## 3. Suitable scenarios - Downloading and organizing A/H-share annual reports, announcements, circulars, prospectuses, and listing documents. - Local disclosure document precipitation for financial analysis, BP, investment research, and strategic analysis. - Providing `EvidencePacket` for AI analysis processes, allowing models to read only relevant pages rather than entire PDFs. ## 4. Why it's not just another downloader - It not only downloads PDFs but also organizes files into local data assets. - It not only extracts text but also generates `meta.json`, `pages.jsonl`, `quality_report.json`, and local search indexes. - It not only performs search but also routes questions to structured data, disclosure documents, and evidence page levels. - It not only serves human reading but also serves `MCP` / AI workflows. ## 5. v1.0 positioning ```text Local data workspace for A/H-share company disclosure documents and non-trading company information ``` Core capabilities: - A-share structured company data: obtained through AKShare. - H-share structured company data: obtained through AKShare. - A-share original announcements and annual reports PDF: obtained through CNINFO. - H-share original announcements, annual reports, circulars, and performance announcements: obtained through HKEXnews. - Prospectuses, listing documents, and listing prospectuses: obtained through CNINFO, HKEXnews, and Oriental Fortune/AKShare. - Local PDF parsing: PyMuPDF extracts page text, generates `meta.json`, `pages.jsonl`, `quality_report.json`. - Local search: SQLite FTS + substring bottom-up search. - Large model analysis: reads only relevant pages, tables, or structured data from EvidencePacket, not the entire document by default. ## 6. Why this kit is needed when files can be downloaded online Public websites can solve the issue of finding and downloading files but usually cannot solve the following problems: - File sources are scattered: A-share, H-share, prospectuses, and listing documents are often dispersed across different portals. - Downloaded files are not reusable: files viewed in a browser once are difficult to precipitate into local searchable assets. - High model cost: directly feeding entire annual reports or prospectuses to models is costly in terms of tokens and does not facilitate tracing. - Unstable evidence chain: many analyses can only provide summaries and cannot stably return to specific pages, paragraphs, or tables. - Difficult cross-document review: issues like revenue recognition, stock incentives, IPO financing, and institutional investors often require navigating different files. This kit's value is not to replace download websites but to string together the process of "download -> parse -> search -> evidence package -> reuse" into a local workspace suitable for AI-assisted analysis and financial research. ## 7. Suitable users - Financial analysts, BP, investment researchers, or strategic analysts who need to view A/H-share disclosure documents. - Users who need AI to answer questions based on evidence pages rather than entire PDFs. - Users who need to precipitate local disclosure document assets and reuse them. ## 8. Supported environments Current version support: | Environment | Support status | Description | | --- | --- | --- | | Python 3.11+ | Supported | `CLI`, `MCP server`, and local parsing capabilities rely on Python. | | Windows 10/11 PowerShell | Supported | Current documentation, installation scripts, and default commands are mainly written for Windows. | | macOS / Linux | Basically available | Python packages can be installed, but installation instructions and scripts are not fully adapted to the same level of completeness. | | Claude Code | Supported | Current README, example commands, and MCP registration process directly face Claude Code. | | Codex / Codex for VS Code | Supported | Current directory provides `.codex` Skill usage, and documentation is covered. | | Kimi Code CLI | Connectable | This project's MCP server uses `stdio` to start; supports `MCP` clients can manually connect, but the current repository does not provide a one-click configuration script. | | Other MCP clients | Connectable | As long as the client supports local `stdio MCP server`, it can usually be manually configured. | Among them: - `Claude Code` / `Codex`: belong to the main target environments directly covered by the current documentation. - `Kimi Code CLI`: belongs to the protocol layer that can be connected, but the current repository has not written special configuration instructions for Kimi. ## 9. Quick start ```powershell python -m pip install -e ".[pdf]" python -m ah_disclosure.cli --version python -m ah_disclosure.cli server-info ``` If you want to connect it to an MCP-supported client, use the same startup command: ```text python -m ah_disclosure.mcp_server ``` ## 10. Usage scenario examples - Download annual reports, announcements, and circulars of companies like Tencent, Alibaba, and Meituan, and establish a local index. - Organize important accounting policies such as revenue recognition, cost recognition, bad debt, and deferred revenue. - Analyze stock incentive plans, share-based payment expenses, and their impact on profits. - Extract IPO financing history, major investors, preferred shares, and special rights arrangements from prospectuses. - Let AI answer questions based on evidence pages rather than entire PDFs. ## 11. Supported clients Current understanding: - `Claude Code`: out-of-the-box, documentation and commands are covered. - `Codex / Codex for VS Code`: supported, suitable for use with `.codex` Skill and local MCP. - `Kimi Code`: protocol compatible, can be manually connected through MCP. - Other `stdio MCP` supported clients: usually can be manually connected. ## 12. Roadmap - Add special access instructions for `Kimi Code`. - Supplement one-click installation scripts for `macOS / Linux`. - Add more prospectus, financing history, stock incentive-related example question templates. - Continue to improve optional capabilities such as PDF table extraction, OCR, and vector retrieval. ## 13. FAQ ### 13.1 Will this kit replace public disclosure websites? No, it relies on public disclosure websites as data sources but focuses on making downloads, parsing, search, and evidence reuse into a local workflow. ### 13.2 Can I just download PDFs without parsing? Yes, as long as you explicitly say "only download PDFs", the tool will not continue to ingest. ### 13.3 Do I have to use Claude Code? No, as long as your client supports local `stdio MCP server`, it can usually be connected; only the current documentation covers `Claude Code / Codex` most comprehensively. ## 14. Default behavior When only downloading PDFs, the tool saves only the PDFs and returns the local path and source URL. Only when the user requests "read, analyze, search, summarize, extract evidence", it will continue to execute PDF ingest: ```text PDF -> PyMuPDF extract page text -> meta.json / pages.jsonl / quality_report.json -> SQLite FTS ``` Does not generate by default: - `full_text.txt` - `document.md` - Vector index These belong to on-demand enhanced products. ## 15. Installation ### 15.1 Installation prerequisites Before installation, it is recommended to confirm: - Python 3.11 or higher has been installed. - The `python` command is available in PowerShell / Terminal. - This tool uses the existing global Python or user Python environment by default and does not create a `.venv` in the kit directory. - `python -m pip install ...` will install Python package dependencies such as AKShare, pandas, MCP, and PyMuPDF. - If the machine does not have Python, this kit will not automatically install the Python interpreter. - Optional OCR functionality requires additional system-level Tesseract OCR installation; installing Python packages does not equal installing Tesseract. ### 15.2 One-click installation / check Windows PowerShell: ```powershell Set-ExecutionPolicy -Scope Process Bypass .\scripts\INSTALL_AND_CHECK.ps1 ``` The script will: - Check if the existing Python is 3.11+. - Install/update Python package dependencies, defaulting to install `.[pdf]`. - Create a default data directory. - Copy the `ah-disclosure` Skill to `.codex\skills`. - If the current environment has a `claude` command, register the MCP server. - Verify the `ah-disclosure-kit` version and CLI basic commands. The script will not: - Install the Python interpreter. - Install Tesseract OCR. - Create a project `.venv`. If you only want to check the installation without registering MCP: ```powershell .\scripts\INSTALL_AND_CHECK.ps1 -SkipMcpRegistration ``` If you want to check if Tesseract exists: ```powershell .\scripts\INSTALL_AND_CHECK.ps1 -CheckTesseract ``` ### 15.3 Manual installation ```powershell python -m pip install --upgrade pip python -m pip install -e ".[pdf]" ``` Complete optional dependencies: ```powershell python -m pip install -e ".[pdf,table,ocr,vector,dev]" ``` ## 16. MCP registration ```powershell claude mcp add --transport stdio --scope user ah-disclosure "python -m ah_disclosure.mcp_server" ``` After registration, execute in Claude Code: ```text /mcp ``` Confirm that `ah-disclosure` is connected. If you are using another MCP-supported client, you can also reuse the same startup command: ```text python -m ah_disclosure.mcp_server ``` As long as the client supports local `stdio` MCP server, it can be manually connected. ## 17. Skill installation Move this directory: ```text skills/ah-disclosure ``` to: ```text C:\Users\<username>\.codex\skills\ah-disclosure ``` Example path: ```text C:\Users\<username>\.codex\skills\ah-disclosure ``` ## 18. Data directory Default data directory: ```text ./data/ah_disclosure ``` Can also be specified through environment variables: ```powershell $env:AH_DISCLOSURE_DATA_DIR="C:\path\to\data\ah_disclosure" ``` ## 19. Documentation entry Recommended reading order: 1. `docs/A0_DOC_INDEX.md` 2. `docs/A1_INSTALLATION_AND_USAGE.md` 3. `docs/A3_WORKFLOW.md` 4. `docs/A4_MCP_TOOLS.md` 5. `docs/B1_PDF_INGEST.md` 6. `docs/C1_TEST_PLAN.md` ## 20. Acknowledgements and sources This project is built on the open-source Python ecosystem, with core dependencies including: - `AKShare`: A/H-share structured company data and some public market data interfaces. - `pandas`: structured data processing. - `requests` / `httpx` / `beautifulsoup4` / `lxml`: public webpage and file requests, parsing. - `mcp`: MCP server capability encapsulation. - `PyMuPDF` / `pypdf` / `pdfplumber` / `camelot-py` / `pytesseract`: PDF text, table, and OCR processing. - `ChromaDB` / `sentence-transformers`: optional vector index capability. This project also uses public disclosure channels as data sources, including: - `CNINFO`: A-share announcements, annual reports, listing prospectuses, etc. - `HKEXnews`: H-share announcements, annual reports, circulars, listing documents, etc. - `Oriental Fortune / AKShare accessible public paths`: some prospectus and issuance document retrieval entries. The overall workflow design, directory organization, MCP tool encapsulation, evidence packet constraints, local search linkages, and A/H disclosure scenario integration belong to engineering implementations based on open-source ecosystems and public data sources. The current repository does not claim to directly copy or secondarily encapsulate a specific GitHub open-source project; if specific projects are referenced in the future, they will be added to the README or a separate document. ## 21. Open-source release suggestions If publicly released to GitHub, it is suggested that the repository title and description include searchable terms, such as: - Repository title: `ah-disclosure-kit` - GitHub Description: `A/H-share disclosure documents, HKEXnews/CNINFO PDF ingest, local search, and MCP toolkit for AI-assisted financial analysis.` - Topics suggestion: `mcp`, `python`, `finance`, `hkex`, `cninfo`, `pdf`, `prospectus`, `annual-report`, `a-share`, `h-share` ## 22. Version information Current version: v1.0.0 Development and finalization time: 2026-07-03 15:44