# How to List All Topics in the Maths CS & AI Compendium Using MCP

> Easily list all topics in the Maths CS & AI Compendium using the MCP list_topics tool. This command scans the repository and returns a formatted outline of chapters and sections.

- Repository: [Henry Ndubuaku/maths-cs-ai-compendium](https://github.com/HenryNdubuaku/maths-cs-ai-compendium)
- Tags: tutorial
- Published: 2026-07-16

---

**The `list_topics` tool in the HenryNdubuaku/maths-cs-ai-compendium MCP server enumerates every chapter and section by scanning the repository structure and returning a formatted plain-text outline.**

The Maths CS & AI Compendium provides a Model-Context-Protocol (MCP) server that exposes programmatic access to its educational content. When you need to discover available chapters and their sections programmatically, the `list_topics` tool offers a deterministic way to retrieve the complete table of contents or filter results to a specific chapter.

## How the `list_topics` MCP Tool Works

The tool operates by scanning the filesystem to discover chapters and their corresponding sections dynamically. It relies on two core utility functions defined in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) to build the content hierarchy.

### Chapter Discovery via `getChapters()`

The `getChapters()` function reads the repository root directory—defaulting to `process.env.COMPENDIUM_ROOT` or `../..`—and identifies chapter folders using the regex pattern `^chapter (\d{2}): (.+)$`. According to the source code at lines 34-44, it returns an ordered array of objects containing `{ number, name, path }` for each chapter found in the repository.

### Section Discovery via `getSections()`

For each chapter directory discovered, `getSections(chapterPath)` scans the contents and matches markdown files against the pattern `^(\d{2})\. (.+)\.md$`. As implemented in lines 46-56 of [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts), this yields an array of section objects `{ number, name, path }` sorted numerically, representing individual topics within that chapter.

### Tool Handler Implementation

When an MCP client invokes `list_topics`, the handler accepts an optional `chapter` parameter. It first calls `getChapters()` to retrieve the full list, filters by chapter number if specified, then iterates through each chapter calling `getSections()`. The results assemble into a plain-text outline:

```

## Chapter <num>: <name>

  <secNum>. <secName>

```

This implementation in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) (lines 97-126) returns the formatted output wrapped in an MCP response object without external dependencies, ensuring fast execution even across the full compendium of approximately 20 chapters.

## Listing All Topics via TypeScript

To retrieve the complete topic list programmatically, instantiate an MCP client and invoke the tool with no arguments:

```typescript
import { McpClient } from "@modelcontextprotocol/sdk/client";

const client = new McpClient({ url: "http://localhost:8000" });
const res = await client.invokeTool("list_topics", {});   // no args
console.log(res.content[0].text);

```

The output displays every chapter and its sections in a hierarchical plain-text format:

```

## Chapter 01: Foundations of Mathematics

  01. Set Theory
  02. Logic
  ...

## Chapter 02: Linear Algebra

  01. Vectors
  02. Matrices
  ...

```

## Filtering Topics by Specific Chapter

Pass the `chapter` parameter to restrict results to a single chapter:

```typescript
const res = await client.invokeTool("list_topics", { chapter: 7 });
console.log(res.content[0].text);

```

This returns only the sections for Chapter 07:

```

## Chapter 07: Optimization

  01. Gradient Descent
  02. Convex Optimization
  03. Stochastic Methods
  ...

```

## Command Line Access

If the package provides a CLI interface, you can list topics directly from the terminal:

```bash
npx compendium-mcp list_topics          # all topics

npx compendium-mcp list_topics --chapter 12   # only chapter 12

```

## Key Files in the Implementation

Understanding the source structure helps when extending or debugging the topic listing functionality:

- **[`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts)** – Contains the main MCP server definition, including the `list_topics` tool registration, `getChapters()` and `getSections()` implementations, and the handler logic at lines 97-126.

- **[`mcp/package.json`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/package.json)** – Declares the package name `compendium-mcp` and dependencies on the Model-Context-Protocol SDK.

- **[`mkdocs.yml`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mkdocs.yml)** – References the same chapter folders that the MCP tool discovers dynamically.

- **[`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/llms.txt)** – Provides metadata for sections used by other tools like `search`, though `list_topics` relies solely on filesystem scanning.

## Summary

- The `list_topics` tool in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) provides deterministic enumeration of all compendium content through filesystem scanning.
- `getChapters()` discovers chapter folders using regex pattern matching against the repository root at lines 34-44.
- `getSections()` extracts individual topics from markdown files within each chapter directory at lines 46-56.
- The tool accepts an optional `chapter` parameter to filter output to specific chapters.
- Results return as plain text suitable for any MCP-compatible client, from CLI tools to web interfaces.

## Frequently Asked Questions

### What MCP server powers the Maths CS & AI Compendium?

The repository HenryNdubuaku/maths-cs-ai-compendium ships with a dedicated MCP server defined in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts). This server exposes the `list_topics` tool alongside `read_section` and `search` functionality, enabling programmatic access to the educational content.

### Can I list topics without running the full MCP server?

No, the `list_topics` functionality requires an active MCP server connection because it invokes the tool handler defined in the server implementation. However, you can run the server locally and connect via any MCP client, or use the provided CLI if available according to the [`mcp/package.json`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/package.json) configuration.

### How does the tool handle missing or malformed chapters?

The `getChapters()` function in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) strictly matches folder names against the pattern `^chapter (\d{2}): (.+)$`. Folders not matching this pattern are excluded from results, ensuring only properly formatted chapters appear in the topic list.

### Is there a performance limit when listing all topics?

No, the implementation scales efficiently to the full compendium size of approximately 20 chapters. Because `list_topics` performs direct filesystem reads without external API calls or database queries, it remains fast and deterministic regardless of whether you request all chapters or filter to a specific one.