# How the MCP Server Integrates with AI Assistants and Exposes Knowledge Base Tools

> Discover how the MCP server integrates with AI assistants and exposes knowledge base tools. Learn how the Maths-CS-AI Compendium leverages `@modelcontextprotocol/sdk` for seamless query access to repository content.

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

---

**The Maths-CS-AI Compendium ships an MCP server built on the `@modelcontextprotocol/sdk` that registers filesystem-backed knowledge base tools and exposes them over STDIO, allowing any Model-Context-Protocol-compatible AI assistant to query repository content through JSON-RPC-style calls.**

The `HenryNdubuaku/maths-cs-ai-compendium` repository transforms its educational markdown content into an interactive knowledge base through a dedicated MCP server. This integration lets AI assistants discover, search, and retrieve sections of the compendium without hard-coded indexes or manual ingestion. Because the server uses filesystem introspection and the [`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/llms.txt) metadata file, it automatically stays synchronized with the latest repository content.

## MCP Server Architecture and STDIO Transport

In [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts), the server creates a **`McpServer`** instance and attaches a **STDIO transport** for communication. The STDIO transport enables the server to read and write JSON-RPC-style messages over standard input and output streams, which is the default channel used by integrations such as Claude Code, Cursor, and VS Code extensions. The `@modelcontextprotocol/sdk` handles serialization, **Zod** schema validation, and response formatting automatically.

## Knowledge Base Tools Registered in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts)

The server exposes five tools that turn the repository into a structured knowledge source. Each tool defines its input schema with Zod and implements a handler that runs filesystem operations:

- **`list_topics`** — Enumerates chapter folders (`chapter XX: …`) and their markdown files, with an optional `{ chapter?: number }` filter.
- **`read_section`** — Returns the full text of a specific section given `{ chapter: number, section: number }`.
- **`search`** — Performs full-text search across all markdown files for a `{ query: string }` and returns surrounding excerpts.
- **`recommend`** — Parses [`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/llms.txt) metadata and scores sections via keyword matching to suggest content for a learning goal.
- **`get_examples`** — Scans markdown for fenced code blocks, optionally filtered by `{ query?, language?, chapter? }`.

### `list_topics`: Enumerate Chapters and Sections

The `list_topics` handler reads the filesystem to enumerate chapter folders and the markdown files they contain. It accepts an optional `chapter` parameter and is implemented in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) (lines 102–126). This lets an AI assistant discover the repository structure dynamically rather than relying on a static manifest.

### `read_section`: Retrieve Full Section Content

The `read_section` handler resolves the appropriate markdown file for a given chapter and section number, then streams its full content back to the caller. It requires `{ chapter: number, section: number }` and is defined in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) (lines 129–155).

### `search`: Full-Text Search Across the Repository

The `search` tool loads each markdown file and scans for occurrences of the supplied `query` string, returning excerpts with surrounding context. This gives AI assistants keyword-level retrieval over the entire compendium. The implementation lives in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) (lines 158–196).

### `recommend`: Suggest Relevant Sections via [`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/llms.txt)

