ashare-mcp-server 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.
Files changed (31) hide show
  1. ashare_mcp_server-0.1.0/.env.example +9 -0
  2. ashare_mcp_server-0.1.0/.github/workflows/ci.yml +25 -0
  3. ashare_mcp_server-0.1.0/.github/workflows/refresh-page.yml +29 -0
  4. ashare_mcp_server-0.1.0/.github/workflows/release.yml +26 -0
  5. ashare_mcp_server-0.1.0/.gitignore +15 -0
  6. ashare_mcp_server-0.1.0/LICENSE +21 -0
  7. ashare_mcp_server-0.1.0/PKG-INFO +13 -0
  8. ashare_mcp_server-0.1.0/README.md +138 -0
  9. ashare_mcp_server-0.1.0/app.py +527 -0
  10. ashare_mcp_server-0.1.0/docs/index.html +111 -0
  11. ashare_mcp_server-0.1.0/pyproject.toml +24 -0
  12. ashare_mcp_server-0.1.0/requirements.txt +3 -0
  13. ashare_mcp_server-0.1.0/scripts/build_page.py +240 -0
  14. ashare_mcp_server-0.1.0/smithery.yaml +23 -0
  15. ashare_mcp_server-0.1.0/src/ashare_mcp/__init__.py +3 -0
  16. ashare_mcp_server-0.1.0/src/ashare_mcp/backtest/__init__.py +1 -0
  17. ashare_mcp_server-0.1.0/src/ashare_mcp/backtest/engine.py +223 -0
  18. ashare_mcp_server-0.1.0/src/ashare_mcp/config.py +28 -0
  19. ashare_mcp_server-0.1.0/src/ashare_mcp/data/__init__.py +1 -0
  20. ashare_mcp_server-0.1.0/src/ashare_mcp/data/akshare_data.py +638 -0
  21. ashare_mcp_server-0.1.0/src/ashare_mcp/data/facade.py +37 -0
  22. ashare_mcp_server-0.1.0/src/ashare_mcp/data/tushare_data.py +155 -0
  23. ashare_mcp_server-0.1.0/src/ashare_mcp/server.py +402 -0
  24. ashare_mcp_server-0.1.0/src/ashare_mcp/trading/__init__.py +1 -0
  25. ashare_mcp_server-0.1.0/src/ashare_mcp/trading/paper.py +355 -0
  26. ashare_mcp_server-0.1.0/src/ashare_mcp/utils.py +149 -0
  27. ashare_mcp_server-0.1.0/tests/test_engine.py +70 -0
  28. ashare_mcp_server-0.1.0/tests/test_paper.py +94 -0
  29. ashare_mcp_server-0.1.0/tests/test_server.py +24 -0
  30. ashare_mcp_server-0.1.0/tests/test_utils.py +82 -0
  31. ashare_mcp_server-0.1.0/uv.lock +3513 -0
