stock-analysis-plugin 0.2.10 → 0.2.12

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 (47) hide show
  1. package/README.md +237 -381
  2. package/docs/mcp.md +60 -0
  3. package/hermes/__init__.py +35 -0
  4. package/hermes/plugin.yaml +131 -0
  5. package/hermes/schemas.py +6 -0
  6. package/hermes/tools.py +630 -0
  7. package/mcp_host/__init__.py +1 -0
  8. package/mcp_host/__main__.py +3 -0
  9. package/mcp_host/server.py +222 -0
  10. package/package.json +17 -10
  11. package/pi/index.ts +53 -2887
  12. package/scripts/cli-json.mjs +23 -0
  13. package/scripts/exec-process.mjs +89 -0
  14. package/scripts/setup-python.mjs +37 -4
  15. package/scripts/tool-calls.mjs +489 -0
  16. package/skills/event-driven/SKILL.md +2 -2
  17. package/skills/growth-quality/SKILL.md +1 -1
  18. package/skills/stock-analysis/SKILL.md +12 -7
  19. package/skills/stock-analysis/references/stateless-analysis.md +9 -1
  20. package/tools/_cache.py +13 -0
  21. package/tools/_subproc.py +46 -0
  22. package/tools/alert_rules.py +65 -16
  23. package/tools/backtest.py +3 -3
  24. package/tools/capabilities.py +32 -9
  25. package/tools/cli_budgets.json +2 -0
  26. package/tools/diagnostics.py +3 -4
  27. package/tools/gather.py +2 -6
  28. package/tools/import_parser.py +3 -4
  29. package/tools/lixinger.py +119 -27
  30. package/tools/market_regime.py +5 -2
  31. package/tools/market_review.py +5 -6
  32. package/tools/name_resolver.py +82 -21
  33. package/tools/report_renderer.py +3 -3
  34. package/tools/requirements.txt +6 -5
  35. package/tools/risk_screening.py +3 -2
  36. package/tools/screener.py +6 -4
  37. package/tools/search_intel.py +81 -12
  38. package/tools/sec_edgar.py +266 -0
  39. package/tools/sec_holders.py +6 -0
  40. package/tools/signal_tracker.py +11 -10
  41. package/tools/stateless_analysis.py +115 -0
  42. package/tools/stock_data.py +707 -222
  43. package/tools/tiaa_disclosures.py +267 -0
  44. package/tools/tool_schemas.json +2704 -0
  45. package/tools/trading_calendar.py +65 -30
  46. package/tools/value_data.py +366 -134
  47. 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`),所以 74 个工具的名称、参数和输出与其他宿主一致。
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
+ 保存后,客户端里出现 74 个工具(如 `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,131 @@
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_earnings_calendar
23
+ - get_shareholder_structure
24
+ - get_etf_details
25
+ - get_dividends
26
+ - get_kline
27
+ - get_quote
28
+ - get_fund_quote
29
+ - get_capital_flow
30
+ - get_news
31
+ - get_financials
32
+ - get_technical_analysis
33
+ - analyze_pattern
34
+ - get_market_indices
35
+ - get_sector_rankings
36
+ - get_sector_constituents
37
+ - resolve_stock_sectors
38
+ - get_stock_info
39
+ - get_chip_distribution
40
+ - get_market_stats
41
+ - get_limit_up_pool
42
+ - get_dragon_tiger
43
+ - get_hot_stocks
44
+ - get_margin_trading
45
+ - get_northbound_flow
46
+ - get_fundamental_context
47
+ - screen_stocks
48
+ - run_backtest
49
+ - evaluate_signal
50
+ - resolve_stock_name
51
+ - check_trading_day
52
+ - get_trading_days
53
+ - get_trading_phase
54
+ - calculate_ma
55
+ - get_volume_analysis
56
+ - search_stock_news
57
+ - search_comprehensive_intel
58
+ - get_social_sentiment
59
+ - get_trending_sentiment
60
+ - extract_article
61
+ - screen_risk
62
+ - detect_market_regime
63
+ - get_market_review
64
+ - get_watchlist
65
+ - run_watchlist_analysis
66
+ - detect_anomaly
67
+ - diagnose_data_sources
68
+ - get_market_capabilities
69
+ - render_stock_report
70
+ - render_market_report
71
+ - build_watchlist_context
72
+ - analyze_position_context
73
+ - check_alert_rules
74
+ - record_signal
75
+ - evaluate_signals
76
+ - get_signal_summary
77
+ - get_review_history
78
+ - parse_stock_list
79
+ requires_env:
80
+ - name: TAVILY_API_KEY
81
+ description: "Tavily search API key (optional, one search engine is enough)"
82
+ url: "https://tavily.com"
83
+ secret: true
84
+ - name: BRAVE_API_KEY
85
+ description: "Brave search API key (optional)"
86
+ url: "https://brave.com/search/api/"
87
+ secret: true
88
+ - name: SERPAPI_KEY
89
+ description: "SerpAPI key (optional)"
90
+ url: "https://serpapi.com"
91
+ secret: true
92
+ - name: BOCHA_API_KEY
93
+ description: "Bocha AI search API key (optional)"
94
+ secret: true
95
+ - name: SENTIMENT_API_KEY
96
+ description: "Social sentiment API key (optional, for Eastmoney + Xueqiu)"
97
+ secret: true
98
+ - name: SENTIMENT_API_URL
99
+ description: "Sentiment API endpoint (default: https://api.adanos.org)"
100
+ secret: false
101
+ - name: FINNHUB_API_KEY
102
+ description: "Finnhub API key (US stock quotes and financials)"
103
+ url: "https://finnhub.io"
104
+ secret: true
105
+ - name: ALPHAVANTAGE_API_KEY
106
+ description: "Alpha Vantage API key (US stock klines)"
107
+ url: "https://www.alphavantage.co"
108
+ secret: true
109
+ - name: LONGBRIDGE_APP_KEY
110
+ description: "Longbridge app key (HK stock quotes)"
111
+ url: "https://open.longportapp.com"
112
+ secret: true
113
+ - name: LONGBRIDGE_APP_SECRET
114
+ description: "Longbridge app secret"
115
+ secret: true
116
+ - name: LONGBRIDGE_ACCESS_TOKEN
117
+ description: "Longbridge access token"
118
+ secret: true
119
+ - name: TUSHARE_TOKEN
120
+ description: "Tushare token (A-share enhanced data, optional)"
121
+ url: "https://tushare.pro"
122
+ secret: true
123
+ - name: XUEQIU_TOKEN
124
+ description: "Xueqiu token (optional, A-share industry fallback for resolve_stock_sectors)"
125
+ url: "https://xueqiu.com"
126
+ secret: true
127
+ requires_mcp:
128
+ - name: wisburg-mcp-server
129
+ description: "Wisburg research data — institutional reports, earnings calls, filings, market daily"
130
+ url: "https://wisburg.com"
131
+ optional: true
@@ -0,0 +1,6 @@
1
+ import json
2
+
3
+ from .tools import TOOLS_DIR
4
+
5
+ # One schema file for every host: Pi/OpenClaw/dsh import the same JSON (see scripts/tool-calls.mjs).
6
+ TOOL_SCHEMAS = json.loads((TOOLS_DIR / "tool_schemas.json").read_text(encoding="utf-8"))