What Is the MCP Server in the Maths, CS & AI Compendium?

The MCP server is a lightweight Node.js service that exposes the entire knowledge base through programmable tools, enabling AI assistants to query, read, search, and recommend sections directly from a local repository clone.

The Maths, CS & AI Compendium (HenryNdubuaku/maths-cs-ai-compendium) bundles an MCP server to bridge static documentation with interactive AI workflows. This Model Context Protocol implementation transforms the markdown-based knowledge base into a structured, searchable API that Claude Code, Cursor, and VS Code extensions can consume programmatically.

Architecture and Core Components

The MCP server follows a modular architecture built on the official Model Context Protocol SDK. It runs as a CLI process using stdin/stdout transport, making it compatible with any AI assistant that spawns subprocesses.

McpServer and Transport Layer

At src/index.ts line 1, the server imports McpServer from @modelcontextprotocol/sdk/server/mcp.js to register tools and handle incoming JSON-RPC calls. Line 2 initializes StdioServerTransport from @modelcontextprotocol/sdk/server/stdio.js, providing a simple stdin/stdout transport layer that requires no network configuration.

The server bootstrap occurs at lines 325-332, where the transport connects and prints "Compendium MCP server running on stdio" to stderr before listening for requests.

File System Discovery

The ROOT constant defined at line 9 points to the repository root, overridable via the COMPENDIUM_ROOT environment variable. Lines 34-56 implement chapter and section discovery through getChapters and getSections functions, which scan for folders matching chapter XX: … and markdown files matching NN. …\.md patterns.

Available Tools and Capabilities

The server exposes five distinct tools that give AI agents structured access to the compendium content.

list_topics

The list_topics tool (lines 102-126) returns a formatted list of all chapters and their sections. It accepts an optional chapter filter parameter and formats the output as Markdown that AI assistants can render directly.

read_section

The read_section tool (lines 129-155) loads the full markdown content of a specific chapter and section. This enables assistants to retrieve complete educational content on demand rather than loading the entire repository into context.

search

The search tool (lines 158-196) performs case-insensitive full-text searches across every section in the compendium. It returns matches with surrounding context lines, allowing assistants to locate specific concepts without prior knowledge of the file structure.

recommend

The recommend tool (lines 199-256) parses llms.txt for human-written meta-descriptions, extracts keywords, scores sections against the query, and suggests a personalized reading order. This goes beyond simple search to provide curated learning paths.

get_examples

The get_examples tool (lines 259-322) extracts fenced code blocks from the repository, optionally filtered by programming language, query terms, or specific chapters. It returns the code with surrounding context, making it ideal for AI assistants helping users implement algorithms from the compendium.

Getting Started with the MCP Server

Installation and Startup

The server requires Node.js and the dependencies declared in package.json. Navigate to the repository root and start the server:

node mcp/src/index.ts

The process writes "Compendium MCP server running on stdio" to stderr and begins listening on stdin for JSON-RPC requests.

Example JSON-RPC Requests

List all topics:

{
  "method": "list_topics",
  "params": {}
}

Read a specific section:

{
  "method": "read_section",
  "params": { "chapter": 6, "section": 3 }
}

Search for a term:

{
  "method": "search",
  "params": { "query": "gradient descent" }
}

Get recommended reading:

{
  "method": "recommend",
  "params": { "query": "how transformers work" }
}

Extract Python examples:

{
  "method": "get_examples",
  "params": { "query": "attention", "language": "python" }
}

All responses contain a content field with Markdown that the assistant can render directly.

Key Files and Configuration

File	Purpose
mcp/src/index.ts	Full implementation of the MCP server and all registered tools
llms.txt	Human-written meta-data used by the recommend tool for ranking sections
README.md	Documentation explaining the MCP server presence and educational intent
package.json	Declares @modelcontextprotocol/sdk dependencies
tsconfig.json	TypeScript configuration for the mcp module

Summary

• The MCP server in the Maths, CS & AI Compendium is a Node.js service implementing the Model Context Protocol specification.
• It uses StdioServerTransport at src/index.ts line 2 to communicate via stdin/stdout, requiring no network setup.
• Five tools (list_topics, read_section, search, recommend, get_examples) provide structured access to chapters, sections, and code examples.
• The recommend tool leverages llms.txt meta-descriptions to suggest personalized reading paths.
• Set COMPENDIUM_ROOT to override the default repository root directory.

Frequently Asked Questions

What does MCP stand for?

MCP stands for Model Context Protocol, an open standard that allows AI assistants to connect to external data sources and tools through a standardized interface. The compendium implements this protocol to make its educational content programmatically accessible.

How does the server communicate with AI assistants?

The server uses stdio transport via StdioServerTransport from the MCP SDK. It reads JSON-RPC requests from standard input and writes responses to standard output, making it compatible with any AI assistant that can spawn and communicate with CLI processes.

What is the llms.txt file used for?

The llms.txt file contains human-written meta-descriptions and keywords for sections of the compendium. The recommend tool parses this file at lines 199-256 of src/index.ts to score and rank sections against user queries, providing curated learning recommendations rather than simple keyword matches.

Can I run the server against a different directory structure?

Yes. Set the COMPENDIUM_ROOT environment variable to override the default repository root. The server uses this variable at line 9 of src/index.ts to locate the ROOT directory, allowing you to point the MCP server at custom installations or forked versions of the compendium.

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