datasinking 0.1.1__tar.gz → 0.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. {datasinking-0.1.1/datasinking.egg-info → datasinking-0.2.1}/PKG-INFO +40 -19
  2. datasinking-0.1.1/PKG-INFO → datasinking-0.2.1/README.md +120 -121
  3. {datasinking-0.1.1 → datasinking-0.2.1}/datasinking/client.py +11 -0
  4. datasinking-0.2.1/datasinking/mcp_server.py +132 -0
  5. datasinking-0.2.1/datasinking.egg-info/PKG-INFO +142 -0
  6. {datasinking-0.1.1 → datasinking-0.2.1}/datasinking.egg-info/SOURCES.txt +3 -0
  7. datasinking-0.2.1/datasinking.egg-info/entry_points.txt +2 -0
  8. datasinking-0.2.1/datasinking.egg-info/requires.txt +4 -0
  9. {datasinking-0.1.1 → datasinking-0.2.1}/pyproject.toml +9 -3
  10. datasinking-0.1.1/README.md +0 -102
  11. {datasinking-0.1.1 → datasinking-0.2.1}/LICENSE +0 -0
  12. {datasinking-0.1.1 → datasinking-0.2.1}/datasinking/__init__.py +0 -0
  13. {datasinking-0.1.1 → datasinking-0.2.1}/datasinking.egg-info/dependency_links.txt +0 -0
  14. {datasinking-0.1.1 → datasinking-0.2.1}/datasinking.egg-info/top_level.txt +0 -0
  15. {datasinking-0.1.1 → datasinking-0.2.1}/setup.cfg +0 -0
{datasinking-0.1.1/datasinking.egg-info → datasinking-0.2.1}/PKG-INFO RENAMED
@@ -1,13 +1,13 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: datasinking
3
- Version: 0.1.1
4
- Summary: Python client for DataSinking — full-text China A-share financial reports as Markdown.
3
+ Version: 0.2.1
4
+ Summary: Python client for DataSinking — full-text Asian financial reports (China, Korea, Japan) as Markdown.
5
5
  Author: DataSinking
6
6
  License: MIT
7
7
  Project-URL: Homepage, https://datasink.ing
8
8
  Project-URL: Documentation, https://datasink.ing/docs
9
9
  Project-URL: Repository, https://github.com/heubme2020/datasinking
10
- Keywords: a-share,china,financial reports,markdown,api,stock
10
+ Keywords: a-share,china,korea,japan,financial reports,markdown,api,mcp,model-context-protocol,rag,llm
11
11
  Classifier: Programming Language :: Python :: 3
12
12
  Classifier: License :: OSI Approved :: MIT License
13
13
  Classifier: Operating System :: OS Independent
@@ -15,24 +15,43 @@ Classifier: Topic :: Office/Business :: Financial
15
15
  Requires-Python: >=3.8
16
16
  Description-Content-Type: text/markdown
17
17
  License-File: LICENSE
18
+ Provides-Extra: mcp
19
+ Requires-Dist: mcp>=1.0.0; extra == "mcp"
20
+ Requires-Dist: requests>=2.28; extra == "mcp"
18
21
  Dynamic: license-file
19
22
 
20
23
  # DataSinking
21
24
 
