datasinking 0.1.1__tar.gz → 0.2.0__tar.gz

{datasinking-0.1.1 → datasinking-0.2.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: datasinking
-Version: 0.1.1
-Summary: Python client for DataSinking — full-text China A-share financial reports as Markdown.
+Version: 0.2.0
+Summary: Python client for DataSinking — full-text Asian financial reports (China, Korea, Japan) as Markdown.
 Author: DataSinking
 License: MIT
 Project-URL: Homepage, https://datasink.ing
 Project-URL: Documentation, https://datasink.ing/docs
 Project-URL: Repository, https://github.com/heubme2020/datasinking
-Keywords: a-share,china,financial reports,markdown,api,stock
+Keywords: a-share,china,korea,japan,financial reports,markdown,api,mcp,model-context-protocol,rag,llm
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -15,21 +15,23 @@ Classifier: Topic :: Office/Business :: Financial
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Requires-Dist: requests>=2.28; extra == "mcp"
 Dynamic: license-file
 
 # DataSinking
 
 [![PyPI version](https://img.shields.io/pypi/v/datasinking.svg)](https://pypi.org/project/datasinking/)
 
-**Full-text A-share financial reports, as clean Markdown.**
+**Full-text financial reports across Asia, as clean Markdown.**
 
-[DataSinking](https://datasink.ing) is a **China stock market data API** that serves
-**full-text A-share financial reports** — annual, semi-annual and quarterly — as clean
-**Markdown**. Download China A-share financial statements (balance sheet, income statement,
-cash flow) by FMP-style symbol (`600519.SS`) or filter by exchange / report period, through a
-simple REST API. Raw PDFs are sourced from [cninfo.com.cn](http://www.cninfo.com.cn) (the
-officially designated disclosure platform) and parsed into structured Markdown with YAML
-frontmatter, preserved headings, paragraphs and tables — ready for LLM reading and analysis.
+[DataSinking](https://datasink.ing) serves **full-text financial reports** — annual, semi-annual
+and quarterly — from **China, Korea and Japan** as clean **Markdown**, ready for LLM reading
+and RAG. Query by FMP-style symbol (`600519.SS`, `005930.KS`, `7203.T`) or filter by exchange,
+report period, or **section** — pull just the MD&A / risk section instead of the whole report.
+Reports are sourced from official disclosure platforms and parsed into structured Markdown with
+YAML frontmatter, preserved headings, paragraphs and tables.
 
 ---
 
@@ -41,8 +43,9 @@ Examples, research and tutorials showing how to work with financial report data,
 datasinking/
 ├── examples/     # Example scripts: pull data from the API and analyze it
 ├── research/     # Research notes / blog posts (reproducing paper-style presentation)
-├── datasinking/  # Python client — pip install datasinking
-├── llm-examples.md  # Ask an LLM — no code needed (3 end-to-end examples)
+├── datasinking/  # Python client + MCP server — pip install "datasinking[mcp]"
+├── mcp-server.md # How to configure the MCP server (for AI agents: Claude / Cursor / Codex / DeepSeek)
+├── llm-examples.md  # Ask an LLM — no code needed (8 end-to-end examples)
 ├── api-examples.md  # 7 examples × 3 interfaces (curl / Python / LLM)
 └── README.md
 ```
@@ -76,7 +79,7 @@ All five functions (curl / Python / LLM): [`api-examples.md`](api-examples.md).
 
 Don't want to write code? Point any LLM at [datasink.ing](https://datasink.ing),
 give it your API key, and ask in plain language. See
-[`llm-examples.md`](llm-examples.md) for three end-to-end examples — explore
+[`llm-examples.md`](llm-examples.md) for eight end-to-end examples — explore
 coverage, list a company's reports, and extract a figure with correct units.
 
 ## Examples (`examples/`)
@@ -89,7 +92,7 @@ coverage, list a company's reports, and extract a figure with correct units.
 
 Every example pulls from the live API and runs as-is.
 
-> `03_download_exchange.py` fetches every report on an exchange (e.g. all of Shenzhen — 130k+ documents). Free keys work too, but fall back to slow per-document fetching (1 req/s + shared daily quota); a **paid (yearly)** key is strongly recommended for full-exchange downloads.
+> `03_download_exchange.py` fetches every report on an exchange (e.g. all of Shenzhen — 150k+ documents). Free keys work too, but fall back to slow per-document fetching (1 req/s + shared daily quota); a **paid (yearly)** key is strongly recommended for full-exchange downloads.
 
 ## Research (`research/`)
 
@@ -105,16 +108,17 @@ Start from [`research/TEMPLATE.md`](research/TEMPLATE.md).
 
 | | |
 |---|---|
-| Coverage | SSE / SZSE / BSE, 5,000+ A-share companies |
+| Coverage | China (SSE / SZSE / BSE) · Korea (KOSPI / KOSDAQ / KONEX) · Japan (TSE) |
 | Document types | annual / semiannual / q1 / q3 / amendment |
+| Update frequency | Daily — Korea/Japan via official DART/EDINET APIs (new filings within ~24h of publication) |
 | Format | Full-text Markdown (with YAML frontmatter) |
-| API | REST — `GET /documents`, batch download, `with_content=1` for full text |
-| Symbols | FMP style: `600519.SS` / `000001.SZ` / `830799.BJ` |
+| API | REST — `GET /documents`, batch download, `with_content=1` for full text, `?section=` + `/sections` for chapter-level access |
+| Symbols | FMP style: `600519.SS` / `005930.KS` / `7203.T` |
 | Auth | `?apikey=` query parameter (FMP style) |
 
 ## Data source
 
-All reports originate from [cninfo.com.cn](http://www.cninfo.com.cn), the officially designated information disclosure platform of China's listed companies.
+Reports are sourced from official regulatory disclosure platforms in each market and converted in-house to clean Markdown.
 
 ## License
 

{datasinking-0.1.1 → datasinking-0.2.0}/README.md

@@ -2,15 +2,14 @@
 
 [![PyPI version](https://img.shields.io/pypi/v/datasinking.svg)](https://pypi.org/project/datasinking/)
 
-**Full-text A-share financial reports, as clean Markdown.**
+**Full-text financial reports across Asia, as clean Markdown.**
 
-[DataSinking](https://datasink.ing) is a **China stock market data API** that serves
-**full-text A-share financial reports** — annual, semi-annual and quarterly — as clean
-**Markdown**. Download China A-share financial statements (balance sheet, income statement,
-cash flow) by FMP-style symbol (`600519.SS`) or filter by exchange / report period, through a
-simple REST API. Raw PDFs are sourced from [cninfo.com.cn](http://www.cninfo.com.cn) (the
-officially designated disclosure platform) and parsed into structured Markdown with YAML
-frontmatter, preserved headings, paragraphs and tables — ready for LLM reading and analysis.
+[DataSinking](https://datasink.ing) serves **full-text financial reports** — annual, semi-annual
+and quarterly — from **China, Korea and Japan** as clean **Markdown**, ready for LLM reading
+and RAG. Query by FMP-style symbol (`600519.SS`, `005930.KS`, `7203.T`) or filter by exchange,
+report period, or **section** — pull just the MD&A / risk section instead of the whole report.
+Reports are sourced from official disclosure platforms and parsed into structured Markdown with
+YAML frontmatter, preserved headings, paragraphs and tables.
 
 ---
 
@@ -22,8 +21,9 @@ Examples, research and tutorials showing how to work with financial report data,
 datasinking/
 ├── examples/     # Example scripts: pull data from the API and analyze it
 ├── research/     # Research notes / blog posts (reproducing paper-style presentation)
-├── datasinking/  # Python client — pip install datasinking
-├── llm-examples.md  # Ask an LLM — no code needed (3 end-to-end examples)
+├── datasinking/  # Python client + MCP server — pip install "datasinking[mcp]"
+├── mcp-server.md # How to configure the MCP server (for AI agents: Claude / Cursor / Codex / DeepSeek)
+├── llm-examples.md  # Ask an LLM — no code needed (8 end-to-end examples)
 ├── api-examples.md  # 7 examples × 3 interfaces (curl / Python / LLM)
 └── README.md
 ```
@@ -57,7 +57,7 @@ All five functions (curl / Python / LLM): [`api-examples.md`](api-examples.md).
 
 Don't want to write code? Point any LLM at [datasink.ing](https://datasink.ing),
 give it your API key, and ask in plain language. See
-[`llm-examples.md`](llm-examples.md) for three end-to-end examples — explore
+[`llm-examples.md`](llm-examples.md) for eight end-to-end examples — explore
 coverage, list a company's reports, and extract a figure with correct units.
 
 ## Examples (`examples/`)
@@ -70,7 +70,7 @@ coverage, list a company's reports, and extract a figure with correct units.
 
 Every example pulls from the live API and runs as-is.
 
-> `03_download_exchange.py` fetches every report on an exchange (e.g. all of Shenzhen — 130k+ documents). Free keys work too, but fall back to slow per-document fetching (1 req/s + shared daily quota); a **paid (yearly)** key is strongly recommended for full-exchange downloads.
+> `03_download_exchange.py` fetches every report on an exchange (e.g. all of Shenzhen — 150k+ documents). Free keys work too, but fall back to slow per-document fetching (1 req/s + shared daily quota); a **paid (yearly)** key is strongly recommended for full-exchange downloads.
 
 ## Research (`research/`)
 
@@ -86,16 +86,17 @@ Start from [`research/TEMPLATE.md`](research/TEMPLATE.md).
 
 | | |
 |---|---|
-| Coverage | SSE / SZSE / BSE, 5,000+ A-share companies |
+| Coverage | China (SSE / SZSE / BSE) · Korea (KOSPI / KOSDAQ / KONEX) · Japan (TSE) |
 | Document types | annual / semiannual / q1 / q3 / amendment |
+| Update frequency | Daily — Korea/Japan via official DART/EDINET APIs (new filings within ~24h of publication) |
 | Format | Full-text Markdown (with YAML frontmatter) |
-| API | REST — `GET /documents`, batch download, `with_content=1` for full text |
-| Symbols | FMP style: `600519.SS` / `000001.SZ` / `830799.BJ` |
+| API | REST — `GET /documents`, batch download, `with_content=1` for full text, `?section=` + `/sections` for chapter-level access |
+| Symbols | FMP style: `600519.SS` / `005930.KS` / `7203.T` |
 | Auth | `?apikey=` query parameter (FMP style) |
 
 ## Data source
 
-All reports originate from [cninfo.com.cn](http://www.cninfo.com.cn), the officially designated information disclosure platform of China's listed companies.
+Reports are sourced from official regulatory disclosure platforms in each market and converted in-house to clean Markdown.
 
 ## License
 

datasinking-0.2.0/datasinking/mcp_server.py

@@ -0,0 +1,119 @@
+# -*- coding: utf-8 -*-
+"""DataSinking MCP server (Model Context Protocol).
+
+Expose the DataSinking API — full-text financial reports across Asia
+(China, Korea, Japan) as clean Markdown — to AI agents (Claude, Cursor,
+Codex, DeepSeek, Windsurf, …).
+
+Install the MCP extra::
+
+    pip install "datasinking[mcp]"
+
+Then run::
+
+    datasinking-mcp
+
+or add to any MCP client with ``command: datasinking-mcp`` (stdio). Requires
+the environment variable ``DATASINK_API_KEY`` (get a free key at
+https://datasink.ing).
+"""
+
+import os
+from typing import Optional
+
+import requests
+
+# mcp v1 uses FastMCP; v2 renamed it to MCPServer. Support both.
+try:
+    from mcp.server.fastmcp import FastMCP  # mcp v1
+except ImportError:  # pragma: no cover
+    from mcp.server.mcpserver import MCPServer as FastMCP  # mcp v2
+
+BASE_URL = "https://api.datasink.ing"
+API_KEY = os.environ.get("DATASINK_API_KEY", "")
+
+mcp = FastMCP(
+    "DataSinking",
+    instructions=(
+        "DataSinking 提供亚洲（中国/韩国/日本）上市公司财报的全文 Markdown。"
+        "symbol 用 FMP 风格：600519.SS（茅台）、005930.KS（三星）、7203.T（丰田）。"
+        "要省 token 时用 get_section 只取某一章（如 MD&A），而不是 get_report 拿整篇。"
+    ),
+)
+
+
+def _get(path: str, params: Optional[dict] = None) -> dict:
+    """Call the DataSinking API, carrying the API key automatically."""
+    if not API_KEY:
+        raise RuntimeError("缺少 DATASINK_API_KEY 环境变量（去 datasink.ing 免费拿一个）")
+    p = dict(params or {})
+    p["apikey"] = API_KEY
+    r = requests.get(f"{BASE_URL}{path}", params=p, timeout=90)
+    r.raise_for_status()
+    return r.json()
+
+
+@mcp.tool()
+def list_exchanges() -> list:
+    """列出 DataSinking 覆盖的交易所代码（sse/szse/bj/ksc/koe/knx/jpx）。"""
+    return _get("/exchanges").get("exchanges", [])
+
+
+@mcp.tool()
+def list_stocks(exchange: str, limit: int = 20) -> dict:
+    """列出某交易所的股票（含每家公司的报告数）。
+
+    Args:
+        exchange: 交易所代码，如 sse / szse / ksc / koe / jpx
+        limit: 返回前 N 家（默认 20，防止列表过长）
+    """
+    data = _get("/stocks", {"exchange": exchange})
+    return {"exchange": exchange, "total": data.get("total", 0), "items": data.get("items", [])[:limit]}
+
+
+@mcp.tool()
+def list_reports(symbol: str, doc_type: str = "annual", size: int = 10) -> dict:
+    """列出某公司的报告（元数据，不含正文）。
+
+    Args:
+        symbol: FMP 风格代码，如 600519.SS / 005930.KS / 7203.T
+        doc_type: annual / semiannual / q1 / q3
+        size: 返回条数（默认 10）
+    """
+    return _get("/documents", {"symbol": symbol, "doc_type": doc_type, "size": size})
+
+
+@mcp.tool()
+def get_report(document_id: int) -> dict:
+    """获取单篇报告的全文（元数据 + Markdown 正文）。
+
+    Args:
+        document_id: 报告 ID，从 list_reports 的 items[].id 拿
+    """
+    return _get(f"/documents/{document_id}")
+
+
+@mcp.tool()
+def list_sections(document_id: int) -> dict:
+    """列出某报告的所有章节标题（供 get_section 用）。"""
+    return _get(f"/documents/{document_id}/sections")
+
+
+@mcp.tool()
+def get_section(document_id: int, section: str) -> dict:
+    """只取报告的某一章（省 token，适合 RAG）。
+
+    Args:
+        document_id: 报告 ID
+        section: 章节标题的关键词，如 "管理层讨论与分析" / "MD&A" / "财务报告"
+    """
+    return _get(f"/documents/{document_id}", {"section": section})
+
+
+def main() -> None:
+    """Entry point for the ``datasinking-mcp`` console script."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

{datasinking-0.1.1 → datasinking-0.2.0}/datasinking.egg-info/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: datasinking
-Version: 0.1.1
-Summary: Python client for DataSinking — full-text China A-share financial reports as Markdown.
+Version: 0.2.0
+Summary: Python client for DataSinking — full-text Asian financial reports (China, Korea, Japan) as Markdown.
 Author: DataSinking
 License: MIT
 Project-URL: Homepage, https://datasink.ing
 Project-URL: Documentation, https://datasink.ing/docs
 Project-URL: Repository, https://github.com/heubme2020/datasinking
-Keywords: a-share,china,financial reports,markdown,api,stock
+Keywords: a-share,china,korea,japan,financial reports,markdown,api,mcp,model-context-protocol,rag,llm
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -15,21 +15,23 @@ Classifier: Topic :: Office/Business :: Financial
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Requires-Dist: requests>=2.28; extra == "mcp"
 Dynamic: license-file
 
 # DataSinking
 
 [![PyPI version](https://img.shields.io/pypi/v/datasinking.svg)](https://pypi.org/project/datasinking/)
 
-**Full-text A-share financial reports, as clean Markdown.**
+**Full-text financial reports across Asia, as clean Markdown.**
 
-[DataSinking](https://datasink.ing) is a **China stock market data API** that serves
-**full-text A-share financial reports** — annual, semi-annual and quarterly — as clean
-**Markdown**. Download China A-share financial statements (balance sheet, income statement,
-cash flow) by FMP-style symbol (`600519.SS`) or filter by exchange / report period, through a
-simple REST API. Raw PDFs are sourced from [cninfo.com.cn](http://www.cninfo.com.cn) (the
-officially designated disclosure platform) and parsed into structured Markdown with YAML
-frontmatter, preserved headings, paragraphs and tables — ready for LLM reading and analysis.
+[DataSinking](https://datasink.ing) serves **full-text financial reports** — annual, semi-annual
+and quarterly — from **China, Korea and Japan** as clean **Markdown**, ready for LLM reading
+and RAG. Query by FMP-style symbol (`600519.SS`, `005930.KS`, `7203.T`) or filter by exchange,
+report period, or **section** — pull just the MD&A / risk section instead of the whole report.
+Reports are sourced from official disclosure platforms and parsed into structured Markdown with
+YAML frontmatter, preserved headings, paragraphs and tables.
 
 ---
 
@@ -41,8 +43,9 @@ Examples, research and tutorials showing how to work with financial report data,
 datasinking/
 ├── examples/     # Example scripts: pull data from the API and analyze it
 ├── research/     # Research notes / blog posts (reproducing paper-style presentation)
-├── datasinking/  # Python client — pip install datasinking
-├── llm-examples.md  # Ask an LLM — no code needed (3 end-to-end examples)
+├── datasinking/  # Python client + MCP server — pip install "datasinking[mcp]"
+├── mcp-server.md # How to configure the MCP server (for AI agents: Claude / Cursor / Codex / DeepSeek)
+├── llm-examples.md  # Ask an LLM — no code needed (8 end-to-end examples)
 ├── api-examples.md  # 7 examples × 3 interfaces (curl / Python / LLM)
 └── README.md
 ```
@@ -76,7 +79,7 @@ All five functions (curl / Python / LLM): [`api-examples.md`](api-examples.md).
 
 Don't want to write code? Point any LLM at [datasink.ing](https://datasink.ing),
 give it your API key, and ask in plain language. See
-[`llm-examples.md`](llm-examples.md) for three end-to-end examples — explore
+[`llm-examples.md`](llm-examples.md) for eight end-to-end examples — explore
 coverage, list a company's reports, and extract a figure with correct units.
 
 ## Examples (`examples/`)
@@ -89,7 +92,7 @@ coverage, list a company's reports, and extract a figure with correct units.
 
 Every example pulls from the live API and runs as-is.
 
-> `03_download_exchange.py` fetches every report on an exchange (e.g. all of Shenzhen — 130k+ documents). Free keys work too, but fall back to slow per-document fetching (1 req/s + shared daily quota); a **paid (yearly)** key is strongly recommended for full-exchange downloads.
+> `03_download_exchange.py` fetches every report on an exchange (e.g. all of Shenzhen — 150k+ documents). Free keys work too, but fall back to slow per-document fetching (1 req/s + shared daily quota); a **paid (yearly)** key is strongly recommended for full-exchange downloads.
 
 ## Research (`research/`)
 
@@ -105,16 +108,17 @@ Start from [`research/TEMPLATE.md`](research/TEMPLATE.md).
 
 | | |
 |---|---|
-| Coverage | SSE / SZSE / BSE, 5,000+ A-share companies |
+| Coverage | China (SSE / SZSE / BSE) · Korea (KOSPI / KOSDAQ / KONEX) · Japan (TSE) |
 | Document types | annual / semiannual / q1 / q3 / amendment |
+| Update frequency | Daily — Korea/Japan via official DART/EDINET APIs (new filings within ~24h of publication) |
 | Format | Full-text Markdown (with YAML frontmatter) |
-| API | REST — `GET /documents`, batch download, `with_content=1` for full text |
-| Symbols | FMP style: `600519.SS` / `000001.SZ` / `830799.BJ` |
+| API | REST — `GET /documents`, batch download, `with_content=1` for full text, `?section=` + `/sections` for chapter-level access |
+| Symbols | FMP style: `600519.SS` / `005930.KS` / `7203.T` |
 | Auth | `?apikey=` query parameter (FMP style) |
 
 ## Data source
 
-All reports originate from [cninfo.com.cn](http://www.cninfo.com.cn), the officially designated information disclosure platform of China's listed companies.
+Reports are sourced from official regulatory disclosure platforms in each market and converted in-house to clean Markdown.
 
 ## License
 

{datasinking-0.1.1 → datasinking-0.2.0}/datasinking.egg-info/SOURCES.txt

@@ -3,7 +3,10 @@ README.md
 pyproject.toml
 datasinking/__init__.py
 datasinking/client.py
+datasinking/mcp_server.py
 datasinking.egg-info/PKG-INFO
 datasinking.egg-info/SOURCES.txt
 datasinking.egg-info/dependency_links.txt
+datasinking.egg-info/entry_points.txt
+datasinking.egg-info/requires.txt
 datasinking.egg-info/top_level.txt

datasinking-0.2.0/datasinking.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+datasinking-mcp = datasinking.mcp_server:main

datasinking-0.2.0/datasinking.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[mcp]
+mcp>=1.0.0
+requests>=2.28

{datasinking-0.1.1 → datasinking-0.2.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "datasinking"
-version = "0.1.1"
-description = "Python client for DataSinking — full-text China A-share financial reports as Markdown."
+version = "0.2.0"
+description = "Python client for DataSinking — full-text Asian financial reports (China, Korea, Japan) as Markdown."
 readme = "README.md"
 requires-python = ">=3.8"
 license = { text = "MIT" }
 authors = [{ name = "DataSinking" }]
-keywords = ["a-share", "china", "financial reports", "markdown", "api", "stock"]
+keywords = ["a-share", "china", "korea", "japan", "financial reports", "markdown", "api", "mcp", "model-context-protocol", "rag", "llm"]
 classifiers = [
     "Programming Language :: Python :: 3",
     "License :: OSI Approved :: MIT License",
@@ -19,6 +19,12 @@ classifiers = [
 ]
 dependencies = []
 
+[project.optional-dependencies]
+mcp = ["mcp>=1.0.0", "requests>=2.28"]
+
+[project.scripts]
+datasinking-mcp = "datasinking.mcp_server:main"
+
 [project.urls]
 Homepage = "https://datasink.ing"
 Documentation = "https://datasink.ing/docs"