feat(mcp): hy3-research-mcp — Hy3-powered research/code-review/document-Q&A MCP server (issue #3) - #212
Open
TPJHtpjh wants to merge 7 commits into
Open
feat(mcp): hy3-research-mcp — Hy3-powered research/code-review/document-Q&A MCP server (issue #3)#212TPJHtpjh wants to merge 7 commits into
TPJHtpjh wants to merge 7 commits into
Conversation
Build an MCP Server powered by Hy3 (rhinobird2026): - 4 stdio tools: web_search, deep_research, analyze_document, review_code - Hy3 called via OpenAI-compatible API with reasoning_effort control - 2 external data sources: web search (Tavily/Bocha) + local file parsing - All secrets via environment variables, no hardcoded keys - Client configs for CodeBuddy/WorkBuddy, Cursor, Cline - 20 mocked unit tests + real stdio smoke test, bilingual README
- scripts/validate_clients.py proves the server works end-to-end with two distinct MCP clients (official MCP Python SDK + hand-rolled JSON-RPC) - scripts/demo_session.py, make_demo_gif.py, record_demo.sh + assets/demo.gif and DEMO_GUIDE.md document the headless demo runbook - auto-load .env via python-dotenv so local runs work out-of-the-box - document two-client validation in README
- build dist/hy3_research_mcp-0.1.0-py3-none-any.whl (one-click install via 'pip install .' or the wheel) - examples/local.mcp.json: single-file client config for the local install (command 'hy3-research-mcp', keys injected via env) - satisfies issue's one-click install + no-hardcoded-keys requirements - verified the packaged console script starts over stdio and exposes all 4 tools
- server.py now uses find_dotenv(usecwd=True) so .env is discovered from the client's launch directory upward; API keys stay out of the MCP config - add mcp.json (no env block) for use in both WorkBuddy and Trae - examples/local.mcp.json updated to the secret-free form - rebuilt wheel (dist/) with the .env loading fix
- Load secrets from .env with resolution order: HY3_ENV_FILE -> launch dir (walk-up) -> ~/.config/hy3-research-mcp/.env and ~/.hy3-research-mcp.env. Keeps API keys out of mcp.json. - Validate configuration lazily per tool call instead of at startup, so the server still starts and lists tools before credentials are set. - Promote pypdf to a core dependency (PDF works out of the box). - Add ready-to-use .workbuddy/mcp.json and .trae/mcp.json (secret-free, bare 'hy3-research-mcp' command) for one-click client setup. - Add scripts/probe_console.py to verify the bare command over stdio. - Update README accordingly.
- assets/demo_workbuddy.mp4 + assets/demo_trae.mp4: compressed (1600x1000, ~5-9MB each) live recordings driving all 4 tools from two real MCP clients. - hy3_research_demo_summary.md: per-tool inputs/outputs/citations write-up. - examples/demo_prompt.md: copy-paste demo prompt (comprehensive + per-tool). - scripts/probe_trae.py: verifies the server launches from a foreign cwd with HY3_ENV_FILE (matches how clients invoke it). - README: add a 'Real-client screen recordings' section. - .gitignore: exclude local-only artifacts (session memory, task PDF, raw screen captures, logs).
Author
演示视频直达（可在线播放，均 < 10MB）
逐工具输入/输出/引用：hy3_research_demo_summary.md 视频均在本 PR 的 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
概述 / Summary
本 PR 实现 issue #3 要求的 hy3-research-mcp：一个由 Hy3 驱动的 MCP Server（官方 Python SDK / FastMCP / stdio），提供 4 个工具，串成一条完整的研究流水线：
web_searchdeep_research[n]引用的研究报告reasoning_effort=high/lowanalyze_documentno_think/low/highreview_codehigh外部数据源（2 个）：web 搜索 API + 本地文件读取，满足“额外接入 1~2 个数据源”要求。
Hy3 接入：OpenAI 兼容端点（vLLM/SGLang/托管 API），
reasoning_effort经chat_template_kwargs传入；利用 Hy3 256K 长上下文并做字符预算截断。所有 Key 走.env，mcp.json零明文密钥。双客户端验证（真实录屏）
assets/demo_workbuddy.mp4assets/demo_trae.mp4两端均端到端跑通全部 4 个工具；逐工具输入/输出/引用见
hy3_research_demo_summary.md。另由
scripts/validate_clients.py用「官方 MCP Python SDK 客户端 + 手写 JSON-RPC 客户端」完成协议级双客户端验证（全部 PASS）。一键安装
uvx --from git+https://github.com/TPJHtpjh/Hy3-MCP.git@rhinobird2026#subdirectory=mcp-server/hy3-research-mcp hy3-research-mcp # 或 pip install . / install.sh / install.ps1，详见 mcp-server/hy3-research-mcp/README.md验收对照
reasoning_effort分级）assets/demo_*.mp4）请评审，谢谢！