Skip to content

MkDocs MCP Server

The MkDocs handbook is the curated documentation layer next to MantisBT.

Mantis tracks operational work. MkDocs explains durable knowledge: workflow rules, setup, architecture, release conventions, and decisions that should outlive a single issue note.

Goal

Create an MCP server that lets agents update the handbook while they work in Mantis.

The server should make documentation a normal part of the development loop:

  1. Read the Mantis issue and child tasks.
  2. Decide whether documentation is affected.
  3. Read the relevant handbook pages.
  4. Update or create Markdown pages.
  5. Run mkdocs build --strict.
  6. Add a Mantis note linking the documentation update.
  7. Only then move the issue to review or done.

Useful MCP Tools

  • docs_search: search handbook pages by title and content.
  • docs_read_page: read one Markdown page.
  • docs_create_page: create a new Markdown page and add it to navigation.
  • docs_update_page: update an existing Markdown page.
  • docs_link_issue: add a Mantis issue reference to a page or return the page link for an issue note.
  • docs_build_check: run mkdocs build --strict and return a concise result.
  • docs_list_pages: list known handbook pages and nav order.

Guardrails

  • Do not move an issue to done if relevant docs are missing.
  • If no documentation is needed, add a Mantis note explaining why.
  • Keep operational task chatter in Mantis notes, not in the handbook.
  • Keep durable conventions, setup, architecture, and release rules in MkDocs.
  • Prefer small page edits over rewriting whole documents.

Suggested Data Model

Each docs update should be traceable to Mantis:

  • Mantis issue id
  • page path
  • change summary
  • validation result
  • whether changelog/release notes were affected

The MCP server does not need to be complicated. It mainly needs safe Markdown file edits, navigation updates, and deterministic validation.