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

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

// 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) creates a searchable metadata table from the 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 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:

// 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.

// 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 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.

// 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.

// 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.

// 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, the server initializes with a stdio transport that connects the LLM client to the tool handlers:

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 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 (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 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 metadata file.

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