How to Search the Maths, CS & AI Compendium Using the MCP Server

The Maths, CS & AI Compendium ships with a Model-Context-Protocol (MCP) server that exposes the entire textbook as a programmable knowledge base, allowing you to search, read, and extract code examples via JSON-RPC over standard I/O.

The HenryNdubuaku/maths-cs-ai-compendium repository includes a fully functional MCP server that transforms the static textbook into an interactive knowledge base. When you search the Maths, CS & AI Compendium using the MCP server, you can query chapters, sections, and code examples programmatically from any AI-augmented IDE or custom tooling. The server runs locally, requires only a clone of the repository, and communicates via standard I/O using the @modelcontextprotocol/sdk.

Available MCP Tools

The server implementation in mcp/src/index.ts registers five tools that handle different types of queries against the compendium content.

list_topics

Lists all chapters and sections, or filters to a single chapter when provided with a chapter number. The optional chapter parameter accepts a number.

read_section

Returns the full Markdown content of a specific chapter and section. Requires both chapter and section parameters as integers.

search

Performs case-insensitive full-text search across every section of the textbook using a query string parameter.

recommend

Suggests a reading order based on a learning goal, utilizing metadata from llms.txt to score relevance against the provided query string.

get_examples

Extracts code blocks from the compendium, with optional filtering by language (e.g., "python", "javascript") or chapter number.

Starting the MCP Server

To begin searching the compendium, start the MCP server from the repository root. The server creates a McpServer instance named "compendium" and waits for JSON-RPC requests on standard input.

node mcp/src/index.ts

# → prints "Compendium MCP server running on stdio" to stderr

The server reads the repository root from the COMPENDIUM_ROOT environment variable or defaults to the repository location. It walks chapter folders formatted as chapter NN: ... to build an in-memory index of content and metadata from llms.txt.

Searching the Compendium

Once the server is running, you send JSON-RPC messages to invoke specific tools. The server responds with structured data containing human-readable text or code blocks.

Performing Full-Text Searches

Use the search tool to find all occurrences of a term across the entire textbook.

const { spawn } = require('child_process');
const server = spawn('node', ['mcp/src/index.ts']);

function rpc(method, params) {
  const id = Math.random();
  const msg = JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n';
  server.stdin.write(msg);
  return new Promise((resolve) => {
    server.stdout.once('data', (data) => {
      const resp = JSON.parse(data.toString());
      resolve(resp.result);
    });
  });
}

// Find every occurrence of "attention"
rpc('search', { query: 'attention' }).then(console.log);

Reading Specific Sections

To retrieve the content of a specific chapter and section, use the read_section tool with numeric parameters.

// Read Chapter 7, Section 3
rpc('read_section', { chapter: 7, section: 3 }).then(console.log);

Extracting Code Examples

The get_examples tool allows you to filter code blocks by language or topic, making it easy to find implementation references.

// Extract Python code examples about "gradient descent"
rpc('get_examples', { query: 'gradient descent', language: 'python' }).then(console.log);

Getting Recommendations

Use the recommend tool to receive a curated reading list based on your learning goals.

// Get recommended reading for "How do transformers work?"
rpc('recommend', { query: 'How do transformers work?' }).then(console.log);

Implementation Details

The MCP server is built with the @modelcontextprotocol/sdk and handles filesystem traversal to index the textbook content. Key implementation files include:

• mcp/src/index.ts – The main server implementation that registers the five tools and handles JSON-RPC communication.
• mcp/package.json – Declares the entry point and dependencies, including the MCP SDK.
• llms.txt – Contains chapter metadata used by the recommend tool for relevance scoring.

Because communication occurs via JSON-RPC over stdio, any client that can spawn the server process and pipe JSON messages can use the compendium programmatically, including Claude Code, Cursor, VS Code, or custom Node.js scripts.

Summary

• The MCP server in mcp/src/index.ts exposes the Maths, CS & AI Compendium as a programmable knowledge base using the @modelcontextprotocol/sdk.
• Five tools are available: list_topics, read_section, search, recommend, and get_examples.
• The server runs locally via standard I/O and accepts JSON-RPC requests, returning structured content from the textbook files.
• You can filter code examples by language, search full-text across sections, and retrieve recommended reading paths based on learning goals.
• The server uses the COMPENDIUM_ROOT environment variable to locate content and reads metadata from llms.txt for recommendation scoring.

Frequently Asked Questions

What is the MCP server in the Maths, CS & AI Compendium?

The MCP server is a local service implemented in mcp/src/index.ts that uses the Model-Context-Protocol to expose the textbook's content as searchable tools. It allows AI assistants and custom scripts to query the compendium programmatically via JSON-RPC over standard I/O.

How do I start the MCP server locally?

Navigate to the repository root and run node mcp/src/index.ts or npm start from the mcp directory. The server will initialize and print "Compendium MCP server running on stdio" to stderr, indicating it is ready to accept JSON-RPC requests.

What tools are available for searching the compendium?

The server provides five tools: search for full-text queries, list_topics for browsing the table of contents, read_section for retrieving specific content, get_examples for extracting code blocks, and recommend for generating learning paths based on topics.

Can I filter code examples by programming language?

Yes. The get_examples tool accepts an optional language parameter (e.g., "python", "javascript") to filter results. You can also combine this with a query string to find code examples about specific topics like "gradient descent" or "transformer" within that language.

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