# SKZ Quant MCP

[![CI](https://github.com/sheng-ke-zhi/skz-quant-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sheng-ke-zhi/skz-quant-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/skz-quant-mcp.svg)](https://pypi.org/project/skz-quant-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/skz-quant-mcp.svg)](https://pypi.org/project/skz-quant-mcp/)

`skz-quant-mcp` 是胜可知量化平台的 MCP 服务。它通过官方 `skz` CLI 向 MCP 客户端提供投研、因子、策略和组合能力，并附带符合 WorkBuddy Connector 规范的 Token 表单和 Skill。

## 架构

MCP 服务提供四个工具：

- `skz_status`：检查 SKZ CLI、contract 版本和认证状态。
- `skz_help`：读取当前 CLI 的真实帮助信息，避免在 MCP 中复制易变化的参数说明。
- `skz_read`：执行白名单内的只读命令，并强制设置 `SKZ_READ_ONLY=1`。
- `skz_write`：执行白名单内的写入、付费触发和资产处置命令；每次调用都要求记录用户的明确确认。

WorkBuddy 使用 `auth_mode: "token"` 在本地收集 `SKZ_API_KEY`。MCP 进程随后在独立临时 HOME 中通过 stdin 执行 `skz auth add`，不会把 Key 放进命令参数，也不会修改用户全局的 `~/.config/skz/credentials`。

SKZ CLI 的解析顺序如下：

1. `SKZ_BIN` 指定的可执行文件；
2. 系统 PATH 中已安装的 `skz`；
3. WorkBuddy 托管 Node 20 环境中的 `npx --package @shengkezhi-com/skz-quant-cli@0.1.31`。

因此 WorkBuddy 用户无需提前安装 SKZ CLI。HTTP 协议、凭据格式、只读策略、退出码和业务 JSON 结构仍以官方 CLI 为唯一契约来源。

## 环境要求

### WorkBuddy

Connector 要求 WorkBuddy `5.0.0` 或更高版本，并由 `mcp.json` 请求托管 Node 20。WorkBuddy 通过 `uvx` 安装和运行 Python MCP 包，通过 `npx` 在需要时提供官方 SKZ CLI。

### 本地开发

本地开发需要：

- Python 3.10 或更高版本；
- `uv`；
- 已安装的 SKZ CLI，或者 Node.js 18 及以上版本。

安装 SKZ CLI：

```bash
# macOS / Linux
brew install sheng-ke-zhi/tap/skz

# 任意支持 Node.js 的平台
npm install -g @shengkezhi-com/skz-quant-cli
```

检查版本：

```bash
skz --version
```

预期返回类似：

```json
{"cli":"0.1.31","contract":"4.1"}
```

## 开发与测试

安装开发依赖：

```bash
UV_CACHE_DIR=.uv-cache \
UV_PYTHON_INSTALL_DIR=.uv-python \
uv sync
```

运行静态检查、测试和 Connector 校验：

```bash
UV_CACHE_DIR=.uv-cache \
UV_TOOL_DIR=.uv-tools \
UV_PYTHON_INSTALL_DIR=.uv-python \
uvx --from ruff ruff check src tests scripts

UV_CACHE_DIR=.uv-cache \
UV_PYTHON_INSTALL_DIR=.uv-python \
uv run pytest

UV_CACHE_DIR=.uv-cache \
UV_PYTHON_INSTALL_DIR=.uv-python \
uv run python scripts/validate_connector.py connector/skz
```

直接启动 MCP stdio 服务：

```bash
UV_CACHE_DIR=.uv-cache uv run skz-mcp
```

stdio 服务会等待 MCP Host 输入，不显示普通终端提示，这是正常行为。

## 使用 MCP Inspector 测试

不要把真实 API Key 写进命令历史、源文件、测试夹具或 `mcp.json`。可以先隐藏输入并导出临时环境变量：

```bash
printf "请输入只读 SKZ API Key: "
read -s SKZ_API_KEY
printf "\n"
export SKZ_API_KEY
```

启动 MCP Inspector：

```bash
NPM_CONFIG_CACHE="$PWD/.npm-cache" \
npx -y @modelcontextprotocol/inspector \
"$PWD/.venv/bin/python" -m skz_mcp
```

在 Inspector 中依次验证：

1. `skz_status`：应返回 `ok: true`、`credentialMode: "workbuddy-token"` 和 `auth.present: true`；
2. `skz_read`，参数 `{"args":["whoami"]}`；
3. `skz_read`，参数 `{"args":["markets"]}`；
4. 确认工具列表只包含 `skz_status`、`skz_help`、`skz_read`、`skz_write`。

结束后清理当前终端变量：

```bash
unset SKZ_API_KEY
```

## 在 WorkBuddy MCP 管理器中测试本地源码

WorkBuddy 的“配置 MCP”页面只编辑 `~/.workbuddy/mcp.json`，不是 Connector ZIP 上传入口。发包前可以让它直接启动当前项目。

先准备环境：

```bash
cd /Users/jun/Documents/vscodePro/skz-mcp
UV_CACHE_DIR=.uv-cache UV_PYTHON_INSTALL_DIR=.uv-python uv sync
```

安全创建本地测试 Key 文件，不把 Key 写入 `mcp.json` 或 shell 历史：

```bash
mkdir -p "$HOME/.workbuddy"
umask 077
printf "请输入只读 SKZ API Key: "
read -s SKZ_API_KEY
printf "\n"
printf '%s\n' "$SKZ_API_KEY" > "$HOME/.workbuddy/skz-quant-mcp-local.key"
unset SKZ_API_KEY
chmod 600 "$HOME/.workbuddy/skz-quant-mcp-local.key"
```

在 WorkBuddy 的 MCP 编辑器中保存：

```json
{
  "mcpServers": {
    "skz-quant-local": {
      "type": "stdio",
      "command": "/Users/jun/Documents/vscodePro/skz-mcp/scripts/run_local_workbuddy_mcp.sh",
      "args": [],
      "env": {
        "SKZ_API_KEY_FILE": "/Users/jun/.workbuddy/skz-quant-mcp-local.key",
        "SKZ_BIN": "/opt/homebrew/bin/skz"
      },
      "timeout": 60000
    }
  }
}
```

保存后新建会话，依次要求调用 `skz_status`、`skz_read` 的 `whoami` 和 `markets`。预期 `credentialMode` 为 `workbuddy-token`、`auth.present` 为 `true`，且能发现四个工具。测试结束后删除本地 Key 文件：

```bash
rm "$HOME/.workbuddy/skz-quant-mcp-local.key"
```

这个页面只验证 MCP 服务和工具，不会安装 Connector 的 Logo、Token 表单和 Skill；完整 Connector 体验仍需市场包或平台提供的本地 Connector 导入能力。

## WorkBuddy Connector

提交目录位于 `connector/skz/`：

```text
connector/skz/
├── connector-meta.json
├── mcp.json
├── token-schema.json
├── icon.svg
└── skills/
    └── shengkezhi-quant-skill/
        └── SKILL.md
```

当前配置遵循 MCP + Skill Token 模式：

- 只包含一个 stdio MCP Server；
- `auth_mode: "token"`；
- `token-schema.json` 的 `SKZ_API_KEY` 与 `mcp.json` 中的 `${SKZ_API_KEY}` 一致；
- 使用 WorkBuddy 托管 Node 20；
- 最低 WorkBuddy 版本为 `5.0.0`；
- 元信息和 Token 表单包含中英文文案；
- Skill 覆盖所有 MCP 工具、分页、重试、写后核对及用户确认边界。

正式配置使用以下发布坐标：

```text
skz-quant-mcp==0.1.1
```

发包前如需在 WorkBuddy 中测试，可复制一份 `connector/skz/`，将副本 `mcp.json` 中的发布坐标改为本地 wheel 绝对路径：

```text
/Users/jun/Documents/vscodePro/skz-mcp/dist/skz_quant_mcp-0.1.1-py3-none-any.whl
```

不要修改准备提交的正式 `mcp.json`。

## 构建与发布

构建 wheel 和源码包：

```bash
UV_CACHE_DIR=.uv-cache \
UV_PYTHON_INSTALL_DIR=.uv-python \
uv build
```

产物：

```text
dist/skz_quant_mcp-0.1.1-py3-none-any.whl
dist/skz_quant_mcp-0.1.1.tar.gz
```

发布后，应从目标包索引重新执行：

```bash
uvx --from skz-quant-mcp==0.1.1 skz-mcp
```

然后再提交 `connector/skz/` 给 WorkBuddy 审核。

### GitHub Actions 发布

`.github/workflows/ci.yml` 在 main 分支和 Pull Request 上执行：

- Ruff lint 和 format check；
- Python 3.10、3.11、3.12、3.13 测试；
- Connector 结构和 Skill 契约校验；
- wheel、sdist 和 Connector ZIP 构建。

`.github/workflows/release.yml` 在推送 `vX.Y.Z` tag 时执行完整验证，并通过 PyPI Trusted Publishing 发布。发布前需要在 PyPI 配置一次 Trusted Publisher：

```text
Owner: sheng-ke-zhi
Repository: skz-quant-mcp
Workflow: release.yml
Environment: pypi
```

首次发布前可使用 PyPI 的 Pending Publisher 创建项目；不需要向 GitHub 添加 PyPI API Token。然后发布版本：

```bash
git tag -a v0.1.1 -m "Release 0.1.1"
git push origin v0.1.1
```

workflow 会校验 tag 与 Python 包版本完全一致，向 PyPI 上传 wheel 和 sdist，并创建附带 Connector ZIP 的 GitHub Release。

## 安全边界

- MCP 工具禁止调用 `auth`、`plugin` 和 `update`。
- 所有 CLI 参数通过 `subprocess.run` 参数数组传递，不使用 shell。
- 拒绝 `--token`、`--api-key`、`--config`、`--base-url` 等敏感覆盖参数。
- 读写命令使用显式白名单，未知命令默认拒绝。
- Token 仅通过 stdin 写入隔离临时凭据目录，进程结束后删除。
- 子进程只继承必要环境变量，不继承其他 Connector 密钥。
- 输出、错误和异常中的 `sk_` 凭据会统一脱敏。
- 自动 CLI 回退固定使用官方 npm 包 `0.1.31`，不动态拼接 shell 命令。
- 读调用强制 `SKZ_READ_ONLY=1`。
- 写调用不自动重试；写超时返回 `outcome: "unknown"`，必须先查询已有资源。
- `skz_write` 的确认字段只是审计上下文，不能代替真实用户确认。Skill 要求先展示具体参数和影响，再取得本次直接确认。

## 验证状态

当前版本已经验证：

- MCP 协议初始化和四个工具发现；
- 工具输入 Schema 和 annotations；
- 系统 SKZ CLI 路径；
- PATH 中没有系统 `skz` 时的 npx 自动回退；
- WorkBuddy Token 隔离认证；
- 使用临时只读 Key 调用 `whoami` 和 `markets`；
- 全局 SKZ credentials 不变；
- MCP 退出后临时 credentials 被删除；
- wheel 安装后的完整 stdio MCP 调用链。