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.
Files changed (54) hide show
  1. package/README.md +234 -382
  2. package/docs/mcp.md +60 -0
  3. package/hermes/__init__.py +35 -0
  4. package/hermes/plugin.yaml +132 -0
  5. package/hermes/schemas.py +6 -0
  6. package/hermes/tools.py +647 -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 +7 -1
  11. package/pi/index.ts +52 -2906
  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 +493 -0
  16. package/skills/bull-trend/SKILL.md +2 -2
  17. package/skills/bull-trend/references/fat-tails.md +76 -3
  18. package/skills/bull-trend/scripts/tail_analysis.py +92 -3
  19. package/skills/event-driven/SKILL.md +2 -2
  20. package/skills/growth-quality/SKILL.md +1 -1
  21. package/skills/market-review/SKILL.md +1 -0
  22. package/skills/stock-analysis/SKILL.md +12 -7
  23. package/skills/stock-analysis/references/stateless-analysis.md +9 -1
  24. package/skills/stock-screener/SKILL.md +1 -1
  25. package/skills/strategy-backtest/SKILL.md +1 -1
  26. package/tools/_cache.py +13 -0
  27. package/tools/_subproc.py +46 -0
  28. package/tools/alert_rules.py +2 -2
  29. package/tools/backtest.py +3 -3
  30. package/tools/capabilities.py +33 -9
  31. package/tools/cli_budgets.json +1 -0
  32. package/tools/credit_data.py +293 -0
  33. package/tools/diagnostics.py +3 -4
  34. package/tools/gather.py +2 -6
  35. package/tools/import_parser.py +3 -4
  36. package/tools/lixinger.py +119 -27
  37. package/tools/market_regime.py +5 -2
  38. package/tools/market_review.py +5 -6
  39. package/tools/name_resolver.py +45 -33
  40. package/tools/report_renderer.py +3 -3
  41. package/tools/requirements.txt +5 -4
  42. package/tools/risk_screening.py +3 -2
  43. package/tools/screener.py +41 -30
  44. package/tools/search_intel.py +79 -10
  45. package/tools/sec_edgar.py +268 -1
  46. package/tools/sec_holders.py +6 -0
  47. package/tools/signal_tracker.py +5 -5
  48. package/tools/stateless_analysis.py +132 -19
  49. package/tools/stock_data.py +1020 -817
  50. package/tools/tiaa_disclosures.py +4 -0
  51. package/tools/tool_schemas.json +2734 -0
  52. package/tools/trading_calendar.py +65 -30
  53. package/tools/value_data.py +423 -175
  54. 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
@@ -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"))