# What Is the MCP Server in the Maths, CS & AI Compendium? > Discover the MCP server in the Maths, CS & AI Compendium. This Node.js service makes the knowledge base programmable for AI assistants, enabling local repository queries and recommendations. - Repository: [Henry Ndubuaku/maths-cs-ai-compendium](https://github.com/HenryNdubuaku/maths-cs-ai-compendium) - Tags: getting-started - Published: 2026-07-16 --- **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`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/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`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/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`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/package.json). Navigate to the repository root and start the server: ```bash 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:** ```json { "method": "list_topics", "params": {} } ``` **Read a specific section:** ```json { "method": "read_section", "params": { "chapter": 6, "section": 3 } } ``` **Search for a term:** ```json { "method": "search", "params": { "query": "gradient descent" } } ``` **Get recommended reading:** ```json { "method": "recommend", "params": { "query": "how transformers work" } } ``` **Extract Python examples:** ```json { "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`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) | Full implementation of the MCP server and all registered tools | | [`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/llms.txt) | Human-written meta-data used by the `recommend` tool for ranking sections | | [`README.md`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/README.md) | Documentation explaining the MCP server presence and educational intent | | [`package.json`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/package.json) | Declares `@modelcontextprotocol/sdk` dependencies | | [`tsconfig.json`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/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`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/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`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/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`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/llms.txt) file used for? The [`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/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`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/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`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/src/index.ts) to locate the `ROOT` directory, allowing you to point the MCP server at custom installations or forked versions of the compendium.