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

> Understand how the MCP tool delivers results by comparing aggregate mode `#path` links to paginated mode `[path.md]` file references. Optimize your workflow with deepwiki-mcp.

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

---

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

```typescript
// 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`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/lib/linkRewrite.ts), where the `rehypeRewriteLinks` plugin checks the mode and transforms `href` properties accordingly:

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

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

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

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

```typescript
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`](https://github.com/regenrek/deepwiki-mcp/blob/main/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`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/schemas/deepwiki.ts), processed in [`src/tools/deepwiki.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/tools/deepwiki.ts), and implemented in [`src/lib/linkRewrite.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/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`](https://github.com/regenrek/deepwiki-mcp/blob/main/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`](https://github.com/regenrek/deepwiki-mcp/blob/main/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`](https://github.com/regenrek/deepwiki-mcp/blob/main/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.