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

> Learn to perform keyword based searches with deepwiki mcp. Use deepwiki fetch and deepwiki search tools to find specific information within crawled content. Get the complete guide.

- Repository: [Kevin Kern/deepwiki-mcp](https://github.com/regenrek/deepwiki-mcp)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/regenrek/deepwiki-mcp/blob/main/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`](https://github.com/regenrek/deepwiki-mcp/blob/main/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`](https://github.com/regenrek/deepwiki-mcp/blob/main/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`](https://github.com/regenrek/deepwiki-mcp/blob/main/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):

```typescript
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:

```bash
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:

```json
{
  "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:

```typescript
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`](https://github.com/regenrek/deepwiki-mcp/blob/main/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`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/tools/deepwiki.ts) | Implements `deepwiki_fetch`, normalises URLs, extracts keywords | [deepwiki.ts](https://github.com/regenrek/deepwiki-mcp/blob/main/src/tools/deepwiki.ts) |
| [`src/utils/extractKeyword.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/utils/extractKeyword.ts) | NLP-based keyword extraction (`extractKeyword`) | [extractKeyword.ts](https://github.com/regenrek/deepwiki-mcp/blob/main/src/utils/extractKeyword.ts) |
| [`src/tools/deepwikiSearch.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/tools/deepwikiSearch.ts) | Implements `deepwiki_search`, regex-based snippet extraction | [deepwikiSearch.ts](https://github.com/regenrek/deepwiki-mcp/blob/main/src/tools/deepwikiSearch.ts) |
| [`src/schemas/deepwiki.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/schemas/deepwiki.ts) | Zod schemas for request validation (`FetchRequest`, `SearchRequest`) | [deepwiki.ts schema](https://github.com/regenrek/deepwiki-mcp/blob/main/src/schemas/deepwiki.ts) |

## Summary

- **`deepwiki_fetch`** handles natural language input by extracting keywords via [`src/utils/extractKeyword.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/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`](https://github.com/regenrek/deepwiki-mcp/blob/main/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`](https://github.com/regenrek/deepwiki-mcp/blob/main/deepwiki.ts)) from content searching ([`deepwikiSearch.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/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`](https://github.com/regenrek/deepwiki-mcp/blob/main/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`](https://github.com/regenrek/deepwiki-mcp/blob/main/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`](https://github.com/regenrek/deepwiki-mcp/blob/main/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`](https://github.com/regenrek/deepwiki-mcp/blob/main/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.