How the MCP Tool Returns Results in Aggregate Mode Versus Paginated Mode

The deepwiki_fetch tool in the regenrek/deepwiki-mcp repository always returns a list of Markdown pages, but the mode parameter determines whether internal links are rewritten as anchor references (#path) for single-document aggregation or as separate file references (path.md) for multi-file pagination.

The deepwiki_fetch MCP tool converts crawled HTML documentation into structured Markdown. When invoking this tool from the regenrek/deepwiki-mcp server, developers must choose between aggregate and pages modes—a decision that fundamentally changes how cross-references behave in the generated output.

Understanding the Two Output Modes

The tool's behavior is governed by the ModeEnum defined in the Zod schema, which strictly allows two values: aggregate or pages.

// src/schemas/deepwiki.ts
export const ModeEnum = z.enum(['aggregate', 'pages'])

Aggregate Mode Behavior

In aggregate mode, the tool rewrites all internal href attributes to use anchor-style links (#path). The resulting Markdown concatenates all crawled pages into a single cohesive document where each page is prefixed with a header containing its path.

For example, a link to /chapter1 becomes [Chapter 1](#chapter1), allowing navigation within a single file.

Paginated (Pages) Mode Behavior

In pages mode (paginated), internal links are rewritten to reference separate Markdown files. A link to /chapter1 becomes [Chapter 1](chapter1.md), enabling a multi-file documentation structure where each page can be saved as an individual .md file.

Implementation: How Link Rewriting Works

The mode-dependent logic resides in src/lib/linkRewrite.ts, where the rehypeRewriteLinks plugin checks the mode and transforms href properties accordingly:

// src/lib/linkRewrite.ts (lines 18-23)
if (opts.mode === 'aggregate') {
  node.properties.href = `#${href.replace(/^\//, '')}`   // anchor link
} else {
  node.properties.href = `${href.replace(/^\//, '')}.md` // separate .md file
}

The deepwiki_fetch tool passes the user-specified mode through the conversion pipeline in src/tools/deepwiki.ts:

// src/tools/deepwiki.ts (lines 21-31)
const pages = await Promise.all(
  Object.entries(crawlResult.html).map(async ([path, html]) => ({
    path,
    markdown: await htmlToMarkdown(html, req.mode),   // mode is used here
  }))
)

Finally, each page is wrapped with a path header and returned in the content array:

// src/tools/deepwiki.ts (lines 25-30)
return {
  content: pages.map(page => ({
    type: 'text',
    text: `# ${page.path}\n\n${page.markdown}`,

  })),
}

Practical Code Examples

Using Aggregate Mode

When you need a single downloadable documentation file:

await mcp.runTool('deepwiki_fetch', {
  url: 'owner/repo',
  mode: 'aggregate',
  maxDepth: 1,
  verbose: false,
})

Result: content[0].text contains a single Markdown string where all pages are concatenated with # headers, and internal links use anchor syntax like [#/chapter1](#chapter1).

Using Paginated Mode

When you need to save each page as a separate file:

await mcp.runTool('deepwiki_fetch', {
  url: 'owner/repo',
  mode: 'pages',
  maxDepth: 1,
  verbose: false,
})

Result: content is an array where each entry represents a separate page. Links reference other files using .md extensions, such as [chapter1](chapter1.md), allowing you to write each entry to its own file while maintaining navigable cross-references.

Summary

• Aggregate mode rewrites links as anchor references (#path) and concatenates all crawled pages into a single Markdown document suitable for unified documentation viewing.
• Paginated mode rewrites links as separate file references (path.md) and returns each page as a distinct entry, enabling multi-file documentation structures.
• The mode parameter is defined in src/schemas/deepwiki.ts, processed in src/tools/deepwiki.ts, and implemented in src/lib/linkRewrite.ts.
• Both modes return the same content array structure; only the link rewriting logic and text content differ.

Frequently Asked Questions

What is the default mode for deepwiki_fetch?

The tool requires an explicit mode parameter; there is no default value defined in the ModeEnum schema. You must specify either aggregate or pages when invoking the tool, as enforced by the Zod validation in src/schemas/deepwiki.ts.

Can I switch modes after fetching content?

No, the mode is applied during the HTML-to-Markdown conversion phase in src/tools/deepwiki.ts. Once the tool returns the content array, the links have already been rewritten according to the specified mode. To change the link format, you must re-run the tool with the alternative mode parameter.

How does aggregate mode affect large documentation sites?

In aggregate mode, all crawled pages are concatenated into a single Markdown string. For large sites, this produces a very large single document where navigation relies on anchor links (#path). While this creates a cohesive reading experience, the resulting file size may impact performance in editors or viewers that struggle with extremely large Markdown files.

Are there performance differences between aggregate and pages mode?

The crawling and HTML parsing phases are identical in both modes. The only performance difference occurs during link rewriting in src/lib/linkRewrite.ts, which is negligible. However, aggregate mode produces a single large string in memory before returning, while pages mode returns an array of smaller strings. For very large sites, pages mode may have slightly lower peak memory usage on the client side due to streaming or chunked processing potential.

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