datasinking 0.2.8__tar.gz → 0.2.10__tar.gz

{datasinking-0.2.8 → datasinking-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datasinking
-Version: 0.2.8
+Version: 0.2.10
 Summary: Python client for DataSinking — full-text Asian financial reports (China, Korea, Japan, Taiwan) as Markdown.
 Author: DataSinking
 License: MIT
@@ -31,27 +31,78 @@ Dynamic: license-file
 **Full-text financial reports across Asia, as clean Markdown.**
 
 [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.
+and quarterly — from **China, Korea, Japan and Taiwan** as clean **Markdown**, ready for LLM reading
+and RAG. Query by FMP-style symbol (`600519.SS`, `005930.KS`, `7203.T`, `2330.TW`) 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.
 
 ---
 
 ## MCP server
 
-Ship DataSinking to any AI agent (Claude Desktop / Cursor / Codex / Windsurf) as an
+Ship DataSinking to any AI agent (Claude / 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).
 
+### Hosted — nothing to install
+
+Point any MCP client at our endpoint and you're done. No package, no Python, no local server:
+
+```json
+{
+  "mcpServers": {
+    "datasinking": {
+      "type": "http",
+      "url": "https://api.datasink.ing/mcp?apikey=YOUR_KEY"
+    }
+  }
+}
+```
+
+Claude Code, in one line:
+
+```bash
+claude mcp add --transport http datasinking https://api.datasink.ing/mcp \
+  --header "Authorization: Bearer YOUR_KEY"
+```
+
+Your key rides inside the URL, so treat that config as a secret. Clients that support custom
+headers can send `Authorization: Bearer YOUR_KEY` instead — Claude Code redacts headers in its
+output but can't redact a URL.
+
+### Local — run it yourself
+
+If you'd rather keep everything on your own machine, there are two identical builds — pick
+whichever runtime you already have:
+
+**Node 18+ (no Python needed):**
+
+```json
+{
+  "mcpServers": {
+    "datasinking": {
+      "command": "npx",
+      "args": ["-y", "datasinking-mcp"],
+      "env": { "DATASINK_API_KEY": "YOUR_KEY" }
+    }
+  }
+}
+```
+
+**Python 3.8+:**
+
 ```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).
+Then use `command: datasinking-mcp` in your client.
+
+Both run the same six tools with the same schemas — `npm/` and `datasinking/mcp_server.py` are
+kept in lockstep by [`check_mcp_parity.py`](check_mcp_parity.py).
+
+Full per-client setup: [`mcp-server.md`](mcp-server.md).
 
 ![DataSinking MCP in Claude](docs/images/mcp-demo.png)
 
@@ -64,6 +115,7 @@ datasinking/
 ├── examples/     # Example scripts: pull data from the API and analyze it
 ├── research/     # Research notes / blog posts (reproducing paper-style presentation)
 ├── datasinking/  # Python client + MCP server — pip install "datasinking[mcp]"
+├── npm/          # The same MCP server on npm — npx -y datasinking-mcp (Node 18+)
 ├── 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)

{datasinking-0.2.8 → datasinking-0.2.10}/README.md

@@ -8,27 +8,78 @@
 **Full-text financial reports across Asia, as clean Markdown.**
 
 [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.
+and quarterly — from **China, Korea, Japan and Taiwan** as clean **Markdown**, ready for LLM reading
+and RAG. Query by FMP-style symbol (`600519.SS`, `005930.KS`, `7203.T`, `2330.TW`) 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.
 
 ---
 
 ## MCP server
 
-Ship DataSinking to any AI agent (Claude Desktop / Cursor / Codex / Windsurf) as an
+Ship DataSinking to any AI agent (Claude / 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).
 
+### Hosted — nothing to install
+
+Point any MCP client at our endpoint and you're done. No package, no Python, no local server:
+
+```json
+{
+  "mcpServers": {
+    "datasinking": {
+      "type": "http",
+      "url": "https://api.datasink.ing/mcp?apikey=YOUR_KEY"
+    }
+  }
+}
+```
+
+Claude Code, in one line:
+
+```bash
+claude mcp add --transport http datasinking https://api.datasink.ing/mcp \
+  --header "Authorization: Bearer YOUR_KEY"
+```
+
+Your key rides inside the URL, so treat that config as a secret. Clients that support custom
+headers can send `Authorization: Bearer YOUR_KEY` instead — Claude Code redacts headers in its
+output but can't redact a URL.
+
+### Local — run it yourself
+
+If you'd rather keep everything on your own machine, there are two identical builds — pick
+whichever runtime you already have:
+
+**Node 18+ (no Python needed):**
+
+```json
+{
+  "mcpServers": {
+    "datasinking": {
+      "command": "npx",
+      "args": ["-y", "datasinking-mcp"],
+      "env": { "DATASINK_API_KEY": "YOUR_KEY" }
+    }
+  }
+}
+```
+
+**Python 3.8+:**
+
 ```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).
+Then use `command: datasinking-mcp` in your client.
+
+Both run the same six tools with the same schemas — `npm/` and `datasinking/mcp_server.py` are
+kept in lockstep by [`check_mcp_parity.py`](check_mcp_parity.py).
+
+Full per-client setup: [`mcp-server.md`](mcp-server.md).
 
 ![DataSinking MCP in Claude](docs/images/mcp-demo.png)
 
@@ -41,6 +92,7 @@ datasinking/
 ├── examples/     # Example scripts: pull data from the API and analyze it
 ├── research/     # Research notes / blog posts (reproducing paper-style presentation)
 ├── datasinking/  # Python client + MCP server — pip install "datasinking[mcp]"
+├── npm/          # The same MCP server on npm — npx -y datasinking-mcp (Node 18+)
 ├── 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)

