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

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, 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, where the MCP framework registers the get_examples tool between source lines 60‑70. The implementation scans each chapter and section for fenced code blocks, applies optional filters, and returns structured results (source lines 68‑104).

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.

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 of mcp/src/index.ts.

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:

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:

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 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 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, 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.

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