feat(tools): add HugeGraph DeepWiki assistant#3045
Conversation
dosubot
Bot
added
size:XL
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds a standalone “HugeGraph DeepWiki” skill/module that integrates with the official DeepWiki MCP server to answer repository-scoped questions, with local caching and a small CLI for querying/inspecting wiki content.
Changes:
- Introduces a Python MCP client CLI (
deepwiki_mcp.py) with cached wiki retrieval and local snippet search. - Adds repository alias configuration (
references/repos.json) and agent/tool wiring (agents/openai.yaml). - Adds plugin manifests and end-user documentation (README + SKILL.md) for Claude Code/Codex installation and usage.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| tools/ai/hugegraph-deepwiki-skill/plugins/hugegraph-deepwiki-skill/skills/hugegraph-deepwiki-skill/scripts/deepwiki_mcp.py | Implements MCP client + caching + CLI commands (ask/structure/contents/context/tools). |
| tools/ai/hugegraph-deepwiki-skill/plugins/hugegraph-deepwiki-skill/skills/hugegraph-deepwiki-skill/references/repos.json | Defines default repo alias (hugegraph → apache/hugegraph). |
| tools/ai/hugegraph-deepwiki-skill/plugins/hugegraph-deepwiki-skill/skills/hugegraph-deepwiki-skill/agents/openai.yaml | Configures DeepWiki MCP tool dependency and default prompt metadata. |
| tools/ai/hugegraph-deepwiki-skill/plugins/hugegraph-deepwiki-skill/skills/hugegraph-deepwiki-skill/SKILL.md | Documents workflow/routing rules for using cache first, then online ask. |
| tools/ai/hugegraph-deepwiki-skill/plugins/hugegraph-deepwiki-skill/.codex-plugin/plugin.json | Codex plugin metadata for packaging and UI surface. |
| tools/ai/hugegraph-deepwiki-skill/plugins/hugegraph-deepwiki-skill/.claude-plugin/plugin.json | Claude plugin metadata for packaging. |
| tools/ai/hugegraph-deepwiki-skill/README.md | English installation + usage documentation. |
| tools/ai/hugegraph-deepwiki-skill/README-zh.md | Chinese installation + usage documentation. |
| tools/ai/hugegraph-deepwiki-skill/.claude-plugin/marketplace.json | Marketplace pointer for Claude plugin distribution. |
| tools/ai/hugegraph-deepwiki-skill/.agents/plugins/marketplace.json | Marketplace pointer for agent/plugin discovery. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| content_type = response.headers.get("Content-Type", "") | ||
| if "text/event-stream" in content_type: | ||
| parsed = read_sse_response(response, payload.get("id")) | ||
| else: | ||
| text = response.read().decode("utf-8") | ||
| if not text.strip(): | ||
| raise McpError("DeepWiki MCP returned an empty response.") | ||
| parsed = parse_json(text) |
There was a problem hiding this comment.
Fixed in 278a7f3f: updated the DeepWiki MCP client as suggested and re-ran local validation, including mvn apache-rat:check -DskipTests, Claude plugin validation, Codex temp install, structure, and context commands.
| def load_repos() -> dict[str, dict[str, Any]]: | ||
| with REPOS_PATH.open("r", encoding="utf-8") as file: | ||
| return json.load(file) | ||
|
|
||
|
|
||
| def resolve_repo(alias_or_name: str) -> str: | ||
| repos = load_repos() | ||
| profile = repos.get(alias_or_name) | ||
| if profile is None: | ||
| known = ", ".join(sorted(repos)) | ||
| raise McpError(f"Unknown repository alias '{alias_or_name}'. Known aliases: {known}.") | ||
| if not profile.get("enabled", False): | ||
| raise McpError( | ||
| f"Repository alias '{alias_or_name}' is reserved but not enabled yet " | ||
| f"({profile.get('repoName')})." | ||
| ) | ||
| return str(profile["repoName"]) |
There was a problem hiding this comment.
Fixed in 278a7f3f: updated the DeepWiki MCP client as suggested and re-ran local validation, including mvn apache-rat:check -DskipTests, Claude plugin validation, Codex temp install, structure, and context commands.
| def score_window(text: str, terms: list[str]) -> int: | ||
| lowered = text.lower() | ||
| score = 0 | ||
| for term in terms: | ||
| pattern = rf"(?<![a-z0-9_]){re.escape(term)}(?![a-z0-9_])" | ||
| count = len(re.findall(pattern, lowered)) | ||
| if count: | ||
| score += count * max(1, min(len(term), 12)) | ||
| if "relevant source files" in lowered: | ||
| score -= 40 |
There was a problem hiding this comment.
Fixed in 278a7f3f: updated the DeepWiki MCP client as suggested and re-ran local validation, including mvn apache-rat:check -DskipTests, Claude plugin validation, Codex temp install, structure, and context commands.
| lines = contents.splitlines() | ||
| window_size = 30 | ||
| stride = 10 | ||
| candidates: list[tuple[int, int, int, str]] = [] |
There was a problem hiding this comment.
Fixed in 278a7f3f: updated the DeepWiki MCP client as suggested and re-ran local validation, including mvn apache-rat:check -DskipTests, Claude plugin validation, Codex temp install, structure, and context commands.
| while True: | ||
| if time.monotonic() > deadline: | ||
| break | ||
| raw_line = response.readline() | ||
| if not raw_line: | ||
| break | ||
|
|
There was a problem hiding this comment.
Fixed in 278a7f3f: updated the DeepWiki MCP client as suggested and re-ran local validation, including mvn apache-rat:check -DskipTests, Claude plugin validation, Codex temp install, structure, and context commands.
| preview = "\n".join(seen_payloads[-3:]) | ||
| raise McpError( | ||
| f"DeepWiki MCP stream ended without response id {expected_id} " | ||
| f"within {max_seconds:.0f}s: {preview[:500]}" | ||
| ) |
There was a problem hiding this comment.
Fixed in 278a7f3f: updated the DeepWiki MCP client as suggested and re-ran local validation, including mvn apache-rat:check -DskipTests, Claude plugin validation, Codex temp install, structure, and context commands.
| ## Usage | ||
|
|
||
| After installation, ask for the skill explicitly when needed: | ||
|
|
||
| ```text |
| ## 使用方式 | ||
|
|
||
| 安装后，可以在提问时显式指定： | ||
|
|
||
| ```text |
There was a problem hiding this comment.
已修复。最新 deepwiki-skill 分支的 README-zh.md 已补充 Python 3.9+ 最低版本要求，并说明当前环境需要能访问 https://mcp.deepwiki.com/mcp。
| - Source repository: `https://github.com/apache/hugegraph` | ||
| - DeepWiki page: `https://deepwiki.com/apache/hugegraph` | ||
| - MCP endpoint: `https://mcp.deepwiki.com/mcp` | ||
| - Default repository: `apache/hugegraph` | ||
|
|
Purpose of the PR
Main Changes
tools/ai/hugegraph-deepwiki-skillas a standalone installable module.hugegraph-deepwiki-skillskill.structure,contents,context,ask, andtoolscommands.tools/ai/so it does not affect HugeGraph runtime, Maven modules, or repository root plugin configuration.Verifying these changes
python3 -m json.tool tools/ai/hugegraph-deepwiki-skill/.agents/plugins/marketplace.jsonpython3 -m json.tool tools/ai/hugegraph-deepwiki-skill/.claude-plugin/marketplace.jsonpython3 -m json.tool tools/ai/hugegraph-deepwiki-skill/plugins/hugegraph-deepwiki-skill/.codex-plugin/plugin.jsonpython3 -m json.tool tools/ai/hugegraph-deepwiki-skill/plugins/hugegraph-deepwiki-skill/.claude-plugin/plugin.jsonpython3 -m py_compile tools/ai/hugegraph-deepwiki-skill/plugins/hugegraph-deepwiki-skill/skills/hugegraph-deepwiki-skill/scripts/deepwiki_mcp.pyclaude plugin validate tools/ai/hugegraph-deepwiki-skillclaude plugin validate tools/ai/hugegraph-deepwiki-skill/plugins/hugegraph-deepwiki-skillcodex plugin marketplace add "$(pwd)/tools/ai/hugegraph-deepwiki-skill"codex plugin add hugegraph-deepwiki-skill@hugegraph-deepwiki-skillpython3 scripts/deepwiki_mcp.py structure --repo hugegraphpython3 scripts/deepwiki_mcp.py context --repo hugegraph --query "Which components handle schema operations?" --limit 1DEEPWIKI_MCP_STREAM_TIMEOUT=60 python3 scripts/deepwiki_mcp.py ask --repo hugegraph --question "Which HugeGraph components handle schema operations?"Does this PR potentially affect the following parts?
tools/ai/.Documentation Status
Doc - TODODoc - DoneDoc - No Need