Documentation Audit

AI agents can audit your documentation for currency against a live product schema — catching fields that exist in code but aren't yet documented, or documented features that were removed or renamed. This page describes the two-MCP pattern that makes this possible for any braised-built docs site.

How it works

The audit connects two MCP endpoints to an AI agent simultaneously:

Endpoint 1 — docs site (braised mcp serve) Exposes the current state of your docs: get_page, get_page_index, get_nav_structure. The agent reads this to see what is documented now.

Endpoint 2 — product schema (your product's MCP server) Exposes the authoritative reference: config fields, API endpoints, block types, whatever your product surfaces through MCP. The agent reads this as the source of truth.

The agent bridges them: read the schema, read the relevant docs page, compare. Neither endpoint needs to know about the other. braised provides the docs-reading half of the pattern; the product provides the schema half. Any product with an MCP server can plug into this workflow.

Setting up

Run a full build first, then start the docs site MCP server:

braised build
braised mcp serve

The server binds to 127.0.0.1:8081 by default. See Deploying mcp serve for production configuration.

Configure your AI client with both servers. In Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "my-product": {
      "command": "my-product",
      "args": ["mcp"]
    },
    "my-docs-site": {
      "url": "http://127.0.0.1:8081/mcp"
    }
  }
}

In Claude Code (.claude/settings.json):

{
  "mcpServers": {
    "my-product": {
      "command": "my-product",
      "args": ["mcp"]
    },
    "my-docs-site": {
      "url": "http://127.0.0.1:8081/mcp"
    }
  }
}

Both Claude Desktop and Claude Code use "url" for HTTP transport servers and "command" for stdio servers. Replace my-product and the command with your product's actual MCP entrypoint.

Running a manual audit

Once both servers are connected, audit a specific page with a direct prompt:

Read the config schema from the my-product server. Then fetch the page at
/configuration/reference/ from the my-docs-site server. Compare them:
which fields in the schema are missing or incomplete in the docs? Which
documented fields don't appear in the schema?

For a targeted check after a specific change:

The authentication section was updated in the latest release. Compare only
the auth-related fields from the product schema against what is documented
at /configuration/authentication/.

The agent reads both endpoints, produces a gap list, and can propose edits to the affected pages directly. Because it has access to get_page on the docs site and the product schema in the same session, it can draft the missing content with correct field names and types on the first pass.

Automating in CI

The same audit runs unattended in a CI pipeline. The pattern: build the docs, start the MCP server, run the audit agent with a fixed prompt, fail the pipeline if gaps are found.

# .github/workflows/doc-audit.yml
on:
  push:
    paths:
      - 'config/**'   # trigger when config schema source changes
      - 'api/**'

jobs:
  doc-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build docs
        run: braised build

      - name: Start docs MCP server
        run: |
          braised mcp serve &
          echo "MCP_PID=$!" >> $GITHUB_ENV
          until curl -sf http://127.0.0.1:8081/health > /dev/null; do sleep 1; done

      - name: Run doc audit
        run: |
          claude -p "$(cat .claude/audit-prompt.txt)" \
            > audit-result.txt
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Check for gaps
        run: |
          if ! grep -q "ALL CLEAR" audit-result.txt; then
            cat audit-result.txt
            exit 1
          fi

      - name: Stop MCP server
        if: always()
        run: kill $MCP_PID 2>/dev/null || true

Configure both MCP servers in .claude/settings.json in the repo root — Claude Code picks them up automatically when invoked from that directory. The audit prompt (audit-prompt.txt) should instruct the agent to end its response with the literal string GAPS FOUND if it identifies any documentation gaps, making the CI check a simple grep. End with ALL CLEAR if none — this prevents false negatives from an empty or truncated response.

Trigger the audit on changes to schema source files, not on every commit. Known deferred gaps can be suppressed by listing them in the prompt or in an allowlist file the prompt references.

Braised auditing itself

Braised documents itself using this pattern. The product schema comes from braised mcp --site /path/to/braised-docs, which exposes braised://config-schema, braised://blocks, and braised://nav-schema. The docs site MCP server reads the built braised-docs site.

{
  "mcpServers": {
    "braised": {
      "command": "braised",
      "args": ["mcp", "--site", "/path/to/braised-docs"]
    },
    "braised-docs": {
      "url": "http://127.0.0.1:8081/mcp"
    }
  }
}

An audit prompt for braised's config reference:

Read braised://config-schema from the braised server. Then use get_page on
the braised-docs server to fetch /configuration/braised-yaml/. Compare every
field in the schema against the docs page. Report:
- Fields in the schema with no matching docs section
- Documented fields whose name does not appear in the schema
- Fields where the schema has a description but the docs section is shorter
  or missing examples

The same pattern applies to braised://blocks versus the block reference pages, and braised://nav-schema versus the nav.yaml reference page.

What the agent can and cannot do

The audit identifies gaps reliably. Filling them well requires judgment about tone, audience, and which aspects of a field matter most to document — the agent can draft the addition, but a human reviewer should confirm it matches the docs voice and is complete.

Structural changes (a field was renamed, a section reorganised) are harder. The agent may flag a renamed field as both a missing addition and a stale removal. Review rename cases manually; the gap report is a starting point, not a complete diagnosis.

The audit works best on reference pages (config fields, API endpoints, block types) where the product schema and the docs structure are in one-to-one correspondence. Narrative pages (guides, tutorials) cannot be audited against a schema — there is no schema to compare them to.