datasinking 0.2.9__tar.gz → 0.2.11__tar.gz

{datasinking-0.2.9 → datasinking-0.2.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datasinking
-Version: 0.2.9
+Version: 0.2.11
 Summary: Python client for DataSinking — full-text Asian financial reports (China, Korea, Japan, Taiwan) as Markdown.
 Author: DataSinking
 License: MIT
@@ -73,7 +73,24 @@ output but can't redact a URL.
 
 ### Local — run it yourself
 
-If you'd rather keep everything on your own machine:
+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]"
@@ -82,7 +99,13 @@ datasinking-mcp          # requires DATASINK_API_KEY (free at https://datasink.i
 
 Then use `command: datasinking-mcp` in your client.
 
-Full per-client setup: [`mcp-server.md`](mcp-server.md).
+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) (overview) ·
+[`docs/mcp/`](docs/mcp/) (one guide per client).
+Hosted endpoint is **POST-only and stateless** — `GET /mcp` returns 405, no session id, and every
+client needs a restart after a config change. That trips up most first connections.
 
 ![DataSinking MCP in Claude](docs/images/mcp-demo.png)
 
@@ -95,12 +118,27 @@ 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]"
-├── mcp-server.md # How to configure the MCP server (for AI agents: Claude / Cursor / Codex / DeepSeek)
+├── npm/          # The same MCP server on npm — npx -y datasinking-mcp (Node 18+)
+├── docs/mcp/     # Per-client MCP setup: Claude Code, Claude Desktop, Cursor, Codex, WorkBuddy
+├── mcp-server.md # MCP server overview — the two config shapes, tools, endpoint limits
 ├── 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
 ```
 
+Per-client MCP guides — one file each, with the exact config path, both scopes, verification and the
+errors that client actually produces:
+
+| Client | Guide |
+|---|---|
+| Claude Code | [`docs/mcp/claude-code.md`](docs/mcp/claude-code.md) |
+| Claude Desktop | [`docs/mcp/claude-desktop.md`](docs/mcp/claude-desktop.md) |
+| OpenAI Codex CLI | [`docs/mcp/codex.md`](docs/mcp/codex.md) |
+| WorkBuddy / CodeBuddy | [`docs/mcp/workbuddy.md`](docs/mcp/workbuddy.md) |
+| Cursor | [`docs/mcp/cursor.md`](docs/mcp/cursor.md) |
+| DeepSeek | [`docs/mcp/deepseek.md`](docs/mcp/deepseek.md) |
+| Windsurf | [`docs/mcp/windsurf.md`](docs/mcp/windsurf.md) |
+
 ## Quick start
 
 1. Get an API key at [datasink.ing](https://datasink.ing)

{datasinking-0.2.9 → datasinking-0.2.11}/README.md

@@ -50,7 +50,24 @@ output but can't redact a URL.
 
 ### Local — run it yourself
 
-If you'd rather keep everything on your own machine:
+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]"
@@ -59,7 +76,13 @@ datasinking-mcp          # requires DATASINK_API_KEY (free at https://datasink.i
 
 Then use `command: datasinking-mcp` in your client.
 
-Full per-client setup: [`mcp-server.md`](mcp-server.md).
+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) (overview) ·
+[`docs/mcp/`](docs/mcp/) (one guide per client).
+Hosted endpoint is **POST-only and stateless** — `GET /mcp` returns 405, no session id, and every
+client needs a restart after a config change. That trips up most first connections.
 
 ![DataSinking MCP in Claude](docs/images/mcp-demo.png)
 
@@ -72,12 +95,27 @@ 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]"
-├── mcp-server.md # How to configure the MCP server (for AI agents: Claude / Cursor / Codex / DeepSeek)
+├── npm/          # The same MCP server on npm — npx -y datasinking-mcp (Node 18+)
+├── docs/mcp/     # Per-client MCP setup: Claude Code, Claude Desktop, Cursor, Codex, WorkBuddy
+├── mcp-server.md # MCP server overview — the two config shapes, tools, endpoint limits
 ├── 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
 ```
 
