xtree-mcp 0.1.0__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.
- xtree_mcp-0.1.0/.github/workflows/publish.yml +22 -0
- xtree_mcp-0.1.0/.github/workflows/test.yml +18 -0
- xtree_mcp-0.1.0/PKG-INFO +93 -0
- xtree_mcp-0.1.0/README.md +71 -0
- xtree_mcp-0.1.0/pyproject.toml +43 -0
- xtree_mcp-0.1.0/tests/test_api.py +79 -0
- xtree_mcp-0.1.0/tests/test_library.py +63 -0
- xtree_mcp-0.1.0/tests/test_registry.py +24 -0
- xtree_mcp-0.1.0/xtree_mcp/__init__.py +3 -0
- xtree_mcp-0.1.0/xtree_mcp/api.py +229 -0
- xtree_mcp-0.1.0/xtree_mcp/format.py +36 -0
- xtree_mcp-0.1.0/xtree_mcp/registry.py +23 -0
- xtree_mcp-0.1.0/xtree_mcp/server.py +131 -0
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
name: publish
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
tags:
|
|
6
|
+
- "v*"
|
|
7
|
+
|
|
8
|
+
permissions:
|
|
9
|
+
id-token: write
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
pypi:
|
|
13
|
+
runs-on: ubuntu-latest
|
|
14
|
+
environment: pypi
|
|
15
|
+
steps:
|
|
16
|
+
- uses: actions/checkout@v4
|
|
17
|
+
- uses: actions/setup-python@v5
|
|
18
|
+
with:
|
|
19
|
+
python-version: "3.12"
|
|
20
|
+
- run: pip install build twine
|
|
21
|
+
- run: python -m build
|
|
22
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
name: test
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [main]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
steps:
|
|
13
|
+
- uses: actions/checkout@v4
|
|
14
|
+
- uses: actions/setup-python@v5
|
|
15
|
+
with:
|
|
16
|
+
python-version: "3.12"
|
|
17
|
+
- run: pip install -e ".[dev]"
|
|
18
|
+
- run: pytest tests -q
|
xtree_mcp-0.1.0/PKG-INFO
ADDED
|
@@ -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,71 @@
|
|
|
1
|
+
# xtree-mcp — XTREE MCP server
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
Tools call `https://api.xtree.io` with your own API Key and wallet (pay per call).
|
|
6
|
+
|
|
7
|
+
## Install / run
|
|
8
|
+
|
|
9
|
+
Package may not be on PyPI yet. Prefer GitHub:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
# one-shot via uvx
|
|
13
|
+
uvx --from "git+https://github.com/xtree-io/xtree-mcp.git" xtree-mcp
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Or install editable after cloning:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
git clone https://github.com/xtree-io/xtree-mcp.git
|
|
20
|
+
cd xtree-mcp
|
|
21
|
+
pip install xtree-sdk
|
|
22
|
+
pip install -e .
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Get an API Key
|
|
26
|
+
|
|
27
|
+
1. Sign up at [www.xtree.io](https://www.xtree.io/login?tab=signup).
|
|
28
|
+
2. Set `XTREE_API_KEY=xt_live_...`.
|
|
29
|
+
|
|
30
|
+
## Cursor / Claude config
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"mcpServers": {
|
|
35
|
+
"xtree": {
|
|
36
|
+
"command": "uvx",
|
|
37
|
+
"args": ["--from", "git+https://github.com/xtree-io/xtree-mcp.git", "xtree-mcp"],
|
|
38
|
+
"env": {
|
|
39
|
+
"XTREE_API_KEY": "xt_live_..."
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Billing
|
|
47
|
+
|
|
48
|
+
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).
|
|
49
|
+
|
|
50
|
+
## Docs
|
|
51
|
+
|
|
52
|
+
- Website docs: https://www.xtree.io/docs
|
|
53
|
+
- OpenAPI: https://api.xtree.io/api/openapi.json
|
|
54
|
+
- Python SDK: https://github.com/xtree-io/xtree-python
|
|
55
|
+
- Skills: https://github.com/xtree-io/xtree-skills
|
|
56
|
+
|
|
57
|
+
## Environment
|
|
58
|
+
|
|
59
|
+
| Variable | Required | Default |
|
|
60
|
+
|----------|----------|---------|
|
|
61
|
+
| `XTREE_API_KEY` | yes | — |
|
|
62
|
+
| `XTREE_BASE_URL` | no | `https://api.xtree.io/api` |
|
|
63
|
+
| `XTREE_VERIFY_CODE` | no | — |
|
|
64
|
+
|
|
65
|
+
## Mirror notice
|
|
66
|
+
|
|
67
|
+
**Do not develop in this repository.** Public mirror only. Issues welcome. Contact: [business@xtree.io](mailto:business@xtree.io).
|
|
68
|
+
|
|
69
|
+
## License
|
|
70
|
+
|
|
71
|
+
MIT.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "xtree-mcp"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "MCP server exposing XTREE API tools for AI agents"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
authors = [{ name = "XTREE", email = "business@xtree.io" }]
|
|
13
|
+
keywords = ["xtree", "mcp", "wechat", "agent"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 3 - Alpha",
|
|
16
|
+
"Intended Audience :: Developers",
|
|
17
|
+
"Programming Language :: Python :: 3",
|
|
18
|
+
"Typing :: Typed",
|
|
19
|
+
]
|
|
20
|
+
dependencies = [
|
|
21
|
+
"mcp>=1.2,<2",
|
|
22
|
+
"xtree-sdk>=0.1.0",
|
|
23
|
+
"httpx>=0.27,<1",
|
|
24
|
+
]
|
|
25
|
+
|
|
26
|
+
[project.optional-dependencies]
|
|
27
|
+
dev = [
|
|
28
|
+
"pytest>=8",
|
|
29
|
+
]
|
|
30
|
+
|
|
31
|
+
[project.urls]
|
|
32
|
+
Homepage = "https://www.xtree.io"
|
|
33
|
+
Documentation = "https://www.xtree.io/docs"
|
|
34
|
+
Repository = "https://github.com/xtree-io/xtree-mcp"
|
|
35
|
+
|
|
36
|
+
[project.scripts]
|
|
37
|
+
xtree-mcp = "xtree_mcp.server:main"
|
|
38
|
+
|
|
39
|
+
[tool.hatch.build.targets.wheel]
|
|
40
|
+
packages = ["xtree_mcp"]
|
|
41
|
+
|
|
42
|
+
[tool.pytest.ini_options]
|
|
43
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
"""MCP API helper tests."""
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
|
|
5
|
+
import httpx
|
|
6
|
+
|
|
7
|
+
from xtree.client import XTreeClient
|
|
8
|
+
from xtree_mcp import api
|
|
9
|
+
from xtree_mcp.format import as_tool_json
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def _envelope(data, **meta):
|
|
13
|
+
return {
|
|
14
|
+
"ok": True,
|
|
15
|
+
"data": data,
|
|
16
|
+
"meta": {"request_id": "01JMCP", **meta},
|
|
17
|
+
"error": None,
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def test_as_tool_json_includes_meta():
|
|
22
|
+
transport = httpx.MockTransport(
|
|
23
|
+
lambda r: httpx.Response(200, json=_envelope({"x": 1}, cost_cny=0.5))
|
|
24
|
+
)
|
|
25
|
+
http = httpx.Client(transport=transport, base_url="https://api.xtree.io/api")
|
|
26
|
+
client = XTreeClient(api_key="xt_test", http_client=http)
|
|
27
|
+
raw = api.account_balance(client=client)
|
|
28
|
+
payload = json.loads(raw)
|
|
29
|
+
assert payload["data"]["x"] == 1
|
|
30
|
+
assert payload["_meta"]["cost_cny"] == 0.5
|
|
31
|
+
assert payload["_meta"]["request_id"] == "01JMCP"
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def test_wechat_search_videos_path_and_body():
|
|
35
|
+
captured = {}
|
|
36
|
+
|
|
37
|
+
def handler(request: httpx.Request) -> httpx.Response:
|
|
38
|
+
captured["path"] = request.url.path
|
|
39
|
+
captured["body"] = json.loads(request.content.decode())
|
|
40
|
+
return httpx.Response(200, json=_envelope({"items": []}))
|
|
41
|
+
|
|
42
|
+
transport = httpx.MockTransport(handler)
|
|
43
|
+
http = httpx.Client(transport=transport, base_url="https://api.xtree.io/api")
|
|
44
|
+
client = XTreeClient(api_key="xt_test", http_client=http)
|
|
45
|
+
api.wechat_search_videos("hello", page=2, session="sess1", client=client)
|
|
46
|
+
assert captured["path"] == "/api/wechat/search/videos"
|
|
47
|
+
assert captured["body"] == {"keyword": "hello", "page": 2, "session": "sess1"}
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def test_wechat_accounts_posts_path():
|
|
51
|
+
captured = {}
|
|
52
|
+
|
|
53
|
+
def handler(request: httpx.Request) -> httpx.Response:
|
|
54
|
+
captured["path"] = request.url.path
|
|
55
|
+
captured["body"] = json.loads(request.content.decode())
|
|
56
|
+
return httpx.Response(200, json=_envelope({}))
|
|
57
|
+
|
|
58
|
+
transport = httpx.MockTransport(handler)
|
|
59
|
+
http = httpx.Client(transport=transport, base_url="https://api.xtree.io/api")
|
|
60
|
+
client = XTreeClient(api_key="xt_test", http_client=http)
|
|
61
|
+
api.wechat_accounts_posts("gh_363b924965e9", client=client)
|
|
62
|
+
assert captured["path"] == "/api/wechat/accounts/posts/list"
|
|
63
|
+
assert captured["body"]["account_id"] == "gh_363b924965e9"
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def test_wechat_channels_feeds_path():
|
|
67
|
+
captured = {}
|
|
68
|
+
|
|
69
|
+
def handler(request: httpx.Request) -> httpx.Response:
|
|
70
|
+
captured["path"] = request.url.path
|
|
71
|
+
captured["body"] = json.loads(request.content.decode())
|
|
72
|
+
return httpx.Response(200, json=_envelope({}))
|
|
73
|
+
|
|
74
|
+
transport = httpx.MockTransport(handler)
|
|
75
|
+
http = httpx.Client(transport=transport, base_url="https://api.xtree.io/api")
|
|
76
|
+
client = XTreeClient(api_key="xt_test", http_client=http)
|
|
77
|
+
api.wechat_channels_feeds("ch123", client=client)
|
|
78
|
+
assert captured["path"] == "/api/wechat/channels/feeds/list"
|
|
79
|
+
assert captured["body"]["channel_id"] == "ch123"
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
"""MCP library API tests."""
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
|
|
5
|
+
import httpx
|
|
6
|
+
import pytest
|
|
7
|
+
|
|
8
|
+
from xtree.client import XTreeClient
|
|
9
|
+
from xtree_mcp import api
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def _envelope(data, **meta):
|
|
13
|
+
return {
|
|
14
|
+
"ok": True,
|
|
15
|
+
"data": data,
|
|
16
|
+
"meta": {"request_id": "01JMCP", **meta},
|
|
17
|
+
"error": None,
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
@pytest.fixture
|
|
22
|
+
def mock_client():
|
|
23
|
+
captured = {}
|
|
24
|
+
|
|
25
|
+
def handler(request: httpx.Request) -> httpx.Response:
|
|
26
|
+
captured["method"] = request.method
|
|
27
|
+
captured["path"] = request.url.path
|
|
28
|
+
if request.content:
|
|
29
|
+
captured["body"] = json.loads(request.content.decode())
|
|
30
|
+
return httpx.Response(200, json=_envelope({"items": []}))
|
|
31
|
+
|
|
32
|
+
transport = httpx.MockTransport(handler)
|
|
33
|
+
http = httpx.Client(transport=transport, base_url="https://api.xtree.io/api")
|
|
34
|
+
client = XTreeClient(api_key="xt_test", http_client=http)
|
|
35
|
+
return client, captured
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def test_wechat_library_search_articles(mock_client):
|
|
39
|
+
client, captured = mock_client
|
|
40
|
+
api.wechat_library_search_articles("AI", page=2, page_size=10, client=client)
|
|
41
|
+
assert captured["path"] == "/api/wechat/library/articles/search"
|
|
42
|
+
assert captured["body"] == {"keyword": "AI", "page": 2, "page_size": 10}
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def test_wechat_library_search_articles_tokenized(mock_client):
|
|
46
|
+
client, captured = mock_client
|
|
47
|
+
api.wechat_library_search_articles_tokenized("AI", page=1, page_size=15, client=client)
|
|
48
|
+
assert captured["path"] == "/api/wechat/library/articles/search/tokenized"
|
|
49
|
+
assert captured["body"] == {"keyword": "AI", "page": 1, "page_size": 15}
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def test_wechat_library_search_accounts(mock_client):
|
|
53
|
+
client, captured = mock_client
|
|
54
|
+
api.wechat_library_search_accounts("人民日报", page=3, client=client)
|
|
55
|
+
assert captured["path"] == "/api/wechat/library/accounts/search"
|
|
56
|
+
assert captured["body"] == {"keyword": "人民日报", "page": 3, "page_size": 20}
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def test_wechat_library_accounts_metrics(mock_client):
|
|
60
|
+
client, captured = mock_client
|
|
61
|
+
api.wechat_library_accounts_metrics("人民日报", client=client)
|
|
62
|
+
assert captured["path"] == "/api/wechat/library/accounts/metrics"
|
|
63
|
+
assert captured["body"] == {"name": "人民日报"}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"""MCP tool registry tests."""
|
|
2
|
+
|
|
3
|
+
from xtree_mcp.registry import MCP_TOOLS
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
def test_mcp_tool_count():
|
|
7
|
+
assert len(MCP_TOOLS) == 15
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def test_mcp_tool_names_unique():
|
|
11
|
+
names = [name for name, _ in MCP_TOOLS]
|
|
12
|
+
assert len(names) == len(set(names))
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def test_mcp_library_tools():
|
|
16
|
+
library = [(n, s) for n, s in MCP_TOOLS if s.startswith("wechat.library.")]
|
|
17
|
+
assert len(library) == 4
|
|
18
|
+
slugs = {s for _, s in library}
|
|
19
|
+
assert slugs == {
|
|
20
|
+
"wechat.library.articles.search",
|
|
21
|
+
"wechat.library.articles.tokenized",
|
|
22
|
+
"wechat.library.accounts.search",
|
|
23
|
+
"wechat.library.accounts.metrics",
|
|
24
|
+
}
|
|
@@ -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))
|
|
@@ -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)
|
|
@@ -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
|
+
]
|
|
@@ -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()
|