---
icon: lucide/server
---

# Runtime And Static Docs Layout

## Purpose

The project serves native MCP content and a pre-built documentation site from one FastAPI process. Markdown is authored once under `docs/`; runtime providers and Zensical consume that same packaged tree for different purposes.

## Repository Layout

```mermaid
---
config:
    treeView:
        rowIndent: 32
        lineThickness: 2
---
treeView-beta
   "project-root"
      "docs"
         "prompts/<prompt-id>/PROMPT.md"
         "skills/<skill-id>/SKILL.md"
         "skills/<skill-id>/<supporting-files>"
         "<general-pages>.md"
      "site"
         "static build output"
      "src/personal_mcp"
         "mcp.py"
         "prompts/components/*.py"
         "prompts/content.py"
         "prompts/provider.py"
         "registry/"
         "skills/provider.py"
         "web/"
```

Ownership rules:

1. `docs/skills/` is owned exclusively by `SkillsDirectoryProvider` at runtime.
2. `docs/prompts/` owns prompt prose; Python components own prompt metadata and argument schemas.
3. The docs registry owns only general Markdown resources and explicitly excludes skills.
4. `site/` is generated output.
5. The deleted custom `catalog/` package is not part of the runtime.

## Runtime Composition

```mermaid
flowchart TD
   A[Packaged Skills] --> B[SkillsDirectoryProvider]
   C[Prompt Components] --> D[FileSystemProvider]
   E[Packaged Markdown] --> F[Docs Registry]
   B --> G[FastMCP]
   D --> G
   F --> G
   G --> H[MCP Transport]
   H --> K[FastAPI Application]
   L[Pre-built site] --> M[Static /docs Mount]
   K --> M
```

Runtime guarantees:

1. Providers are installed before serving requests.
2. Production provider discovery uses `reload=False`.
3. Duplicate components fail according to FastMCP's configured duplicate policy.
4. Skills and prompts use native FastMCP component surfaces.
5. General docs path parsing rejects traversal, backslashes, non-Markdown paths, and the skill namespace.

## Build And Publish Flow

1. Author Markdown under `docs/` and typed prompts under `src/personal_mcp/prompts/components/`.
2. Run `uv run zensical build` to produce `site/`.
3. Build the wheel, which packages the authored docs under `personal_mcp/docs/`.
4. Start the app and serve MCP plus the static site.

No runtime Markdown-to-HTML conversion occurs.

## Machine-Facing Mapping

1. `docs/skills/<skill-id>/SKILL.md` maps to `skill://<skill-id>/SKILL.md`.
2. Skill supporting files map to `skill://<skill-id>/<path>`.
3. Typed prompt components map to native MCP prompt names.
4. General `docs/<path>.md` maps to `resource://docs/{path*}`.

The server publishes no tool projections of resources or prompts.

## Public Surface Policy

Canonical provider and protocol surfaces are the only public interfaces.

## Static Mount Expectations

The FastAPI app mounts the Zensical output, serves index and asset files, and returns a clear unavailable response when the static output is absent. The site directory is immutable for a given build and remains separate from packaged authored Markdown.