How to Read a Specific Section of the Compendium Using MCP: A Complete Guide

The Math‑CS‑AI Compendium exposes a read_section tool through its Model Context Protocol (MCP) server that retrieves specific educational content by accepting numeric chapter and section identifiers.

The HenryNdubuaku/maths-cs-ai-compendium repository organizes its educational materials into a structured markdown format and exposes them through a Model Context Protocol (MCP) server. When you need to read a specific section of the compendium using MCP, the server provides a dedicated tool that handles content lookup, validation, and retrieval automatically.

Understanding the MCP Server Architecture

The MCP server implementation resides in mcp/src/index.ts and registers the read_section tool during server initialization (lines 30‑55). This tool acts as the primary interface for accessing the compendium's structured content, which is organized into numbered chapters (1‑20) and sections (typically 0‑7, though exact ranges vary by chapter).

How to Read a Specific Section Using the read_section Tool

Tool Parameters and Validation

The read_section tool accepts two required numeric parameters:

• chapter: An integer from 1 to 20 representing the target chapter.
• section: An integer representing the section within that chapter (typically ranging 0‑7, though exact ranges vary by chapter).

When invoked, the tool validates these parameters against the actual content structure stored in the repository.

Implementation Steps in mcp/src/index.ts

According to the source code at lines 38‑53, the tool executes a four-step retrieval process:

1. Locate the requested chapter – The server calls getChapters() to load all available chapters, then filters for the one whose number property matches the supplied chapter parameter. If the chapter does not exist, it returns a descriptive error message.

2. Locate the requested section – Using getSections(ch.path), the server loads the chapter's sections and finds the one matching the section parameter. Missing sections trigger an error listing valid section numbers for that chapter.

3. Read the markdown file – The server reads the section's file using readFile(sec.path, "utf-8") to obtain the raw markdown content.

4. Return formatted content – The response object contains a content array with a single text block prefixed by a heading that displays the chapter and section titles (lines 52‑54).

Practical Code Examples

Using the MCP CLI

If you have the MCP CLI installed, you can start the server and invoke the tool directly:

# Start the MCP server (runs on stdio)

node ./mcp/src/index.ts &

# Read Chapter 5, Section 2

./mcp-cli call read_section '{"chapter":5,"section":2}'

The CLI returns the full markdown content of the requested section, including the automatically generated header showing the chapter and section titles.

Programmatic Access with JavaScript/TypeScript

For applications requiring dynamic access, use the MCP SDK client:

import { McpClient } from "@modelcontextprotocol/sdk/client/mcp.js";

async function fetchSection(ch: number, sec: number) {
  const client = new McpClient({ name: "compendium" });
  await client.connect();               // connects to the stdio server
  const result = await client.callTool("read_section", { 
    chapter: ch, 
    section: sec 
  });
  console.log(result.content[0].text); // full markdown of the section
}

// Example: Read Chapter 9, Section 4 (audio and speech - speaker analysis)
fetchSection(9, 4);

This approach handles the JSON-RPC exchange automatically and returns the same structured response format that the server generates.

Summary

• The read_section tool in mcp/src/index.ts provides programmatic access to specific compendium content.
• It requires two parameters: chapter (1‑20) and section (varies by chapter).
• The implementation validates inputs against actual content using getChapters() and getSections() before reading files with readFile().
• You can invoke the tool via MCP CLI commands or programmatically using the TypeScript SDK.
• The server returns markdown content prefixed with contextual headings showing the chapter and section titles.

Frequently Asked Questions

What parameters does the read_section tool require?

The tool requires two numeric parameters: chapter (integer 1‑20) and section (integer, typically 0‑7 depending on the chapter). These correspond to the physical organization of the markdown files in the repository.

Which file contains the MCP server implementation?

The MCP server is implemented in mcp/src/index.ts, specifically lines 30‑55 where the read_section tool is registered and defined. The mcp/package.json file declares the required MCP SDK dependencies.

How does the server handle invalid chapter or section numbers?

The server performs validation by checking against available chapters via getChapters() and sections via getSections(ch.path). If a chapter or section does not exist, it returns a helpful error message that includes the valid available numbers for the requested resource.

Can I integrate this with AI assistants or other applications?

Yes. Because the compendium exposes a standard MCP interface, any MCP-compatible client—including AI assistants, IDE extensions, or custom applications—can invoke the read_section tool to retrieve specific educational content programmatically.

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