{datasinking-0.2.8 → datasinking-0.2.10}/datasinking/_version.py

@@ -8,4 +8,4 @@ pyproject.toml 用 `dynamic = ["version"]` 从这里读，`client.py` 的 User-A
 写着旧版本）。现在只有这一处需要改。
 """
 
-__version__ = "0.2.8"
+__version__ = "0.2.10"

{datasinking-0.2.8 → datasinking-0.2.10}/datasinking/mcp_server.py

@@ -2,7 +2,7 @@
 """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,
+(China, Korea, Japan, Taiwan) as clean Markdown — to AI agents (Claude, Cursor,
 Codex, DeepSeek, Windsurf, …).
 
 Install the MCP extra::
@@ -70,7 +70,7 @@ def _get(path: str, params: Optional[dict] = None) -> dict:
 
 @mcp.tool()
 def list_exchanges() -> list:
-    """List the exchanges DataSinking covers and their report counts.
+    """List the exchanges DataSinking covers.
 
     Returns exchange codes (sse / szse / bj / ksc / koe / knx / jpx / twse / tpex) with
     the number of reports available per exchange. Call this first to discover coverage.
@@ -82,13 +82,13 @@ def list_exchanges() -> list:
 @mcp.tool()
 def list_stocks(
     exchange: Annotated[
-        str, Field(description="Exchange code: sse / szse / bj / ksc / koe / knx / jpx / twse / tpex")
+        str, Field(description="Exchange code, e.g. sse / szse / bj / ksc / koe / knx / jpx / twse / tpex")
     ],
     limit: Annotated[
         int, Field(description="Return only the first N companies (default 20) to keep the response short.")
     ] = 20,
 ) -> dict:
-    """List stocks on an exchange, including the report count per company."""
+    """List the stocks on one exchange, including the report count per company."""
     data = _get("/stocks", {"exchange": exchange})
     return {"exchange": exchange, "total": data.get("total", 0), "items": data.get("items", [])[:limit]}
 
@@ -99,13 +99,13 @@ def list_reports(
         str, Field(description="FMP-style symbol, e.g. 600519.SS / 005930.KS / 7203.T / 2330.TW")
     ],
     doc_type: Annotated[
-        str, Field(description="annual / semiannual / q1 / q3")
+        str, Field(description="Report type to filter on. Defaults to annual.")
     ] = "annual",
     size: Annotated[int, Field(description="Number of reports to return (default 10).")] = 10,
 ) -> dict:
     """List a company's reports — metadata only (id, title, period), no body text.
 
-    Each item carries a ``source`` field naming the official disclosure platform;
+    Each item carries a `source` field naming the official disclosure platform;
     keep that attribution when you cite it.
     """
     return _get("/documents", {"symbol": symbol, "doc_type": doc_type, "size": size})
