feat(tools): add HugeGraph AI DeepWiki assistant by LRriver · Pull Request #355 · apache/hugegraph-ai

LRriver · 2026-06-01T10:57:41Z

Purpose

Add an optional HugeGraph AI repository knowledge assistant under tools/ai. The assistant is intended for Claude Code and Codex users who want repository-scoped Q&A for https://github.com/apache/hugegraph-ai, using DeepWiki as the online knowledge source while caching wiki contents locally for repeated context search.

Changes

Add tools/ai/hugegraph-ai-deepwiki-skill as a standalone installable module.
Include Claude and Codex plugin manifests plus marketplace manifests.
Add bilingual installation and usage docs: README.md and README-zh.md.
Add a small DeepWiki MCP client CLI for structure, contents, context, ask, and tools.
Keep the assistant isolated from runtime code and project dependencies.

Verification

python3 -m json.tool on all new JSON manifests.
python3 -m py_compile tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/deepwiki_mcp.py.
uv run --extra dev ruff format --check tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/deepwiki_mcp.py.
uv run --extra dev ruff check tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/deepwiki_mcp.py.
claude plugin validate tools/ai/hugegraph-ai-deepwiki-skill.
claude plugin validate tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill.
Temporary Codex install via codex plugin marketplace add and codex plugin add.
DeepWiki smoke tests: structure, cached context, and online ask for apache/hugegraph-ai.

Compatibility

This is an optional tool module only. It does not change HugeGraph AI runtime behavior, public APIs, package dependencies, or default configuration.

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a new “HugeGraph AI DeepWiki” skill/plugin that can query the official DeepWiki MCP server, cache wiki contents locally, and provide repository-scoped Q&A and context search for apache/hugegraph-ai.

Changes:

Introduces a Python MCP client script (deepwiki_mcp.py) with commands for ask, structure, contents, context, and tools.
Adds repository profile mapping (references/repos.json) and agent/tool configuration (agents/openai.yaml).
Adds plugin packaging + documentation for Codex/Claude installs (plugin manifests, marketplace entries, READMEs, SKILL.md).

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/deepwiki_mcp.py	Implements the MCP client, caching, and CLI workflows described in docs.
tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/references/repos.json	Defines repository alias → repoName mapping used by the CLI and skill.
tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/agents/openai.yaml	Declares the MCP dependency and default prompt wiring for the agent.
tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/SKILL.md	Documents the intended workflow (context search first, then ask).
tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/.codex-plugin/plugin.json	Codex plugin manifest for distributing the skill.
tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/.claude-plugin/plugin.json	Claude plugin manifest for distributing the skill.
tools/ai/hugegraph-ai-deepwiki-skill/README.md	Installation and usage docs (English).
tools/ai/hugegraph-ai-deepwiki-skill/README-zh.md	Installation and usage docs (Chinese).
tools/ai/hugegraph-ai-deepwiki-skill/.claude-plugin/marketplace.json	Marketplace entry for Claude plugin discovery.
tools/ai/hugegraph-ai-deepwiki-skill/.agents/plugins/marketplace.json	Marketplace entry for agents/plugin discovery.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

LRriver · 2026-06-01T11:02:10Z

+    max_seconds = float(os.environ.get("DEEPWIKI_MCP_STREAM_TIMEOUT", "120"))
+    deadline = time.monotonic() + max_seconds
+    timed_out = False
+
+    while True:
+        if time.monotonic() > deadline:
+            timed_out = True
+            break
+        raw_line = response.readline()


Fixed in 3a3e8e6.

Follow-up Python 3.9 socket timeout compatibility fix added in 8305e3d.

LRriver · 2026-06-01T11:02:12Z

+        try:
+            with urllib.request.urlopen(req, timeout=90) as response:
+                session_id = response.headers.get("Mcp-Session-Id")


Fixed in 3a3e8e6.

Follow-up Python 3.9 socket timeout compatibility fix added in 8305e3d.

LRriver · 2026-06-01T11:02:15Z

