prompts/docs/mcp_layout.md

icon

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

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

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.