docusaurus-plugin-mcp-server: Instructions file for Codex

AGENTS.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build and Development Commands

npm run build          # Build with tsup (ESM-only output)
npm run dev            # Watch mode for development
npm run lint           # Run ESLint (fails on any warning) and Prettier check
npm run lint:fix       # Auto-fix lint issues
npm run typecheck      # TypeScript type checking
npm run test           # Run unit tests with Vitest
npm run test:watch     # Run tests in watch mode
npm run test:mcp       # Run Playwright MCP integration tests
npm run test:site      # Run the docs site's contract tests (build the site first)
npm run evals -- <name> # Run an agent eval in tests/evals/ (local only, uses your Claude Code login)
npm run test:all       # Build once, then run lint, typecheck, unit and MCP tests, and the snippets check

typecheck, test:mcp, and the built-output tests in tests/docusaurus-load-test.ts and tests/package-files-test.ts read dist/, so they check whatever the last build produced. Run npm run build before running them alone. test:all and prepublishOnly build first.

Run a single test file:

npx vitest run tests/markdown-test.ts

Architecture Overview

This is a Docusaurus plugin that exposes documentation as an MCP (Model Context Protocol) server for AI agents.

Two-Phase Design

Build Time (src/pipeline/, src/plugin/): runs during docusaurus build:

• src/pipeline/build-outputs.ts - The build pipeline, with no Docusaurus in it: buildOutputs({ outDir, options, site }) returns the artifact bundle (or why it skipped) and writes nothing. Test build behavior here, against HTML fixtures (tests/build-outputs-test.ts). New build steps go here, not in the hook
• src/plugin/docusaurus-plugin.ts - The Docusaurus adapter: postBuild maps LoadContext to SiteInfo, calls buildOutputs, and writes the bundle
• Processes HTML files → extracts content → converts to markdown → builds search index
• Packages Agent Skills (built-in docs-research + optional site skills) with digests
• Assembles the artifact bundle, written to build/mcp/bundle.json plus 2.x per-file copies (docs.json, search-index.json, skills.json, manifest.json, indexer extras). See CONTEXT.md for the terms and docs/adr/0001-single-artifact-bundle.md for why