+def write_text_atomic(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_suffix(path.suffix + ".tmp")
+    tmp_path.write_text(text, encoding="utf-8")
+    tmp_path.replace(path)


Fixed in 3a3e8e6.

LRriver · 2026-06-01T11:02:17Z

+            "Accept": "application/json, text/event-stream",
+            "Content-Type": "application/json",
+            "Mcp-Protocol-Version": self.protocol_version,
+            "User-Agent": "hugegraph-ai-deepwiki-skill/0.1.4",


Fixed in 3a3e8e6.

LRriver · 2026-06-01T11:02:20Z

+            {
+                "protocolVersion": self.protocol_version,
+                "capabilities": {},
+                "clientInfo": {"name": "hugegraph-ai-deepwiki-skill", "version": "0.1.4"},


Fixed in 3a3e8e6.

imbajin

Blocking: yes. Summary: The cache hardening still fails recoverable cache cases and the new MCP client lacks regression tests for its failure-prone paths. Evidence: py_compile/JSON smoke passed; fake-client cache write failure reproduced a hard McpError.

imbajin · 2026-06-02T06:07:28Z

+            return path.read_text(encoding="utf-8"), path, False
+
+        text = read_wiki_contents(client, repo_name)
+        write_text_atomic(path, text)


‼️ Do not discard freshly fetched contents on cache write failure

Evidence: read_wiki_contents() runs before this write, but any OSError from write_text_atomic() is converted into McpError, so the command fails even though it already has the fresh wiki text. Impact: a broken cache directory makes context/contents unusable instead of falling back to the live result, which is the recovery path this change is trying to harden. Please return the fetched contents when only the cache write fails, and refetch when an existing cache read fails or is invalid.

Fixed. ensure_cached_contents() now refetches when an existing cache read fails, and if read_wiki_contents() succeeds but the cache write fails, it returns the fresh DeepWiki contents instead of raising McpError. Added regression coverage for both cache write fallback and invalid cache refetch.

imbajin · 2026-06-02T06:07:28Z

+    return parsed
+
+
+def read_sse_response(response: Any, expected_id: int | None) -> dict[str, Any]:


‼️ Add regression tests for the MCP client failure paths

Evidence: this PR adds a custom MCP/SSE client with timeout handling, atomic cache writes, CLI validation, and context scoring, but no automated tests cover those behaviors. Impact: the same timeout/cache paths already needed follow-up fixes in this PR, and future changes can regress them while py_compile and smoke checks still pass. Please add focused tests for read_sse_response(), cache read/write failure fallback, and the cached-context scoring/selection behavior.

LRriver · 2026-06-02T07:08:48Z

Blocking: yes. Summary: The cache hardening still fails recoverable cache cases and the new MCP client lacks regression tests for its failure-prone paths. Evidence: py_compile/JSON smoke passed; fake-client cache write failure reproduced a hard McpError.阻塞项：是。摘要：缓存加固仍无法处理可恢复的缓存故障场景，且新增的 MCP 客户端缺少针对其易故障路径的回归测试。证据：py_compile/JSON 冒烟测试通过；模拟客户端缓存写入失败复现了硬性 McpError 错误。

@imbajin Addressed the DeepWiki MCP review feedback in the latest deepwiki-skill commits. Summary:

Cache read failures now trigger a fresh read_wiki_contents() fetch.
Cache write failures no longer discard already fetched DeepWiki contents.
Added regression tests for SSE timeout handling, cache fallback/refetch, and cached-context selection.
Fixed Ruff format/lint issues from CI.

Local validation passed: uv run ruff check ., uv run ruff format --check ., python3 -m py_compile ..., and python3 -m unittest .../tests/test_deepwiki_mcp.py.

Latest apache/hugegraph-ai#355 CI is passing.

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

imbajin

Blocking: yes. Summary: two packaging/runtime edge cases remain in the DeepWiki skill. Evidence: git archive/static review plus a local partial-SSE timeout reproduction.

imbajin · 2026-06-02T10:58:46Z

@@ -0,0 +1,559 @@
+#!/usr/bin/env python3


‼️ Core script is omitted from source archives

Evidence: on current head 29aae41, git archive HEAD | tar -tf - includes tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/tests/test_deepwiki_mcp.py but not this scripts/deepwiki_mcp.py file. The existing root .gitattributes has scripts/ export-ignore, so archive-based installs and release source tarballs ship the tests/manifests without the executable client. Please either move/rename the plugin script directory or add an explicit archive rule so the skill package is complete in source archives.

imbajin · 2026-06-02T10:58:46Z

+        if expected_id is None or parsed.get("id") == expected_id:
+            return parsed
+
+    if data_lines:


⚠️ Partial SSE timeouts still surface as parse errors

Evidence: a fake response that first returns b'data: {"jsonrpc":"2.0","id":7,\n' and then raises TimeoutError makes read_sse_response() raise McpError: DeepWiki MCP returned non-JSON content... instead of the timeout error path added above. The new timeout test only covers an immediate timeout before any bytes are buffered. Please treat the buffered partial event as a timeout when timed_out is true before parsing the trailing data_lines, and add a regression test for that branch.

LRriver added 3 commits June 1, 2026 17:16

feat(tools): add HugeGraph AI DeepWiki assistant

f57ac8e

docs(tools): clarify HugeGraph AI assistant installs

9d87089

fix(tools): harden HugeGraph AI DeepWiki client

8abb0b6

Copilot AI review requested due to automatic review settings June 1, 2026 10:57

dosubot Bot added size:XL This PR changes 500-999 lines, ignoring generated files. enhancement New feature or request labels Jun 1, 2026

Copilot AI reviewed Jun 1, 2026

View reviewed changes

LRriver added 5 commits June 1, 2026 19:01

fix(tools): improve DeepWiki MCP timeout handling

3a3e8e6

fix(tools): handle DeepWiki socket timeouts

8305e3d

fix(tools): validate HugeGraph AI DeepWiki CLI inputs

f08b6c1

fix(tools): optimize cached DeepWiki context scoring

ede5007

fix(tools): handle DeepWiki cache errors cleanly

afa4643

imbajin reviewed Jun 2, 2026

View reviewed changes

LRriver added 3 commits June 2, 2026 14:38

fix(tools): preserve DeepWiki results on cache errors

91627ee

style(tools): format DeepWiki tests

8b0507e

fix(tools): satisfy DeepWiki test lint

29aae41

imbajin requested a review from Copilot June 2, 2026 10:49

Copilot started reviewing on behalf of imbajin June 2, 2026 10:49 View session

Copilot AI reviewed Jun 2, 2026

View reviewed changes

imbajin reviewed Jun 2, 2026

View reviewed changes

		return parsed


		def read_sse_response(response: Any, expected_id: int \| None) -> dict[str, Any]:

Conversation

LRriver commented Jun 1, 2026

Purpose

Changes

Verification

Compatibility

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

imbajin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LRriver commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

imbajin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

LRriver commented Jun 2, 2026 •

edited

Loading