datasinking 0.2.10__tar.gz → 0.2.12__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.2.10 → datasinking-0.2.12}/PKG-INFO +20 -3
  2. {datasinking-0.2.10 → datasinking-0.2.12}/README.md +19 -2
  3. {datasinking-0.2.10 → datasinking-0.2.12}/datasinking/_version.py +11 -11
  4. {datasinking-0.2.10 → datasinking-0.2.12}/datasinking/mcp_server.py +46 -3
  5. {datasinking-0.2.10 → datasinking-0.2.12}/datasinking.egg-info/PKG-INFO +20 -3
  6. {datasinking-0.2.10 → datasinking-0.2.12}/LICENSE +0 -0
  7. {datasinking-0.2.10 → datasinking-0.2.12}/datasinking/__init__.py +0 -0
  8. {datasinking-0.2.10 → datasinking-0.2.12}/datasinking/client.py +0 -0
  9. {datasinking-0.2.10 → datasinking-0.2.12}/datasinking.egg-info/SOURCES.txt +0 -0
  10. {datasinking-0.2.10 → datasinking-0.2.12}/datasinking.egg-info/dependency_links.txt +0 -0
  11. {datasinking-0.2.10 → datasinking-0.2.12}/datasinking.egg-info/entry_points.txt +0 -0
  12. {datasinking-0.2.10 → datasinking-0.2.12}/datasinking.egg-info/requires.txt +0 -0
  13. {datasinking-0.2.10 → datasinking-0.2.12}/datasinking.egg-info/top_level.txt +0 -0
  14. {datasinking-0.2.10 → datasinking-0.2.12}/pyproject.toml +0 -0
  15. {datasinking-0.2.10 → datasinking-0.2.12}/setup.cfg +0 -0
{datasinking-0.2.10 → datasinking-0.2.12}/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: datasinking
3
- Version: 0.2.10
3
+ Version: 0.2.12
4
4
  Summary: Python client for DataSinking — full-text Asian financial reports (China, Korea, Japan, Taiwan) as Markdown.
5
5
  Author: DataSinking
6
6
  License: MIT
@@ -102,7 +102,10 @@ Then use `command: datasinking-mcp` in your client.
102
102
  Both run the same six tools with the same schemas — `npm/` and `datasinking/mcp_server.py` are
103
103
  kept in lockstep by [`check_mcp_parity.py`](check_mcp_parity.py).
104
104
 
105
- Full per-client setup: [`mcp-server.md`](mcp-server.md).
105
+ Full per-client setup: [`mcp-server.md`](mcp-server.md) (overview) ·
106
+ [`docs/mcp/`](docs/mcp/) (one guide per client).
107
+ Hosted endpoint is **POST-only and stateless** — `GET /mcp` returns 405, no session id, and every
108
+ client needs a restart after a config change. That trips up most first connections.
106
109
 
107
110
  ![DataSinking MCP in Claude](docs/images/mcp-demo.png)
108
111
 
@@ -116,12 +119,26 @@ datasinking/
116
119
  ├── research/ # Research notes / blog posts (reproducing paper-style presentation)
117
120
  ├── datasinking/ # Python client + MCP server — pip install "datasinking[mcp]"
118
121
  ├── npm/ # The same MCP server on npm — npx -y datasinking-mcp (Node 18+)
119
- ├── mcp-server.md # How to configure the MCP server (for AI agents: Claude / Cursor / Codex / DeepSeek)
122
+ ├── docs/mcp/ # Per-client MCP setup: Claude Code, Claude Desktop, Cursor, Codex, WorkBuddy
123
+ ├── mcp-server.md # MCP server overview — the two config shapes, tools, endpoint limits
120
124
  ├── llm-examples.md # Ask an LLM — no code needed (8 end-to-end examples)
121
125
  ├── api-examples.md # 7 examples × 3 interfaces (curl / Python / LLM)
122
126
  └── README.md
