stock-analysis-plugin 0.2.11 → 0.2.13
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.
- package/README.md +234 -382
- package/docs/mcp.md +60 -0
- package/hermes/__init__.py +35 -0
- package/hermes/plugin.yaml +132 -0
- package/hermes/schemas.py +6 -0
- package/hermes/tools.py +647 -0
- package/mcp_host/__init__.py +1 -0
- package/mcp_host/__main__.py +3 -0
- package/mcp_host/server.py +222 -0
- package/package.json +7 -1
- package/pi/index.ts +52 -2906
- package/scripts/cli-json.mjs +23 -0
- package/scripts/exec-process.mjs +89 -0
- package/scripts/setup-python.mjs +37 -4
- package/scripts/tool-calls.mjs +493 -0
- package/skills/bull-trend/SKILL.md +2 -2
- package/skills/bull-trend/references/fat-tails.md +76 -3
- package/skills/bull-trend/scripts/tail_analysis.py +92 -3
- package/skills/event-driven/SKILL.md +2 -2
- package/skills/growth-quality/SKILL.md +1 -1
- package/skills/market-review/SKILL.md +1 -0
- package/skills/stock-analysis/SKILL.md +12 -7
- package/skills/stock-analysis/references/stateless-analysis.md +9 -1
- package/skills/stock-screener/SKILL.md +1 -1
- package/skills/strategy-backtest/SKILL.md +1 -1
- package/tools/_cache.py +13 -0
- package/tools/_subproc.py +46 -0
- package/tools/alert_rules.py +2 -2
- package/tools/backtest.py +3 -3
- package/tools/capabilities.py +33 -9
- package/tools/cli_budgets.json +1 -0
- package/tools/credit_data.py +293 -0
- package/tools/diagnostics.py +3 -4
- package/tools/gather.py +2 -6
- package/tools/import_parser.py +3 -4
- package/tools/lixinger.py +119 -27
- package/tools/market_regime.py +5 -2
- package/tools/market_review.py +5 -6
- package/tools/name_resolver.py +45 -33
- package/tools/report_renderer.py +3 -3
- package/tools/requirements.txt +5 -4
- package/tools/risk_screening.py +3 -2
- package/tools/screener.py +41 -30
- package/tools/search_intel.py +79 -10
- package/tools/sec_edgar.py +268 -1
- package/tools/sec_holders.py +6 -0
- package/tools/signal_tracker.py +5 -5
- package/tools/stateless_analysis.py +132 -19
- package/tools/stock_data.py +1020 -817
- package/tools/tiaa_disclosures.py +4 -0
- package/tools/tool_schemas.json +2734 -0
- package/tools/trading_calendar.py +65 -30
- package/tools/value_data.py +423 -175
- package/tools/watchlist.py +43 -5
package/docs/mcp.md
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# MCP 接入指南(WorkBuddy / Claude Desktop / Cursor)
|
|
2
|
+
|
|
3
|
+
`mcp_host/server.py` 是本插件的 MCP stdio 服务器:一行一条 JSON-RPC 2.0 消息,只用 Python 标准库。它复用所有宿主共用的 JSON Schema(`tools/tool_schemas.json`,经 `hermes/schemas.py` 读取)和参数映射(`hermes/tools.py`),所以 75 个工具的名称、参数和输出与其他宿主一致。
|
|
4
|
+
|
|
5
|
+
## 前置条件
|
|
6
|
+
|
|
7
|
+
- Python >= 3.10
|
|
8
|
+
- 克隆仓库并执行 `npm install`,postinstall 会建好仓库内的 `.venv` 并安装 `tools/requirements.txt`
|
|
9
|
+
- 用 `.venv` 里的解释器启动服务器(下面的示例都用绝对路径)。通过 PyPI 安装时也可以直接运行 `stock-analysis-mcp` 或 `python -m mcp_host`:
|
|
10
|
+
- macOS / Linux:`/path/to/stock-analysis-plugin/.venv/bin/python3`
|
|
11
|
+
- Windows:`C:\\path\\to\\stock-analysis-plugin\\.venv\\Scripts\\python.exe`
|
|
12
|
+
|
|
13
|
+
数据源和搜索凭据(`TUSHARE_TOKEN`、`TAVILY_API_KEY`、`SEC_USER_AGENT` 等)只通过环境变量传入,写在配置的 `env` 字段里。没配置的数据源会自动跳过。
|
|
14
|
+
|
|
15
|
+
## 配置
|
|
16
|
+
|
|
17
|
+
三个客户端都用同样的 `mcpServers` 格式:
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
{
|
|
21
|
+
"mcpServers": {
|
|
22
|
+
"stock-analysis": {
|
|
23
|
+
"command": "/path/to/stock-analysis-plugin/.venv/bin/python3",
|
|
24
|
+
"args": ["/path/to/stock-analysis-plugin/mcp_host/server.py"],
|
|
25
|
+
"env": {
|
|
26
|
+
"SEC_USER_AGENT": "your-name you@example.com"
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
| 客户端 | 配置位置 |
|
|
34
|
+
| --- | --- |
|
|
35
|
+
| WorkBuddy | 侧边栏「插件」→ 右上角「MCP 服务器」→「配置 MCP」;或直接编辑 `~/.workbuddy/mcp.json`(用户级)、`<项目目录>/.workbuddy/mcp.json`(项目级)。参见[官方 MCP 指南](https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/MCP-Guide) |
|
|
36
|
+
| Claude Desktop | `claude_desktop_config.json`(设置 → Developer → Edit Config) |
|
|
37
|
+
| Cursor | `~/.cursor/mcp.json`(全局)或 `<项目目录>/.cursor/mcp.json` |
|
|
38
|
+
|
|
39
|
+
保存后,客户端里出现 75 个工具(如 `get_quote`、`get_technical_analysis`)即接入成功。
|
|
40
|
+
|
|
41
|
+
## 行为说明
|
|
42
|
+
|
|
43
|
+
- **协议**:支持 `initialize`、`ping`、`tools/list`、`tools/call`,以及 `notifications/initialized` 和 `notifications/cancelled`。协商版本为 `2025-11-25`、`2025-06-18`、`2025-03-26`、`2024-11-05`;客户端请求其他版本时,回复 `2025-11-25`。
|
|
44
|
+
- **stdout 只有 JSON-RPC**:日志和误打印都会转到 stderr。
|
|
45
|
+
- **错误**:未知工具、参数不是对象、未知方法、无法解析的 JSON 作为 JSON-RPC 错误返回(`-32602` / `-32601` / `-32700` / `-32600`)。缺少必填参数、数据源失败、Python CLI 超时则作为工具结果返回:`isError: true`,正文为 `{"error": "..."}`。
|
|
46
|
+
- **并发与取消**:每次 `tools/call` 在独立线程里运行。收到 `notifications/cancelled` 后,服务器会结束对应的 Python 子进程,并且不再回复该请求。客户端关闭 stdin 时,服务器结束所有进行中的调用后退出。
|
|
47
|
+
- **超时**:沿用 `tools/cli_budgets.json` 的命令预算,与其他宿主一致。
|
|
48
|
+
- **Skills**:MCP 只提供工具。`skills/*/SKILL.md` 里的 21 个工作流需要客户端自己的 Skills 功能单独导入。
|
|
49
|
+
|
|
50
|
+
## 本地验证
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
.venv/bin/python -m pytest tests/test_mcp_integration.py -v
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
也可以手动发一条请求:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | .venv/bin/python mcp_host/server.py
|
|
60
|
+
```
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import functools
|
|
2
|
+
|
|
3
|
+
from . import schemas, tools
|
|
4
|
+
|
|
5
|
+
PROJECT_ROOT = tools.PROJECT_ROOT
|
|
6
|
+
SKILLS_DIR = PROJECT_ROOT / "skills"
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def _without_nulls(handler):
|
|
10
|
+
# Explicit null optional args would otherwise reach argv as "None"; dropping them applies defaults.
|
|
11
|
+
@functools.wraps(handler)
|
|
12
|
+
def wrapper(args, **kwargs):
|
|
13
|
+
if isinstance(args, dict):
|
|
14
|
+
args = {key: value for key, value in args.items() if value is not None}
|
|
15
|
+
return handler(args, **kwargs)
|
|
16
|
+
|
|
17
|
+
return wrapper
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def register(ctx):
|
|
21
|
+
for schema in schemas.TOOL_SCHEMAS:
|
|
22
|
+
name = schema["name"]
|
|
23
|
+
ctx.register_tool(
|
|
24
|
+
name=name,
|
|
25
|
+
toolset="stock-analysis",
|
|
26
|
+
schema=schema,
|
|
27
|
+
handler=_without_nulls(getattr(tools, name)),
|
|
28
|
+
)
|
|
29
|
+
|
|
30
|
+
for child in sorted(SKILLS_DIR.iterdir()):
|
|
31
|
+
skill_md = child / "SKILL.md"
|
|
32
|
+
if child.is_dir() and skill_md.exists():
|
|
33
|
+
# Hermes PluginContext.register_skill 期望 Path(内部调用 path.exists()),
|
|
34
|
+
# 传 str 会报 'str' object has no attribute 'exists' 导致整个插件加载失败
|
|
35
|
+
ctx.register_skill(child.name, skill_md)
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
name: stock-analysis
|
|
2
|
+
version: 0.1.0
|
|
3
|
+
description: "Stock analysis, screening, and strategy backtesting across A/HK/US/JP/KR/TW markets"
|
|
4
|
+
provides_tools:
|
|
5
|
+
- calculate_rotation_metrics
|
|
6
|
+
- backtest_rotation_allocation
|
|
7
|
+
- analyze_trend_strategy
|
|
8
|
+
- compare_stocks
|
|
9
|
+
- analyze_disclosure_changes
|
|
10
|
+
- analyze_portfolio_risk
|
|
11
|
+
- plan_portfolio_rebalance
|
|
12
|
+
- calculate_position_size
|
|
13
|
+
- calculate_dcf_valuation
|
|
14
|
+
- analyze_event_study
|
|
15
|
+
- validate_backtest
|
|
16
|
+
- compare_analysis_snapshots
|
|
17
|
+
- get_announcements
|
|
18
|
+
- get_us_holdings
|
|
19
|
+
- get_insider_trades
|
|
20
|
+
- get_valuation_history
|
|
21
|
+
- get_index_valuation
|
|
22
|
+
- get_cds_index
|
|
23
|
+
- get_earnings_calendar
|
|
24
|
+
- get_shareholder_structure
|
|
25
|
+
- get_etf_details
|
|
26
|
+
- get_dividends
|
|
27
|
+
- get_kline
|
|
28
|
+
- get_quote
|
|
29
|
+
- get_fund_quote
|
|
30
|
+
- get_capital_flow
|
|
31
|
+
- get_news
|
|
32
|
+
- get_financials
|
|
33
|
+
- get_technical_analysis
|
|
34
|
+
- analyze_pattern
|
|
35
|
+
- get_market_indices
|
|
36
|
+
- get_sector_rankings
|
|
37
|
+
- get_sector_constituents
|
|
38
|
+
- resolve_stock_sectors
|
|
39
|
+
- get_stock_info
|
|
40
|
+
- get_chip_distribution
|
|
41
|
+
- get_market_stats
|
|
42
|
+
- get_limit_up_pool
|
|
43
|
+
- get_dragon_tiger
|
|
44
|
+
- get_hot_stocks
|
|
45
|
+
- get_margin_trading
|
|
46
|
+
- get_northbound_flow
|
|
47
|
+
- get_fundamental_context
|
|
48
|
+
- screen_stocks
|
|
49
|
+
- run_backtest
|
|
50
|
+
- evaluate_signal
|
|
51
|
+
- resolve_stock_name
|
|
52
|
+
- check_trading_day
|
|
53
|
+
- get_trading_days
|
|
54
|
+
- get_trading_phase
|
|
55
|
+
- calculate_ma
|
|
56
|
+
- get_volume_analysis
|
|
57
|
+
- search_stock_news
|
|
58
|
+
- search_comprehensive_intel
|
|
59
|
+
- get_social_sentiment
|
|
60
|
+
- get_trending_sentiment
|
|
61
|
+
- extract_article
|
|
62
|
+
- screen_risk
|
|
63
|
+
- detect_market_regime
|
|
64
|
+
- get_market_review
|
|
65
|
+
- get_watchlist
|
|
66
|
+
- run_watchlist_analysis
|
|
67
|
+
- detect_anomaly
|
|
68
|
+
- diagnose_data_sources
|
|
69
|
+
- get_market_capabilities
|
|
70
|
+
- render_stock_report
|
|
71
|
+
- render_market_report
|
|
72
|
+
- build_watchlist_context
|
|
73
|
+
- analyze_position_context
|
|
74
|
+
- check_alert_rules
|
|
75
|
+
- record_signal
|
|
76
|
+
- evaluate_signals
|
|
77
|
+
- get_signal_summary
|
|
78
|
+
- get_review_history
|
|
79
|
+
- parse_stock_list
|
|
80
|
+
requires_env:
|
|
81
|
+
- name: TAVILY_API_KEY
|
|
82
|
+
description: "Tavily search API key (optional, one search engine is enough)"
|
|
83
|
+
url: "https://tavily.com"
|
|
84
|
+
secret: true
|
|
85
|
+
- name: BRAVE_API_KEY
|
|
86
|
+
description: "Brave search API key (optional)"
|
|
87
|
+
url: "https://brave.com/search/api/"
|
|
88
|
+
secret: true
|
|
89
|
+
- name: SERPAPI_KEY
|
|
90
|
+
description: "SerpAPI key (optional)"
|
|
91
|
+
url: "https://serpapi.com"
|
|
92
|
+
secret: true
|
|
93
|
+
- name: BOCHA_API_KEY
|
|
94
|
+
description: "Bocha AI search API key (optional)"
|
|
95
|
+
secret: true
|
|
96
|
+
- name: SENTIMENT_API_KEY
|
|
97
|
+
description: "Social sentiment API key (optional, for Eastmoney + Xueqiu)"
|
|
98
|
+
secret: true
|
|
99
|
+
- name: SENTIMENT_API_URL
|
|
100
|
+
description: "Sentiment API endpoint (default: https://api.adanos.org)"
|
|
101
|
+
secret: false
|
|
102
|
+
- name: FINNHUB_API_KEY
|
|
103
|
+
description: "Finnhub API key (US stock quotes and financials)"
|
|
104
|
+
url: "https://finnhub.io"
|
|
105
|
+
secret: true
|
|
106
|
+
- name: ALPHAVANTAGE_API_KEY
|
|
107
|
+
description: "Alpha Vantage API key (US stock klines)"
|
|
108
|
+
url: "https://www.alphavantage.co"
|
|
109
|
+
secret: true
|
|
110
|
+
- name: LONGBRIDGE_APP_KEY
|
|
111
|
+
description: "Longbridge app key (HK stock quotes)"
|
|
112
|
+
url: "https://open.longportapp.com"
|
|
113
|
+
secret: true
|
|
114
|
+
- name: LONGBRIDGE_APP_SECRET
|
|
115
|
+
description: "Longbridge app secret"
|
|
116
|
+
secret: true
|
|
117
|
+
- name: LONGBRIDGE_ACCESS_TOKEN
|
|
118
|
+
description: "Longbridge access token"
|
|
119
|
+
secret: true
|
|
120
|
+
- name: TUSHARE_TOKEN
|
|
121
|
+
description: "Tushare token (A-share enhanced data, optional)"
|
|
122
|
+
url: "https://tushare.pro"
|
|
123
|
+
secret: true
|
|
124
|
+
- name: XUEQIU_TOKEN
|
|
125
|
+
description: "Xueqiu token (optional, A-share industry fallback for resolve_stock_sectors)"
|
|
126
|
+
url: "https://xueqiu.com"
|
|
127
|
+
secret: true
|
|
128
|
+
requires_mcp:
|
|
129
|
+
- name: wisburg-mcp-server
|
|
130
|
+
description: "Wisburg research data — institutional reports, earnings calls, filings, market daily"
|
|
131
|
+
url: "https://wisburg.com"
|
|
132
|
+
optional: true
|