prompts/docs/mcp_layout.md

Static Docs Hosting Pattern

Purpose

This document describes the completed layout and runtime pattern used to host a pre-built static documentation site from the same FastAPI app process that runs the FastMCP server.

This design intentionally avoids runtime docs rendering and avoids a separate docs hosting service.

Completed-State Layout

project-root/
|
|- pyproject.toml
|- uv.lock
|- zensical.toml
|
|- docs/
|  |- index.md
|  |- architecture.md
|  |- mcp_layout.md
|  |- generated/
|     |- patterns/
|        |- index.md
|        |- pytest-scaffolding.md
|        |- python-logging-dictconfig.md
|        |- fastapi-uv-docker.md
|
|- site/
|  |- ... static files built by zensical ...
|
|- src/
   |- personal_mcp/
      |- main.py
      |- web/
      |  |- app.py
      |  |- docs_mount.py
      |- catalog/
      |  |- server.py
      |- skills/
         |- pytest_scaffolding/
         |- python_logging_dictconfig/
         |- fastapi_uv_docker/

Notes:

1. docs contains authored pages and generated markdown pages.
2. site contains static build output only.
3. MCP resources and docs generation share the same content contract.

Runtime Composition

The runtime process serves two surfaces:

1. MCP protocol surface from FastMCP
2. Static docs surface from FastAPI static mount

flowchart TD
    A[FastMCP Root Server] --> B[MCP Transport]
    A --> C[FastAPI Application]
    C --> D[Static Mount /docs]
    D --> E[Zensical site output directory]

Build and Publish Flow

The docs flow is pre-build only.

1. Read module resources and catalog metadata.
2. Generate docs markdown pages into docs/generated.
3. Build static site with Zensical into site.
4. Start app and serve site directory as static files.

No runtime markdown conversion is required.

Content Merge Pattern

The published docs site always contains both:

1. Project-authored docs pages
2. Resource-derived pattern pages

This ensures the public docs reflect both architectural guidance and live pattern knowledge.

Resource-to-Docs Mapping

Pattern resources map directly to docs sections.

Example mapping model:

1. resource://skills//overview -> docs/generated/patterns/.md section Overview
2. resource://skills//rules -> docs/generated/patterns/.md section Rules
3. resource://skills//checklist -> docs/generated/patterns/.md section Checklist
4. resource://skills//references -> docs/generated/patterns/.md section References

Catalog resources generate index pages and navigation pages.

Why This Pattern

Operational Simplicity

One application process serves both protocol and static docs surfaces.

Deterministic Docs

Published docs are immutable static assets for a given build.

Documentation Fidelity

Resource-derived pages align docs with the exact methodology contracts exposed to agents.

Maintainer Experience

Authors continue to work in markdown while resource contracts remain machine-consumable.

FastAPI Static Mount Expectations

The FastAPI app is expected to:

1. Mount static directory containing Zensical output.
2. Serve index and asset files from that directory.
3. Keep docs route stable across releases.

Recommended route conventions:

1. /docs for static site root
2. /docs/* for static assets and page routes

Update Lifecycle

For each documentation update:

1. Edit authored markdown and resource content.
2. Regenerate docs markdown from resources.
3. Rebuild static site.
4. Restart runtime if needed.

This keeps docs publication explicit and predictable.

Example Source Material

Existing reference docs remain valid content inputs in this pattern:

1. ../skills/pytest-scaffolding/references/pytest-docs.md
2. ../skills/python-logging-dictconfig/references/python-logging-docs.md
3. ../skills/fastapi-uv-docker/references/fastapi-best-practices.md

These are source documents, not deployment artifacts.