123
127
  ```
124
128
 
129
+ Per-client MCP guides — one file each, with the exact config path, both scopes, verification and the
130
+ errors that client actually produces:
131
+
132
+ | Client | Guide |
133
+ |---|---|
134
+ | Claude Code | [`docs/mcp/claude-code.md`](docs/mcp/claude-code.md) |
135
+ | Claude Desktop | [`docs/mcp/claude-desktop.md`](docs/mcp/claude-desktop.md) |
136
+ | OpenAI Codex CLI | [`docs/mcp/codex.md`](docs/mcp/codex.md) |
137
+ | WorkBuddy / CodeBuddy | [`docs/mcp/workbuddy.md`](docs/mcp/workbuddy.md) |
138
+ | Cursor | [`docs/mcp/cursor.md`](docs/mcp/cursor.md) |
139
+ | DeepSeek | [`docs/mcp/deepseek.md`](docs/mcp/deepseek.md) |
140
+ | Windsurf | [`docs/mcp/windsurf.md`](docs/mcp/windsurf.md) |
141
+
125
142
  ## Quick start
126
143
 
127
144
  1. Get an API key at [datasink.ing](https://datasink.ing)
{datasinking-0.2.10 → datasinking-0.2.12}/README.md RENAMED
@@ -79,7 +79,10 @@ Then use `command: datasinking-mcp` in your client.
79
79
  Both run the same six tools with the same schemas — `npm/` and `datasinking/mcp_server.py` are
80
80
  kept in lockstep by [`check_mcp_parity.py`](check_mcp_parity.py).
81
81
 
82
- Full per-client setup: [`mcp-server.md`](mcp-server.md).
82
+ Full per-client setup: [`mcp-server.md`](mcp-server.md) (overview) ·
83
+ [`docs/mcp/`](docs/mcp/) (one guide per client).
84
+ Hosted endpoint is **POST-only and stateless** — `GET /mcp` returns 405, no session id, and every
85
+ client needs a restart after a config change. That trips up most first connections.
83
86
 
84
87
  ![DataSinking MCP in Claude](docs/images/mcp-demo.png)
85
88
 
@@ -93,12 +96,26 @@ datasinking/
93
96
  ├── research/ # Research notes / blog posts (reproducing paper-style presentation)
94
97
  ├── datasinking/ # Python client + MCP server — pip install "datasinking[mcp]"
95
98
  ├── npm/ # The same MCP server on npm — npx -y datasinking-mcp (Node 18+)
96
- ├── mcp-server.md # How to configure the MCP server (for AI agents: Claude / Cursor / Codex / DeepSeek)
99
+ ├── docs/mcp/ # Per-client MCP setup: Claude Code, Claude Desktop, Cursor, Codex, WorkBuddy
100
+ ├── mcp-server.md # MCP server overview — the two config shapes, tools, endpoint limits
97
101
  ├── llm-examples.md # Ask an LLM — no code needed (8 end-to-end examples)
98
102
  ├── api-examples.md # 7 examples × 3 interfaces (curl / Python / LLM)
99
103
  └── README.md
100
104
  ```
101
105
 
106
+ Per-client MCP guides — one file each, with the exact config path, both scopes, verification and the
107
+ errors that client actually produces:
108
+
109
+ | Client | Guide |
110
+ |---|---|
111
+ | Claude Code | [`docs/mcp/claude-code.md`](docs/mcp/claude-code.md) |
112
+ | Claude Desktop | [`docs/mcp/claude-desktop.md`](docs/mcp/claude-desktop.md) |
113
+ | OpenAI Codex CLI | [`docs/mcp/codex.md`](docs/mcp/codex.md) |
114
+ | WorkBuddy / CodeBuddy | [`docs/mcp/workbuddy.md`](docs/mcp/workbuddy.md) |
115
+ | Cursor | [`docs/mcp/cursor.md`](docs/mcp/cursor.md) |
116
+ | DeepSeek | [`docs/mcp/deepseek.md`](docs/mcp/deepseek.md) |
117
+ | Windsurf | [`docs/mcp/windsurf.md`](docs/mcp/windsurf.md) |
118
+
102
119
  ## Quick start
103
120
 
