# How the MCP Server Queries the Compendium Knowledge Base: A File-System Deep Dive

> Discover how the MCP server queries the compendium knowledge base by directly reading filesystem Markdown files, utilizing a Node.js implementation for efficient operations without external databases. Learn the technical details.

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

---

**The MCP server queries the Maths-CS-AI compendium by reading Markdown files directly from the repository's filesystem, using a lightweight Node.js implementation that exposes filesystem operations as Model-Context-Protocol tools without any external database.**

The HenryNdubuaku/maths-cs-ai-compendium repository includes a Model-Context-Protocol (MCP) server that enables LLMs to interact with its structured knowledge base. Unlike traditional database-backed systems, this implementation satisfies all queries by reading plain-text Markdown files on-the-fly from the repository structure. This file-system approach eliminates external dependencies while providing fast, direct access to the compendium's chapters and sections.

## File-System Architecture of the Knowledge Base

The compendium organizes content as Markdown files within a hierarchical directory structure. The MCP server discovers and reads these files using native Node.js filesystem operations.

### Locating the Compendium Root

The server first determines where to find the knowledge base content. In [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts), the `ROOT` constant (lines 9-10) checks for the `COMPENDIUM_ROOT` environment variable. If not set, it falls back to the repository root two levels up from the source file:

```typescript
// From mcp/src/index.ts, lines 9-10
const ROOT = process.env.COMPENDIUM_ROOT 
  ? path.resolve(process.env.COMPENDIUM_ROOT) 
  : path.join(__dirname, "..", "..");

```

### Discovering Chapters and Sections

The server implements two discovery functions to map the repository structure:

- **`getChapters()`** (lines 34-44): Scans the root directory for folders matching the pattern `chapter NN: ...`
- **`getSections()`** (lines 46-56): Within each chapter folder, scans for files named `DD. <title>.md`

These functions enable the server to build a complete index of available content without maintaining a separate database.

### The llms.txt Metadata Index

For intelligent recommendations, the server parses a human-written index file. The `parseLlmsTxt()` function (lines 58-84 in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts)) creates a searchable metadata table from the [`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/llms.txt) file, extracting titles and descriptions used by the **recommend** tool.

## Query Tools Implementation

The MCP server registers five primary tools in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) that expose the file-system knowledge base to LLM clients. Each tool handler reads and processes Markdown content directly.

### Reading Specific Sections

The `read_section` tool (lines 38-53) loads a specific Markdown file based on chapter and section numbers. It constructs the file path from the chapter directory and section filename, then returns the raw content:

```typescript
// Example invocation
await server.invokeTool("read_section", { chapter: 3, section: 2 });

```

### Full-Text Search

The `search` tool implementation (lines 64-96) performs brute-force full-text search by iterating over every section in the compendium. It loads each Markdown file, extracts matching excerpts for the query term, and returns aggregated results with file paths and context snippets.

```typescript
// Searching for gradient descent across all sections
await server.invokeTool("search", { query: "gradient descent" });

```

### Intelligent Recommendations

The `recommend` tool (lines 7-34) provides fuzzy matching against the [`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/llms.txt) metadata. It filters stop-words from the query, scores matches against the metadata index created by `parseLlmsTxt()`, and returns an ordered list of relevant sections. This approach provides semantic relevance without requiring vector embeddings or external AI services.

```typescript
// Getting tailored recommendations
await server.invokeTool("recommend", { query: "how do transformers work?" });

```

### Code Example Extraction

The `get_examples` tool (lines 68-108) searches Markdown files for fenced code blocks. It optionally filters by programming language (e.g., `cpp`, `python`) or keywords, extracting relevant snippets for technical queries.

```typescript
// Fetching CUDA examples in C++
await server.invokeTool("get_examples", {
  query: "CUDA",
  language: "cpp",
});

```

### Listing Available Topics

The `list_topics` tool returns a formatted enumeration of all chapters and sections discovered by the `getChapters()` and `getSections()` functions, providing LLMs with a complete map of the available knowledge base.

```typescript
// Listing all chapters and sections
await server.invokeTool("list_topics", {});

```

## Server Initialization and Transport

The server uses the **Model-Context-Protocol SDK** to expose these filesystem operations as standardized tools. According to the source code in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts), the server initializes with a `stdio` transport that connects the LLM client to the tool handlers:

```typescript
const server = new McpServer({ name: "compendium", version: "1.0.0" });
const transport = new StdioServerTransport();
await server.connect(transport);

```

This architecture means every query—whether listing topics, reading sections, searching text, or recommending material—is fulfilled by reading the plain-text Markdown files that form the compendium. No external services, databases, or caches are involved; the knowledge base is the repository itself.

## Summary

The MCP server in the HenryNdubuaku/maths-cs-ai-compendium repository implements a lightweight, file-system-backed knowledge base:

- **Direct filesystem access**: All queries read Markdown files directly from `COMPENDIUM_ROOT` without database abstraction
- **Dynamic discovery**: The `getChapters()` and `getSections()` functions map the repository structure at runtime
- **Metadata-driven recommendations**: The `parseLlmsTxt()` function enables fuzzy matching against the [`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/llms.txt) index
- **Five query tools**: `list_topics`, `read_section`, `search`, `recommend`, and `get_examples` provide comprehensive access patterns
- **Zero external dependencies**: The server requires only Node.js and the MCP SDK, operating entirely on the repository's Markdown content

## Frequently Asked Questions

### What is the MCP server in the maths-cs-ai-compendium repository?

The MCP server is a lightweight Node.js service that implements the Model-Context-Protocol, exposing tools that allow LLMs to query the compendium's knowledge base. It runs as a stdio-based transport service that reads the repository's Markdown files directly to satisfy information requests.

### How does the MCP server locate the compendium files?

The server checks the `COMPENDIUM_ROOT` environment variable first. If unset, it defaults to the repository root two levels up from the source file, as defined by the `ROOT` constant in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) (lines 9-10). This ensures the server can find the chapter directories whether running in development or production environments.

### What is the difference between the search and recommend tools?

The **search** tool performs full-text content scanning across all Markdown files, loading each section and extracting literal keyword matches. The **recommend** tool uses the [`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/llms.txt) metadata index to perform fuzzy, stop-word-filtered scoring against section titles and descriptions, providing semantic relevance without loading full file contents.

### Does the MCP server require a database or external API?

No. The server operates entirely on the filesystem, reading Markdown files directly from the repository. It has no database dependencies, cache layers, or external API requirements. The knowledge base consists solely of the repository's Markdown files and the [`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/llms.txt) metadata file.