25
+ <!-- mcp-name: io.github.heubme2020/datasinking -->
26
+
22
27
  [![PyPI version](https://img.shields.io/pypi/v/datasinking.svg)](https://pypi.org/project/datasinking/)
28
+ [![MCP server](https://img.shields.io/badge/MCP-server-blue)](https://github.com/heubme2020/datasinking#mcp-server)
23
29
 
24
- **Full-text A-share financial reports, as clean Markdown.**
30
+ **Full-text financial reports across Asia, as clean Markdown.**
25
31
 
26
- [DataSinking](https://datasink.ing) is a **China stock market data API** that serves
27
- **full-text A-share financial reports** — annual, semi-annual and quarterly — as clean
28
- **Markdown**. Download China A-share financial statements (balance sheet, income statement,
29
- cash flow) by FMP-style symbol (`600519.SS`) or filter by exchange / report period, through a
30
- simple REST API. Raw PDFs are sourced from [cninfo.com.cn](http://www.cninfo.com.cn) (the
31
- officially designated disclosure platform) and parsed into structured Markdown with YAML
32
- frontmatter, preserved headings, paragraphs and tables — ready for LLM reading and analysis.
32
+ [DataSinking](https://datasink.ing) serves **full-text financial reports** — annual, semi-annual
33
+ and quarterly — from **China, Korea and Japan** as clean **Markdown**, ready for LLM reading
34
+ and RAG. Query by FMP-style symbol (`600519.SS`, `005930.KS`, `7203.T`) or filter by exchange,
35
+ report period, or **section** — pull just the MD&A / risk section instead of the whole report.
36
+ Reports are sourced from official disclosure platforms and parsed into structured Markdown with
37
+ YAML frontmatter, preserved headings, paragraphs and tables.
33
38
 
34
39
  ---
35
40
 
41
+ ## MCP server
42
+
43
+ Ship DataSinking to any AI agent (Claude Desktop / Cursor / Codex / Windsurf) as an
44
+ [MCP](https://modelcontextprotocol.io) server — 6 tools: list exchanges, list stocks,
45
+ list reports, fetch a report, list sections, fetch one section (token-friendly for RAG).
46
+
47
+ ```bash
48
+ pip install "datasinking[mcp]"
49
+ datasinking-mcp # requires DATASINK_API_KEY (free at https://datasink.ing)
50
+ ```
51
+
52
+ Or add to your client with `command: datasinking-mcp`. A remote streamable-HTTP endpoint
53
+ is also live at `https://api.datasink.ing/mcp`. See [`mcp-server.md`](mcp-server.md).
54
+
36
55
  ## What this repo is
37
56
 
38
57
  Examples, research and tutorials showing how to work with financial report data, including reproducing the presentation styles found in financial-report research papers.
@@ -41,8 +60,9 @@ Examples, research and tutorials showing how to work with financial report data,
41
60
  datasinking/
42
61
  ├── examples/ # Example scripts: pull data from the API and analyze it
43
62
  ├── research/ # Research notes / blog posts (reproducing paper-style presentation)
44
- ├── datasinking/ # Python client — pip install datasinking
45
- ├── llm-examples.md # Ask an LLM — no code needed (3 end-to-end examples)
63
+ ├── datasinking/ # Python client + MCP server — pip install "datasinking[mcp]"
64
+ ├── mcp-server.md # How to configure the MCP server (for AI agents: Claude / Cursor / Codex / DeepSeek)
65
+ ├── llm-examples.md # Ask an LLM — no code needed (8 end-to-end examples)
46
66
  ├── api-examples.md # 7 examples × 3 interfaces (curl / Python / LLM)
47
67
  └── README.md
48
68
  ```
@@ -76,7 +96,7 @@ All five functions (curl / Python / LLM): [`api-examples.md`](api-examples.md).
76
96
 
77
97
  Don't want to write code? Point any LLM at [datasink.ing](https://datasink.ing),
78
98
  give it your API key, and ask in plain language. See
79
- [`llm-examples.md`](llm-examples.md) for three end-to-end examples — explore
99
+ [`llm-examples.md`](llm-examples.md) for eight end-to-end examples — explore
80
100
  coverage, list a company's reports, and extract a figure with correct units.
81
101
 
82
102
  ## Examples (`examples/`)
@@ -89,7 +109,7 @@ coverage, list a company's reports, and extract a figure with correct units.
89
109
 
90
110
  Every example pulls from the live API and runs as-is.
91
111
 
92
- > `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.
112
+ > `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.
93
113
 
94
114
  ## Research (`research/`)
95
115
 
@@ -105,16 +125,17 @@ Start from [`research/TEMPLATE.md`](research/TEMPLATE.md).
105
125
 
106
126
  | | |
107
127
  |---|---|
108
- | Coverage | SSE / SZSE / BSE, 5,000+ A-share companies |
128
+ | Coverage | China (SSE / SZSE / BSE) · Korea (KOSPI / KOSDAQ / KONEX) · Japan (TSE) |
109
129
  | Document types | annual / semiannual / q1 / q3 / amendment |
130
+ | Update frequency | Daily — Korea/Japan via official DART/EDINET APIs (new filings within ~24h of publication) |
110
131
  | Format | Full-text Markdown (with YAML frontmatter) |
111
- | API | REST — `GET /documents`, batch download, `with_content=1` for full text |
112
- | Symbols | FMP style: `600519.SS` / `000001.SZ` / `830799.BJ` |
132
+ | API | REST — `GET /documents`, batch download, `with_content=1` for full text, `?section=` + `/sections` for chapter-level access |
133
+ | Symbols | FMP style: `600519.SS` / `005930.KS` / `7203.T` |
113
134
  | Auth | `?apikey=` query parameter (FMP style) |
114
135
 
115
136
  ## Data source
116
137
 
117
- All reports originate from [cninfo.com.cn](http://www.cninfo.com.cn), the officially designated information disclosure platform of China's listed companies.
138
+ Reports are sourced from official regulatory disclosure platforms in each market and converted in-house to clean Markdown.
118
139
 
119
140
  ## License
120
141
 
datasinking-0.1.1/PKG-INFO → datasinking-0.2.1/README.md RENAMED
@@ -1,121 +1,120 @@
1
- Metadata-Version: 2.4
2
- Name: datasinking
3
- Version: 0.1.1
4
- Summary: Python client for DataSinking — full-text China A-share financial reports as Markdown.
5
- Author: DataSinking
6
- License: MIT
7
- Project-URL: Homepage, https://datasink.ing
8
- Project-URL: Documentation, https://datasink.ing/docs
9
- Project-URL: Repository, https://github.com/heubme2020/datasinking
10
- Keywords: a-share,china,financial reports,markdown,api,stock
11
- Classifier: Programming Language :: Python :: 3
12
- Classifier: License :: OSI Approved :: MIT License
13
- Classifier: Operating System :: OS Independent
14
- Classifier: Topic :: Office/Business :: Financial
15
- Requires-Python: >=3.8
16
- Description-Content-Type: text/markdown
17
- License-File: LICENSE
18
- Dynamic: license-file
19
-
20
- # DataSinking
21
-
22
- [![PyPI version](https://img.shields.io/pypi/v/datasinking.svg)](https://pypi.org/project/datasinking/)
23
-
24
- **Full-text A-share financial reports, as clean Markdown.**
25
-
26
- [DataSinking](https://datasink.ing) is a **China stock market data API** that serves
27
- **full-text A-share financial reports** — annual, semi-annual and quarterly — as clean
28
- **Markdown**. Download China A-share financial statements (balance sheet, income statement,
29
- cash flow) by FMP-style symbol (`600519.SS`) or filter by exchange / report period, through a
30
- simple REST API. Raw PDFs are sourced from [cninfo.com.cn](http://www.cninfo.com.cn) (the
31
- officially designated disclosure platform) and parsed into structured Markdown with YAML
32
- frontmatter, preserved headings, paragraphs and tables — ready for LLM reading and analysis.
33
-
34
- ---
35
-
36
- ## What this repo is
37
-
38
- Examples, research and tutorials showing how to work with financial report data, including reproducing the presentation styles found in financial-report research papers.
39
-
40
- ```
41
- datasinking/
42
- ├── examples/ # Example scripts: pull data from the API and analyze it
43
- ├── research/ # Research notes / blog posts (reproducing paper-style presentation)
44
- ├── datasinking/ # Python client — pip install datasinking
45
- ├── llm-examples.md # Ask an LLM — no code needed (3 end-to-end examples)
46
- ├── api-examples.md # 7 examples × 3 interfaces (curl / Python / LLM)
47
- └── README.md
48
- ```
49
-
50
- ## Quick start
51
-
52
- 1. Get an API key at [datasink.ing](https://datasink.ing)
53
- 2. One line (FMP-style `?apikey=`):
54
-
55
- ```bash
56
- curl "https://api.datasink.ing/documents?symbol=600519.SS&with_content=1&apikey=YOUR_KEY"
57
- ```
58
-
59
- Or in Python:
60
-
61
- ```bash
62
- pip install datasinking
63
- ```
64
-
65
- ```python
66
- from datasinking import DataSinking
67
-
68
- ds = DataSinking("YOUR_KEY")
69
- for r in ds.get_stock_reports("600519.SS", limit=3):
70
- print(r["report_period"], r["title"], len(r["content"]), "chars")
71
- ```
72
-
73
- All five functions (curl / Python / LLM): [`api-examples.md`](api-examples.md).
74
-
75
- ## Ask an LLM (no code)
76
-
77
- Don't want to write code? Point any LLM at [datasink.ing](https://datasink.ing),
78
- give it your API key, and ask in plain language. See
79
- [`llm-examples.md`](llm-examples.md) for three end-to-end examples — explore
80
- coverage, list a company's reports, and extract a figure with correct units.
81
-
82
- ## Examples (`examples/`)
83
-
84
- | File | What it does |
85
- |---|---|
86
- | `01_quickstart.py` | The 5 core functions: list exchanges / stocks / reports / fetch a report / fetch a stock's reports |
87
- | `02_download_company.py` | Download a company's full reports to local Markdown files |
88
- | `03_download_exchange.py` | Download an entire exchange's reports (all stocks) to local Markdown files |
89
-
90
- Every example pulls from the live API and runs as-is.
91
-
92
- > `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.
93
-
94
- ## Research (`research/`)
95
-
96
- `research/` hosts research notes and blog posts, each based on DataSinking data with the source cited. You can reproduce charts and presentations found in financial-report research papers, e.g.:
97
-
98
- - Long-term revenue / profit trends
99
- - Industry comparison and distribution
100
- - Time series of financial metrics
101
-
102
- Start from [`research/TEMPLATE.md`](research/TEMPLATE.md).
103
-
104
- ## Data overview
105
-
106
- | | |
107
- |---|---|
108
- | Coverage | SSE / SZSE / BSE, 5,000+ A-share companies |
109
- | Document types | annual / semiannual / q1 / q3 / amendment |
110
- | Format | Full-text Markdown (with YAML frontmatter) |
111
- | API | REST — `GET /documents`, batch download, `with_content=1` for full text |
112
- | Symbols | FMP style: `600519.SS` / `000001.SZ` / `830799.BJ` |
113
- | Auth | `?apikey=` query parameter (FMP style) |
114
-
115
- ## Data source
116
-
117
- All reports originate from [cninfo.com.cn](http://www.cninfo.com.cn), the officially designated information disclosure platform of China's listed companies.
118
-
119
- ## License
120
-
121
- [MIT](LICENSE)
1
+ # DataSinking
2
+
3
+ <!-- mcp-name: io.github.heubme2020/datasinking -->
4
+
5
+ [![PyPI version](https://img.shields.io/pypi/v/datasinking.svg)](https://pypi.org/project/datasinking/)
6
+ [![MCP server](https://img.shields.io/badge/MCP-server-blue)](https://github.com/heubme2020/datasinking#mcp-server)
7
+
8
+ **Full-text financial reports across Asia, as clean Markdown.**
9
+
10
+ [DataSinking](https://datasink.ing) serves **full-text financial reports** — annual, semi-annual
11
+ and quarterly — from **China, Korea and Japan** as clean **Markdown**, ready for LLM reading
12
+ and RAG. Query by FMP-style symbol (`600519.SS`, `005930.KS`, `7203.T`) or filter by exchange,
13
+ report period, or **section** — pull just the MD&A / risk section instead of the whole report.
14
+ Reports are sourced from official disclosure platforms and parsed into structured Markdown with
15
+ YAML frontmatter, preserved headings, paragraphs and tables.
16
+
17
+ ---
18
+
19
+ ## MCP server
20
+
21
+ Ship DataSinking to any AI agent (Claude Desktop / Cursor / Codex / Windsurf) as an
22
+ [MCP](https://modelcontextprotocol.io) server — 6 tools: list exchanges, list stocks,
23
+ list reports, fetch a report, list sections, fetch one section (token-friendly for RAG).
24
+
25
+ ```bash
26
+ pip install "datasinking[mcp]"
27
+ datasinking-mcp # requires DATASINK_API_KEY (free at https://datasink.ing)
28
+ ```
29
+
30
+ Or add to your client with `command: datasinking-mcp`. A remote streamable-HTTP endpoint
31
+ is also live at `https://api.datasink.ing/mcp`. See [`mcp-server.md`](mcp-server.md).
32
+
33
+ ## What this repo is
34
+
35
+ Examples, research and tutorials showing how to work with financial report data, including reproducing the presentation styles found in financial-report research papers.
36
+
37
+ ```
38
+ datasinking/
39
+ ├── examples/ # Example scripts: pull data from the API and analyze it
40
+ ├── research/ # Research notes / blog posts (reproducing paper-style presentation)
41
+ ├── datasinking/ # Python client + MCP server — pip install "datasinking[mcp]"
42
+ ├── mcp-server.md # How to configure the MCP server (for AI agents: Claude / Cursor / Codex / DeepSeek)
43
+ ├── llm-examples.md # Ask an LLM — no code needed (8 end-to-end examples)
44
+ ├── api-examples.md # 7 examples × 3 interfaces (curl / Python / LLM)
45
+ └── README.md
46
+ ```
47
+
48
+ ## Quick start
49
+
50
+ 1. Get an API key at [datasink.ing](https://datasink.ing)
51
+ 2. One line (FMP-style `?apikey=`):
52
+
53
+ ```bash
54
+ curl "https://api.datasink.ing/documents?symbol=600519.SS&with_content=1&apikey=YOUR_KEY"
55
+ ```
56
+
57
+ Or in Python:
58
+
59
+ ```bash
60
+ pip install datasinking
61
+ ```
62
+
63
+ ```python
64
+ from datasinking import DataSinking
65
+
66
+ ds = DataSinking("YOUR_KEY")
67
+ for r in ds.get_stock_reports("600519.SS", limit=3):
68
+ print(r["report_period"], r["title"], len(r["content"]), "chars")
69
+ ```
70
+
71
+ All five functions (curl / Python / LLM): [`api-examples.md`](api-examples.md).
72
+
73
+ ## Ask an LLM (no code)
74
+
75
+ Don't want to write code? Point any LLM at [datasink.ing](https://datasink.ing),
76
+ give it your API key, and ask in plain language. See
77
+ [`llm-examples.md`](llm-examples.md) for eight end-to-end examples — explore
78
+ coverage, list a company's reports, and extract a figure with correct units.
79
+
80
+ ## Examples (`examples/`)
81
+
82
+ | File | What it does |
83
+ |---|---|
84
+ | `01_quickstart.py` | The 5 core functions: list exchanges / stocks / reports / fetch a report / fetch a stock's reports |
85
+ | `02_download_company.py` | Download a company's full reports to local Markdown files |
86
+ | `03_download_exchange.py` | Download an entire exchange's reports (all stocks) to local Markdown files |
87
+
88
+ Every example pulls from the live API and runs as-is.
89
+
90
+ > `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.
91
+
92
+ ## Research (`research/`)
93
+
94
+ `research/` hosts research notes and blog posts, each based on DataSinking data with the source cited. You can reproduce charts and presentations found in financial-report research papers, e.g.:
95
+
96
+ - Long-term revenue / profit trends
97
+ - Industry comparison and distribution
98
+ - Time series of financial metrics
99
+
100
+ Start from [`research/TEMPLATE.md`](research/TEMPLATE.md).
101
+
102
+ ## Data overview
103
+
104
+ | | |
105
+ |---|---|
106
+ | Coverage | China (SSE / SZSE / BSE) · Korea (KOSPI / KOSDAQ / KONEX) · Japan (TSE) |
107
+ | Document types | annual / semiannual / q1 / q3 / amendment |
108
+ | Update frequency | Daily — Korea/Japan via official DART/EDINET APIs (new filings within ~24h of publication) |
109
+ | Format | Full-text Markdown (with YAML frontmatter) |
110
+ | API | REST — `GET /documents`, batch download, `with_content=1` for full text, `?section=` + `/sections` for chapter-level access |
111
+ | Symbols | FMP style: `600519.SS` / `005930.KS` / `7203.T` |
112
+ | Auth | `?apikey=` query parameter (FMP style) |
113
+
114
+ ## Data source
115
+
116
+ Reports are sourced from official regulatory disclosure platforms in each market and converted in-house to clean Markdown.
117
+
118
+ ## License
119
+
120
+ [MIT](LICENSE)
{datasinking-0.1.1 → datasinking-0.2.1}/datasinking/client.py RENAMED
@@ -130,3 +130,14 @@ class DataSinking:
130
130
  d = self._get("/documents", dict(params, size=limit, order="desc"))
131
131
  ids = [it["id"] for it in d["items"]]
132
132
  return self._batch_content(ids)
133
+
134
+ def list_sections(self, doc_id):
135
+ """列出报告的章节标题 -> list[str]（供 get_section 用）"""
136
+ return self._get(f"/documents/{doc_id}/sections")["sections"]
137
+
138
+ def get_section(self, doc_id, section):
139
+ """只取报告的某一章（省 token，适合 RAG）-> dict，含 content 和 section
140
+
141
+ section: 章节标题关键词，如 "管理层讨论与分析" / "财务报告" / "MD&A"
142
+ """
143
+ return self._get(f"/documents/{doc_id}", {"section": section})
datasinking-0.2.1/datasinking/mcp_server.py ADDED
@@ -0,0 +1,132 @@
1
+ # -*- coding: utf-8 -*-
2
+ """DataSinking MCP server (Model Context Protocol).
3
+
4
+ Expose the DataSinking API — full-text financial reports across Asia
5
+ (China, Korea, Japan) as clean Markdown — to AI agents (Claude, Cursor,
6
+ Codex, DeepSeek, Windsurf, …).
7
+
8
+ Install the MCP extra::
9
+
10
+ pip install "datasinking[mcp]"
11
+
12
+ Then run::
13
+
14
+ datasinking-mcp
15
+
16
+ or add to any MCP client with ``command: datasinking-mcp`` (stdio). Requires
17
+ the environment variable ``DATASINK_API_KEY`` (get a free key at
18
+ https://datasink.ing).
19
+ """
20
+
21
+ import os
22
+ from typing import Optional
23
+
24
+ import requests
25
+
26
+ # mcp v1 uses FastMCP; v2 renamed it to MCPServer. Support both.
27
+ try:
28
+ from mcp.server.fastmcp import FastMCP # mcp v1
29
+ except ImportError: # pragma: no cover
30
+ from mcp.server.mcpserver import MCPServer as FastMCP # mcp v2
31
+
32
+ BASE_URL = "https://api.datasink.ing"
33
+ API_KEY = os.environ.get("DATASINK_API_KEY", "")
34
+
35
+ mcp = FastMCP(
36
+ "DataSinking",
37
+ version="0.2.1",
38
+ instructions=(
39
+ "DataSinking serves full-text financial reports (annual / semi-annual / quarterly) "
40
+ "from China, Korea and Japan as clean Markdown, ready for LLM reading and RAG. "
41
+ "Use FMP-style symbols: 600519.SS (Kweichow Moutai), 005930.KS (Samsung Electronics), "
42
+ "7203.T (Toyota). To save tokens, prefer get_section to pull one chapter (e.g. MD&A) "
43
+ "instead of get_report for the whole document."
44
+ ),
45
+ )
46
+
47
+
48
+ def _get(path: str, params: Optional[dict] = None) -> dict:
49
+ """Call the DataSinking API, carrying the API key automatically."""
50
+ if not API_KEY:
51
+ raise RuntimeError(
52
+ "Missing DATASINK_API_KEY environment variable (get a free key at https://datasink.ing)"
53
+ )
54
+ p = dict(params or {})
55
+ p["apikey"] = API_KEY
56
+ r = requests.get(f"{BASE_URL}{path}", params=p, timeout=90)
57
+ r.raise_for_status()
58
+ return r.json()
59
+
60
+
61
+ @mcp.tool()
62
+ def list_exchanges() -> list:
63
+ """List the exchanges DataSinking covers and their report counts.
64
+
65
+ Returns exchange codes (sse / szse / bj / ksc / koe / knx / jpx) with the number
66
+ of reports available per exchange. Call this first to discover coverage.
67
+ """
68
+ return _get("/exchanges").get("exchanges", [])
69
+
70
+
71
+ @mcp.tool()
72
+ def list_stocks(exchange: str, limit: int = 20) -> dict:
73
+ """List stocks on an exchange, including the report count per company.
74
+
75
+ Args:
76
+ exchange: Exchange code, e.g. sse / szse / bj / ksc / koe / knx / jpx
77
+ limit: Return the first N companies (default 20) to keep responses short.
78
+ """
79
+ data = _get("/stocks", {"exchange": exchange})
80
+ return {"exchange": exchange, "total": data.get("total", 0), "items": data.get("items", [])[:limit]}
81
+
82
+
83
+ @mcp.tool()
84
+ def list_reports(symbol: str, doc_type: str = "annual", size: int = 10) -> dict:
85
+ """List a company's reports — metadata only (id, title, period), no body text.
86
+
87
+ Args:
88
+ symbol: FMP-style symbol, e.g. 600519.SS / 005930.KS / 7203.T
89
+ doc_type: annual / semiannual / q1 / q3
90
+ size: Number of reports to return (default 10).
91
+ """
92
+ return _get("/documents", {"symbol": symbol, "doc_type": doc_type, "size": size})
93
+
94
+
95
+ @mcp.tool()
96
+ def get_report(document_id: int) -> dict:
97
+ """Fetch a single report's full text (metadata + Markdown body).
98
+
99
+ Args:
100
+ document_id: Report id, from list_reports items[].id
101
+ """
102
+ return _get(f"/documents/{document_id}")
103
+
104
+
105
+ @mcp.tool()
106
+ def list_sections(document_id: int) -> dict:
107
+ """List every section heading in a report (feed the headings to get_section).
108
+
109
+ Args:
110
+ document_id: Report id
111
+ """
112
+ return _get(f"/documents/{document_id}/sections")
113
+
114
+
115
+ @mcp.tool()
116
+ def get_section(document_id: int, section: str) -> dict:
117
+ """Fetch only one section of a report by keyword — cheaper than get_report for RAG.
118
+
119
+ Args:
120
+ document_id: Report id
121
+ section: Heading keyword, e.g. "management discussion" / "MD&A" / "financial statements" / "notes"
122
+ """
123
+ return _get(f"/documents/{document_id}", {"section": section})
124
+
125
+
126
+ def main() -> None:
127
+ """Entry point for the ``datasinking-mcp`` console script."""
128
+ mcp.run()
129
+
130
+
131
+ if __name__ == "__main__":
132
+ main()
datasinking-0.2.1/datasinking.egg-info/PKG-INFO ADDED
@@ -0,0 +1,142 @@
1
+ Metadata-Version: 2.4
2
+ Name: datasinking
3
+ Version: 0.2.1
4
+ Summary: Python client for DataSinking — full-text Asian financial reports (China, Korea, Japan) as Markdown.
5
+ Author: DataSinking
6
+ License: MIT
7
+ Project-URL: Homepage, https://datasink.ing
8
+ Project-URL: Documentation, https://datasink.ing/docs
9
+ Project-URL: Repository, https://github.com/heubme2020/datasinking
10
+ Keywords: a-share,china,korea,japan,financial reports,markdown,api,mcp,model-context-protocol,rag,llm
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Topic :: Office/Business :: Financial
15
+ Requires-Python: >=3.8
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Provides-Extra: mcp
19
+ Requires-Dist: mcp>=1.0.0; extra == "mcp"
20
+ Requires-Dist: requests>=2.28; extra == "mcp"
21
+ Dynamic: license-file
22
+
23
+ # DataSinking
24
+
25
+ <!-- mcp-name: io.github.heubme2020/datasinking -->
26
+
27
+ [![PyPI version](https://img.shields.io/pypi/v/datasinking.svg)](https://pypi.org/project/datasinking/)
28
+ [![MCP server](https://img.shields.io/badge/MCP-server-blue)](https://github.com/heubme2020/datasinking#mcp-server)
29
+
30
+ **Full-text financial reports across Asia, as clean Markdown.**
31
+
32
+ [DataSinking](https://datasink.ing) serves **full-text financial reports** — annual, semi-annual
33
+ and quarterly — from **China, Korea and Japan** as clean **Markdown**, ready for LLM reading
34
+ and RAG. Query by FMP-style symbol (`600519.SS`, `005930.KS`, `7203.T`) or filter by exchange,
35
+ report period, or **section** — pull just the MD&A / risk section instead of the whole report.
36
+ Reports are sourced from official disclosure platforms and parsed into structured Markdown with
37
+ YAML frontmatter, preserved headings, paragraphs and tables.
38
+
39
+ ---
40
+
41
+ ## MCP server
42
+
43
+ Ship DataSinking to any AI agent (Claude Desktop / Cursor / Codex / Windsurf) as an
44
+ [MCP](https://modelcontextprotocol.io) server — 6 tools: list exchanges, list stocks,
45
+ list reports, fetch a report, list sections, fetch one section (token-friendly for RAG).
46
+
47
+ ```bash
48
+ pip install "datasinking[mcp]"
49
+ datasinking-mcp # requires DATASINK_API_KEY (free at https://datasink.ing)
50
+ ```
51
+
52
+ Or add to your client with `command: datasinking-mcp`. A remote streamable-HTTP endpoint
53
+ is also live at `https://api.datasink.ing/mcp`. See [`mcp-server.md`](mcp-server.md).
54
+
55
+ ## What this repo is
56
+
57
+ Examples, research and tutorials showing how to work with financial report data, including reproducing the presentation styles found in financial-report research papers.
58
+
59
+ ```
60
+ datasinking/
61
+ ├── examples/ # Example scripts: pull data from the API and analyze it
62
+ ├── research/ # Research notes / blog posts (reproducing paper-style presentation)
63
+ ├── datasinking/ # Python client + MCP server — pip install "datasinking[mcp]"
64
+ ├── mcp-server.md # How to configure the MCP server (for AI agents: Claude / Cursor / Codex / DeepSeek)
65
+ ├── llm-examples.md # Ask an LLM — no code needed (8 end-to-end examples)
66
+ ├── api-examples.md # 7 examples × 3 interfaces (curl / Python / LLM)
67
+ └── README.md
68
+ ```
69
+
70
+ ## Quick start
71
+
72
+ 1. Get an API key at [datasink.ing](https://datasink.ing)
73
+ 2. One line (FMP-style `?apikey=`):
74
+
75
+ ```bash
76
+ curl "https://api.datasink.ing/documents?symbol=600519.SS&with_content=1&apikey=YOUR_KEY"
77
+ ```
78
+
79
+ Or in Python:
80
+
81
+ ```bash
82
+ pip install datasinking
83
+ ```
84
+
85
+ ```python
86
+ from datasinking import DataSinking
87
+
88
+ ds = DataSinking("YOUR_KEY")
89
+ for r in ds.get_stock_reports("600519.SS", limit=3):
90
+ print(r["report_period"], r["title"], len(r["content"]), "chars")
91
+ ```
92
+
93
+ All five functions (curl / Python / LLM): [`api-examples.md`](api-examples.md).
94
+
95
+ ## Ask an LLM (no code)
96
+
97
+ Don't want to write code? Point any LLM at [datasink.ing](https://datasink.ing),
98
+ give it your API key, and ask in plain language. See
99
+ [`llm-examples.md`](llm-examples.md) for eight end-to-end examples — explore
100
+ coverage, list a company's reports, and extract a figure with correct units.
101
+
102
+ ## Examples (`examples/`)
103
+
104
+ | File | What it does |
105
+ |---|---|
106
+ | `01_quickstart.py` | The 5 core functions: list exchanges / stocks / reports / fetch a report / fetch a stock's reports |
107
+ | `02_download_company.py` | Download a company's full reports to local Markdown files |
108
+ | `03_download_exchange.py` | Download an entire exchange's reports (all stocks) to local Markdown files |
109
+
110
+ Every example pulls from the live API and runs as-is.
111
+
112
+ > `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.
113
+
114
+ ## Research (`research/`)
115
+
116
+ `research/` hosts research notes and blog posts, each based on DataSinking data with the source cited. You can reproduce charts and presentations found in financial-report research papers, e.g.:
117
+
118
+ - Long-term revenue / profit trends
119
+ - Industry comparison and distribution
120
+ - Time series of financial metrics
121
+
122
+ Start from [`research/TEMPLATE.md`](research/TEMPLATE.md).
123
+
124
+ ## Data overview
125
+
126
+ | | |
127
+ |---|---|
128
+ | Coverage | China (SSE / SZSE / BSE) · Korea (KOSPI / KOSDAQ / KONEX) · Japan (TSE) |
129
+ | Document types | annual / semiannual / q1 / q3 / amendment |
130
+ | Update frequency | Daily — Korea/Japan via official DART/EDINET APIs (new filings within ~24h of publication) |
131
+ | Format | Full-text Markdown (with YAML frontmatter) |
132
+ | API | REST — `GET /documents`, batch download, `with_content=1` for full text, `?section=` + `/sections` for chapter-level access |
133
+ | Symbols | FMP style: `600519.SS` / `005930.KS` / `7203.T` |
134
+ | Auth | `?apikey=` query parameter (FMP style) |
135
+
136
+ ## Data source
137
+
138
+ Reports are sourced from official regulatory disclosure platforms in each market and converted in-house to clean Markdown.
139
+
140
+ ## License
141
+
142
+ [MIT](LICENSE)
{datasinking-0.1.1 → datasinking-0.2.1}/datasinking.egg-info/SOURCES.txt RENAMED
@@ -3,7 +3,10 @@ README.md
3
3
  pyproject.toml
4
4
  datasinking/__init__.py
5
5
  datasinking/client.py
6
+ datasinking/mcp_server.py
6
7
  datasinking.egg-info/PKG-INFO
7
8
  datasinking.egg-info/SOURCES.txt
8
9
  datasinking.egg-info/dependency_links.txt
10
+ datasinking.egg-info/entry_points.txt
11
+ datasinking.egg-info/requires.txt
9
12
  datasinking.egg-info/top_level.txt
datasinking-0.2.1/datasinking.egg-info/entry_points.txt ADDED
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ datasinking-mcp = datasinking.mcp_server:main
datasinking-0.2.1/datasinking.egg-info/requires.txt ADDED
@@ -0,0 +1,4 @@
1
+
2
+ [mcp]
3
+ mcp>=1.0.0
4
+ requests>=2.28
{datasinking-0.1.1 → datasinking-0.2.1}/pyproject.toml RENAMED
@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "datasinking"
7
- version = "0.1.1"
8
- description = "Python client for DataSinking — full-text China A-share financial reports as Markdown."
7
+ version = "0.2.1"
8
+ description = "Python client for DataSinking — full-text Asian financial reports (China, Korea, Japan) as Markdown."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.8"
11
11
  license = { text = "MIT" }
12
12
  authors = [{ name = "DataSinking" }]
13
- keywords = ["a-share", "china", "financial reports", "markdown", "api", "stock"]
13
+ keywords = ["a-share", "china", "korea", "japan", "financial reports", "markdown", "api", "mcp", "model-context-protocol", "rag", "llm"]
14
14
  classifiers = [
15
15
  "Programming Language :: Python :: 3",
16
16
  "License :: OSI Approved :: MIT License",
@@ -19,6 +19,12 @@ classifiers = [
19
19
  ]
20
20
  dependencies = []
21
21
 
22
+ [project.optional-dependencies]
23
+ mcp = ["mcp>=1.0.0", "requests>=2.28"]
24
+
25
+ [project.scripts]
26
+ datasinking-mcp = "datasinking.mcp_server:main"
27
+
22
28
  [project.urls]
23
29
  Homepage = "https://datasink.ing"
24
30
  Documentation = "https://datasink.ing/docs"
datasinking-0.1.1/README.md DELETED
@@ -1,102 +0,0 @@
1
- # DataSinking
2
-
3
- [![PyPI version](https://img.shields.io/pypi/v/datasinking.svg)](https://pypi.org/project/datasinking/)
4
-
5
- **Full-text A-share financial reports, as clean Markdown.**
6
-
7
- [DataSinking](https://datasink.ing) is a **China stock market data API** that serves
8
- **full-text A-share financial reports** — annual, semi-annual and quarterly — as clean
9
- **Markdown**. Download China A-share financial statements (balance sheet, income statement,
10
- cash flow) by FMP-style symbol (`600519.SS`) or filter by exchange / report period, through a
11
- simple REST API. Raw PDFs are sourced from [cninfo.com.cn](http://www.cninfo.com.cn) (the
12
- officially designated disclosure platform) and parsed into structured Markdown with YAML
13
- frontmatter, preserved headings, paragraphs and tables — ready for LLM reading and analysis.
14
-
15
- ---
16
-
17
- ## What this repo is
18
-
19
- Examples, research and tutorials showing how to work with financial report data, including reproducing the presentation styles found in financial-report research papers.
20
-
21
- ```
22
- datasinking/
23
- ├── examples/ # Example scripts: pull data from the API and analyze it
24
- ├── research/ # Research notes / blog posts (reproducing paper-style presentation)
25
- ├── datasinking/ # Python client — pip install datasinking
26
- ├── llm-examples.md # Ask an LLM — no code needed (3 end-to-end examples)
27
- ├── api-examples.md # 7 examples × 3 interfaces (curl / Python / LLM)
28
- └── README.md
29
- ```
30
-
31
- ## Quick start
32
-
33
- 1. Get an API key at [datasink.ing](https://datasink.ing)
34
- 2. One line (FMP-style `?apikey=`):
35
-
36
- ```bash
37
- curl "https://api.datasink.ing/documents?symbol=600519.SS&with_content=1&apikey=YOUR_KEY"
38
- ```
39
-
40
- Or in Python:
41
-
42
- ```bash
43
- pip install datasinking
44
- ```
45
-
46
- ```python
47
- from datasinking import DataSinking
48
-
49
- ds = DataSinking("YOUR_KEY")
50
- for r in ds.get_stock_reports("600519.SS", limit=3):
51
- print(r["report_period"], r["title"], len(r["content"]), "chars")
52
- ```
53
-
54
- All five functions (curl / Python / LLM): [`api-examples.md`](api-examples.md).
55
-
56
- ## Ask an LLM (no code)
57
-
58
- Don't want to write code? Point any LLM at [datasink.ing](https://datasink.ing),
59
- give it your API key, and ask in plain language. See
60
- [`llm-examples.md`](llm-examples.md) for three end-to-end examples — explore
61
- coverage, list a company's reports, and extract a figure with correct units.
62
-
63
- ## Examples (`examples/`)
64
-
65
- | File | What it does |
66
- |---|---|
67
- | `01_quickstart.py` | The 5 core functions: list exchanges / stocks / reports / fetch a report / fetch a stock's reports |
68
- | `02_download_company.py` | Download a company's full reports to local Markdown files |
69
- | `03_download_exchange.py` | Download an entire exchange's reports (all stocks) to local Markdown files |
70
-
71
- Every example pulls from the live API and runs as-is.
72
-
73
- > `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.
74
-
75
- ## Research (`research/`)
76
-
77
- `research/` hosts research notes and blog posts, each based on DataSinking data with the source cited. You can reproduce charts and presentations found in financial-report research papers, e.g.:
78
-
79
- - Long-term revenue / profit trends
80
- - Industry comparison and distribution
81
- - Time series of financial metrics
82
-
83
- Start from [`research/TEMPLATE.md`](research/TEMPLATE.md).
84
-
85
- ## Data overview
86
-
87
- | | |
88
- |---|---|
89
- | Coverage | SSE / SZSE / BSE, 5,000+ A-share companies |
90
- | Document types | annual / semiannual / q1 / q3 / amendment |
91
- | Format | Full-text Markdown (with YAML frontmatter) |
92
- | API | REST — `GET /documents`, batch download, `with_content=1` for full text |
93
- | Symbols | FMP style: `600519.SS` / `000001.SZ` / `830799.BJ` |
94
- | Auth | `?apikey=` query parameter (FMP style) |
95
-
96
- ## Data source
97
-
98
- All reports originate from [cninfo.com.cn](http://www.cninfo.com.cn), the officially designated information disclosure platform of China's listed companies.
99
-
100
- ## License
101
-
102
- [MIT](LICENSE)
{datasinking-0.1.1 → datasinking-0.2.1}/LICENSE RENAMED
File without changes
{datasinking-0.1.1 → datasinking-0.2.1}/setup.cfg RENAMED
File without changes