The `recommend` handler parses the human-written metadata in [`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/llms.txt) and scores sections using keyword matching against the provided query. It returns an ordered list of the most relevant sections for a stated learning goal. You can find this logic in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) (lines 200–256).

### `get_examples`: Extract Code Blocks by Topic or Language

The `get_examples` tool scans markdown files for fenced code blocks and returns them with surrounding narrative context. It supports optional filters for `query`, `language`, and `chapter`. This is implemented in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) (lines 259–322).

## How AI Assistants Call MCP Tools Over STDIO

When an AI assistant launches the MCP server as a background process, its runtime issues JSON-RPC-style calls through the STDIO channel. The SDK validates inputs against the Zod schemas and formats the JSON responses so the assistant can treat the compendium as a native knowledge source. Typical request-response flow looks like this:

```text
> assistant> list_topics { "chapter": 5 }
< server> { "content": [{ "type": "text", "text": "..."}] }

```

Because the server relies on `readdir` and `readFile` rather than a compiled index, an assistant always receives content that reflects the current state of the repository.

### JavaScript Client Integration Example

An external program or AI-assistant plugin can start the server and invoke tools using a client from `@modelcontextprotocol/sdk`. The example below assumes Node.js ≥ 20 and a local clone of the repository:

```javascript
// Start the MCP server (normally done by the assistant host)
import { spawn } from 'node:child_process';
const mcp = spawn('npm', ['run', 'start'], { cwd: '/path/to/maths-cs-ai-compendium/mcp' });

// Connect a simple client that talks over stdio
import { McpClient } from '@modelcontextprotocol/sdk/client/mcp.js';

const client = new McpClient({
  transport: {
    send: (msg) => mcp.stdin.write(JSON.stringify(msg) + '\n'),
    onMessage: (handler) => {
      let buffer = '';
      mcp.stdout.on('data', (data) => {
        buffer += data.toString();
        const lines = buffer.split('\n');
        while (lines.length > 1) {
          const line = lines.shift();
          if (line.trim()) handler(JSON.parse(line));
        }
        buffer = lines[0];
      });
    },
  },
});

// List all chapters
await client.callTool('list_topics', {})

// Read chapter 7, section 3
await client.callTool('read_section', { chapter: 7, section: 3 })

// Search for "attention mechanism"
await client.callTool('search', { query: 'attention mechanism' })

```

### CLI Wrapper for Terminal Queries

You can also query the server directly from a terminal using the CLI wrapper bundled with the SDK:

```bash

# Start the server in the background

npm run start --workspace=mcp &

# Call a tool via the SDK CLI

npx @modelcontextprotocol/sdk mcp call list_topics '{"chapter":2}'

```

Both methods return JSON objects containing a `content` array with markdown-formatted text that the assistant can render or process further.

## Automatic Indexing via Filesystem Introspection and [`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/llms.txt)

The MCP server requires **no hard-coded indexes**. Instead, [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) uses Node.js filesystem APIs to discover chapters and sections at runtime. The `recommend` tool augments this with metadata from the repository root’s **[`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/llms.txt)** file, which provides human-written descriptions for scoring relevance. This design means new chapters and sections are immediately available to AI assistants as soon as they are committed to the filesystem.

## Summary

- The **MCP server** in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) uses the `@modelcontextprotocol/sdk` to expose five knowledge base tools over **STDIO**.
- **AI assistants** communicate via JSON-RPC-style messages, calling tools such as `list_topics`, `read_section`, `search`, `recommend`, and `get_examples`.
- **Zod schemas** validate every tool input, while filesystem introspection and **[`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/llms.txt)** keep responses current without rebuilds.
- Clients can integrate through a **JavaScript SDK client** or the provided **CLI wrapper** for direct terminal access.

## Frequently Asked Questions

### How does the MCP server communicate with AI assistants?

The server attaches a **STDIO transport** to the `McpServer` instance in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts), enabling JSON-RPC-style communication over standard input and output streams. This channel is compatible with Claude Code, Cursor, and other Model-Context-Protocol-aware hosts.

### What knowledge base tools does the MCP server expose?

The server registers five tools: **`list_topics`** for discovery, **`read_section`** for full-text retrieval, **`search`** for keyword queries, **`recommend`** for relevance scoring via [`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/llms.txt), and **`get_examples`** for extracting fenced code blocks. Each tool is defined with a Zod input schema inside [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) and returns markdown-formatted results through the STDIO transport.

### How does the server stay up-to-date when new content is added?

Because the handlers in [`mcp/src/index.ts`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/mcp/src/index.ts) call `readdir` and `readFile` at runtime, the server performs live filesystem introspection rather than relying on static indexes. Any new chapter or section appears in tool results immediately after it is written to disk.

### Which metadata file powers the recommendation tool?

The **`recommend`** tool parses [`llms.txt`](https://github.com/HenryNdubuaku/maths-cs-ai-compendium/blob/main/llms.txt) from the repository root to score and rank sections. This human-curated metadata allows the tool to match user learning goals with relevant compendium content using keyword scoring.