104
121
  1. Get an API key at [datasink.ing](https://datasink.ing)
{datasinking-0.2.10 → datasinking-0.2.12}/datasinking/_version.py RENAMED
@@ -1,11 +1,11 @@
1
- # -*- coding: utf-8 -*-
2
- """版本号的**唯一来源**。
3
-
4
- pyproject.toml 用 `dynamic = ["version"]` 从这里读，`client.py` 的 User-Agent 也读它。
5
-
6
- 为什么单独抽一个文件：之前 pyproject.toml 和 `__init__.py` 各写各的版本号，
7
- 结果 `__version__` 长期停在 0.1.0 没跟上（发 0.2.4 时才发现，User-Agent 里也一直
8
- 写着旧版本）。现在只有这一处需要改。
9
- """
10
-
11
- __version__ = "0.2.10"
1
+ # -*- coding: utf-8 -*-
2
+ """版本号的**唯一来源**。
3
+
4
+ pyproject.toml 用 `dynamic = ["version"]` 从这里读，`client.py` 的 User-Agent 也读它。
5
+
6
+ 为什么单独抽一个文件：之前 pyproject.toml 和 `__init__.py` 各写各的版本号，
7
+ 结果 `__version__` 长期停在 0.1.0 没跟上（发 0.2.4 时才发现，User-Agent 里也一直
8
+ 写着旧版本）。现在只有这一处需要改。
9
+ """
10
+
11
+ __version__ = "0.2.12"
{datasinking-0.2.10 → datasinking-0.2.12}/datasinking/mcp_server.py RENAMED
@@ -18,6 +18,7 @@ the environment variable ``DATASINK_API_KEY`` (get a free key at
18
18
  https://datasink.ing).
19
19
  """
20
20
 
21
+ import json
21
22
  import os
22
23
  from typing import Annotated, Optional
23
24
 
@@ -32,6 +33,25 @@ try:
32
33
  except ImportError: # pragma: no cover
33
34
  from mcp.server.mcpserver import MCPServer as FastMCP # mcp v2
34
35
 
36
+ # ⚠️ **工具里必须抛 ToolError，不能抛 RuntimeError。**
37
+ #
38
+ # mcp v2（实测 2.2.0）对两者的处理完全不同：
39
+ # 抛 RuntimeError → 客户端收到 isError:true，但文本是**通用句**
40
+ # 「Error executing tool <名字>」，**消息内容被剥掉**，只进 stderr
41
+ # 抛 ToolError → 客户端收到 isError:true，文本带上你的原话
42
+ # 「Error executing tool <名字>: <你的消息>」
43
+ #
44
+ # 这不是细节：get_section 的描述让模型「用真实标题重试」，标题列表就在消息里；
45
+ # 缺 API key 的提示也只在这里。用 RuntimeError 的话，模型看到的是一个**没有任何线索**的
46
+ # 失败 —— 2026-09-22 用真 key 走 uvx 发布版实测确认（`Error executing tool get_section`，32 字符）。
47
+ try:
48
+ from mcp.server.fastmcp.exceptions import ToolError # mcp v1
49
+ except ImportError: # pragma: no cover
50
+ try:
51
+ from mcp.server.mcpserver.exceptions import ToolError # mcp v2
52
+ except ImportError: # 极老的 mcp 没有这个类：退回普通异常（消息会丢，但不至于起不来）
53
+ ToolError = RuntimeError # type: ignore[assignment,misc]
54
+
35
55
  # ⚠️ 参数描述必须写成 `Annotated[T, Field(description=...)]`，**不能只靠 docstring 的 Args 段**。
36
56
  # mcp v2（MCPServer）不再解析 docstring 的 Args —— 实测把整段 Args 当散文塞进工具描述，
37
57
  # 参数级 description 全是空的（2026-09-22 用真实 stdio 握手验证）。v1 两种都认，所以这样写两边通用。
@@ -56,15 +76,38 @@ mcp = FastMCP(
56
76
 
57
77
 
58
78
  def _get(path: str, params: Optional[dict] = None) -> dict:
59
- """Call the DataSinking API, carrying the API key automatically."""
79
+ """Call the DataSinking API, carrying the API key automatically.
80
+
81
+ 出错时**把服务端 body 原文带出去**。它写的不是「失败了」，而是「该怎么办」：
82
+
83
+ ``detail`` 一句人话（「未找到章节「X」」）
84
+ ``available`` 那份报告的**全部真实标题**
85
+
86
+ ``get_section`` 的工具描述明确让模型「retry with one of those」，所以这个列表
87
+ 必须跟着异常走。原来这里是一句 ``r.raise_for_status()``，body 整个丢掉 ——
88
+ 模型只看到裸的 ``404 Client Error: Not Found for url: ...``，既不知道错在哪，
89
+ 也没有可重试的标题（2026-09-22 用真 key 实测，三份实现里这份丢得最干净）。
90
+ """
60
91
  if not API_KEY:
61
- raise RuntimeError(
92
+ raise ToolError(
62
93
  "Missing DATASINK_API_KEY environment variable (get a free key at https://datasink.ing)"
63
94
  )
64
95
  p = dict(params or {})
65
96
  p["apikey"] = API_KEY
66
97
  r = requests.get(f"{BASE_URL}{path}", params=p, timeout=90)
67
- r.raise_for_status()
98
+ if not r.ok:
99
+ try:
100
+ body = r.json()
101
+ except ValueError:
102
+ body = None
103
+ if not isinstance(body, dict):
104
+ body = {}
105
+ msg = f"HTTP {r.status_code}: {body.get('detail') or r.text[:2000]}"
106
+ available = body.get("available")
107
+ if isinstance(available, list):
108
+ msg += "\nAvailable sections: " + json.dumps(available, ensure_ascii=False)
109
+ # ToolError 而非 RuntimeError —— 否则 mcp v2 把 msg 剥成通用句，见文件顶部注释
110
+ raise ToolError(msg)
68
111
  return r.json()
69
112
 
70
113
 
{datasinking-0.2.10 → datasinking-0.2.12}/datasinking.egg-info/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: datasinking
3
- Version: 0.2.10
3
+ Version: 0.2.12
4
4
  Summary: Python client for DataSinking — full-text Asian financial reports (China, Korea, Japan, Taiwan) as Markdown.
5
5
  Author: DataSinking
6
6
  License: MIT
@@ -102,7 +102,10 @@ Then use `command: datasinking-mcp` in your client.
102
102
  Both run the same six tools with the same schemas — `npm/` and `datasinking/mcp_server.py` are
103
103
  kept in lockstep by [`check_mcp_parity.py`](check_mcp_parity.py).
104
104
 
105
- Full per-client setup: [`mcp-server.md`](mcp-server.md).
105
+ Full per-client setup: [`mcp-server.md`](mcp-server.md) (overview) ·
106
+ [`docs/mcp/`](docs/mcp/) (one guide per client).
107
+ Hosted endpoint is **POST-only and stateless** — `GET /mcp` returns 405, no session id, and every
108
+ client needs a restart after a config change. That trips up most first connections.
106
109
 
107
110
  ![DataSinking MCP in Claude](docs/images/mcp-demo.png)
108
111
 
@@ -116,12 +119,26 @@ datasinking/
116
119
  ├── research/ # Research notes / blog posts (reproducing paper-style presentation)
117
120
  ├── datasinking/ # Python client + MCP server — pip install "datasinking[mcp]"
118
121
  ├── npm/ # The same MCP server on npm — npx -y datasinking-mcp (Node 18+)
119
- ├── mcp-server.md # How to configure the MCP server (for AI agents: Claude / Cursor / Codex / DeepSeek)
122
+ ├── docs/mcp/ # Per-client MCP setup: Claude Code, Claude Desktop, Cursor, Codex, WorkBuddy
123
+ ├── mcp-server.md # MCP server overview — the two config shapes, tools, endpoint limits
120
124
  ├── llm-examples.md # Ask an LLM — no code needed (8 end-to-end examples)
121
125
  ├── api-examples.md # 7 examples × 3 interfaces (curl / Python / LLM)
122
126
  └── README.md
123
127
  ```
124
128
 
129
+ Per-client MCP guides — one file each, with the exact config path, both scopes, verification and the
130
+ errors that client actually produces:
131
+
132
+ | Client | Guide |
133
+ |---|---|
134
+ | Claude Code | [`docs/mcp/claude-code.md`](docs/mcp/claude-code.md) |
135
+ | Claude Desktop | [`docs/mcp/claude-desktop.md`](docs/mcp/claude-desktop.md) |
136
+ | OpenAI Codex CLI | [`docs/mcp/codex.md`](docs/mcp/codex.md) |
137
+ | WorkBuddy / CodeBuddy | [`docs/mcp/workbuddy.md`](docs/mcp/workbuddy.md) |
138
+ | Cursor | [`docs/mcp/cursor.md`](docs/mcp/cursor.md) |
139
+ | DeepSeek | [`docs/mcp/deepseek.md`](docs/mcp/deepseek.md) |
140
+ | Windsurf | [`docs/mcp/windsurf.md`](docs/mcp/windsurf.md) |
141
+
125
142
  ## Quick start
126
143
 
127
144
  1. Get an API key at [datasink.ing](https://datasink.ing)
{datasinking-0.2.10 → datasinking-0.2.12}/LICENSE RENAMED
File without changes
{datasinking-0.2.10 → datasinking-0.2.12}/setup.cfg RENAMED
File without changes