What Is the `llms.txt` File Used for in the Maths‑CS‑AI Compendium?

The llms.txt file serves as the single source of truth for language model identifiers supported by the Mathematics‑CS‑AI Compendium (MCP), enabling runtime validation of user requests and automatic generation of documentation.

The llms.txt file lives at the root of the HenryNdubuaku/maths-cs-ai-compendium repository. It is a plain-text configuration file that lists every LLM identifier the MCP tooling recognizes. By externalizing this list from the source code, the compendium ensures that adding support for a new model requires only a text edit rather than code changes across multiple files.

Purpose and Location

According to the repository structure, llms.txt sits at the repository root alongside configuration files like mkdocs.yml. The file contains one model identifier per line—for example, gpt-4, claude-3-opus, or other supported strings. The MCP TypeScript entry point (mcp/src/index.ts) reads this file at runtime to determine which models are available for operations.

How mcp/src/index.ts Consumes llms.txt

The TypeScript tooling does not hard-code supported models. Instead, it dynamically loads llms.txt and parses its contents into an array of strings.

Reading the Configuration File

The entry point uses Node.js fs/promises to read the file asynchronously, resolving the path relative to the execution directory:

import { readFile } from "fs/promises";
import { join } from "path";

const ROOT = __dirname;           // repository root (when the package is executed)
const content = await readFile(join(ROOT, "llms.txt"), "utf-8");

Dynamic Prompt Construction

Once parsed, the list drives validation logic. When a user specifies a model via CLI or API call, the tool checks the identifier against the llms.txt contents. If the requested model is absent, the system either falls back to a default model or throws a descriptive error preventing invocation of unsupported providers.

Documentation Generation

The MkDocs static site generator consumes the same file to build the "Supported LLMs" page. By feeding the parsed list into the site template, the documentation automatically reflects the current codebase without manual editing, ensuring the docs and code never drift out of sync.

Code Implementation Examples

The following patterns demonstrate how the compendium interacts with llms.txt in practice.

Retrieving the Supported Model List

As implemented in mcp/src/index.ts, the utility function reads, splits, and filters the file content:

import { readFile } from "fs/promises";
import { join } from "path";

async function getSupportedLLMs(): Promise<string[]> {
  const raw = await readFile(join(__dirname, "..", "..", "llms.txt"), "utf-8");
  return raw
    .split("\n")
    .map(line => line.trim())
    .filter(Boolean);        // remove empty lines / comments
}

Validating User Input

Before initiating an API call, the tooling validates the requested model against the allowed list:

async function validateModel(requested: string) {
  const supported = await getSupportedLLMs();
  if (!supported.includes(requested)) {
    throw new Error(
      `Model "${requested}" is not supported. Choose from: ${supported.join(", ")}`
    );
  }
  // continue with the API call…
}

Generating Documentation Tables

The documentation pipeline uses the list to render markdown tables dynamically:

async function renderSupportedModels() {
  const models = await getSupportedLLMs();
  const rows = models.map(m => `| ${m} |`).join("\n");
  return `
| Supported LLM |
|---------------|
${rows}
`;
}

Summary

• llms.txt acts as a centralized registry of supported LLM identifiers at the repository root.
• mcp/src/index.ts reads the file at runtime to validate user requests and prevent unsupported model invocations.
• Documentation automation uses the same file to generate the "Supported LLMs" page via MkDocs, keeping documentation synchronized with code.
• Extensibility is straightforward: append a new identifier to llms.txt and the tooling picks it up automatically without code changes.

Frequently Asked Questions

What happens if I request a model not listed in llms.txt?

The MCP tooling will reject the request by throwing an error listing the supported alternatives, or it will fall back to a default model configuration. This prevents accidental API calls to unsupported or unavailable providers.

How do I add a new LLM to the compendium?

Open the llms.txt file at the repository root and append the new model identifier on its own line. The TypeScript validation logic and documentation generator will automatically include the new model on the next build.

Does llms.txt support comments or empty lines?

Yes. The parsing logic in mcp/src/index.ts filters out empty lines using .filter(Boolean), allowing you to use blank lines for readability. While the parser trims whitespace, it treats any non-empty line as a model identifier, so comments should be avoided or handled cautiously.

Is the file used only by the TypeScript MCP tools?

While primarily consumed by the TypeScript entry point in mcp/src/index.ts, the file is also read by the documentation build pipeline configured in mkdocs.yml. This dual use ensures both the runtime tooling and the static site reflect the same set of supported models.

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