Metadata-Version: 2.5
Name: workbuddy-mcp-stockshort
Version: 1.0.1
Summary: WorkBuddy Connector MCP server for self-hosted StockShort workbench (stdio, auth_mode: token)
Author: dangsys
License: MIT
Keywords: mcp,model-context-protocol,stock,trading,workbuddy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.2
Description-Content-Type: text/markdown

# StockShort Connector（WorkBuddy）

为腾讯 WorkBuddy 生态开发的 StockShort 连接器：MCP stdio + 用户自填 Token 模式
（规范 06 / 06D 附录C），让 AI 通过自然语言查询用户自建的 A 股短线盯盘/模拟盘系统
（跑在本机 TS-001 `:8765`）。**全部工具只读**，不含任何写操作。

## 目录结构

```
stockshort/
├── connector-meta.json   # 连接器元信息（type: mcp, auth_mode: token, minWorkbuddyVersion: 4.24.0）
├── mcp.json              # MCP Server 连接配置（stdio + uvx，凭证经 env 注入）
├── token-schema.json     # 用户自填表单（STOCKSHORT_URL 必填 + STOCKSHORT_AUTH 可选）
├── stockshort_mcp/       # MCP Server（Python，官方 mcp SDK FastMCP）
│   ├── __init__.py
│   ├── __main__.py       # python -m stockshort_mcp 入口
│   └── server.py         # 6 个只读 tool
├── skills/
│   └── SKILL.md          # Skill 文件（按 05 规范，教 AI 如何使用工具）
├── icon.svg              # 连接器图标
└── README.md
```

## 工具与后端端点对照（2026-09-09 实测调研）

StockShort 服务端为标准库 http.server（`stockshort/server.py` + `server_routes.py`），
无鉴权（公网场景由反代 basic auth 兜底，经 STOCKSHORT_AUTH 注入）。

| 工具 | 后端端点 | 参数 | 返回摘要 |
|---|---|---|---|
| `get_today_candidates` | `GET /static/today_picks.json` | limit | 今日多源候选：代码/名称/votes/动作/评分/预期收益 + 入场计划（触发区间、止损、止盈、最大持有天数、仓位） |
| `get_paper_positions` | `GET /api/positions` | — | 模拟盘持仓（开仓价/止损/目标/现价/pnl/pnl_pct/衰减天数）+ 硬熔断与盘中暂停风控状态 |
| `get_paper_review` | `GET /static/paper_review.json` + `GET /static/paper_status.json` | — | 每日复盘体检各项检查（权限单/信号捕获/meta打分/结算）+ 台账统计（胜率、通过组/拦截组分 组胜率） |
| `get_rotation_status` | `GET /static/rotation_summary.json` | limit | 宏观闸门（主力净流入、涨跌家数比、pass）、强势板块、轮动候选（动作/强度评分/置信度） |
| `get_stock_detail` | `GET /api/stock/detail?code=` | code | 个股实时行情：现价/涨跌/开高低/量额/买卖五档前3档 |
| `get_event_warnings` | `GET /api/eventwarn/latest` | severity, limit | 盘后事件预警：解禁/减持/质押/回购/增持等（severity 过滤，danger 优先） |

未接入的其他只读端点（后续可扩展）：`/api/scan/latest`（每日扫描）、
`/api/shortlist/latest`（筑底启动等三策略短名单）、`/api/tailpick/shadow`、
`/api/xianren/shadow`、`/api/backtest/latest`、`/api/portfolio-check`（组合风控体检）、
`/api/quote/batch`（批量行情）、`/api/chart`（日K）、`/api/chart/minute`（分时）。
写操作端点（`/api/scan/run`、`/api/positions` POST、`/api/picks/add` 等）一律不做。

## 凭证说明

- `STOCKSHORT_URL`（必填）：服务入口，默认 `http://127.0.0.1:8765`（内网 IP 或反代域名按需修改）；
  跨网访问填公网反代地址。
- `STOCKSHORT_AUTH`（可选，password 类型）：Basic Auth，格式 `user:pass`；
  仅公网反代启用 auth_basic 时需要，非空时 server 自动附加 `Authorization: Basic` 头。
- 两个凭证均只存储在用户本机（WorkBuddy credentials），不上传云端。

## 本地测试

```bash
cd <项目目录>/connectors/stockshort

# 1. 装依赖
python3 -m venv .venv
.venv/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "mcp[cli]>=1.2,<2" httpx

# 2. 导出凭证（内网直连无需 AUTH）
export STOCKSHORT_URL="http://127.0.0.1:8765"
export STOCKSHORT_AUTH=""

# 3a. MCP Inspector 交互测试
.venv/bin/mcp dev stockshort_mcp/server.py

# 3b. 或 uvx 从本地构建运行（与 mcp.json 的正式形态一致）
UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple \
  ~/.local/bin/uvx --from . workbuddy-stock-mcp
```

## 错误处理约定

- 连接失败 → 提示检查 STOCKSHORT_URL / 网络可达性
- 401 → 提示 Basic Auth 缺失或不正确，指引更新 STOCKSHORT_AUTH（user:pass）
- 超时 / 非 200 / JSON 解析失败 → 返回可读中文错误，不抛栈给 AI

## 正式提交前 TODO

- [ ] **发布 PyPI 包**：`workbuddy-mcp-stockshort` 发布后 mcp.json 的 uvx 才能拉到
      （骨架阶段用 `uvx --from .` 或 `python -m stockshort_mcp` 验证）。
- [ ] **压测报告**：按 06 规范 2.2.5 完成压测（QPS ≥ 50、P50 ≤ 500ms、P99 ≤ 3000ms）。
      注：本服务为个人自建单机系统，如不上架公开市场可评估豁免。
- [ ] 用真实服务跑通全部 6 个 tool 的正路径（当前已验证 candidates/positions/
      rotation/detail 等 5 类端点连通）。
- [ ] 提交前对照 06D 第 13.8 提交检查清单逐项复核。
- [ ] 按灵感模块 08 规范：提交 Skill 时同步提交 3~5 个灵感案例。
