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

> Discover how to search the Maths, CS & AI Compendium using the MCP server. Access and query the programmable knowledge base via JSON-RPC for efficient data extraction. Learn more now.

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

---

**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](https://github.com/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`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/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`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/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.

```bash
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`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/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.

```javascript
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.

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

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

```javascript
// 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`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts)** – The main server implementation that registers the five tools and handles JSON-RPC communication.
- **[`mcp/package.json`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/package.json)** – Declares the entry point and dependencies, including the MCP SDK.
- **[`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/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`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/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`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/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`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/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.