skz-quant-mcp 0.1.0__tar.gz

skz_quant_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  UV_CACHE_DIR: ${{ github.workspace }}/.uv-cache
+  UV_PYTHON_INSTALL_DIR: ${{ github.workspace }}/.uv-python
+  NPM_CONFIG_CACHE: ${{ github.workspace }}/.npm-cache
+
+jobs:
+  lint:
+    name: Lint and validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          version: "0.11.8"
+          enable-cache: true
+          cache-suffix: lint
+      - run: uv python install 3.12
+      - run: uv sync --locked --all-groups --python 3.12
+      - run: uv run ruff check src tests scripts
+      - run: uv run ruff format --check src tests scripts
+      - run: uv run python scripts/validate_connector.py connector/skz
+
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          version: "0.11.8"
+          enable-cache: true
+          cache-suffix: py-${{ matrix.python-version }}
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --locked --all-groups --python ${{ matrix.python-version }}
+      - run: uv run pytest
+
+  build:
+    name: Build release artifacts
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          version: "0.11.8"
+          enable-cache: true
+          cache-suffix: build
+      - run: uv python install 3.12
+      - run: uv sync --locked --all-groups --python 3.12
+      - name: Read package version
+        run: echo "PACKAGE_VERSION=$(uv run python -c 'import skz_mcp; print(skz_mcp.__version__)')" >> "$GITHUB_ENV"
+      - run: uv build --out-dir dist/pypi
+      - name: Build WorkBuddy Connector archive
+        run: |
+          mkdir -p dist/connector
+          (cd connector/skz && zip -r "../../dist/connector/shengkezhi-quant-connector-${PACKAGE_VERSION}.zip" . -x '*.DS_Store')
+      - name: Validate archives
+        run: |
+          python -m zipfile -t "dist/pypi/skz_quant_mcp-${PACKAGE_VERSION}-py3-none-any.whl"
+          unzip -t "dist/connector/shengkezhi-quant-connector-${PACKAGE_VERSION}.zip"
+      - uses: actions/upload-artifact@v7.0.1
+        with:
+          name: release-artifacts
+          path: dist/
+          if-no-files-found: error

skz_quant_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,93 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  UV_CACHE_DIR: ${{ github.workspace }}/.uv-cache
+  UV_PYTHON_INSTALL_DIR: ${{ github.workspace }}/.uv-python
+  NPM_CONFIG_CACHE: ${{ github.workspace }}/.npm-cache
+
+jobs:
+  build:
+    name: Verify and build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          version: "0.11.8"
+          enable-cache: true
+          cache-suffix: release
+      - run: uv python install 3.12
+      - run: uv sync --locked --all-groups --python 3.12
+      - name: Verify tag matches package version
+        run: |
+          PACKAGE_VERSION=$(uv run python -c 'import skz_mcp; print(skz_mcp.__version__)')
+          test "v${PACKAGE_VERSION}" = "${GITHUB_REF_NAME}"
+          echo "PACKAGE_VERSION=${PACKAGE_VERSION}" >> "$GITHUB_ENV"
+      - run: uv run ruff check src tests scripts
+      - run: uv run ruff format --check src tests scripts
+      - run: uv run pytest
+      - run: uv run python scripts/validate_connector.py connector/skz
+      - run: uv build --out-dir dist/pypi
+      - name: Check PyPI metadata
+        run: uvx --from twine twine check dist/pypi/*
+      - name: Build WorkBuddy Connector archive
+        run: |
+          mkdir -p dist/connector
+          (cd connector/skz && zip -r "../../dist/connector/shengkezhi-quant-connector-${PACKAGE_VERSION}.zip" . -x '*.DS_Store')
+      - name: Validate archives
+        run: |
+          python -m zipfile -t "dist/pypi/skz_quant_mcp-${PACKAGE_VERSION}-py3-none-any.whl"
+          unzip -t "dist/connector/shengkezhi-quant-connector-${PACKAGE_VERSION}.zip"
+      - uses: actions/upload-artifact@v7.0.1
+        with:
+          name: release-artifacts
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: pypi
+      url: https://pypi.org/p/skz-quant-mcp
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8.0.1
+        with:
+          name: release-artifacts
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@v1.14.2
+        with:
+          packages-dir: dist/pypi
+
+  github-release:
+    name: Create GitHub release
+    runs-on: ubuntu-latest
+    needs: [build, publish-pypi]
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8.0.1
+        with:
+          name: release-artifacts
+          path: dist
+      - uses: softprops/action-gh-release@v3.0.3
+        with:
+          generate_release_notes: true
+          files: |
+            dist/pypi/*
+            dist/connector/*

skz_quant_mcp-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.npm-cache/
+.venv/
+.uv-cache/
+.uv-python/
+.uv-tools/
+dist/
+build/
+*.egg-info/
+.DS_Store

skz_quant_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

skz_quant_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shanghai Shengkezhi Intelligent Technology Co., Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skz_quant_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,325 @@
+Metadata-Version: 2.5
+Name: skz-quant-mcp
+Version: 0.1.0
+Summary: MCP bridge for the Shengkezhi skz quant CLI
+Project-URL: Documentation, https://docs.shengkezhi.com/install
+Project-URL: Homepage, https://github.com/sheng-ke-zhi/skz-quant-mcp
+Project-URL: Issues, https://github.com/sheng-ke-zhi/skz-quant-mcp/issues
+Project-URL: Repository, https://github.com/sheng-ke-zhi/skz-quant-mcp.git
+Author: Shengkezhi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: mcp,quant,shengkezhi,skz,workbuddy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: mcp<3,>=2.1.1
+Requires-Dist: typing-extensions>=4.12
+Description-Content-Type: text/markdown
+
+# 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.0
+```
+
+发包前如需在 WorkBuddy 中测试，可复制一份 `connector/skz/`，将副本 `mcp.json` 中的发布坐标改为本地 wheel 绝对路径：
+
+```text
+/Users/jun/Documents/vscodePro/skz-mcp/dist/skz_quant_mcp-0.1.0-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.0-py3-none-any.whl
+dist/skz_quant_mcp-0.1.0.tar.gz
+```
+
+发布后，应从目标包索引重新执行：
+
+```bash
+uvx --from skz-quant-mcp==0.1.0 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.0 -m "Release 0.1.0"
+git push origin v0.1.0
+```
+
+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 调用链。