xtree-mcp 0.1.0__py3-none-any.whl

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.
xtree_mcp/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """XTREE MCP server."""
2
+
3
+ __version__ = "0.1.0"
xtree_mcp/api.py ADDED
@@ -0,0 +1,229 @@
1
+ """XTREE API calls used by MCP tools."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+ from xtree.client import XTreeClient
8
+
9
+ from xtree_mcp.format import as_tool_json
10
+
11
+ _client: XTreeClient | None = None
12
+
13
+
14
+ def get_client() -> XTreeClient:
15
+ global _client
16
+ if _client is None:
17
+ _client = XTreeClient()
18
+ return _client
19
+
20
+
21
+ def reset_client(client: XTreeClient | None = None) -> None:
22
+ global _client
23
+ if _client is not None:
24
+ _client.close()
25
+ _client = client
26
+
27
+
28
+ def _search_body(
29
+ *,
30
+ keyword: str,
31
+ page: int = 1,
32
+ session: str | None = None,
33
+ **extra: Any,
34
+ ) -> dict[str, Any]:
35
+ body: dict[str, Any] = {"keyword": keyword, "page": page, **extra}
36
+ if session is not None:
37
+ body["session"] = session
38
+ return body
39
+
40
+
41
+ def account_balance(client: XTreeClient | None = None) -> str:
42
+ c = client or get_client()
43
+ return as_tool_json(c.request("GET", "/account/balance"))
44
+
45
+
46
+ def wechat_search_articles(
47
+ keyword: str,
48
+ page: int = 1,
49
+ session: str | None = None,
50
+ *,
51
+ client: XTreeClient | None = None,
52
+ ) -> str:
53
+ """搜一搜公众号文章。翻页须回传上一轮 data.session。"""
54
+ c = client or get_client()
55
+ body = _search_body(keyword=keyword, page=page, session=session)
56
+ return as_tool_json(c.request("POST", "/wechat/search/articles", json=body))
57
+
58
+
59
+ def wechat_search_videos(
60
+ keyword: str,
61
+ page: int = 1,
62
+ session: str | None = None,
63
+ *,
64
+ client: XTreeClient | None = None,
65
+ ) -> str:
66
+ c = client or get_client()
67
+ body = _search_body(keyword=keyword, page=page, session=session)
68
+ return as_tool_json(c.request("POST", "/wechat/search/videos", json=body))
69
+
70
+
71
+ def wechat_search_accounts(
72
+ keyword: str,
73
+ page: int = 1,
74
+ session: str | None = None,
75
+ *,
76
+ client: XTreeClient | None = None,
77
+ ) -> str:
78
+ c = client or get_client()
79
+ body = _search_body(keyword=keyword, page=page, session=session)
80
+ return as_tool_json(c.request("POST", "/wechat/search/accounts", json=body))
81
+
82
+
83
+ def wechat_channels_search(
84
+ keyword: str,
85
+ page: int = 1,
86
+ session: str | None = None,
87
+ *,
88
+ client: XTreeClient | None = None,
89
+ ) -> str:
90
+ c = client or get_client()
91
+ body = _search_body(keyword=keyword, page=page, session=session)
92
+ return as_tool_json(c.request("POST", "/wechat/channels/search", json=body))
93
+
94
+
95
+ def wechat_channels_feeds(
96
+ channel_id: str,
97
+ page: int = 1,
98
+ session: str | None = None,
99
+ *,
100
+ client: XTreeClient | None = None,
101
+ ) -> str:
102
+ """视频号作品列表。翻页须回传上一轮 data.session。"""
103
+ c = client or get_client()
104
+ body: dict[str, Any] = {"page": page, "channel_id": channel_id}
105
+ if session is not None:
106
+ body["session"] = session
107
+ return as_tool_json(c.request("POST", "/wechat/channels/feeds/list", json=body))
108
+
109
+
110
+ def wechat_articles_metrics(
111
+ url: str,
112
+ *,
113
+ client: XTreeClient | None = None,
114
+ ) -> str:
115
+ """获取公众号文章阅读、拇指赞、在看等指标。"""
116
+ c = client or get_client()
117
+ return as_tool_json(c.request("POST", "/wechat/articles/metrics", json={"url": url}))
118
+
119
+
120
+ def wechat_articles_metrics_pro(
121
+ url: str,
122
+ *,
123
+ client: XTreeClient | None = None,
124
+ ) -> str:
125
+ """获取公众号文章扩展互动指标(含分享、收藏、评论数等)。"""
126
+ c = client or get_client()
127
+ return as_tool_json(c.request("POST", "/wechat/articles/metrics/pro", json={"url": url}))
128
+
129
+
130
+ def wechat_accounts_posts(
131
+ account_id: str,
132
+ page: int = 1,
133
+ cursor: str | None = None,
134
+ *,
135
+ client: XTreeClient | None = None,
136
+ ) -> str:
137
+ """公众号历史发文列表。翻页须回传上一轮 data.next_cursor。"""
138
+ c = client or get_client()
139
+ body: dict[str, Any] = {"page": page, "account_id": account_id}
140
+ if cursor is not None:
141
+ body["cursor"] = cursor
142
+ return as_tool_json(c.request("POST", "/wechat/accounts/posts/list", json=body))
143
+
144
+
145
+ def wechat_accounts_search_by_owner_live(
146
+ owner_name: str,
147
+ page: int = 1,
148
+ *,
149
+ client: XTreeClient | None = None,
150
+ ) -> str:
151
+ """实时主体名下搜号(legacy web_search_owner_mp)。"""
152
+ c = client or get_client()
153
+ return as_tool_json(
154
+ c.request(
155
+ "POST",
156
+ "/wechat/accounts/search-by-owner/live",
157
+ json={"owner_name": owner_name, "page": page},
158
+ )
159
+ )
160
+
161
+
162
+ def wechat_channels_feeds_convert_id(
163
+ export_id: str | None = None,
164
+ object_id: str | None = None,
165
+ *,
166
+ client: XTreeClient | None = None,
167
+ ) -> str:
168
+ """视频号 export_id 与 object_id 互转。"""
169
+ c = client or get_client()
170
+ body: dict[str, Any] = {}
171
+ if export_id is not None:
172
+ body["export_id"] = export_id
173
+ if object_id is not None:
174
+ body["object_id"] = object_id
175
+ return as_tool_json(c.request("POST", "/wechat/channels/feeds/convert-id", json=body))
176
+
177
+
178
+ def wechat_library_search_articles(
179
+ keyword: str,
180
+ page: int = 1,
181
+ page_size: int = 20,
182
+ *,
183
+ client: XTreeClient | None = None,
184
+ ) -> str:
185
+ """关键词搜索微信文章库(需 ES 灌库)。Phase 2。"""
186
+ c = client or get_client()
187
+ return as_tool_json(
188
+ c.wechat.library.search_articles(keyword, page=page, page_size=page_size)
189
+ )
190
+
191
+
192
+ def wechat_library_search_articles_tokenized(
193
+ keyword: str,
194
+ page: int = 1,
195
+ page_size: int = 20,
196
+ *,
197
+ client: XTreeClient | None = None,
198
+ ) -> str:
199
+ """分词搜索微信文章库(需 ES 灌库)。Phase 2。"""
200
+ c = client or get_client()
201
+ return as_tool_json(
202
+ c.wechat.library.search_articles_tokenized(
203
+ keyword, page=page, page_size=page_size
204
+ )
205
+ )
206
+
207
+
208
+ def wechat_library_search_accounts(
209
+ keyword: str,
210
+ page: int = 1,
211
+ page_size: int = 20,
212
+ *,
213
+ client: XTreeClient | None = None,
214
+ ) -> str:
215
+ """关键字查公众号库(需 ES 灌库)。Phase 2。"""
216
+ c = client or get_client()
217
+ return as_tool_json(
218
+ c.wechat.library.search_accounts(keyword, page=page, page_size=page_size)
219
+ )
220
+
221
+
222
+ def wechat_library_accounts_metrics(
223
+ name: str,
224
+ *,
225
+ client: XTreeClient | None = None,
226
+ ) -> str:
227
+ """获取公众号预估粉丝与指数(需 ES 灌库)。name 为公众号名称。Phase 2。"""
228
+ c = client or get_client()
229
+ return as_tool_json(c.wechat.library.accounts_metrics(name=name))
xtree_mcp/format.py ADDED
@@ -0,0 +1,36 @@
1
+ """Format API responses for MCP tool output."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from typing import Any
7
+
8
+ from xtree.types import APIResponse, ResponseMeta
9
+
10
+
11
+ def meta_dict(meta: ResponseMeta) -> dict[str, Any]:
12
+ out: dict[str, Any] = {
13
+ "request_id": meta.request_id,
14
+ "cost_cny": meta.cost_cny,
15
+ "balance_cny": meta.balance_cny,
16
+ "rate_limit_remaining": meta.rate_limit_remaining,
17
+ }
18
+ for key in (
19
+ "observation_id",
20
+ "observed_at",
21
+ "basis",
22
+ "contract_rev",
23
+ "origin",
24
+ "cache_hit",
25
+ "cache_age_sec",
26
+ ):
27
+ value = getattr(meta, key)
28
+ if value is not None:
29
+ out[key] = value
30
+ return out
31
+
32
+
33
+ def as_tool_json(resp: APIResponse[Any]) -> str:
34
+ """Return business data plus _meta footer for Agent transparency."""
35
+ payload = {"data": resp.data, "_meta": meta_dict(resp.meta)}
36
+ return json.dumps(payload, ensure_ascii=False)
xtree_mcp/registry.py ADDED
@@ -0,0 +1,23 @@
1
+ # -*- coding: utf-8 -*-
2
+ """MCP tool registry - keep in sync with server.py @mcp.tool names."""
3
+
4
+ from __future__ import annotations
5
+
6
+ # (tool_name, slug)
7
+ MCP_TOOLS: list[tuple[str, str]] = [
8
+ ("account_balance", "account.balance"),
9
+ ("wechat_search_articles", "wechat.search.articles"),
10
+ ("wechat_search_videos", "wechat.search.videos"),
11
+ ("wechat_search_accounts", "wechat.search.accounts"),
12
+ ("wechat_channels_search", "wechat.channels.search"),
13
+ ("wechat_channels_feeds", "wechat.channels.feeds"),
14
+ ("wechat_channels_feeds_convert_id", "wechat.channels.feeds.convert-id"),
15
+ ("wechat_articles_metrics", "wechat.articles.metrics"),
16
+ ("wechat_articles_metrics_pro", "wechat.articles.metrics-pro"),
17
+ ("wechat_accounts_posts", "wechat.accounts.posts"),
18
+ ("wechat_accounts_search_by_owner_live", "wechat.accounts.search-by-owner-live"),
19
+ ("wechat_library_search_articles", "wechat.library.articles.search"),
20
+ ("wechat_library_search_articles_tokenized", "wechat.library.articles.tokenized"),
21
+ ("wechat_library_search_accounts", "wechat.library.accounts.search"),
22
+ ("wechat_library_accounts_metrics", "wechat.library.accounts.metrics"),
23
+ ]
xtree_mcp/server.py ADDED
@@ -0,0 +1,131 @@
1
+ """MCP server entry — exposes XTREE API as Agent tools."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from mcp.server.fastmcp import FastMCP
6
+
7
+ from xtree_mcp import api
8
+
9
+ mcp = FastMCP(
10
+ "xtree",
11
+ instructions=(
12
+ "XTREE 极树 — 新媒体数据服务。"
13
+ "调用工具获取账号、粉丝、内容、音视频、评论等实时原始 JSON 数据(微信搜一搜、视频号、文章互动、历史发文等)。"
14
+ "实时接口(搜一搜/视频号/发文)翻页时必须将上一轮响应 data.session 作为 session 参数回传。"
15
+ "库搜索 tools(wechat_library_*)查询 ES 灌库数据,使用 keyword/name 翻页,无 session。"
16
+ "每次响应含 _meta.cost_cny 与 _meta.request_id。"
17
+ ),
18
+ )
19
+
20
+
21
+ @mcp.tool()
22
+ def account_balance() -> str:
23
+ """查询 API 账户余额(免费,不扣费)。"""
24
+ return api.account_balance()
25
+
26
+
27
+ @mcp.tool()
28
+ def wechat_search_articles(keyword: str, page: int = 1, session: str | None = None) -> str:
29
+ """搜一搜:搜索微信公众号文章。翻页时将上一轮 data.session 传入 session。"""
30
+ return api.wechat_search_articles(keyword, page=page, session=session)
31
+
32
+
33
+ @mcp.tool()
34
+ def wechat_search_videos(keyword: str, page: int = 1, session: str | None = None) -> str:
35
+ """搜一搜:搜索视频号视频。翻页时将上一轮 data.session 传入 session。"""
36
+ return api.wechat_search_videos(keyword, page=page, session=session)
37
+
38
+
39
+ @mcp.tool()
40
+ def wechat_search_accounts(keyword: str, page: int = 1, session: str | None = None) -> str:
41
+ """搜一搜:搜索微信公众号账号。翻页时将上一轮 data.session 传入 session。"""
42
+ return api.wechat_search_accounts(keyword, page=page, session=session)
43
+
44
+
45
+ @mcp.tool()
46
+ def wechat_channels_search(keyword: str, page: int = 1, session: str | None = None) -> str:
47
+ """关键词搜索视频号账号。翻页时将上一轮 data.session 传入 session。"""
48
+ return api.wechat_channels_search(keyword, page=page, session=session)
49
+
50
+
51
+ @mcp.tool()
52
+ def wechat_channels_feeds(
53
+ channel_id: str,
54
+ page: int = 1,
55
+ session: str | None = None,
56
+ ) -> str:
57
+ """获取指定视频号的作品列表。channel_id 来自搜索或 resolve 接口。"""
58
+ return api.wechat_channels_feeds(channel_id, page=page, session=session)
59
+
60
+
61
+ @mcp.tool()
62
+ def wechat_articles_metrics(url: str) -> str:
63
+ """获取微信公众号文章的阅读数、点赞数、在看数等指标。url 为文章链接。"""
64
+ return api.wechat_articles_metrics(url)
65
+
66
+
67
+ @mcp.tool()
68
+ def wechat_articles_metrics_pro(url: str) -> str:
69
+ """获取微信公众号文章扩展互动指标(含分享、收藏、评论数等)。url 为文章链接。"""
70
+ return api.wechat_articles_metrics_pro(url)
71
+
72
+
73
+ @mcp.tool()
74
+ def wechat_accounts_posts(
75
+ account_id: str,
76
+ page: int = 1,
77
+ cursor: str | None = None,
78
+ ) -> str:
79
+ """获取公众号历史发文列表。account_id 当前需传 gh_id。翻页回传 data.next_cursor。"""
80
+ return api.wechat_accounts_posts(account_id, page=page, cursor=cursor)
81
+
82
+
83
+ @mcp.tool()
84
+ def wechat_accounts_search_by_owner_live(owner_name: str, page: int = 1) -> str:
85
+ """实时主体名下搜号(legacy web_search_owner_mp)。"""
86
+ return api.wechat_accounts_search_by_owner_live(owner_name, page=page)
87
+
88
+
89
+ @mcp.tool()
90
+ def wechat_channels_feeds_convert_id(
91
+ export_id: str | None = None,
92
+ object_id: str | None = None,
93
+ ) -> str:
94
+ """视频号 export_id 与 object_id 互转。至少提供其一。"""
95
+ return api.wechat_channels_feeds_convert_id(export_id=export_id, object_id=object_id)
96
+
97
+
98
+ @mcp.tool()
99
+ def wechat_library_search_articles(keyword: str, page: int = 1, page_size: int = 20) -> str:
100
+ """关键词搜索微信文章库(ES 灌库 / Phase 2)。使用 page 翻页,无 session。"""
101
+ return api.wechat_library_search_articles(keyword, page=page, page_size=page_size)
102
+
103
+
104
+ @mcp.tool()
105
+ def wechat_library_search_articles_tokenized(
106
+ keyword: str,
107
+ page: int = 1,
108
+ page_size: int = 20,
109
+ ) -> str:
110
+ """分词搜索微信文章库(ES 灌库 / Phase 2)。使用 page 翻页,无 session。"""
111
+ return api.wechat_library_search_articles_tokenized(keyword, page=page, page_size=page_size)
112
+
113
+
114
+ @mcp.tool()
115
+ def wechat_library_search_accounts(keyword: str, page: int = 1, page_size: int = 20) -> str:
116
+ """关键字查公众号库(ES 灌库 / Phase 2)。使用 page 翻页,无 session。"""
117
+ return api.wechat_library_search_accounts(keyword, page=page, page_size=page_size)
118
+
119
+
120
+ @mcp.tool()
121
+ def wechat_library_accounts_metrics(name: str) -> str:
122
+ """获取公众号预估粉丝与指数(ES 灌库 / Phase 2)。name 为公众号名称。"""
123
+ return api.wechat_library_accounts_metrics(name)
124
+
125
+
126
+ def main() -> None:
127
+ mcp.run()
128
+
129
+
130
+ if __name__ == "__main__":
131
+ main()
@@ -0,0 +1,93 @@
1
+ Metadata-Version: 2.5
2
+ Name: xtree-mcp
3
+ Version: 0.1.0
4
+ Summary: MCP server exposing XTREE API tools for AI agents
5
+ Project-URL: Homepage, https://www.xtree.io
6
+ Project-URL: Documentation, https://www.xtree.io/docs
7
+ Project-URL: Repository, https://github.com/xtree-io/xtree-mcp
8
+ Author-email: XTREE <business@xtree.io>
9
+ License: MIT
10
+ Keywords: agent,mcp,wechat,xtree
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Typing :: Typed
15
+ Requires-Python: >=3.10
16
+ Requires-Dist: httpx<1,>=0.27
17
+ Requires-Dist: mcp<2,>=1.2
18
+ Requires-Dist: xtree-sdk>=0.1.0
19
+ Provides-Extra: dev
20
+ Requires-Dist: pytest>=8; extra == 'dev'
21
+ Description-Content-Type: text/markdown
22
+
23
+ # xtree-mcp — XTREE MCP server
24
+
25
+ MCP server for [XTREE](https://www.xtree.io), a real-time social media data API. This repository exposes **WeChat** tools (search, Channels, article metrics, account history, library search) plus account balance for Cursor, Claude Desktop, and any MCP client. Other live platforms are on the REST API and the [Python SDK](https://github.com/xtree-io/xtree-python). **Not** a BI or copywriting product.
26
+
27
+ Tools call `https://api.xtree.io` with your own API Key and wallet (pay per call).
28
+
29
+ ## Install / run
30
+
31
+ Package may not be on PyPI yet. Prefer GitHub:
32
+
33
+ ```bash
34
+ # one-shot via uvx
35
+ uvx --from "git+https://github.com/xtree-io/xtree-mcp.git" xtree-mcp
36
+ ```
37
+
38
+ Or install editable after cloning:
39
+
40
+ ```bash
41
+ git clone https://github.com/xtree-io/xtree-mcp.git
42
+ cd xtree-mcp
43
+ pip install xtree-sdk
44
+ pip install -e .
45
+ ```
46
+
47
+ ## Get an API Key
48
+
49
+ 1. Sign up at [www.xtree.io](https://www.xtree.io/login?tab=signup).
50
+ 2. Set `XTREE_API_KEY=xt_live_...`.
51
+
52
+ ## Cursor / Claude config
53
+
54
+ ```json
55
+ {
56
+ "mcpServers": {
57
+ "xtree": {
58
+ "command": "uvx",
59
+ "args": ["--from", "git+https://github.com/xtree-io/xtree-mcp.git", "xtree-mcp"],
60
+ "env": {
61
+ "XTREE_API_KEY": "xt_live_..."
62
+ }
63
+ }
64
+ }
65
+ }
66
+ ```
67
+
68
+ ## Billing
69
+
70
+ Each tool call is a billed API request from your wallet (CNY). Incomplete delivery is not billed. Unit prices: [API Catalog](https://www.xtree.io/catalog). Scenario playbooks (when to call which tool, pagination): [xtree-skills](https://github.com/xtree-io/xtree-skills).
71
+
72
+ ## Docs
73
+
74
+ - Website docs: https://www.xtree.io/docs
75
+ - OpenAPI: https://api.xtree.io/api/openapi.json
76
+ - Python SDK: https://github.com/xtree-io/xtree-python
77
+ - Skills: https://github.com/xtree-io/xtree-skills
78
+
79
+ ## Environment
80
+
81
+ | Variable | Required | Default |
82
+ |----------|----------|---------|
83
+ | `XTREE_API_KEY` | yes | — |
84
+ | `XTREE_BASE_URL` | no | `https://api.xtree.io/api` |
85
+ | `XTREE_VERIFY_CODE` | no | — |
86
+
87
+ ## Mirror notice
88
+
89
+ **Do not develop in this repository.** Public mirror only. Issues welcome. Contact: [business@xtree.io](mailto:business@xtree.io).
90
+
91
+ ## License
92
+
93
+ MIT.
@@ -0,0 +1,9 @@
1
+ xtree_mcp/__init__.py,sha256=qtiIQrqD0JRpEmqfyXPZML8NdXv3UbGTq44GU4cFazE,47
2
+ xtree_mcp/api.py,sha256=KHE45NxajOVmqmzWeKw1VNt1Ub0j92Ouinou9gfm-MY,6346
3
+ xtree_mcp/format.py,sha256=gISPnBgA2CMeQZjp2y8qspWyahLVvaMzmOBlllRsrqM,961
4
+ xtree_mcp/registry.py,sha256=DGsX7W7osnxXdbv0_Eyunq61M5uVcmP3cs3Xm7bkIHc,1178
5
+ xtree_mcp/server.py,sha256=YWOPDKfxFJF8Ev0PFTVM1jaxRh2Iw3_4p3Pw59q1m9U,4819
6
+ xtree_mcp-0.1.0.dist-info/METADATA,sha256=agL9ZdnisgZGcO9tf3QfR1GKfisfVuOe6WickGmf4g0,2831
7
+ xtree_mcp-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
8
+ xtree_mcp-0.1.0.dist-info/entry_points.txt,sha256=StXaPQpnzZ_ihCb6sWZgTOJuQZ1mgFoa7tMoKRWEVn0,52
9
+ xtree_mcp-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ xtree-mcp = xtree_mcp.server:main