How Content Is Organized in the Maths CS & AI Compendium: A Complete Guide

The Maths, CS & AI Compendium organizes content into 20 numbered chapter folders with sequentially sectioned Markdown files, supported by a Model Context Protocol (MCP) server that enables programmatic discovery of the curriculum.

The HenryNdubuaku/maths-cs-ai-compendium repository structures itself as a self-contained digital textbook covering mathematics, computer science, and artificial intelligence. Understanding how content is organized in the Maths CS & AI Compendium reveals a hybrid architecture designed for both human readers browsing a static site and AI assistants consuming the material through a programmatic interface.

Chapter-Based Folder Structure

The repository implements a strict hierarchical filesystem that mirrors a traditional textbook outline. Each of the 20 chapters resides in its own directory following the naming convention chapter NN: <Chapter Name>, where NN represents a two-digit chapter number.

Naming Conventions

Chapter folders use the pattern chapter 01: vectors, chapter 02: matrices, and so forth through artificial intelligence topics. Inside each chapter directory, individual sections appear as Markdown files named DD. <Section Title>.md, where DD denotes a two-digit section number. For example, chapter 01: vectors/01. vector spaces.md contains the introductory content on vector theory.

Section Files

Each .md file represents a discrete learning unit containing educational content, mathematical notation, and code snippets. The sequential numbering ensures a logical reading progression, while the human-readable titles facilitate quick navigation. This structure allows the compendium to scale across vectors, matrices, calculus, and AI inference topics while maintaining strict organizational consistency.

Machine-Readable Architecture

Beyond static documentation, the repository exposes its content hierarchy through a Model Context Protocol (MCP) server implemented in mcp/src/index.ts. This TypeScript server automatically discovers chapters and sections at runtime, transforming the filesystem into a queryable knowledge base.

MCP Server Discovery Logic

The server uses regular expressions to parse the directory structure without hard-coding paths. In mcp/src/index.ts, the code defines:

CHAPTER_RE = /^chapter (\d{2}): (.+)$/
SECTION_RE = /^(\d{2})\. (.+)\.md$/

Using fs.readdir, the server iterates through the repository root to identify chapter folders matching CHAPTER_RE, then descends into each folder to locate section files matching SECTION_RE. This dynamic discovery builds arrays of Chapter and Section objects containing numeric identifiers, human-readable names, and absolute filesystem paths.

Available Tools

The MCP server exposes four primary tools that consume the discovered hierarchy:

• list_topics – Returns all chapters and their sections, or filters to a specific chapter when requested
• read_section – Retrieves the full Markdown content of a specific chapter and section combination
• search – Performs full-text search across every section in the repository
• recommend – Suggests a personalized reading order based on a learning goal query

The server runs on standard I/O (StdioServerTransport), enabling integration with IDE extensions, CLI tools, and other MCP-compatible clients.

Content Delivery and Assets

The compendium supports multiple consumption modes through complementary configuration files and asset organization.

MkDocs Integration

The mkdocs.yml file configures the MkDocs static site generator, which renders the Markdown chapters into a browsable website. This allows human readers to navigate the content at henryndubuaku.github.io/maths-cs-ai-compendium with semantic URLs and search functionality that mirrors the underlying filesystem structure.

Visual Assets

A top-level images/ directory stores SVG and PNG illustrations referenced by the Markdown files. Assets like vector_addition.svg provide visual explanations that enrich the textual material, maintaining a clear separation between content and presentation layers.

Practical Usage Examples

Developers can interact with the compendium's organization programmatically using the MCP server. Below are implementations demonstrating how to traverse the content structure.

Listing All Chapters and Sections

import { createClient } from "@modelcontextprotocol/sdk/client";

async function showContents() {
  const client = await createClient({ transport: "stdio" });
  const resp = await client.callTool("list_topics", {});
  console.log(resp.content[0].text);
}
showContents();

This returns a hierarchical outline:

## Chapter 01: Vectors

  01. vector spaces
  02. vector properties

## Chapter 02: Matrices

  01. matrix properties

Reading Specific Content

import { createClient } from "@modelcontextprotocol/sdk/client";

async function readVectorSpaces() {
  const client = await createClient({ transport: "stdio" });
  const resp = await client.callTool("read_section", { chapter: 1, section: 1 });
  console.log(resp.content[0].text);
}
readVectorSpaces();

Searching Across the Curriculum

import { createClient } from "@modelcontextprotocol/sdk/client";

async function searchAttention() {
  const client = await createClient({ transport: "stdio" });
  const resp = await client.callTool("search", { query: "attention" });
  console.log(resp.content[0].text);
}
searchAttention();

Generating Learning Recommendations

import { createClient } from "@modelcontextprotocol/sdk/client";

async function recommendForTransformers() {
  const client = await createClient({ transport: "stdio" });
  const resp = await client.callTool("recommend", { query: "how do transformers work?" });
  console.log(resp.content[0].text);
}
recommendForTransformers();

Summary

• The repository organizes 20 chapters into folders named chapter NN: <Name> containing sequentially numbered Markdown sections (DD. <Title>.md)
• The mcp/src/index.ts server uses regex patterns CHAPTER_RE and SECTION_RE to dynamically discover content without hard-coded paths
• Four MCP tools—list_topics, read_section, search, and recommend—provide programmatic access to the curriculum
• mkdocs.yml enables static site generation for human readers, while the images/ folder stores visual assets separately from text content
• The architecture supports both browsing via GitHub Pages and AI-assisted consumption through the Model Context Protocol

Frequently Asked Questions

How are chapter and section numbers formatted in the repository?

Chapter folders use two-digit zero-padded numbers followed by a colon and the chapter name (e.g., chapter 01: vectors). Section files within these folders use two-digit numbers followed by a period and the section title (e.g., 01. vector spaces.md). This formatting allows the MCP server in mcp/src/index.ts to parse the hierarchy using specific regular expressions.

Can I access the content without using the MCP server?

Yes. The repository functions as a standard Markdown documentation project. You can read files directly from the chapter NN: folders or browse the rendered site via the MkDocs configuration in mkdocs.yml. The README.md provides a high-level table of contents linking to each chapter, making manual navigation straightforward.

What technologies enable the search and recommendation features?

The search and recommendation capabilities rely on the TypeScript MCP server located at mcp/src/index.ts. This server implements the search and recommend tools, which process queries against the discovered content structure. The server runs on standard I/O (StdioServerTransport), allowing it to integrate with various clients and development environments.

Where are images and diagrams stored?

Visual assets reside in the top-level images/ directory as SVG and PNG files. These files are referenced from within the chapter Markdown files using relative paths, keeping the textual content separate from graphical illustrations while maintaining the ability to render rich educational materials.

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