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 为唯一契约来源。

Related MCP server: Quant Research Platform MCP Server

环境要求

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：

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

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

检查版本：

skz --version

预期返回类似：

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

开发与测试

安装开发依赖：

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

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

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 服务：

UV_CACHE_DIR=.uv-cache uv run skz-mcp

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

使用 MCP Inspector 测试

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

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

启动 MCP Inspector：

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。

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

unset SKZ_API_KEY

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

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

先准备环境：

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 历史：

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 编辑器中保存：

{
  "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 文件：

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

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

WorkBuddy Connector

提交目录位于 connector/skz/：

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 工具、分页、重试、写后核对及用户确认边界。

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

skz-quant-mcp==0.1.1

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

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

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

构建与发布

构建 wheel 和源码包：

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

产物：

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

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

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：

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

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

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 调用链。