How to Perform Keyword-Based Searches with deepwiki-mcp: A Complete Guide

Use the deepwiki_fetch tool with natural language phrases to extract keywords and resolve repositories, then use deepwiki_search to find specific snippets within the crawled content.

The deepwiki-mcp repository provides a Model Context Protocol (MCP) server that enables intelligent keyword-based searches across Deepwiki documentation. Whether you're asking "how can I use X with Y" or searching for specific implementation details, the tool extracts meaningful keywords from natural language and maps them to relevant code repositories.

Understanding the Keyword-Based Search Architecture

The system relies on two complementary MCP tools that handle different stages of the search process.

The deepwiki_fetch Tool and Keyword Extraction

Located in src/tools/deepwiki.ts, the deepwiki_fetch tool handles the initial keyword extraction and repository resolution. When you provide a free-form phrase like "how can I use gpt-image-1 with vercel ai sdk" instead of a URL, the tool invokes the extractKeyword function from src/utils/extractKeyword.ts (lines 13-30).

This utility parses the natural language input to identify the most likely library or framework name. The extracted keyword is then passed to resolveRepo (lines 42-49 in src/tools/deepwiki.ts), which maps it to a GitHub owner/repo format. Finally, the tool constructs the Deepwiki URL (https://deepwiki.com/<owner>/<repo>) and initiates the crawling process.

The deepwiki_search Tool and Snippet Matching

Once the repository is fetched, the deepwiki_search tool in src/tools/deepwikiSearch.ts enables precise keyword-based searches within the crawled content. This tool accepts a literal search term in the query parameter and constructs a safe regular expression by escaping special characters (lines 66-68):

req.query.replace(/[.*+?^${}()|[\\]\\/]/g, '\\$&')

The tool performs a case-insensitive search across all Markdown-converted pages, extracts surrounding context (approximately 160 characters), and wraps matches in **bold** formatting (lines 81-83). Results are returned as structured snippet objects containing the matched text and source paths.

Step-by-Step Workflow for "How Can I Use X with Y" Queries

The complete workflow for performing keyword-based searches follows this architecture:

1. Submit natural language query – Provide a phrase like "how can I use gpt-image-1 with vercel ai sdk" via CLI or MCP JSON payload.
2. Extract and resolve keywords – The extractKeyword utility identifies "vercel ai" as the target library, and resolveRepo maps it to vercel/ai.
3. Fetch and crawl repository – The tool constructs https://deepwiki.com/vercel/ai, crawls the documentation, and converts HTML to Markdown.
4. Search for specific snippets – Use deepwiki_search with query: "gpt-image-1" to find relevant implementation examples within the fetched content.

Practical Code Examples

CLI Usage with Natural Language

You can perform keyword-based searches directly from the command line using natural language phrases:

deepwiki fetch "how can I use gpt-image-1 with vercel ai sdk"

The CLI internally chains deepwiki_fetch → extractKeyword → resolveRepo → crawling, returning the full Markdown documentation for the resolved repository.

MCP JSON Payload for Direct API Calls

For direct MCP server integration, structure your request as follows:

{
  "id": "req-1",
  "action": "deepwiki_search",
  "params": {
    "url": "https://deepwiki.com/vercel/ai",
    "query": "gpt-image-1 with vercel ai",
    "maxMatches": 5,
    "mode": "aggregate"
  }
}

Parameter breakdown:

• url: The Deepwiki repository URL (obtain via deepwiki_fetch with keywords first).
• query: The literal search phrase (case-insensitive).
• maxMatches: Maximum snippets to return (default: 10).
• mode: "aggregate" returns a single Markdown string; "pages" returns per-page objects.

Programmatic Integration in Node.js

Integrate keyword-based searches into your Node.js applications using an MCP client:

import { McpClient } from 'mcp-client'   // hypothetical client lib

const client = new McpClient({ url: 'http://localhost:3000/mcp' })

await client.call('deepwiki_search', {
  url: 'https://deepwiki.com/vercel/ai',
  query: 'gpt-image-1 with vercel ai',
  maxMatches: 3,
  mode: 'aggregate',
})

The client sends the JSON payload to the MCP server, which processes the request through src/tools/deepwikiSearch.ts and returns structured matches containing the snippet text and source paths.

Key Implementation Files

The keyword-based search functionality is implemented across these source files:

File	Role	Location
src/tools/deepwiki.ts	Implements deepwiki_fetch, normalises URLs, extracts keywords	deepwiki.ts
src/utils/extractKeyword.ts	NLP-based keyword extraction (extractKeyword)	extractKeyword.ts
src/tools/deepwikiSearch.ts	Implements deepwiki_search, regex-based snippet extraction	deepwikiSearch.ts
src/schemas/deepwiki.ts	Zod schemas for request validation (FetchRequest, SearchRequest)	deepwiki.ts schema

Summary

• deepwiki_fetch handles natural language input by extracting keywords via src/utils/extractKeyword.ts and resolving them to GitHub repositories before crawling Deepwiki content.
• deepwiki_search performs case-insensitive literal searches across crawled Markdown, using safe regex construction in src/tools/deepwikiSearch.ts to highlight matches in context.
• You can query using conversational phrases like "how can I use X with Y" and the tool chain will resolve the library, fetch documentation, and extract relevant snippets.
• The architecture separates repository resolution (deepwiki.ts) from content searching (deepwikiSearch.ts), enabling both broad documentation retrieval and precise keyword-based searches.

Frequently Asked Questions

How does deepwiki-mcp extract keywords from natural language queries?

The tool uses the extractKeyword function in src/utils/extractKeyword.ts to parse free-form text and identify the most likely library or framework name. This extracted keyword is then passed to resolveRepo in src/tools/deepwiki.ts to map it to a GitHub owner/repo format before crawling begins.

Can I search for specific phrases within a repository after fetching it?

Yes. After using deepwiki_fetch to resolve and crawl a repository, you can use deepwiki_search with the query parameter to perform case-insensitive literal searches. The tool builds a safe regular expression from your query (escaping special characters in src/tools/deepwikiSearch.ts lines 66-68) and returns highlighted snippets with surrounding context.

What is the difference between deepwiki_fetch and deepwiki_search?

deepwiki_fetch handles repository resolution and crawling, including keyword extraction from natural language phrases like "how can I use X with Y". It returns the full Markdown documentation for the resolved repository. deepwiki_search operates on already-fetched repositories, performing precise keyword-based searches across the crawled content and returning specific snippets with highlighted matches.

Is the keyword extraction limited to specific programming languages?

No, the keyword extraction in src/utils/extractKeyword.ts is language-agnostic. It identifies library and framework names from natural language context regardless of the underlying programming language, making it suitable for searching documentation across Python, JavaScript, Go, Rust, and other ecosystems hosted on Deepwiki.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}