datasinking 0.2.0__tar.gz → 0.2.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datasinking
-Version: 0.2.0
+Version: 0.2.2
 Summary: Python client for DataSinking — full-text Asian financial reports (China, Korea, Japan) as Markdown.
 Author: DataSinking
 License: MIT
@@ -22,7 +22,10 @@ Dynamic: license-file
 
 # DataSinking
 
+<!-- mcp-name: io.github.heubme2020/datasinking -->
+
 [![PyPI version](https://img.shields.io/pypi/v/datasinking.svg)](https://pypi.org/project/datasinking/)
+[![MCP server](https://img.shields.io/badge/MCP-server-blue)](https://github.com/heubme2020/datasinking#mcp-server)
 
 **Full-text financial reports across Asia, as clean Markdown.**
 
@@ -35,6 +38,20 @@ YAML frontmatter, preserved headings, paragraphs and tables.
 
 ---
 
+## MCP server
+
+Ship DataSinking to any AI agent (Claude Desktop / Cursor / Codex / Windsurf) as an
+[MCP](https://modelcontextprotocol.io) server — 6 tools: list exchanges, list stocks,
+list reports, fetch a report, list sections, fetch one section (token-friendly for RAG).
+
+```bash
+pip install "datasinking[mcp]"
+datasinking-mcp          # requires DATASINK_API_KEY (free at https://datasink.ing)
+```
+
+Or add to your client with `command: datasinking-mcp`. A remote streamable-HTTP endpoint
+is also live at `https://api.datasink.ing/mcp`. See [`mcp-server.md`](mcp-server.md).
+
 ## What this repo is
 
 Examples, research and tutorials showing how to work with financial report data, including reproducing the presentation styles found in financial-report research papers.

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

@@ -1,6 +1,9 @@
 # DataSinking
 
+<!-- mcp-name: io.github.heubme2020/datasinking -->
+
 [![PyPI version](https://img.shields.io/pypi/v/datasinking.svg)](https://pypi.org/project/datasinking/)
+[![MCP server](https://img.shields.io/badge/MCP-server-blue)](https://github.com/heubme2020/datasinking#mcp-server)
 
 **Full-text financial reports across Asia, as clean Markdown.**
 
@@ -13,6 +16,20 @@ YAML frontmatter, preserved headings, paragraphs and tables.
 
 ---
 
+## MCP server
+
+Ship DataSinking to any AI agent (Claude Desktop / Cursor / Codex / Windsurf) as an
+[MCP](https://modelcontextprotocol.io) server — 6 tools: list exchanges, list stocks,
+list reports, fetch a report, list sections, fetch one section (token-friendly for RAG).
+
+```bash
+pip install "datasinking[mcp]"
+datasinking-mcp          # requires DATASINK_API_KEY (free at https://datasink.ing)
+```
+
+Or add to your client with `command: datasinking-mcp`. A remote streamable-HTTP endpoint
+is also live at `https://api.datasink.ing/mcp`. See [`mcp-server.md`](mcp-server.md).
+
 ## What this repo is
 
 Examples, research and tutorials showing how to work with financial report data, including reproducing the presentation styles found in financial-report research papers.

{datasinking-0.2.0 → datasinking-0.2.2}/datasinking/client.py

@@ -130,3 +130,14 @@ class DataSinking:
             d = self._get("/documents", dict(params, size=limit, order="desc"))
             ids = [it["id"] for it in d["items"]]
         return self._batch_content(ids)
+
+    def list_sections(self, doc_id):
+        """列出报告的章节标题 -> list[str]（供 get_section 用）"""
+        return self._get(f"/documents/{doc_id}/sections")["sections"]
+
+    def get_section(self, doc_id, section):
+        """只取报告的某一章（省 token，适合 RAG）-> dict，含 content 和 section
+
+        section: 章节标题关键词，如 "管理层讨论与分析" / "财务报告" / "MD&A"
+        """
+        return self._get(f"/documents/{doc_id}", {"section": section})

{datasinking-0.2.0 → datasinking-0.2.2}/datasinking/mcp_server.py

@@ -34,10 +34,15 @@ API_KEY = os.environ.get("DATASINK_API_KEY", "")
 
 mcp = FastMCP(
     "DataSinking",
+    title="DataSinking — Full-text Asian Financial Reports",
+    description="Full-text Asian financial reports (China, Korea, Japan) as clean Markdown via API, with chapter-level access for RAG and AI agents.",
+    version="0.2.2",
     instructions=(
-        "DataSinking 提供亚洲（中国/韩国/日本）上市公司财报的全文 Markdown。"
-        "symbol 用 FMP 风格：600519.SS（茅台）、005930.KS（三星）、7203.T（丰田）。"
-        "要省 token 时用 get_section 只取某一章（如 MD&A），而不是 get_report 拿整篇。"
+        "DataSinking serves full-text financial reports (annual / semi-annual / quarterly) "
+        "from China, Korea and Japan as clean Markdown, ready for LLM reading and RAG. "
+        "Use FMP-style symbols: 600519.SS (Kweichow Moutai), 005930.KS (Samsung Electronics), "
+        "7203.T (Toyota). To save tokens, prefer get_section to pull one chapter (e.g. MD&A) "
+        "instead of get_report for the whole document."
     ),
 )
 
@@ -45,7 +50,9 @@ mcp = FastMCP(
 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 免费拿一个）")
+        raise RuntimeError(
+            "Missing DATASINK_API_KEY environment variable (get a free key at https://datasink.ing)"
+        )
     p = dict(params or {})
     p["apikey"] = API_KEY
     r = requests.get(f"{BASE_URL}{path}", params=p, timeout=90)
@@ -55,17 +62,21 @@ def _get(path: str, params: Optional[dict] = None) -> dict:
 
 @mcp.tool()
 def list_exchanges() -> list:
-    """列出 DataSinking 覆盖的交易所代码（sse/szse/bj/ksc/koe/knx/jpx）。"""
+    """List the exchanges DataSinking covers and their report counts.
+
+    Returns exchange codes (sse / szse / bj / ksc / koe / knx / jpx) with the number
+    of reports available per exchange. Call this first to discover coverage.
+    """
     return _get("/exchanges").get("exchanges", [])
 
 
 @mcp.tool()
 def list_stocks(exchange: str, limit: int = 20) -> dict:
-    """列出某交易所的股票（含每家公司的报告数）。
+    """List stocks on an exchange, including the report count per company.
 
     Args:
-        exchange: 交易所代码，如 sse / szse / ksc / koe / jpx
-        limit: 返回前 N 家（默认 20，防止列表过长）
+        exchange: Exchange code, e.g. sse / szse / bj / ksc / koe / knx / jpx
+        limit: Return the first N companies (default 20) to keep responses short.
     """
     data = _get("/stocks", {"exchange": exchange})
     return {"exchange": exchange, "total": data.get("total", 0), "items": data.get("items", [])[:limit]}
@@ -73,39 +84,43 @@ def list_stocks(exchange: str, limit: int = 20) -> dict:
 
 @mcp.tool()
 def list_reports(symbol: str, doc_type: str = "annual", size: int = 10) -> dict:
-    """列出某公司的报告（元数据，不含正文）。
+    """List a company's reports — metadata only (id, title, period), no body text.
 
     Args:
-        symbol: FMP 风格代码，如 600519.SS / 005930.KS / 7203.T
+        symbol: FMP-style symbol, e.g. 600519.SS / 005930.KS / 7203.T
         doc_type: annual / semiannual / q1 / q3
-        size: 返回条数（默认 10）
+        size: Number of reports to return (default 10).
     """
     return _get("/documents", {"symbol": symbol, "doc_type": doc_type, "size": size})
 
 
 @mcp.tool()
 def get_report(document_id: int) -> dict:
-    """获取单篇报告的全文（元数据 + Markdown 正文）。
+    """Fetch a single report's full text (metadata + Markdown body).
 
     Args:
-        document_id: 报告 ID，从 list_reports 的 items[].id 拿
+        document_id: Report id, from list_reports items[].id
     """
     return _get(f"/documents/{document_id}")
 
 
 @mcp.tool()
 def list_sections(document_id: int) -> dict:
-    """列出某报告的所有章节标题（供 get_section 用）。"""
+    """List every section heading in a report (feed the headings to get_section).
+
+    Args:
+        document_id: Report id
+    """
     return _get(f"/documents/{document_id}/sections")
 
 
 @mcp.tool()
 def get_section(document_id: int, section: str) -> dict:
-    """只取报告的某一章（省 token，适合 RAG）。
+    """Fetch only one section of a report by keyword — cheaper than get_report for RAG.
 
     Args:
-        document_id: 报告 ID
-        section: 章节标题的关键词，如 "管理层讨论与分析" / "MD&A" / "财务报告"
+        document_id: Report id
+        section: Heading keyword, e.g. "management discussion" / "MD&A" / "financial statements" / "notes"
     """
     return _get(f"/documents/{document_id}", {"section": section})
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datasinking
-Version: 0.2.0
+Version: 0.2.2
 Summary: Python client for DataSinking — full-text Asian financial reports (China, Korea, Japan) as Markdown.
 Author: DataSinking
 License: MIT
@@ -22,7 +22,10 @@ Dynamic: license-file
 
 # DataSinking
 
+<!-- mcp-name: io.github.heubme2020/datasinking -->
+
 [![PyPI version](https://img.shields.io/pypi/v/datasinking.svg)](https://pypi.org/project/datasinking/)
+[![MCP server](https://img.shields.io/badge/MCP-server-blue)](https://github.com/heubme2020/datasinking#mcp-server)
 
 **Full-text financial reports across Asia, as clean Markdown.**
 
@@ -35,6 +38,20 @@ YAML frontmatter, preserved headings, paragraphs and tables.
 
 ---
 
+## MCP server
+
+Ship DataSinking to any AI agent (Claude Desktop / Cursor / Codex / Windsurf) as an
+[MCP](https://modelcontextprotocol.io) server — 6 tools: list exchanges, list stocks,
+list reports, fetch a report, list sections, fetch one section (token-friendly for RAG).
+
+```bash
+pip install "datasinking[mcp]"
+datasinking-mcp          # requires DATASINK_API_KEY (free at https://datasink.ing)
+```
+
+Or add to your client with `command: datasinking-mcp`. A remote streamable-HTTP endpoint
+is also live at `https://api.datasink.ing/mcp`. See [`mcp-server.md`](mcp-server.md).
+
 ## What this repo is
 
 Examples, research and tutorials showing how to work with financial report data, including reproducing the presentation styles found in financial-report research papers.

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "datasinking"
-version = "0.2.0"
+version = "0.2.2"
 description = "Python client for DataSinking — full-text Asian financial reports (China, Korea, Japan) as Markdown."
 readme = "README.md"
 requires-python = ">=3.8"