# How to Get Code Examples from the Compendium Using MCP: A Complete Guide

> Easily extract code examples from the Maths-CS-AI Compendium using MCP. Query by topic, language, or chapter and get up to 10 relevant markdown snippets.

- 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 exposes a `get_examples` tool through its STDIO-based MCP server that extracts fenced code blocks from markdown sections, allowing you to query by topic, programming language, or chapter and receive up to 10 matching snippets.**

The **HenryNdubuaku/maths-cs-ai-compendium** repository ships with a built-in **Model Context Protocol (MCP)** server that transforms static markdown documentation into a queryable code database. By leveraging the **`get_examples`** tool implemented in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts), developers can programmatically extract code examples without manually parsing files or chapters.

## Understanding the MCP Server Implementation

The server logic resides in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts), where the MCP framework registers the **`get_examples`** tool between [source lines 60‑70](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts#L60). The implementation scans each chapter and section for fenced code blocks, applies optional filters, and returns structured results ([source lines 68‑104](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts#L68)).

### STDIO Transport and Environment Configuration

The server communicates via **STDIO transport**, reading the repository root from the **`COMPENDIUM_ROOT`** environment variable (defaulting to the repository root). This architecture allows any subprocess-capable language to interact with the server through standard input and output streams, making it compatible with command-line tools, Node.js scripts, or Python subprocess modules.

## How to Get Code Examples from the Compendium Using MCP

### Starting the MCP Server

Prerequisites: Node.js ≥ 18 and a cloned copy of the repository.

```bash
git clone https://github.com/HenryNdubuaku/maths-cs-ai-compendium.git
cd maths-cs-ai-compendium

npm install --prefix mcp

node mcp/src/index.ts

```

When successful, the server outputs:

```

Compendium MCP server running on stdio

```

### Querying by Topic and Language

Use the **`get_examples`** tool with the `query` and `language` parameters to filter results. The tool accepts an `inputSchema` defined at [lines 62‑68](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts#L62) of [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts).

```javascript
import { McpClient } from "@modelcontextprotocol/sdk/client/mcp.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function getExamples() {
  const transport = new StdioClientTransport();
  const client = new McpClient({ transport });

  const response = await client.callTool("get_examples", {
    query: "attention",
    language: "python",
  });

  console.log(response.content[0].text);
}

getExamples().catch(console.error);

```

This returns up to 10 Python code examples related to attention mechanisms, each preceded by its chapter/section header.

### Filtering by Chapter

To retrieve all code examples from a specific chapter, pass the numeric chapter index to the `chapter` parameter:

```javascript
const response = await client.callTool("get_examples", {
  chapter: 16,
});

```

This targets Chapter 16 (SIMD & GPU programming) and returns every fenced code block found within that chapter's sections.

### Quick Testing with Command Line

For rapid validation without writing a client, pipe JSON directly to the server via STDIO:

```bash
printf '{"tool":"get_examples","arguments":{"query":"CUDA kernel","language":"cpp"}}\n' \
| node mcp/src/index.ts

```

The server responds with a JSON payload where the `content[0].text` field contains the matched C++ examples.

## MCP Tool Specification and Parameters

The **`get_examples`** tool accepts the following input schema:

- **`query`** (string): Search term to match against code content
- **`language`** (string): Programming language filter (e.g., "python", "cpp", "javascript")
- **`chapter`** (number): Numeric chapter index to restrict the search scope

The tool returns a structured content payload containing up to **10 matching examples**, including contextual excerpts and source locations.

## Summary

- The **`get_examples`** tool in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) enables programmatic extraction of code snippets from the compendium.
- It supports **STDIO transport**, allowing interaction via subprocesses in any programming language.
- Filter parameters include `query` (search term), `language` (programming language), and `chapter` (numeric index).
- Results are capped at **10 examples** per request and include contextual chapter/section headers.
- The server requires the `COMPENDIUM_ROOT` environment variable to locate the repository root.

## Frequently Asked Questions

### What is the maximum number of code examples returned by the MCP tool?

The **`get_examples`** tool returns up to **10 matching examples** per invocation. This limit is hardcoded in the implementation logic at lines 68‑104 of [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) to ensure efficient response times and manageable context windows for downstream AI assistants.

### Can I use the MCP server without installing Node.js dependencies?

No. The server requires Node.js ≥ 18 and the dependencies specified in [`mcp/package.json`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/package.json), including the `@modelcontextprotocol/sdk`. You must run `npm install --prefix mcp` before starting the server to ensure the MCP framework libraries are available for the STDIO transport and JSON-RPC handling.

### How does the server locate the compendium files?

The server reads the **`COMPENDIUM_ROOT`** environment variable to determine the repository root. If unset, it defaults to the current working directory. Therefore, you should launch the server from the cloned repository root or explicitly set the variable to the correct path containing the markdown chapters.

### What transport protocol does the MCP server use?

The server uses **STDIO transport** (standard input/output), making it compatible with any client capable of spawning subprocesses and handling JSON-RPC over pipes. This includes command-line tools, Node.js scripts, Python subprocess modules, or any MCP-compliant client that can communicate over STDIN/STDOUT.