96 lines
3.0 KiB
Markdown
96 lines
3.0 KiB
Markdown
---
|
|
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.
|