From 38b6ed6e3978a1aa1e34cf7d773c794c9b16598f Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Wed, 24 Dec 2025 02:49:53 +0900 Subject: [PATCH 1/4] feat(librarian): add DeepWiki MCP integration for documentation lookup - Add DeepWiki MCP server configuration (SSE type) to .mcp.json - Update librarian agent to use DeepWiki MCP for wiki/documentation search - Add DeepWiki to tool reference with usage examples - Include DeepWiki in parallel execution requirements for comprehensive research - Add DeepWiki to failure recovery section as alternative to Context7 MCP This enables the librarian agent to query AI-generated documentation for GitHub repositories, improving capability to understand repository architecture and component interactions. Closes #69 --- .mcp.json | 4 ++++ agents/librarian.md | 58 +++++++++++++++++++++++++++++++++++---------- 2 files changed, 49 insertions(+), 13 deletions(-) diff --git a/.mcp.json b/.mcp.json index 53cbb0e..e101ce0 100644 --- a/.mcp.json +++ b/.mcp.json @@ -3,6 +3,10 @@ "grep": { "type": "http", "url": "https://mcp.grep.app" + }, + "deepwiki": { + "type": "sse", + "url": "https://mcp.deepwiki.com/sse" } } } diff --git a/agents/librarian.md b/agents/librarian.md index 03a932f..c7350cb 100644 --- a/agents/librarian.md +++ b/agents/librarian.md @@ -89,16 +89,20 @@ Classify EVERY request into one of these categories before taking action: ### TYPE A: CONCEPTUAL QUESTION **Trigger**: "How do I...", "What is...", "Best practice for...", rough/general questions -**Execute in parallel (3+ calls)**: +**Execute in parallel (4+ calls)**: ```bash # Tool 1: Context7 MCP for official docs mcp-cli call plugin_context7_context7/resolve-library-id '{"libraryName": "library-name"}' # then: mcp-cli call plugin_context7_context7/get-library-docs '{"context7CompatibleLibraryID": "", "topic": "specific-topic"}' -# Tool 2: WebSearch for latest info +# Tool 2: DeepWiki MCP for wiki/documentation +mcp-cli call deepwiki/read_wiki_structure '{"repoName": "owner/repo"}' +# then: mcp-cli call deepwiki/read_wiki_contents '{"repoName": "owner/repo", "path": "path/from/structure"}' + +# Tool 3: WebSearch for latest info WebSearch("library-name topic 2025") -# Tool 3: GitHub code search +# Tool 4: GitHub code search gh search code "usage pattern" --language TypeScript ``` @@ -126,7 +130,7 @@ cd ${TMPDIR:-/tmp}/repo-name && git rev-parse HEAD # https://github.com/owner/repo/blob//path/to/file#L10-L20 ``` -**Parallel acceleration (4+ calls)**: +**Parallel acceleration (5+ calls)**: ```bash # Tool 1: Clone repository gh repo clone owner/repo ${TMPDIR:-/tmp}/repo -- --depth 1 @@ -139,6 +143,9 @@ gh api repos/owner/repo/commits/HEAD --jq '.sha' # Tool 4: Fetch related docs via Context7 MCP mcp-cli call plugin_context7_context7/get-library-docs '{"context7CompatibleLibraryID": "", "topic": "relevant-api"}' + +# Tool 5: DeepWiki for architectural understanding +mcp-cli call deepwiki/read_wiki_structure '{"repoName": "owner/repo"}' ``` --- @@ -175,25 +182,27 @@ gh api repos/owner/repo/pulls//files ### TYPE D: COMPREHENSIVE RESEARCH **Trigger**: Complex questions, ambiguous requests, "deep dive into..." -**Execute ALL in parallel (6+ calls)**: +**Execute ALL in parallel (7+ calls)**: ```bash # Documentation & Web # Tool 1: Context7 MCP mcp-cli call plugin_context7_context7/resolve-library-id '{"libraryName": "..."}' -# Tool 2: WebSearch +# Tool 2: DeepWiki MCP +mcp-cli call deepwiki/read_wiki_structure '{"repoName": "owner/repo"}' +# Tool 3: WebSearch WebSearch("topic recent updates 2025") # Code Search -# Tool 3-4: GitHub code search with varied queries +# Tool 4-5: GitHub code search with varied queries gh search code "pattern1" --language TypeScript gh search code "pattern2" --language TypeScript # Source Analysis -# Tool 5: Clone repository +# Tool 6: Clone repository gh repo clone owner/repo ${TMPDIR:-/tmp}/repo -- --depth 1 # Context -# Tool 6: Search issues +# Tool 7: Search issues gh search issues "topic" --repo owner/repo ``` @@ -240,6 +249,7 @@ https://github.com/tanstack/query/blob/abc123def/packages/react-query/src/useQue | Purpose | Tool | Command/Usage | |---------|------|---------------| | **Official Docs** | Context7 MCP | `mcp-cli call plugin_context7_context7/resolve-library-id` → `get-library-docs` | +| **Wiki/Docs Search** | DeepWiki MCP | `mcp-cli call deepwiki/read_wiki_structure` → `deepwiki/read_wiki_contents` | | **Latest Info** | WebSearch | `WebSearch("query 2025")` | | **Fast Code Search** | gh CLI (Bash) | `gh search code "query" --repo owner/repo` | | **Clone Repo** | gh CLI (Bash) | `gh repo clone owner/repo ${TMPDIR:-/tmp}/name -- --depth 1` | @@ -264,16 +274,37 @@ ${TMPDIR:-/tmp}/repo-name # Windows: C:\Users\...\AppData\Local\Temp\repo-name ``` +### DeepWiki MCP + +DeepWiki provides AI-generated documentation for GitHub repositories: + +```bash +# Step 1: Get wiki structure (required first) +mcp-cli call deepwiki/read_wiki_structure '{"repoName": "owner/repo"}' + +# Step 2: Read specific content from the structure +mcp-cli call deepwiki/read_wiki_contents '{"repoName": "owner/repo", "path": "path/from/structure"}' + +# Alternative: Ask questions about a repository +mcp-cli call deepwiki/ask_question '{"repoName": "owner/repo", "question": "How does X work?"}' +``` + +**When to use DeepWiki**: +- Understanding repository architecture +- Getting high-level explanations of complex codebases +- Finding how components interact +- Complement to Context7 for richer documentation + --- ## PARALLEL EXECUTION REQUIREMENTS | Request Type | Minimum Parallel Calls | |--------------|----------------------| -| TYPE A (Conceptual) | 3+ | -| TYPE B (Implementation) | 4+ | +| TYPE A (Conceptual) | 4+ | +| TYPE B (Implementation) | 5+ | | TYPE C (Context) | 4+ | -| TYPE D (Comprehensive) | 6+ | +| TYPE D (Comprehensive) | 7+ | **Always vary queries** when searching: ```bash @@ -293,7 +324,8 @@ gh search code "useQuery" | Failure | Recovery Action | |---------|-----------------| -| Context7 not found | Clone repo, read source + README directly | +| Context7 not found | Try DeepWiki, or clone repo and read source + README directly | +| DeepWiki not available | Use Context7 MCP or clone repo directly | | Search no results | Broaden query, try concept instead of exact name | | gh API rate limit | Use cloned repo in temp directory | | Repo not found | Search for forks or mirrors | From 91b7a3249725d69d4107c8142d188e39be725a96 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Wed, 24 Dec 2025 02:59:02 +0900 Subject: [PATCH 2/4] docs(librarian): add mcp-cli info step to DeepWiki examples --- agents/librarian.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/agents/librarian.md b/agents/librarian.md index c7350cb..cfd2bd2 100644 --- a/agents/librarian.md +++ b/agents/librarian.md @@ -279,6 +279,9 @@ ${TMPDIR:-/tmp}/repo-name DeepWiki provides AI-generated documentation for GitHub repositories: ```bash +# Step 0: Check schema (mandatory before first use) +mcp-cli info deepwiki/read_wiki_structure + # Step 1: Get wiki structure (required first) mcp-cli call deepwiki/read_wiki_structure '{"repoName": "owner/repo"}' From d08272851564a97db9d2f7ab0e8ee92389f58c33 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Wed, 24 Dec 2025 03:00:45 +0900 Subject: [PATCH 3/4] docs(librarian): add limitations section and use named identifiers - Add DeepWiki limitations section for error handling guidance - Replace numbered tool comments with named identifiers [context7], [deepwiki], etc. - Improves maintainability when adding/removing tools --- agents/librarian.md | 43 ++++++++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/agents/librarian.md b/agents/librarian.md index cfd2bd2..7b2bcd7 100644 --- a/agents/librarian.md +++ b/agents/librarian.md @@ -91,18 +91,18 @@ Classify EVERY request into one of these categories before taking action: **Execute in parallel (4+ calls)**: ```bash -# Tool 1: Context7 MCP for official docs +# [context7] Official docs mcp-cli call plugin_context7_context7/resolve-library-id '{"libraryName": "library-name"}' # then: mcp-cli call plugin_context7_context7/get-library-docs '{"context7CompatibleLibraryID": "", "topic": "specific-topic"}' -# Tool 2: DeepWiki MCP for wiki/documentation +# [deepwiki] Wiki/documentation mcp-cli call deepwiki/read_wiki_structure '{"repoName": "owner/repo"}' # then: mcp-cli call deepwiki/read_wiki_contents '{"repoName": "owner/repo", "path": "path/from/structure"}' -# Tool 3: WebSearch for latest info +# [websearch] Latest info WebSearch("library-name topic 2025") -# Tool 4: GitHub code search +# [gh-search] Code search gh search code "usage pattern" --language TypeScript ``` @@ -132,19 +132,19 @@ cd ${TMPDIR:-/tmp}/repo-name && git rev-parse HEAD **Parallel acceleration (5+ calls)**: ```bash -# Tool 1: Clone repository +# [clone] Clone repository gh repo clone owner/repo ${TMPDIR:-/tmp}/repo -- --depth 1 -# Tool 2: Search code on GitHub +# [gh-search] Search code on GitHub gh search code "function_name" --repo owner/repo -# Tool 3: Get HEAD SHA via API +# [gh-api] Get HEAD SHA via API gh api repos/owner/repo/commits/HEAD --jq '.sha' -# Tool 4: Fetch related docs via Context7 MCP +# [context7] Fetch related docs mcp-cli call plugin_context7_context7/get-library-docs '{"context7CompatibleLibraryID": "", "topic": "relevant-api"}' -# Tool 5: DeepWiki for architectural understanding +# [deepwiki] Architectural understanding mcp-cli call deepwiki/read_wiki_structure '{"repoName": "owner/repo"}' ``` @@ -155,18 +155,18 @@ mcp-cli call deepwiki/read_wiki_structure '{"repoName": "owner/repo"}' **Execute in parallel (4+ calls)**: ```bash -# Tool 1: Search issues +# [gh-issues] Search issues gh search issues "keyword" --repo owner/repo --state all --limit 10 -# Tool 2: Search PRs +# [gh-prs] Search PRs gh search prs "keyword" --repo owner/repo --state merged --limit 10 -# Tool 3: Clone and get history +# [clone+history] Clone and get history gh repo clone owner/repo ${TMPDIR:-/tmp}/repo -- --depth 50 cd ${TMPDIR:-/tmp}/repo && git log --oneline -n 20 -- path/to/file git blame -L 10,30 path/to/file -# Tool 4: Get releases +# [gh-api] Get releases gh api repos/owner/repo/releases --jq '.[0:5]' ``` @@ -185,24 +185,24 @@ gh api repos/owner/repo/pulls//files **Execute ALL in parallel (7+ calls)**: ```bash # Documentation & Web -# Tool 1: Context7 MCP +# [context7] Official docs mcp-cli call plugin_context7_context7/resolve-library-id '{"libraryName": "..."}' -# Tool 2: DeepWiki MCP +# [deepwiki] Wiki/documentation mcp-cli call deepwiki/read_wiki_structure '{"repoName": "owner/repo"}' -# Tool 3: WebSearch +# [websearch] Latest info WebSearch("topic recent updates 2025") # Code Search -# Tool 4-5: GitHub code search with varied queries +# [gh-search-1] [gh-search-2] Varied queries gh search code "pattern1" --language TypeScript gh search code "pattern2" --language TypeScript # Source Analysis -# Tool 6: Clone repository +# [clone] Clone repository gh repo clone owner/repo ${TMPDIR:-/tmp}/repo -- --depth 1 # Context -# Tool 7: Search issues +# [gh-issues] Search issues gh search issues "topic" --repo owner/repo ``` @@ -298,6 +298,11 @@ mcp-cli call deepwiki/ask_question '{"repoName": "owner/repo", "question": "How - Finding how components interact - Complement to Context7 for richer documentation +**Limitations**: +- DeepWiki generates documentation for public repositories only +- Not all repositories have documentation generated yet +- If no content is available, fall back to Context7 or direct source reading + --- ## PARALLEL EXECUTION REQUIREMENTS From a451e36321ffa482b990e58b6e4cde8b2738e0e8 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Wed, 24 Dec 2025 03:11:17 +0900 Subject: [PATCH 4/4] docs(librarian): use ask_question for TYPE A conceptual queries Apply gemini-code-assist suggestion: use deepwiki/ask_question instead of two-step read_wiki_structure/contents for conceptual questions. --- agents/librarian.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/agents/librarian.md b/agents/librarian.md index 7b2bcd7..384b82c 100644 --- a/agents/librarian.md +++ b/agents/librarian.md @@ -95,9 +95,8 @@ Classify EVERY request into one of these categories before taking action: mcp-cli call plugin_context7_context7/resolve-library-id '{"libraryName": "library-name"}' # then: mcp-cli call plugin_context7_context7/get-library-docs '{"context7CompatibleLibraryID": "", "topic": "specific-topic"}' -# [deepwiki] Wiki/documentation -mcp-cli call deepwiki/read_wiki_structure '{"repoName": "owner/repo"}' -# then: mcp-cli call deepwiki/read_wiki_contents '{"repoName": "owner/repo", "path": "path/from/structure"}' +# [deepwiki] Conceptual questions (more direct than two-step browsing) +mcp-cli call deepwiki/ask_question '{"repoName": "owner/repo", "question": "How does X work?"}' # [websearch] Latest info WebSearch("library-name topic 2025")