+Per-client MCP guides — one file each, with the exact config path, both scopes, verification and the
+errors that client actually produces:
+
+| Client | Guide |
+|---|---|
+| Claude Code | [`docs/mcp/claude-code.md`](docs/mcp/claude-code.md) |
+| Claude Desktop | [`docs/mcp/claude-desktop.md`](docs/mcp/claude-desktop.md) |
+| OpenAI Codex CLI | [`docs/mcp/codex.md`](docs/mcp/codex.md) |
+| WorkBuddy / CodeBuddy | [`docs/mcp/workbuddy.md`](docs/mcp/workbuddy.md) |
+| Cursor | [`docs/mcp/cursor.md`](docs/mcp/cursor.md) |
+| DeepSeek | [`docs/mcp/deepseek.md`](docs/mcp/deepseek.md) |
+| Windsurf | [`docs/mcp/windsurf.md`](docs/mcp/windsurf.md) |
+
 ## Quick start
 
 1. Get an API key at [datasink.ing](https://datasink.ing)

{datasinking-0.2.9 → datasinking-0.2.11}/datasinking/_version.py

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

{datasinking-0.2.9 → datasinking-0.2.11}/datasinking/mcp_server.py

@@ -18,6 +18,7 @@ the environment variable ``DATASINK_API_KEY`` (get a free key at
 https://datasink.ing).
 """
 
+import json
 import os
 from typing import Annotated, Optional
 
@@ -56,7 +57,18 @@ mcp = FastMCP(
 
 
 def _get(path: str, params: Optional[dict] = None) -> dict:
-    """Call the DataSinking API, carrying the API key automatically."""
+    """Call the DataSinking API, carrying the API key automatically.
+
+    出错时**把服务端 body 原文带出去**。它写的不是「失败了」，而是「该怎么办」：
+
+      ``detail``     一句人话（「未找到章节「X」」）
+      ``available``  那份报告的**全部真实标题**
+
+    ``get_section`` 的工具描述明确让模型「retry with one of those」，所以这个列表
+    必须跟着异常走。原来这里是一句 ``r.raise_for_status()``，body 整个丢掉 ——
+    模型只看到裸的 ``404 Client Error: Not Found for url: ...``，既不知道错在哪，
+    也没有可重试的标题（2026-09-22 用真 key 实测，三份实现里这份丢得最干净）。
+    """
     if not API_KEY:
         raise RuntimeError(
             "Missing DATASINK_API_KEY environment variable (get a free key at https://datasink.ing)"
@@ -64,13 +76,24 @@ def _get(path: str, params: Optional[dict] = None) -> dict:
     p = dict(params or {})
     p["apikey"] = API_KEY
     r = requests.get(f"{BASE_URL}{path}", params=p, timeout=90)
-    r.raise_for_status()
+    if not r.ok:
+        try:
+            body = r.json()
+        except ValueError:
+            body = None
+        if not isinstance(body, dict):
+            body = {}
+        msg = f"HTTP {r.status_code}: {body.get('detail') or r.text[:2000]}"
+        available = body.get("available")
+        if isinstance(available, list):
+            msg += "\nAvailable sections: " + json.dumps(available, ensure_ascii=False)
+        raise RuntimeError(msg)
     return r.json()
 
 
 @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 +105,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 +122,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 +138,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,13 +150,13 @@ def get_report(
 def list_sections(
     document_id: Annotated[int, Field(description="Report id, from list_reports items[].id")],
 ) -> dict:
-    """List every section of a report with its size — call this before pulling anything.
+    """List every section of a report with its size, before you decide what to pull.
 
-    Returns ``sections`` (titles, in order) plus ``section_details``: the same list as
-    objects with ``title``, ``has_tables``, ``chars`` and ``estimated_tokens``.
+    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 a chapter needs special handling (tables are the
+    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.
     """
@@ -157,7 +180,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.9 → datasinking-0.2.11}/datasinking.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datasinking
-Version: 0.2.9
+Version: 0.2.11
 Summary: Python client for DataSinking — full-text Asian financial reports (China, Korea, Japan, Taiwan) as Markdown.
 Author: DataSinking
 License: MIT
@@ -73,7 +73,24 @@ output but can't redact a URL.
 
 ### Local — run it yourself
 
-If you'd rather keep everything on your own machine:
+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]"
@@ -82,7 +99,13 @@ datasinking-mcp          # requires DATASINK_API_KEY (free at https://datasink.i
 
 Then use `command: datasinking-mcp` in your client.
 
-Full per-client setup: [`mcp-server.md`](mcp-server.md).
+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) (overview) ·
+[`docs/mcp/`](docs/mcp/) (one guide per client).
+Hosted endpoint is **POST-only and stateless** — `GET /mcp` returns 405, no session id, and every
+client needs a restart after a config change. That trips up most first connections.
 
 ![DataSinking MCP in Claude](docs/images/mcp-demo.png)
 
@@ -95,12 +118,27 @@ 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]"
-├── mcp-server.md # How to configure the MCP server (for AI agents: Claude / Cursor / Codex / DeepSeek)
+├── npm/          # The same MCP server on npm — npx -y datasinking-mcp (Node 18+)
+├── docs/mcp/     # Per-client MCP setup: Claude Code, Claude Desktop, Cursor, Codex, WorkBuddy
+├── mcp-server.md # MCP server overview — the two config shapes, tools, endpoint limits
 ├── 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
 ```
 
+Per-client MCP guides — one file each, with the exact config path, both scopes, verification and the
+errors that client actually produces:
+
+| Client | Guide |
+|---|---|
+| Claude Code | [`docs/mcp/claude-code.md`](docs/mcp/claude-code.md) |
+| Claude Desktop | [`docs/mcp/claude-desktop.md`](docs/mcp/claude-desktop.md) |
+| OpenAI Codex CLI | [`docs/mcp/codex.md`](docs/mcp/codex.md) |
+| WorkBuddy / CodeBuddy | [`docs/mcp/workbuddy.md`](docs/mcp/workbuddy.md) |
+| Cursor | [`docs/mcp/cursor.md`](docs/mcp/cursor.md) |
+| DeepSeek | [`docs/mcp/deepseek.md`](docs/mcp/deepseek.md) |
+| Windsurf | [`docs/mcp/windsurf.md`](docs/mcp/windsurf.md) |
+
 ## Quick start
 
 1. Get an API key at [datasink.ing](https://datasink.ing)