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.

It also treats Markdown as the single source of truth for both MCP resources and published docs.

## Completed-State Layout

```mermaid
---
config:
    treeView:
        rowIndent: 40
        lineThickness: 2
    themeVariables:
        treeView:
            labelColor: '#FFFFFF'
            lineColor: '#FFFFFF'
---
treeView-beta
   "project-root"
      "pyproject.toml"
      "uv.lock"
      "zensical.toml"
      "docs"
         "index.md"
         "architecture.md"
         "mcp_layout.md"
         "skills"
            "pytest-scaffolding"
               "SKILL.md"
               "references"
            "python-logging-dictconfig"
               "SKILL.md"
               "references"
            "fastapi-uv-docker"
               "SKILL.md"
               "references"
      "site"
         "static build output"
      "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 both project-authored pages and the canonical skill Markdown tree.
2. site contains static build output only.
3. docs/skills contains canonical skill Markdown and reference Markdown.
4. MCP resources and docs site read from the same Markdown sources.

## Runtime Composition

The runtime process serves two surfaces:

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

```mermaid
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 authored docs pages and skill markdown sources.
2. Build static site with Zensical into site.
3. 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. Skill Markdown content from docs/skills/*/SKILL.md and references

This ensures the public docs reflect architectural guidance and the exact Markdown served by MCP.

## Markdown-to-Resource Mapping

MCP resources map directly to canonical Markdown documents.

Example mapping model:

1. docs/skills/<slug>/SKILL.md -> resource://skills/<id>/document
2. docs/skills/<slug>/references/*.md -> referenced sections or linked companion documents

Catalog resources provide discovery metadata and stable identifiers.

When clients cannot attach MCP resources directly, catalog-level tools may retrieve the same underlying skill documents indirectly. This does not create a second content source; it is only an alternate access path to the same markdown-backed contract.

## 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

The docs site and MCP resources resolve from the same Markdown sources.

### 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 docs and skill markdown content.
2. Rebuild static site.
3. 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. ../docs/skills/pytest-scaffolding/references/pytest-docs.md
2. ../docs/skills/python-logging-dictconfig/references/python-logging-docs.md
3. ../docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md

These are source documents, not deployment artifacts.