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

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 metadata file, it automatically stays synchronized with the latest repository content.

MCP Server Architecture and STDIO Transport

In 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

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 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 (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 (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 (lines 158–196).

recommend: Suggest Relevant Sections via llms.txt

The recommend handler parses the human-written metadata in 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 (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 (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:

> 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:

// 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:

# 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

The MCP server requires no hard-coded indexes. Instead, 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 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 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 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, 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, and get_examples for extracting fenced code blocks. Each tool is defined with a Zod input schema inside 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 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 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.

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