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.

Fixed. Added focused unittest coverage for read_sse_response() timeout handling, cache write fallback, invalid cache refetch, and cached-context scoring/selection. Local Ruff check/format, py_compile, and unit tests pass; the latest PR CI is also passing.

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.

Fixed in the latest deepwiki-skill head. Added explicit archive rules in the root .gitattributes for this skill’s scripts/ directory and files, and verified with git archive HEAD | tar -tf - that scripts/deepwiki_mcp.py is now included alongside the tests/manifests.

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.

Fixed in the latest deepwiki-skill head. read_sse_response() now treats buffered partial SSE data as a timeout when the stream times out instead of parsing incomplete JSON. Added test_read_sse_response_reports_partial_event_timeout; local Ruff, py_compile, and unittest checks pass.

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

LRriver · 2026-06-04T11:49:55Z

+## Requirements
+
+- Python 3.9 or later for the bundled MCP client script.
+- Network access to `https://mcp.deepwiki.com/mcp`.


Fixed in ad797fd. The English README now states Python 3.10+ for the bundled MCP client, matching the repository requires-python >=3.10 and Ruff target.

LRriver · 2026-06-04T11:50:07Z

+## 前置要求
+
+- Python 3.9 或更高版本，用于运行随附的 MCP 客户端脚本。
+- 当前环境需要能访问 `https://mcp.deepwiki.com/mcp`。


Fixed in ad797fd. The Chinese README now states Python 3.10+ for the bundled MCP client, matching this repository runtime requirement.

LRriver · 2026-06-04T11:50:22Z

+- Source repository: `https://github.com/apache/hugegraph-ai`
+- DeepWiki page: `https://deepwiki.com/apache/hugegraph-ai`
+- MCP endpoint: `https://mcp.deepwiki.com/mcp`
+- Default repository: `apache/hugegraph-ai`
+- Runtime requirements: Python 3.9+ and network access to the MCP endpoint.


Fixed in ad797fd. SKILL.md now declares Python 3.10+ for the bundled MCP client.

LRriver · 2026-06-04T11:50:58Z

+tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/ -export-ignore
+tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/** -export-ignore


Partially addressed in ad797fd. I re-tested git archive without these rules and the archive omitted scripts/deepwiki_mcp.py while keeping the tests, so the negation rules are required for source/archive installs. I kept them and added a comment explaining that they preserve the DeepWiki skill MCP client in release/source archives.

imbajin

Blocking: no. Summary: The skill package is mostly verified, but the CLI repository argument rejects a repository form the docs surface. Evidence: unittest passed (5 tests), py_compile passed, archive includes the skill script, and local resolve_repo("apache/hugegraph-ai") reproduction fails.

imbajin · 2026-06-03T07:29:16Z

+    return repos
+
+
+def resolve_repo(alias_or_name: str) -> str:


⚠️ Accept the documented repository form

Evidence: resolve_repo("hugegraph-ai") returns apache/hugegraph-ai, but resolve_repo("apache/hugegraph-ai") raises McpError: Unknown repository alias ...; the skill docs and metadata repeatedly present the canonical apache/hugegraph-ai value. Impact: users who copy the documented repository name into --repo hit a hard CLI error. Please either accept full owner/repo names as a pass-through or make the CLI/docs explicitly alias-only, and add a regression test for that contract.

Fixed in ad797fd. resolve_repo() now accepts both the documented canonical repository name apache/hugegraph-ai and the alias hugegraph-ai, while still limiting pass-through names to enabled repository profiles. Added test_resolve_repo_accepts_alias_and_full_repo_name for the contract.

LRriver

Submitting pending review draft before posting the latest follow-up replies.

LRriver · 2026-06-02T07:10:02Z

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


Fixed. Added focused unittest coverage for read_sse_response() timeout handling, cache write fallback, invalid cache refetch, and cached-context scoring/selection. Local Ruff check/format, py_compile, and unit tests pass; the latest PR CI is also passing.

LRriver · 2026-06-03T03:28:59Z

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


Fixed in the latest deepwiki-skill head. Added explicit archive rules in the root .gitattributes for this skill’s scripts/ directory and files, and verified with git archive HEAD | tar -tf - that scripts/deepwiki_mcp.py is now included alongside the tests/manifests.

LRriver · 2026-06-03T03:28:59Z

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


Fixed in the latest deepwiki-skill head. read_sse_response() now treats buffered partial SSE data as a timeout when the stream times out instead of parsing incomplete JSON. Added test_read_sse_response_reports_partial_event_timeout; local Ruff, py_compile, and unittest checks pass.

imbajin

Blocking: no. Summary: One current-head lint failure remains in the bundled DeepWiki client. Evidence: uv run ruff check tools/ai/hugegraph-ai-deepwiki-skill fails with UP038 at deepwiki_mcp.py:323.

imbajin · 2026-06-04T21:37:01Z

+        except (TimeoutError, socket.timeout) as exc:  # noqa: UP041
+            raise McpError(f"DeepWiki MCP request timed out after {stream_timeout_seconds():.0f}s.") from exc
+        except urllib.error.URLError as exc:
+            if isinstance(exc.reason, (TimeoutError, socket.timeout)):


⚠️ Fix the current Ruff failure

Evidence: uv run ruff check tools/ai/hugegraph-ai-deepwiki-skill fails on this head with UP038 at this line. Impact: the bundled skill package cannot pass the repository's Ruff checks locally. Please use the Python 3.10 union form that the project lint rule expects.

Suggested change

if isinstance(exc.reason, (TimeoutError, socket.timeout)):

if isinstance(exc.reason, TimeoutError | socket.timeout):

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

fix(tools): handle DeepWiki archive and SSE edge cases

700c783

imbajin requested a review from Copilot June 3, 2026 07:17

Copilot started reviewing on behalf of imbajin June 3, 2026 07:17 View session

Copilot AI reviewed Jun 3, 2026

View reviewed changes

imbajin reviewed Jun 3, 2026

View reviewed changes

fix: align DeepWiki skill runtime and repo args

ad797fd

LRriver commented Jun 4, 2026

View reviewed changes

imbajin reviewed Jun 4, 2026

View reviewed changes

		return parsed


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

	if isinstance(exc.reason, (TimeoutError, socket.timeout)):
	if isinstance(exc.reason, TimeoutError \| socket.timeout):

		tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/ -export-ignore
		tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/** -export-ignore

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

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!

LRriver 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

LRriver commented Jun 2, 2026 •

edited

Loading