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

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 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, 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 (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:

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:

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:

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 – 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 – Declares the package name compendium-mcp and dependencies on the Model-Context-Protocol SDK.

• mkdocs.yml – References the same chapter folders that the MCP tool discovers dynamically.

• 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 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. 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 configuration.

How does the tool handle missing or malformed chapters?

The getChapters() function in 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.

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