@@ -115,9 +115,9 @@ def list_reports(
 def get_report(
     document_id: Annotated[int, Field(description="Report id, from list_reports items[].id")],
 ) -> dict:
-    """Fetch a single report's full text (metadata + Markdown body).
+    """Fetch one report's full text (metadata + Markdown body).
 
-    The ``source`` field names the official disclosure platform; keep that attribution
+    The `source` field names the official disclosure platform; keep that attribution
     when you cite it. Expensive in tokens — prefer get_section when you only need one chapter.
     """
     return _get(f"/documents/{document_id}")
@@ -127,10 +127,15 @@ def get_report(
 def list_sections(
     document_id: Annotated[int, Field(description="Report id, from list_reports items[].id")],
 ) -> dict:
-    """List every section heading in a report (feed the headings to get_section).
+    """List every section of a report with its size, before you decide what to pull.
 
-    Call this before get_section to see the exact headings — the headings are in the
-    report's own language.
+    Returns `sections` (titles, in order) plus `section_details` — same order, one entry
+    per section with `title`, `has_tables`, `chars` and `estimated_tokens`.
+
+    Use `estimated_tokens` to avoid pulling a chapter that would blow your context,
+    and `has_tables` to know whether the chapter needs special handling (tables are the
+    part RAG pipelines usually get wrong). Then call get_section with a heading keyword —
+    the headings are in the report's own language.
     """
     return _get(f"/documents/{document_id}/sections")
 
@@ -152,7 +157,7 @@ def get_section(
         ),
     ],
 ) -> dict:
-    """Fetch only one section of a report by keyword — cheaper than get_report for RAG."""
+    """Fetch only one section of a report by keyword — much cheaper than get_report, best for RAG."""
     return _get(f"/documents/{document_id}", {"section": section})
 
 

{datasinking-0.2.8 → datasinking-0.2.10}/datasinking.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datasinking
-Version: 0.2.8
+Version: 0.2.10
 Summary: Python client for DataSinking — full-text Asian financial reports (China, Korea, Japan, Taiwan) as Markdown.
 Author: DataSinking
 License: MIT
@@ -31,27 +31,78 @@ Dynamic: license-file
 **Full-text financial reports across Asia, as clean Markdown.**
 
 [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.
+and quarterly — from **China, Korea, Japan and Taiwan** as clean **Markdown**, ready for LLM reading
+and RAG. Query by FMP-style symbol (`600519.SS`, `005930.KS`, `7203.T`, `2330.TW`) 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.
 
 ---
 
 ## MCP server
 
-Ship DataSinking to any AI agent (Claude Desktop / Cursor / Codex / Windsurf) as an
+Ship DataSinking to any AI agent (Claude / 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).
 
+### Hosted — nothing to install
+
+Point any MCP client at our endpoint and you're done. No package, no Python, no local server:
+
+```json
+{
+  "mcpServers": {
+    "datasinking": {
+      "type": "http",
+      "url": "https://api.datasink.ing/mcp?apikey=YOUR_KEY"
+    }
+  }
+}
+```
+
+Claude Code, in one line:
+
+```bash
+claude mcp add --transport http datasinking https://api.datasink.ing/mcp \
+  --header "Authorization: Bearer YOUR_KEY"
+```
+
+Your key rides inside the URL, so treat that config as a secret. Clients that support custom
+headers can send `Authorization: Bearer YOUR_KEY` instead — Claude Code redacts headers in its
+output but can't redact a URL.
+
+### Local — run it yourself
+
+If you'd rather keep everything on your own machine, there are two identical builds — pick
+whichever runtime you already have:
+
+**Node 18+ (no Python needed):**
+
+```json
+{
+  "mcpServers": {
+    "datasinking": {
+      "command": "npx",
+      "args": ["-y", "datasinking-mcp"],
+      "env": { "DATASINK_API_KEY": "YOUR_KEY" }
+    }
+  }
+}
+```
+
+**Python 3.8+:**
+
 ```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).
+Then use `command: datasinking-mcp` in your client.
+
+Both run the same six tools with the same schemas — `npm/` and `datasinking/mcp_server.py` are
+kept in lockstep by [`check_mcp_parity.py`](check_mcp_parity.py).
+
+Full per-client setup: [`mcp-server.md`](mcp-server.md).
 
 ![DataSinking MCP in Claude](docs/images/mcp-demo.png)
 
@@ -64,6 +115,7 @@ datasinking/
 ├── examples/     # Example scripts: pull data from the API and analyze it
 ├── research/     # Research notes / blog posts (reproducing paper-style presentation)
 ├── datasinking/  # Python client + MCP server — pip install "datasinking[mcp]"
+├── npm/          # The same MCP server on npm — npx -y datasinking-mcp (Node 18+)
 ├── 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)