@@ -0,0 +1,9 @@
1
+ # Copy to .env or export in your shell. All settings optional.
2
+
3
+ # tushare token (fallback data source). Get one at https://tushare.pro
4
+ # Without it, akshare still works for most things.
5
+ TUSHARE_TOKEN=
6
+
7
+ # Where the paper-trading account JSON is stored.
8
+ # Default: <repo>/data (falls back to ~/.ashare-mcp if not writable)
9
+ # ASHARE_MCP_DATA_DIR=F:/Hermes/ashare-mcp/data
@@ -0,0 +1,25 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ jobs:
9
+ test:
10
+ runs-on: ubuntu-latest
11
+ strategy:
12
+ matrix:
13
+ python-version: ["3.11", "3.12"]
14
+ steps:
15
+ - uses: actions/checkout@v4
16
+ - uses: actions/setup-python@v5
17
+ with:
18
+ python-version: ${{ matrix.python-version }}
19
+ cache: pip
20
+ - name: Install
21
+ run: pip install -e . pytest
22
+ - name: Unit tests (offline)
23
+ run: pytest -q tests/
24
+ - name: MCP tools smoke
25
+ run: python -c "import asyncio; from ashare_mcp.server import mcp; t=asyncio.run(mcp.list_tools()); print(len(t), 'tools')"
@@ -0,0 +1,29 @@
1
+ name: Refresh demo page
2
+
3
+ # Rebuild docs/index.html with fresh market data after A-share close
4
+ # (10:00 UTC = 18:00 Beijing, weekdays only).
5
+ on:
6
+ schedule:
7
+ - cron: "0 10 * * 1-5"
8
+ workflow_dispatch:
9
+
10
+ permissions:
11
+ contents: write
12
+
13
+ jobs:
14
+ build:
15
+ runs-on: ubuntu-latest
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+ - uses: actions/setup-python@v5
19
+ with:
20
+ python-version: "3.12"
21
+ cache: pip
22
+ - name: Install
23
+ run: pip install -e . plotly
24
+ - name: Rebuild page
25
+ run: python scripts/build_page.py
26
+ - uses: stefanzweifel/git-auto-commit-action@v6
27
+ with:
28
+ commit_message: "chore: refresh demo page snapshot"
29
+ file_pattern: docs/index.html
@@ -0,0 +1,26 @@
1
+ name: Release
2
+
3
+ # Publishes to PyPI when a GitHub Release is created.
4
+ # Requires a Trusted Publisher configured on pypi.org:
5
+ # owner=hantrleko repo=ashare-mcp workflow=release.yml environment=pypi
6
+ on:
7
+ release:
8
+ types: [published]
9
+
10
+ permissions:
11
+ id-token: write # OIDC for PyPI trusted publishing — no token needed
12
+
13
+ jobs:
14
+ publish:
15
+ runs-on: ubuntu-latest
16
+ environment: pypi
17
+ steps:
18
+ - uses: actions/checkout@v4
19
+ - uses: actions/setup-python@v5
20
+ with:
21
+ python-version: "3.12"
22
+ - name: Build sdist + wheel
23
+ run: |
24
+ pip install uv
25
+ uv build
26
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,15 @@
1
+ # Python
2
+ .venv/
3
+ __pycache__/
4
+ *.pyc
5
+ *.egg-info/
6
+ .pytest_cache/
7
+
8
+ # Local state / secrets
9
+ .env
10
+ data/paper_account.json
11
+ inspector-config.json
12
+
13
+ # Local tooling binaries (cloudflared etc.)
14
+ tools/
15
+ dist/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 hantrleko
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,13 @@
1
+ Metadata-Version: 2.5
2
+ Name: ashare-mcp-server
3
+ Version: 0.1.0
4
+ Summary: MCP server for A-share market data, paper trading, backtesting and fundamentals (akshare + tushare)
5
+ License-File: LICENSE
6
+ Requires-Python: >=3.10
7
+ Requires-Dist: akshare>=1.16
8
+ Requires-Dist: mcp<2,>=1.8
9
+ Requires-Dist: numpy>=1.24
10
+ Requires-Dist: pandas>=2.0
11
+ Requires-Dist: plotly>=7.1.0
12
+ Requires-Dist: streamlit>=1.65.0
13
+ Requires-Dist: tushare>=1.4.29
@@ -0,0 +1,138 @@
1
+ # ashare-mcp
2
+
3
+ [![Python](https://img.shields.io/badge/Python-3.10%2B-3776ab?logo=python&logoColor=white)](https://github.com/hantrleko/ashare-mcp)
4
+ [![MCP](https://img.shields.io/badge/MCP-stdio-7b7ff2)](https://modelcontextprotocol.io)
5
+ [![CI](https://github.com/hantrleko/ashare-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/hantrleko/ashare-mcp/actions)
6
+ [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
7
+ [![Demo Page](https://img.shields.io/badge/demo-GitHub%20Pages-orange)](https://hantrleko.github.io/ashare-mcp/)
8
+
9
+ MCP server + Streamlit dashboard for **A-share (China mainland) market data,
10
+ paper trading, strategy backtesting and company fundamentals** — built for AI
11
+ agents (Claude Desktop, Cursor, Claude Code, …).
12
+
13
+ Data: **akshare** primary (Sina/Tencent endpoints preferred, East Money
14
+ fallback with rate-limit cooldown), **tushare** automatic fallback when
15
+ `TUSHARE_TOKEN` is set.
16
+
17
+ 📊 **[在线展示页 / Live snapshot](https://hantrleko.github.io/ashare-mcp/)** —
18
+ 每日收盘后 GitHub Actions 自动刷新。
19
+
20
+ ---
21
+
22
+ ## 功能总览
23
+
24
+ | 模块 | MCP 工具 | 说明 |
25
+ |---|---|---|
26
+ | 行情数据 | `search_stock` `get_quote` `get_quotes` `get_kline` `get_index_quote` `get_index_kline` `get_market_overview` `get_limit_pool` `get_money_flow` | 搜索/实时报价/日周月K/指数/涨跌家数/涨停跌停池/主力资金流 |
27
+ | 事件与因子 | `get_earnings_calendar` `get_announcements` `get_factor_snapshot` | 业绩报表/预告/快报、公告查询、动量/波动/Beta/均线位置因子快照 |
28
+ | 财务基本面 | `get_financial_abstract` `get_financial_statement` | 财务指标摘要 + 利润表/资产负债表/现金流量表 |
29
+ | 模拟盘 | `paper_status` `paper_buy` `paper_sell` `paper_positions` `paper_orders` `paper_reset` | 1手=100股、T+1、±10/20/30/5%涨跌停、佣金万2.5+印花税万5+过户费万0.1,JSON持久化 |
30
+ | 条件单 | `paper_add_trigger` `paper_triggers` `paper_cancel_trigger` `paper_check_triggers` | 触发价买卖(突破/止损/低吸),查账户时自动评估成交 |
31
+ | 策略回测 | `run_backtest` | `ma_cross`/`momentum`/`grid`/`buy_hold`,信号收盘产生、次日开盘成交,无未来函数 |
32
+ | 数据源 | `provider_status` | akshare 主源状态、tushare token 配置检查 |
33
+
34
+ 共 **26 个工具**。
35
+
36
+ ## 安装
37
+
38
+ 需要 Python ≥ 3.10。
39
+
40
+ ```powershell
41
+ git clone https://github.com/hantrleko/ashare-mcp
42
+ cd ashare-mcp
43
+ uv venv --python 3.12 .venv # 或 python -m venv .venv
44
+ uv pip install --python .venv\Scripts\python.exe -e .
45
+ ```
46
+
47
+ 可选:复制 `.env.example` → `.env`,填入 `TUSHARE_TOKEN` 启用降级数据源
48
+ (token 在 https://tushare.pro 免费注册)。
49
+
50
+ ## 接入 MCP 客户端
51
+
52
+ Claude Desktop / Cursor(`claude_desktop_config.json` / `.cursor/mcp.json`):
53
+
54
+ ```json
55
+ {
56
+ "mcpServers": {
57
+ "ashare": {
58
+ "command": "F:\\Hermes\\ashare-mcp\\.venv\\Scripts\\python.exe",
59
+ "args": ["-m", "ashare_mcp.server"]
60
+ }
61
+ }
62
+ }
63
+ ```
64
+
65
+ 或直接跑 git 上的最新版:
66
+
67
+ ```json
68
+ {
69
+ "mcpServers": {
70
+ "ashare": {
71
+ "command": "uvx",
72
+ "args": ["--from", "git+https://github.com/hantrleko/ashare-mcp", "ashare-mcp-server"]
73
+ }
74
+ }
75
+ }
76
+ ```
77
+
78
+ Claude Code:
79
+
80
+ ```powershell
81
+ claude mcp add ashare -- F:\Hermes\ashare-mcp\.venv\Scripts\python.exe -m ashare_mcp.server
82
+ ```
83
+
84
+ ## Web 看板
85
+
86
+ ```powershell
87
+ .venv\Scripts\python.exe -m streamlit run app.py # http://127.0.0.1:8501
88
+ ```
89
+
90
+ 四个页面:市场概览(指数/涨跌家数/涨停池/业绩日历)、个股行情
91
+ (K线+资金流+财务+因子快照+公告)、模拟盘(买卖/条件单/持仓/订单)、
92
+ 策略回测(指标+净值曲线+交易明细)。
93
+
94
+ ## 给 agent 的任务示例
95
+
96
+ - "茅台最近一年的日K线" → `get_kline("600519", "daily", adjust="qfq")`
97
+ - "今天涨停的股票有哪些" → `get_limit_pool(pool="zt")`(近30个交易日)
98
+ - "帮我模拟买入 100 股平安银行" → `paper_buy("000001", 100)`
99
+ - "茅台跌到 1400 以下帮我买 100 股" → `paper_add_trigger("600519","buy",100,1400,"<=")`
100
+ - "今年三季报谁的营收增速最快" → `get_earnings_calendar("20250930","yjbb")`
101
+ - "茅台今天发了什么公告" → `get_announcements("600519")`
102
+ - "平安银行的动量和波动率因子" → `get_factor_snapshot("000001")`
103
+ - "用5/20均线在茅台回测2024年以来" → `run_backtest("600519", "ma_cross", {"fast":5,"slow":20}, "20240101")`
104
+ - "茅台的利润表和主要财务指标" → `get_financial_statement` + `get_financial_abstract`
105
+
106
+ ## 注意事项
107
+
108
+ - **代码格式**:`"000001"` `"sz000001"` `"000001.SZ"` `"sh600000"` 都认;
109
+ 6位裸码自动识别市场(6→沪、0/3→深、4/8/92→北)。
110
+ - **指数 vs 股票**:`sh000001`=上证指数;裸 `"000001"`=平安银行。
111
+ - **报价降级链**:东财快照 → 新浪1分钟线 → 新浪全市场快照 → 日线收盘;
112
+ 响应里都标 `source`/`note`,兜底数据不是实时会注明。
113
+ - **K线**:新浪优先、东财 `stock_zh_a_hist_em` 兜底(含限流冷却)。
114
+ - **涨停池**:只覆盖最近约30个交易日(东财接口限制)。
115
+ - **模拟盘**:纯模拟,不下真实订单。T+1 通过日期滚动实现。
116
+ - **回测**:做多、lot取整、最小交易额死区跳过碎单(清仓除外)。
117
+
118
+ ## 项目结构
119
+
120
+ ```
121
+ app.py # Streamlit 看板
122
+ scripts/build_page.py # 生成 docs/index.html(GitHub Pages 快照页)
123
+ docs/index.html # 静态展示页(每日自动刷新)
124
+ .github/workflows/ # refresh-page.yml 定时重建
125
+ src/ashare_mcp/
126
+ ├── server.py # FastMCP 入口,19 个工具
127
+ ├── config.py # env 配置、数据目录
128
+ ├── utils.py # 代码/日期归一化、重采样
129
+ ├── data/ # facade + akshare + tushare
130
+ ├── trading/paper.py # 模拟盘引擎(JSON 状态)
131
+ └── backtest/engine.py # 日线回测器
132
+ data/paper_account.json # 模拟盘状态(gitignored)
133
+ ```
134
+
135
+ ## Disclaimer
136
+
137
+ 仅供研究与模拟交易,不构成投资建议。数据来自新浪/东方财富/同花顺公开
138
+ 接口,时效性与准确性以源站为准。