cnreport-mcp 0.1.0__tar.gz

cnreport_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: cnreport-mcp
+Version: 0.1.0
+Summary: Chinese annual report MCP — outline extraction, AI structured extraction, Elasticsearch store + search
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pypdf>=4.0
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: elasticsearch>=8.0
+Requires-Dist: akshare>=1.13
+Requires-Dist: pandas>=2.0

cnreport_mcp-0.1.0/README.md

@@ -0,0 +1,268 @@
+# cnreport-mcp
+
+MCP server for Chinese A-share annual reports. Sixteen tools across three layers:
+
+| Layer | Tool | What it does |
+|---|---|---|
+| Company API (edgartools-style) | `get_company` | Resolve ticker / name → company entry |
+| | `list_filings` | List CNINFO disclosures by form / category + year |
+| | `get_filing` | One announcement's metadata + PDF URL |
+| | `get_financials` | Income / balance / cashflow via akshare (structured numbers) |
+| | `get_financial_statements` | 三大报表 (`合并利润表` / `合并资产负债表` / `合并现金流量表`) as **text** from the annual-report PDF via TOC |
+| | `get_section` | `(ticker, year, section)` → section text |
+| | `list_report_types` | Browse the CNINFO disclosure category catalog |
+| | `get_special_report` | Retrieve a special-type report (招股说明书 / 收购报告书 / …) by category |
+| PDF / AI / ES | `list_outline` | Parse 目录 from a report URL or PDF path |
+| | `extract_section` | Body text by exact title / regex / ordinal |
+| | `ai_extract` | LLM-structured extraction over section text |
+| | `index_records` | Bulk index extracted records into ES |
+| | `search_reports` | BM25 + filter search with highlights |
+| | `delete_index` | Drop `cnreport-{year}` index |
+| Report cache | `list_cache` | List cached reports (stock / year / form / size / cached_at) |
+| | `clear_cache` | Evict cached reports (all / by company / by company+year) |
+| Indicators | `list_indicators` | Browse the indicator rule set (by module / query / company applicability) |
+| | `get_indicator` | One indicator's value for (indicator, company, period) — routes to akshare / PDF section / computed ratio |
+| | `extract_indicators` | All applicable indicators for one company/year in one pass (one fetch, batched LLM, cached bundle) |
+| | `extract_indicators_by_position` | Indicators named in a position CSV (`docs/indicators_position.csv`) for one company/year — external/realtime ones listed in `skipped` |
+
+## Typical chain
+
+```python
+# 1. Resolve company → 2. find latest annual → 3. pull MD&A → 4. LLM-extract revenue table
+
+co = get_company("600519")
+# {"stock_code": "600519", "name": "贵州茅台", "org_id": "gssh0600519", "exchange": "sse", ...}
+
+filings = list_filings("600519", form="年度报告", year=2023, limit=3)
+# [{"announcement_id": "1219730876", "pdf_url": "http://static.cninfo.com.cn/.../*.PDF", ...}]
+
+sec = get_section("600519", year=2023, section="管理层讨论与分析")
+# {"text": "<full MD&A body>", "pdf_url": "...", "outline_entry": {...}, ...}
+
+records = ai_extract(
+    text=sec["text"],
+    schema={"type": "object", "properties": {
+        "segment": {"type": "string"},
+        "revenue_2023": {"type": "string"},
+    }, "required": ["segment", "revenue_2023"]},
+)
+# {"records": [{"segment": "茅台酒", "revenue_2023": "139,989,000,000"}, ...]}
+```
+
+## Special report types
+
+CNINFO exposes dozens of disclosure categories beyond the four periodic reports
+(招股说明书, 增发, 业绩预告, 收购报告书, 股权激励, …). Browse the catalog, then list or
+retrieve by category:
+
+```python
+# 1. Browse what's available → 2. list filings of a category → 3. pull a section
+
+catalog = list_report_types()
+# {"groups": [{"name": "定期报告", "categories": [...]}, {"name": "融资", ...}, ...], "count": 26}
+
+list_report_types(group="融资")
+# {"group": "融资", "categories": [{name: "首发", code: "category_sf_szsh", ...}, ...], "count": 6}
+
+filings = list_filings("600519", category="首发", limit=3)   # 首发 covers 招股说明书
+# category accepts a catalog name OR a raw category_* code; mutually exclusive with form.
+
+sec = get_special_report("600519", category="首发", section="募集资金运用")
+# {"text": "<section body>", "pdf_url": "...", "outline_entry": {...}, ...}
+
+# Without `section`, the PDF is NOT downloaded — only filing metadata + pdf_url:
+meta = get_special_report("600519", category="业绩预告")
+```
+
+## Three major financial statements (三大报表)
+
+`get_financials` returns akshare's structured numeric tables. `get_financial_statements`
+pulls the three major statement sections **as text straight from the annual-report
+PDF** (via the table of contents), so you get the report's actual narrative + tables,
+not just the numbers:
+
+```python
+stmts = get_financial_statements("600519", year=2023)
+# {
+#   "stock_code": "600519", "company_name": "贵州茅台", "year": 2023,
+#   "form": "年度报告", "pdf_url": "...", "cached": False,
+#   "statements": {
+#     "income_statement": {"title": "2、 合并利润表", "outline_entry": {...}, "char_count": 4521, "text": "..."},
+#     "balance_sheet":    {"title": "1、 合并资产负债表", ...},
+#     "cashflow":         {"title": "3、 合并现金流量表", ...},
+#   },
+#   "missing": [],
+# }
+
+# Consolidated (合并) titles are preferred; the un-prefixed titles are the
+# fallback. Any statement not located in the TOC is listed in `missing`, with
+# the full `available` title list so you can fall back to get_section:
+stmts = get_financial_statements("600519", year=2023)
+# {"missing": ["cashflow"], "available": ["第一节 ...", ...], ...}
+```
+
+## Report cache
+
+Every report fetch (`list_outline`, `extract_section`, `get_section`,
+`get_special_report`, `get_financial_statements`) goes through an on-disk cache:
+the first fetch downloads the PDF + extracts text + outline and stores them
+under `mcp/cnreport-mcp/.cache/reports/`; subsequent fetches of the **same**
+report read from disk — no re-download, no re-`pypdf`-parse. Files are named
+`{stock_code}_{year}_{form}_{announcement_id}.{pdf,txt,outline.json}` (or
+`url_<hash>.*` for raw URL fetches without provenance), so the cache folder is
+human-browseable.
+
+```python
+list_cache()
+# {"cache_dir": ".../.cache/reports", "count": 2,
+#  "entries": [{"stock_code": "600519", "year": "2023", "form": "年度报告",
+#               "announcement_id": "1219730876", "cached_at": "...", "size": 123456}, ...]}
+
+clear_cache()                              # evict everything
+clear_cache(stock_code="600519")           # evict one company
+clear_cache(stock_code="600519", year=2023) # evict one company + year
+```
+
+Override the cache directory with `CNREPORT_CACHE_DIR` (see Configuration).
+CNINFO annual reports are immutable post-publication, so there is no TTL —
+`clear_cache` is the manual eviction path.
+
+The category catalog is the data-driven file `cninfo_categories.json` (sourced from
+CNINFO's own `history-notice.js` via akshare). **Adding a report type = editing that
+JSON** — no code change. Restart the server and the new type appears in
+`list_report_types` and is accepted by `list_filings(category=…)` / `get_special_report(…)`.
+
+Skip the company API and pass a PDF URL directly when you already have one:
+
+```python
+list_outline(source="https://example.com/600519_2023.pdf")
+extract_section(source="...", selector="管理层讨论与分析", company="贵州茅台", year=2023)
+```
+
+## Indicators
+
+`indicator_rules.json` is a data-driven rule set mapping each indicator to
+**where** its value comes from and **how** it is extracted. Each rule carries:
+applicability (`applies_to`: industry / sub-type / explicit company list), a
+section selector chain, an extractor (`"llm"` or `"python:<name>"`), and
+unit/period. The rule set has two sources, both edited without a code change:
+
+- **Banking rules** — hand-authored in `indicator_rules.json` (sourced from
+  `indicators.md`); carry rich, bank-specific selector chains + applicability.
+- **Position-CSV rules** — migrated from `docs/indicators_position.csv` (319
+  indicators across the three statements, notes, risk management, shareholders,
+  HR, profit distribution, …) by `scripts/migrate_indicators_csv.py`. Edit the
+  CSV, re-run the migration, done. Indicators marked `report_type: 实时`
+  (PE-TTM, PB, 市值, …) are classified `source_type: "external"` — they are not
+  in the report PDF and are listed in `skipped` during extraction.
+
+`docs/indicators-methodology.md` is the rendered source-and-process companion
+(regenerate with `python indicators_client.py --render-methodology >
+docs/indicators-methodology.md`; coverage summary with `--render-coverage`).
+
+Different banks disclose the same indicator under different TOC titles, and some
+indicators only appear for certain bank types — so the engine profiles each
+company (国有大行 / 股份制 / 城商行 / 农商行; non-banks profile without a
+sub_type and still receive universal `industry: "*"` rules), filters the rule
+set per company, and walks the selector chain (company-specific override →
+default → fallback, with normalized matching for descriptive section labels).
+Derived ratios are computed locally, never by the LLM.
+
+```python
+# 1. Preview which indicators apply to a company → 2. pull one → 3. pull all → 4. by CSV
+list_indicators(company="工商银行")           # rules applicable to 工商银行 + its profile
+get_indicator("资本充足率", "工商银行", 2023)  # one value, routed per the rule
+extract_indicators("工商银行", 2023)           # all applicable indicators, one PDF fetch
+extract_indicators("工商银行", 2023,
+                   indicators=["资本充足率","不良率","资产负债率"])  # subset
+extract_indicators("工商银行", 2023, extractor_mode="python")        # LLM-free where possible
+extract_indicators_by_position("工商银行", 2023)   # all indicators named in the position CSV
+extract_indicators_by_position("工商银行", 2023,
+                               csv_path="docs/indicators_position.csv",  # default
+                               indicators=["资产总计","负债合计"],         # subset (intersect CSV)
+                               extractor="python")                       # LLM-free where possible
+```
+
+Each periodic form is selectable via `form` (default `年度报告`):
+`半年度报告` / `第一季度报告` / `第三季度报告`. Indicators whose `report_type`
+doesn't include the form are placed in `skipped` (e.g. `分红金额` — annual only —
+is skipped for `第一季度报告`), and quarterly reports fall back to a body-text
+statement search when the outline lacks statement titles.
+
+```python
+extract_indicators_by_position("工商银行", 2023, form="第一季度报告")
+extract_indicators("贵州茅台", 2023, form="半年度报告")
+```
+
+Standalone CLIs run the same pipelines offline — point `--rules` (or `--csv`)
+at a different file per company batch to process different companies with
+different rule sets:
+
+```bash
+# hand-authored + CSV-merged rule set (full engine)
+python scripts/extract_indicators.py 601398 --year 2023 \
+    [--rules indicator_rules.json] [--extractor auto|llm|python] \
+    [--indicators 资本充足率,不良率] [--out-dir ./out]
+
+# position-CSV-driven: the indicators named in a CSV for one company/year/form
+python scripts/extract_indicators_by_position.py 601398 --year 2023 \
+    [--csv docs/indicators_position.csv] [--extractor auto|llm|python] \
+    [--form 年度报告|半年度报告|第一季度报告|第三季度报告] \
+    [--indicators 资产总计,负债合计] [--out-dir ./out]
+# non-default form is appended to the output stem (e.g. 601398_2023_第一季度报告.json)
+
+# sync docs/indicators_position.csv → indicator_rules.json (idempotent)
+python scripts/migrate_indicators_csv.py [--check]
+```
+
+Adding a new Python extractor: write `(section_text, rule, period) -> {value, unit, note}`
+in `indicators_extractors.py`, call `register("name", fn)`, then set
+`"extractor": "python:name"` on the rule. See `docs/indicators-methodology.md`.
+
+## Setup
+
+```bash
+uv sync                    # installs akshare, pypdf, fastmcp, ...
+uv run python server.py    # FastMCP over stdio
+```
+
+Self-check (no network):
+
+```bash
+uv run python selfcheck.py           # DB + outline + company API + special reports
+uv run python selfcheck_cache.py     # report cache + three-statements extraction
+```
+
+Tests (offline; bypasses the user's broken logfire pytest plugin):
+
+```bash
+uv run --with pytest python -m pytest test_cnreport.py -v -p no:logfire
+```
+
+## Configuration
+
+CNINFO and akshare are **keyless**. The other tools need env vars in root `.env`:
+
+| Var | Used by | Required? |
+|---|---|---|
+| `LLM_API_KEY`, `LLM_BASE_URL`, `LLM_MODEL` | `ai_extract` | Yes for AI |
+| `ES_URL` (+ optional `ES_API_KEY` or `ES_USERNAME`/`ES_PASSWORD`) | `index_records`, `search_reports`, `delete_index` | Yes for ES |
+| `DAAS_DATABASE_URL` | provenance writes for `extract_section` | Defaults to `mcp/daas.db` |
+| `CNREPORT_CACHE_DIR` | report cache for all fetch paths | Defaults to `mcp/cnreport-mcp/.cache/reports/` |
+
+## Architecture
+
+- `cninfo_client.py` — single network entry point for CNINFO (`lookup_company`, `query_announcements`, `get_announcement`, `pdf_url`). Three keyless endpoints. Also loads the data-driven category registry (`load_categories`, `resolve_category`).
+- `cninfo_categories.json` — CNINFO disclosure category catalog (name → code, grouped). Source of truth for `list_report_types` and the `category` parameter; extensible by JSON edit.
+- `financials_client.py` — lazy-imports akshare; server boots even without it (`get_financials` returns an `{error}` instead).
+- `cnreport_tools.py` — pure helpers + the company-API wrappers (`list_report_types`, `get_special_report`, `get_financial_statements`). Errors return `{"error": ...}`, never raise.
+- `report_cache.py` — on-disk cache wrapping `fetch_source_with_bytes`; every fetch path (`list_outline`, `extract_section`, `get_section`, `get_special_report`, `get_financial_statements`) checks the cache before downloading and stores the PDF + extracted text + outline on a miss. `list_cache` / `clear_cache` manage it. Also persists the extracted indicator bundle (`{stem}.indicators.json`) used by `extract_indicators`.
+- `indicators_client.py` — indicator rules engine: loads `indicator_rules.json`, profiles a company, filters applicable rules, routes each to akshare / report-section / computed / external, dispatches LLM or Python extractors, evaluates ratio formulas, and renders the methodology + coverage docs. Also exposes `extract_indicators_by_position` (CSV-driven).
+- `indicators_extractors.py` — pluggable Python extractor registry (`register` / `get`) + starter extractors (`regex_amount`, `percent_value`, `table_row`, `headcount`). Add an extractor = add a function + `register`.
+- `indicator_rules.json` — data-driven indicator rule set (name → applicability + section selector chain + extractor + unit + source_type). Hand-authored banking rules + CSV-migrated rules from `docs/indicators_position.csv`. Source of truth for `list_indicators` / `get_indicator` / `extract_indicators` / `extract_indicators_by_position`; extensible by JSON edit.
+- `indicators_csv_migration.py` — converts `docs/indicators_position.csv` into `indicator_rules.json` rules (idempotent; appends CSV-only rules, annotates overlaps, preserves hand-authored rules). Run via `scripts/migrate_indicators_csv.py`.
+- `docs/indicators_position.csv` — maintained human-editable catalog of indicators → section / report_type. The source for CSV-migrated rules.
+- `scripts/extract_indicators.py` — standalone CLI that runs the engine for a company or list, with a selectable rule file (`--rules`) and extractor mode (`--extractor`), writing JSON + CSV.
+- `scripts/extract_indicators_by_position.py` — standalone CLI that extracts the indicators named in a position CSV (`--csv`) for a company/year, writing JSON + CSV (with a `status` column and `skipped` rows for external indicators).
+- `scripts/migrate_indicators_csv.py` — CLI wrapper around `indicators_csv_migration.migrate` (`--check` for a dry-run diff).
+- `server.py` — `@app.tool` registrations; thin pass-through to `cnreport_tools` / `report_cache` / `indicators_client`.

cnreport_mcp-0.1.0/cninfo_client.py

@@ -0,0 +1,362 @@
+"""CNINFO (巨潮资讯) HTTP JSON-API client.
+
+Single network entry point for the cnreport-mcp company API. Wraps three
+public, keyless endpoints CNINFO uses to power its own SPA:
+
+  /new/information/topSearch/query   — company lookup by ticker or name
+  /new/hisAnnouncement/query         — list announcements (filings)
+  static.cninfo.com.cn/<adjunctUrl>  — PDF download URL
+
+Form categories (CNINFO codes) map from user-facing Chinese form names:
+  年度报告      → category_ndbg_szsh
+  半年度报告    → category_bndbg_szsh
+  第一季度报告  → category_yjdbg_szsh
+  第三季度报告  → category_sjdbg_szsh
+
+Form categories (CNINFO codes) live in the data-driven registry
+`cninfo_categories.json` (loaded via `load_categories`); the four periodic
+forms are exposed as the `_FORM_CATEGORIES` dict, derived from that registry so
+the existing `form` path resolves to identical codes. `resolve_category`
+accepts either a Chinese name from the catalog or a raw `category_*` code.
+
+Used by cnreport_tools.{get_company,list_filings,get_filing,get_section,
+list_report_types,get_special_report}. Mock-friendly: tests monkeypatch
+`_post_json` and `_client`, not httpx itself.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+import httpx
+
+_BASE = "http://www.cninfo.com.cn"
+_PDF_CDN = "http://static.cninfo.com.cn/"
+_TIMEOUT = 30.0
+_UA = (
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36"
+)
+
+# ── data-driven CNINFO category registry ───────────────────────────
+# Source of truth: cninfo_categories.json (sourced from CNINFO's own
+# history-notice.js via akshare). Adding a report type = editing the JSON.
+_REGISTRY_PATH = Path(__file__).resolve().parent / "cninfo_categories.json"
+_CATEGORIES_CACHE: Optional[dict] = None
+
+
+def load_categories() -> dict:
+    """Load and cache the CNINFO category registry (cninfo_categories.json).
+
+    Returns `{_source, _todo, groups: [{name, categories: [{name, code, description}]}]}`.
+    Raises `FileNotFoundError` if the registry file is missing, `json.JSONDecodeError`
+    if malformed — both naming the file, so a misconfigured package fails loudly at
+    boot rather than silently degrading to an empty catalog.
+    """
+    global _CATEGORIES_CACHE
+    if _CATEGORIES_CACHE is not None:
+        return _CATEGORIES_CACHE
+    if not _REGISTRY_PATH.exists():
+        raise FileNotFoundError(f"CNINFO category registry not found: {_REGISTRY_PATH}")
+    try:
+        data = json.loads(_REGISTRY_PATH.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise json.JSONDecodeError(
+            f"malformed CNINFO category registry {_REGISTRY_PATH}: {e.msg}",
+            e.doc,
+            e.pos,
+        ) from None
+    _CATEGORIES_CACHE = data
+    return data
+
+
+def resolve_category(category: Optional[str]) -> Optional[str]:
+    """Resolve a CNINFO category name or code to a canonical `category_*` code.
+
+    Accepts either a Chinese name from the catalog (年度报告, 招股说明书, …) or a
+    raw CNINFO code (category_ndbg_szsh). A raw `category_`-prefixed code is
+    passed through unchanged (escape hatch for codes not yet in the registry).
+    Returns `None` when the input is neither a known name nor a `category_` code.
+    """
+    if not category:
+        return None
+    if category.startswith("category_"):
+        return category
+    for group in load_categories().get("groups", []):
+        for cat in group.get("categories", []):
+            if cat.get("name") == category:
+                return cat.get("code")
+    return None
+
+
+def _build_form_categories() -> dict[str, str]:
+    """Derive the periodic-form name→code map from the registry.
+
+    Covers the four periodic forms so the existing `form` path resolves to
+    identical codes without a hardcoded dict. If the registry's 定期报告 group is
+    ever renamed/missing, falls back to the historical four codes so the server
+    still boots and existing `form` calls keep working.
+    """
+    fallback = {
+        "年度报告": "category_ndbg_szsh",
+        "半年度报告": "category_bndbg_szsh",
+        "第一季度报告": "category_yjdbg_szsh",
+        "第三季度报告": "category_sjdbg_szsh",
+    }
+    try:
+        for group in load_categories().get("groups", []):
+            if group.get("name") == "定期报告":
+                return {cat["name"]: cat["code"] for cat in group.get("categories", [])}
+    except (FileNotFoundError, json.JSONDecodeError):
+        pass
+    return fallback
+
+
+# Map user-facing Chinese form names → CNINFO category codes (registry-derived).
+_FORM_CATEGORIES = _build_form_categories()
+
+# Map CNINFO `category` strings (returned by topSearch) to exchange tag.
+_EXCHANGE_BY_PREFIX = {"sh": "sse", "sz": "szse", "bj": "bse"}
+
+
+def _client() -> httpx.Client:
+    """Build a per-call httpx client. Tests patch this to inject a mock."""
+    return httpx.Client(
+        base_url=_BASE,
+        timeout=_TIMEOUT,
+        headers={
+            "User-Agent": _UA,
+            "Accept": "application/json, text/plain, */*",
+            "Origin": _BASE,
+            "Referer": _BASE + "/",
+        },
+        follow_redirects=True,
+    )
+
+
+def _post_json(path: str, data: dict[str, Any]) -> Any:
+    """POST form-encoded data and return parsed JSON. Errors raise."""
+    with _client() as c:
+        resp = c.post(path, data=data)
+        resp.raise_for_status()
+        return resp.json()
+
+
+def _exchange_from_org_id(org_id: str) -> str:
+    """gssh0600519 → sse; gssz0000001 → szse; gsbj0830799 → bse."""
+    if not org_id or len(org_id) < 4:
+        return ""
+    tag = org_id[2:4]  # 'sh' / 'sz' / 'bj'
+    return _EXCHANGE_BY_PREFIX.get(tag, "")
+
+
+def _column_from_org_id(org_id: str) -> str:
+    """The `column` parameter hisAnnouncement expects: sse/szse/bj."""
+    ex = _exchange_from_org_id(org_id)
+    return "bj" if ex == "bse" else ex  # bse → 'bj' for the API
+
+
+def pdf_url(adjunct_url: str) -> str:
+    """Build the static-cdn PDF URL CNINFO uses for filing downloads.
+
+    `adjunct_url` is the path CNINFO returns in announcement rows
+    (e.g. `finalpage/2024-04-02/1219730876.PDF`).
+    """
+    if not adjunct_url:
+        return ""
+    if adjunct_url.startswith("http"):
+        return adjunct_url
+    return _PDF_CDN + adjunct_url.lstrip("/")
+
+
+def lookup_company(ticker_or_name: str) -> Optional[dict]:
+    """Resolve a ticker or name fragment to a CNINFO company entry.
+
+    Returns `{stock_code, name, name_en, org_id, exchange, category}` or
+    `None` when no match is found. The match is the first row CNINFO's
+    own search returns — same ranking the cninfo.com.cn UI shows.
+    """
+    if not ticker_or_name:
+        return None
+    payload = _post_json(
+        "/new/information/topSearch/query",
+        {"keyWord": ticker_or_name, "maxNum": "10"},
+    )
+    if not isinstance(payload, list) or not payload:
+        return None
+    # Prefer an exact stock_code match if the input is 6 digits.
+    if ticker_or_name.isdigit() and len(ticker_or_name) == 6:
+        for row in payload:
+            if str(row.get("code")) == ticker_or_name:
+                return _map_company_row(row)
+    return _map_company_row(payload[0])
+
+
+def _map_company_row(row: dict) -> dict:
+    org_id = row.get("orgId") or ""
+    return {
+        "stock_code": row.get("code") or "",
+        "name": row.get("zwjc") or row.get("pinyin") or "",
+        "name_en": row.get("yjc") or "",
+        "org_id": org_id,
+        "exchange": _exchange_from_org_id(org_id),
+        "category": row.get("category") or "",
+    }
+
+
+def query_announcements(
+    stock_code: str,
+    org_id: str,
+    *,
+    form: Optional[str] = None,
+    category: Optional[str] = None,
+    year: Optional[int] = None,
+    limit: int = 20,
+) -> list[dict]:
+    """Query CNINFO disclosures for a company, filtered by form/category and year.
+
+    `form` accepts either a Chinese title (`年度报告`) or a raw category
+    code (`category_ndbg_szsh`); anything else is sent as a free-text
+    title filter (post-hoc, since CNINFO has no title-search field). The
+    server-side `category` filter is only applied for the four periodic forms.
+    `category` accepts any CNINFO category code or Chinese name from the
+    catalog (`招股说明书`, `增发`, …) and is sent verbatim as the server-side
+    `category` filter. `form` and `category` are mutually exclusive.
+    `year` filters by announcement publication year window — note CN
+    annual reports for FY{year} are typically published in {year+1}.
+    """
+    if form and category:
+        raise ValueError("specify either form or category, not both")
+
+    page_size = max(1, min(int(limit) * 2 + 10, 50))  # over-fetch then post-filter
+
+    data: dict[str, Any] = {
+        "stock": f"{stock_code},{org_id}" if org_id else stock_code,
+        "tabName": "fulltext",
+        "pageSize": str(page_size),
+        "pageNum": "1",
+        "column": _column_from_org_id(org_id) or "sse",
+        "plate": "",
+        "searchkey": "",
+        "secid": "",
+        "sortName": "",
+        "sortType": "",
+        "isHLtitle": "true",
+    }
+
+    # Resolve the server-side `category` filter.
+    if category is not None:
+        category_code = resolve_category(category)
+        if not category_code:
+            raise ValueError(f"unknown CNINFO category: {category!r}")
+        data["category"] = category_code
+    else:
+        category_code = _FORM_CATEGORIES.get(form or "", form or "")
+        if category_code and category_code in _FORM_CATEGORIES.values():
+            data["category"] = category_code
+
+    if year is not None:
+        # CN annual reports for FY{year} publish in {year+1}; widen window
+        # so 半年报/季报 also catch their natural publish windows.
+        data["seDate"] = f"{year}-01-01~{year + 1}-12-31"
+
+    payload = _post_json("/new/hisAnnouncement/query", data)
+    rows = payload.get("announcements") or [] if isinstance(payload, dict) else []
+    if rows is None:
+        rows = []
+
+    results: list[dict] = []
+    for row in rows:
+        mapped = _map_announcement_row(row)
+        # Post-hoc form filter (form path only): belt-and-braces over CNINFO's
+        # server-side `category` filter. Match by mapped["form"] when it's a
+        # known Chinese name; fall back to title substring otherwise.
+        if form:
+            row_form = mapped.get("form") or ""
+            row_title = mapped.get("title") or ""
+            if form in _FORM_CATEGORIES:
+                if row_form != form:
+                    continue
+            else:
+                if form not in row_form and form not in row_title:
+                    continue
+        # Post-hoc year filter: periodic-report titles embed the fiscal year
+        # (e.g. "2023年年度报告", "2023半年度报告"). Most titles use "{year}年",
+        # but some banks omit the 年 between year and form ("2023半年度报告"),
+        # so match the bare year string. The `category` path is skipped —
+        # special-report titles rarely embed the year; rely on seDate there.
+        if (
+            year is not None
+            and category is None
+            and str(year) not in (mapped.get("title") or "")
+        ):
+            continue
+        results.append(mapped)
+        if len(results) >= limit:
+            break
+    return results
+
+
+def _form_from_title(title: str) -> str:
+    """Derive a human-readable Chinese form name from the announcement title.
+
+    CNINFO's `announcementType` field is an opaque, pipe-delimited code
+    string (e.g. `01010503||010113||010301`) — not directly usable. The
+    title, however, reliably contains the form name as a substring.
+    Checks longest forms first so "半年度报告" wins over "年度报告".
+    """
+    if not title:
+        return ""
+    # Order matters: longer forms first.
+    for form in ("半年度报告", "第一季度报告", "第三季度报告", "年度报告"):
+        if form in title:
+            return form
+    return ""
+
+
+def _map_announcement_row(row: dict) -> dict:
+    published_ms = row.get("announcementTime") or 0
+    try:
+        from datetime import datetime, timezone
+
+        published = (
+            datetime.fromtimestamp(int(published_ms) / 1000, tz=timezone.utc)
+            .strftime("%Y-%m-%d")
+            if published_ms
+            else ""
+        )
+    except Exception:
+        published = ""
+    title = row.get("announcementTitle") or ""
+    return {
+        "announcement_id": str(row.get("announcementId") or ""),
+        "title": title,
+        "form": _form_from_title(title),
+        "published": published,
+        "pdf_url": pdf_url(row.get("adjunctUrl") or ""),
+        "stock_code": row.get("secCode") or "",
+        "company_name": row.get("secName") or "",
+    }
+
+
+def get_announcement(
+    announcement_id: str,
+    *,
+    stock_code: Optional[str] = None,
+    org_id: Optional[str] = None,
+) -> Optional[dict]:
+    """Fetch a single announcement by id, narrowed by stock when supplied.
+
+    CNINFO does not expose a `/announcement/<id>` endpoint, so this falls
+    back to the listing endpoint over the company's full disclosure
+    history and picks the matching row. With stock_code+org_id supplied,
+    this is cheap; without, we must enumerate.
+    """
+    if stock_code and org_id:
+        rows = query_announcements(stock_code, org_id, limit=200)
+        for r in rows:
+            if r["announcement_id"] == announcement_id:
+                return r
+    # Fallback: nothing to narrow by → bail.
+    return None