john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc updates

Browse Source
This commit is contained in:
John Lancaster
2026-08-30 11:49:58 -05:00
parent bbaa84720c
commit 9eb4ccbc6e
9 changed files with 203 additions and 675 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/personal_mcp/docs/mcp_layout.md
+25 -78
View File
@@ -2,96 +2,43 @@
icon: lucide/server
---
# Runtime And Static Docs Layout
# Running The Server
## Purpose
Personal MCP can run as an HTTP service or as a local stdio process.
The project serves native MCP content and a pre-built documentation site from one FastAPI process. Markdown is authored once under `src/personal_mcp/docs/`; runtime providers and Zensical consume that same package-owned tree for different purposes.
## Local HTTP Server
## Repository Layout
Build the website before starting the application:
```mermaid
---
config:
treeView:
rowIndent: 32
lineThickness: 2
---
treeView-beta
"project-root"
"src/personal_mcp"
"docs"
"prompts/<prompt-id>/PROMPT.md"
"skills/<skill-id>/SKILL.md"
"skills/<skill-id>/<supporting-files>"
"<general-pages>.md"
"site"
"static build output"
"app.py"
"mcp.py"
"skills.py"
"prompts/"
"registry/"
```bash
uv sync
uv run zensical build
uv run personal-mcp --host 127.0.0.1 --port 8765
```
Ownership rules:
The server then provides:
1. `src/personal_mcp/docs/skills/` is owned exclusively by `SkillsDirectoryProvider` at runtime.
2. Each file under `src/personal_mcp/docs/prompts/` owns its prompt metadata, argument schema, and prose.
3. The docs registry owns only general Markdown resources and explicitly excludes skills.
4. `src/personal_mcp/site/` is generated output.
5. The deleted custom `catalog/` package is not part of the runtime.
- `http://127.0.0.1:8765/docs/` for the website
- `http://127.0.0.1:8765/mcp` for MCP clients
## Runtime Composition
The host, port, log level, debug mode, and reload behavior can be set with command-line options or `PERSONAL_MCP_` environment variables.
```mermaid
flowchart TD
A[Packaged Skills] --> B[SkillsDirectoryProvider]
C[Packaged Prompt Markdown] --> D[Markdown Prompt Provider]
E[Packaged Markdown] --> F[Docs Registry]
B --> G[FastMCP]
D --> G
F --> G
G --> I[ResourcesAsTools]
G --> J[PromptsAsTools]
I --> N[list_resources / read_resource]
J --> O[list_prompts / get_prompt]
G --> H[MCP Transport]
H --> K[FastAPI Application]
L[Pre-built site] --> M[Static /docs Mount]
K --> M
## Local Stdio Server
For clients that manage the server process themselves:
```bash
uv run mcp-stdio
```
Runtime guarantees:
This mode provides MCP only; it does not host the website.
1. Providers are installed before serving requests.
2. Prompt discovery rescans authored files on each list and get request.
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.
## Docker
## Build And Publish Flow
The included Compose configuration builds the website into the image and publishes the service on port `8765`:
1. Author prompt definitions and prose under `src/personal_mcp/docs/prompts/`.
2. Run `uv run zensical build` to produce `src/personal_mcp/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.
```bash
docker compose up --build
```
No runtime Markdown-to-HTML conversion occurs.
## Machine-Facing Mapping
1. `src/personal_mcp/docs/skills/<skill-id>/SKILL.md` maps to `skill://<skill-id>/SKILL.md`.
2. Skill supporting files map to `skill://<skill-id>/<path>`.
3. Declarative prompt documents map to native MCP prompt names.
4. General `src/personal_mcp/docs/<path>.md` maps to `resource://docs/{path*}`.
5. FastMCP's `ResourcesAsTools` transform projects every registered resource and template onto two compatibility tools, `list_resources` and `read_resource`, for tool-only clients.
6. FastMCP's `PromptsAsTools` transform projects every registered prompt onto `list_prompts` and `get_prompt`; rendering still routes through the native prompt provider.
## Public Surface Policy
Native resources and prompts remain the source of truth. Generated compatibility tools delegate to those surfaces instead of maintaining parallel catalogs or rendering logic.
## 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.
For a remote deployment, place the service behind a reverse proxy and review the [security guidance](./securing.md).