feat(mcp): add Hy3 data analyst server

mcp-servers/hy3-data-analyst/.env.example

@@ -0,0 +1,9 @@
+# Local vLLM/SGLang defaults. Use a real key only when your endpoint requires one.
+HY3_API_BASE=http://127.0.0.1:8000/v1
+HY3_API_KEY=EMPTY
+HY3_MODEL=hy3
+
+# Only files below this directory can be read by MCP tools.
+HY3_DATA_DIR=/absolute/path/to/your/data
+HY3_MAX_FILE_BYTES=10485760
+HY3_TIMEOUT_SECONDS=120

mcp-servers/hy3-data-analyst/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/

mcp-servers/hy3-data-analyst/README.md

@@ -0,0 +1,175 @@
+# Hy3 Data Analyst MCP Server
+
+[中文说明](README_CN.md)
+
+A local, stdio-based [Model Context Protocol](https://modelcontextprotocol.io/) server that
+combines safe CSV/JSON inspection with Tencent Hy3 reasoning. It is designed for data-quality,
+business-analysis, and report-writing workflows in CodeBuddy, WorkBuddy, Cursor, and other MCP
+clients.
+
+![Protocol demo](docs/demo.gif)
+
+## Tools
+
+| Tool | Hy3 call | Purpose |
+| --- | --- | --- |
+| `profile_dataset` | No | Inspect schema, missing values, unique counts, numeric statistics, and bounded samples |
+| `analyze_dataset` | Yes | Answer a question using the generated profile and sample rows |
+| `generate_data_report` | Yes | Produce an evidence-grounded Markdown report for a stated objective |
+
+All tools accept `.csv`, `.json`, `.jsonl`, and `.ndjson`. Files must be below `HY3_DATA_DIR`.
+
+## Requirements
+
+- Python 3.10 or newer
+- [`uv`](https://docs.astral.sh/uv/) (recommended) or `pipx`
+- A Hy3 OpenAI-compatible endpoint for the two reasoning tools. Follow the repository's
+  [deployment guide](../../README.md#deployment) to start vLLM or SGLang.
+
+## One-command install
+
+From this directory:
+
+```bash
+uv tool install .
+```
+
+The `hy3-data-analyst` command is then available to MCP clients. To update an existing install:
+
+```bash
+uv tool install --force .
+```
+
+For development, no global install is required. A non-editable sync avoids hidden `.pth`
+compatibility issues in newer Python maintenance releases:
+
+```bash
+uv sync --dev --no-editable
+uv run --no-sync hy3-data-analyst
+```
+
+The process uses stdio, so an empty terminal after startup is expected. MCP clients manage it
+automatically.
+
+## Configuration
+
+No API key is stored in source code. Configure the server process through environment variables:
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `HY3_API_BASE` | `http://127.0.0.1:8000/v1` | OpenAI-compatible Hy3 base URL |
+| `HY3_API_KEY` | `EMPTY` | API key; `EMPTY` is suitable for an unsecured local server |
+| `HY3_MODEL` | `hy3` | Served model name |
+| `HY3_DATA_DIR` | Server working directory | Only directory the tools may read |
+| `HY3_MAX_FILE_BYTES` | `10485760` (10 MiB) | Per-file safety limit |
+| `HY3_TIMEOUT_SECONDS` | `120` | Hy3 request timeout |
+
+Copy [`.env.example`](.env.example) as a reference, but pass values from the MCP client config or a
+secret manager. Do not commit a real key.
+
+## Client setup
+
+Before using a template, replace all `/ABSOLUTE/PATH/...` placeholders. Use `command -v uvx` to get
+the executable path. Absolute paths are important because desktop apps may use a smaller `PATH`
+than your terminal. The templates use `uvx --from <package-path>`, which creates an isolated,
+non-editable install and needs no manual activation.
+
+### CodeBuddy / WorkBuddy
+
+CodeBuddy's current project-level config is `<project>/.mcp.json`. Copy
+[`client-configs/codebuddy.mcp.json`](client-configs/codebuddy.mcp.json) there, update its paths and
+environment, then restart or refresh MCP servers.
+
+For a one-off CLI check without changing user configuration:
+
+```bash
+codebuddy \
+  --mcp-config client-configs/codebuddy.mcp.json \
+  --strict-mcp-config \
+  --settings '{"enabledMcpjsonServers":["hy3-data-analyst"]}' \
+  -p "Use profile_dataset on examples/sample_sales.csv and report the row count."
+```
+
+WorkBuddy's custom MCP dialog accepts the same stdio JSON. A separate
+[`client-configs/workbuddy.mcp.json`](client-configs/workbuddy.mcp.json) is included for direct
+import.
+
+### Cursor
+
+Copy [`client-configs/cursor.mcp.json`](client-configs/cursor.mcp.json) to
+`<project>/.cursor/mcp.json`, update its paths and environment, then enable `hy3-data-analyst` in
+Cursor's MCP settings.
+
+## Tool-call examples
+
+Profile a file without a model call:
+
+```json
+{
+  "file_path": "examples/sample_sales.csv",
+  "max_rows": 10000,
+  "sample_rows": 5
+}
+```
+
+Ask Hy3 an analytical question:
+
+```json
+{
+  "file_path": "examples/sample_sales.csv",
+  "question": "Which region has the strongest observed revenue, and what are the limitations?",
+  "reasoning_effort": "high",
+  "sample_rows": 10
+}
+```
+
+Generate a decision-oriented report:
+
+```json
+{
+  "file_path": "examples/sample_sales.csv",
+  "objective": "Help a sales manager prioritize regions while highlighting data-quality risks",
+  "reasoning_effort": "high"
+}
+```
+
+See [`examples/demo-prompts.md`](examples/demo-prompts.md) for prompts that MCP clients can execute.
+
+## Verification
+
+Run formatting/static checks, unit tests, and an actual stdio protocol round trip:
+
+```bash
+uv sync --dev --no-editable
+uv run --no-sync ruff check .
+uv run --no-sync pytest
+uv run --no-sync python scripts/check_mcp.py
+```
+
+The smoke client initializes an MCP session, verifies the exact three-tool inventory, and calls
+`profile_dataset` on the included sample. The test suite mocks the unavailable remote model while
+verifying that dataset context, the question, and reasoning mode are sent through the Hy3 call
+path. To verify a real model deployment, set `HY3_API_BASE`/`HY3_API_KEY` and call either reasoning
+tool from an MCP client.
+
+## Safety and data boundaries
+
+- Resolved paths cannot escape `HY3_DATA_DIR`, including through `..` or symlinks.
+- Unsupported formats and oversized files are rejected before parsing.
+- At most 100,000 rows are scanned and at most 20 sample rows are sent to Hy3.
+- API keys are environment-only and redacted if an SDK error happens to include them.
+- `profile_dataset` is fully local. The two Hy3 tools send the generated profile and selected sample
+  rows to the configured endpoint, so use `sample_rows=0` for sensitive datasets.
+- The server never modifies source datasets.
+
+## Current limitations
+
+- Numeric statistics are descriptive (`min`, `max`, and `mean`) and do not replace a full analytics
+  engine.
+- Nested JSON values are serialized as strings; deeply nested normalization is intentionally out of
+  scope.
+- `rows_scanned` is the scanned count, not a guaranteed total when `truncated` is `true`.
+
+## License
+
+Apache License 2.0, consistent with the parent repository.

mcp-servers/hy3-data-analyst/README_CN.md

@@ -0,0 +1,153 @@
+# Hy3 数据分析 MCP Server
+
+这是一个本地 stdio 模式的 MCP Server，把 CSV/JSON 安全读取、基础统计与腾讯 Hy3 推理组合
+为可复用的数据分析工作流，可接入 CodeBuddy、WorkBuddy、Cursor 等 MCP 客户端。
+
+![协议调用演示](docs/demo.gif)
+
+## 提供的工具
+
+| 工具 | 是否调用 Hy3 | 功能 |
+| --- | --- | --- |
+| `profile_dataset` | 否 | 检查字段类型、缺失值、唯一值、数值统计和有限样例 |
+| `analyze_dataset` | 是 | 基于数据画像和样例回答具体分析问题 |
+| `generate_data_report` | 是 | 按给定目标生成有数据依据的 Markdown 报告 |
+
+支持 `.csv`、`.json`、`.jsonl`、`.ndjson`，所有文件必须位于 `HY3_DATA_DIR` 内。
+
+## 环境要求
+
+- Python 3.10+
+- 推荐使用 [`uv`](https://docs.astral.sh/uv/)，也可用 `pipx`
+- 后两个工具需要 Hy3 的 OpenAI 兼容接口；本地部署方式见仓库的
+  [部署文档](../../README_CN.md#部署)
+
+## 一条命令安装
+
+在当前目录运行：
+
+```bash
+uv tool install .
+```
+
+安装后，MCP 客户端可直接启动 `hy3-data-analyst`。开发模式无需全局安装；使用非 editable
+安装可避开新版 Python 对隐藏 `.pth` 文件的兼容问题：
+
+```bash
+uv sync --dev --no-editable
+uv run --no-sync hy3-data-analyst
+```
+
+该命令使用 stdio 通信，直接在终端启动后没有输出属于正常现象。
+
+## 环境变量
+
+代码中不保存 API Key，全部配置由 MCP 客户端传入：
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `HY3_API_BASE` | `http://127.0.0.1:8000/v1` | Hy3 OpenAI 兼容接口地址 |
+| `HY3_API_KEY` | `EMPTY` | 接口密钥；无鉴权的本地服务可用 `EMPTY` |
+| `HY3_MODEL` | `hy3` | 服务端模型名 |
+| `HY3_DATA_DIR` | Server 启动目录 | 工具唯一允许读取的根目录 |
+| `HY3_MAX_FILE_BYTES` | `10485760` | 单文件大小上限（10 MiB） |
+| `HY3_TIMEOUT_SECONDS` | `120` | Hy3 请求超时秒数 |
+
+可参考 [`.env.example`](.env.example)，不要把真实密钥提交进 Git。
+
+## 客户端配置
+
+先把模板中的 `/ABSOLUTE/PATH/...` 全部替换为本机绝对路径；`command -v uvx` 可查看 `uvx`
+的真实位置。桌面应用的 `PATH` 往往和终端不同，因此模板建议使用绝对路径。模板通过
+`uvx --from <包路径>` 创建隔离的非 editable 安装，无需手动激活环境。
+
+### CodeBuddy / WorkBuddy
+
+CodeBuddy 当前推荐的项目级配置文件是 `<项目根目录>/.mcp.json`。将
+[`client-configs/codebuddy.mcp.json`](client-configs/codebuddy.mcp.json) 复制到该位置，替换路径
+及环境变量，然后刷新 MCP Server。
+
+也可用 CLI 做一次性验证，而不修改用户级配置：
+
+```bash
+codebuddy \
+  --mcp-config client-configs/codebuddy.mcp.json \
+  --strict-mcp-config \
+  --settings '{"enabledMcpjsonServers":["hy3-data-analyst"]}' \
+  -p "调用 profile_dataset 检查 examples/sample_sales.csv，并告诉我行数。"
+```
+
+WorkBuddy 的自定义 MCP 界面接受相同的 stdio JSON，可直接导入
+[`client-configs/workbuddy.mcp.json`](client-configs/workbuddy.mcp.json)。
+
+### Cursor
+
+将 [`client-configs/cursor.mcp.json`](client-configs/cursor.mcp.json) 复制到
+`<项目根目录>/.cursor/mcp.json`，替换路径和环境变量，然后在 Cursor MCP 设置中启用。
+
+## 调用示例
+
+无需模型即可检查数据：
+
+```json
+{
+  "file_path": "examples/sample_sales.csv",
+  "max_rows": 10000,
+  "sample_rows": 5
+}
+```
+
+让 Hy3 回答数据问题：
+
+```json
+{
+  "file_path": "examples/sample_sales.csv",
+  "question": "哪个地区的已观察营收最强？这个结论有什么局限？",
+  "reasoning_effort": "high",
+  "sample_rows": 10
+}
+```
+
+让 Hy3 生成报告：
+
+```json
+{
+  "file_path": "examples/sample_sales.csv",
+  "objective": "帮助销售经理确定地区优先级，同时指出数据质量风险",
+  "reasoning_effort": "high"
+}
+```
+
+## 验证
+
+```bash
+uv sync --dev --no-editable
+uv run --no-sync ruff check .
+uv run --no-sync pytest
+uv run --no-sync python scripts/check_mcp.py
+```
+
+最后一条命令会真正启动 stdio Server、完成 MCP 初始化、核对 3 个工具并调用
+`profile_dataset`。测试会 mock 当前不可用的远端模型，但会验证问题、数据上下文和推理模式确实
+进入 Hy3 API 调用路径。若要验证真实推理，请设置可用的 `HY3_API_BASE`/`HY3_API_KEY` 后，
+从 MCP 客户端调用后两个工具。
+
+## 安全边界
+
+- 解析后的路径不能越过 `HY3_DATA_DIR`，`..` 与符号链接也不能绕过。
+- 不支持的格式和超大文件会在解析前拒绝。
+- 最多扫描 100,000 行，最多向 Hy3 发送 20 行样例。
+- API Key 只来自环境变量，SDK 错误信息中的 Key 会被脱敏。
+- `profile_dataset` 完全本地执行；后两个工具会把画像和所选样例发送到配置的 Hy3 接口。
+  敏感数据可设置 `sample_rows=0`。
+- Server 不会修改原始数据文件。
+
+## 已知限制
+
+- 数值统计仅包含 `min`、`max`、`mean`，不能代替完整数据分析引擎。
+- 嵌套 JSON 值会序列化为字符串，不做深层展开。
+- 当 `truncated=true` 时，`rows_scanned` 是已扫描行数，不代表文件总行数。
+
+## License
+
+Apache License 2.0，与上级项目保持一致。

mcp-servers/hy3-data-analyst/VALIDATION.md

@@ -0,0 +1,21 @@
+# Validation record
+
+Validated locally on 2026-07-23 (Asia/Shanghai).
+
+| Layer | Client/runtime | Result |
+| --- | --- | --- |
+| Static checks | Ruff 0.15.22 | Passed |
+| Unit/integration tests | pytest on CPython 3.12 | Passed |
+| MCP protocol | MCP Python SDK `ClientSession` over stdio | Initialized, listed 3 tools, called `profile_dataset` |
+| AI client | WorkBuddy 2.115.0 bundled CodeBuddy CLI | Loaded the MCP server and called `profile_dataset` |
+
+Observed result for `examples/sample_sales.csv` in both MCP checks:
+
+- `rows_scanned`: 6
+- `column_count`: 6
+- `units`: 1 missing value
+
+The machine did not provide a reachable Hy3 endpoint or `HY3_API_KEY`. The Hy3 request path is
+therefore covered by mocked integration tests that assert the OpenAI-compatible request payload,
+reasoning mode, grounded dataset context, response handling, and client cleanup. A live model call
+remains environment-dependent and must not be represented as verified until an endpoint is supplied.

mcp-servers/hy3-data-analyst/client-configs/codebuddy.mcp.json

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "hy3-data-analyst": {
+      "type": "stdio",
+      "command": "/ABSOLUTE/PATH/TO/uvx",
+      "args": [
+        "--from",
+        "/ABSOLUTE/PATH/TO/Hy3/mcp-servers/hy3-data-analyst",
+        "hy3-data-analyst"
+      ],
+      "env": {
+        "HY3_API_BASE": "http://127.0.0.1:8000/v1",
+        "HY3_API_KEY": "EMPTY",
+        "HY3_MODEL": "hy3",
+        "HY3_DATA_DIR": "/ABSOLUTE/PATH/TO/DATA"
+      },
+      "description": "Profile local datasets and analyze them with Tencent Hy3"
+    }
+  }
+}