prompts/docs/architecture.md

icon

icon
lucide/library

Architecture

Overview

The platform is implemented as a resource-first MCP system with an integrated static documentation surface. The same methodology content powers both MCP resources and the published docs site.

An MCP server is a runtime that exposes machine-readable resources and tools through stable interfaces so AI clients can discover and consume context consistently. Here, the server's role is intentionally narrow: publish canonical methodology documents as resources, keep discovery predictable through a catalog layer, and serve the same source material as pre-built static documentation.

The system is complete in three layers:

1. Canonical methodology is maintained in Markdown skill documents.
2. Catalog resources provide normalized discovery.
3. Zensical builds a static site from those same Markdown sources and the FastAPI app serves it in the FastMCP runtime process.

Prompt documents under docs/prompts/ are also indexed and exposed as first-class catalog and prompt surfaces.

This architecture is anchored by three contracts:

1. Docs-first authored content contract under docs/ with strict per-skill ownership.
2. Standard SKILL.md frontmatter consumed directly by FastMCP.
3. Native skill:// resource URIs with break-and-replace policy for contract changes.

Detailed contract pages:

1. Content Contract
2. Frontmatter Contract
3. URI Contract

This architecture keeps authored content human-friendly while preserving machine-stable contracts.

Intent

The architecture is designed to satisfy three long-term requirements:

1. Methodology must be editable as markdown by humans.
2. Agents must consume stable, discoverable resource contracts, with a minimal read-only catalog tool fallback for constrained clients.
3. Public documentation must be pre-built static output served from the application runtime without a separate docs service.

System Model

Pattern Modules

Each skill encapsulates one methodology domain in a docs-owned directory:

1. docs/skills/<skill-id>/SKILL.md
2. docs/skills/<skill-id>/references/...

The skill document and references are the authored source of truth; runtime code indexes and serves these files without becoming a second authored source.

Each skill publishes three native resource families:

1. skill://<name>/SKILL.md for primary instructions
2. skill://<name>/_manifest for file discovery and integrity metadata
3. skill://<name>/{path*} for supporting files

The main resource returns canonical Markdown. The generated manifest lists real relative paths, sizes, and SHA256 hashes so clients can load supporting material selectively.

Prompt Modules

Prompt guidance can be authored in docs/prompts/ using either canonical prompt directories (docs/prompts/<prompt-id>/PROMPT.md) or legacy markdown files during migration.

Prompt modules publish two additive surfaces:

1. prompt resources for catalog and document retrieval
2. MCP prompt objects for prompt-list/get-prompt style client workflows

This keeps authored markdown as source-of-truth while allowing clients to discover and invoke prompts directly.

Catalog Module

The catalog publishes normalized records for prompts. Skills use FastMCP's native resource discovery and client utilities instead of a parallel catalog.

Typical catalog resources:

1. resource://catalog/prompts_index
2. resource://catalog/prompts_index{?q,tag,cursor,limit}
3. resource://catalog/prompts/{prompt_id}

Only canonical catalog resources are part of the runtime contract in this phase.

Registry Loader

Importing the package does not read or parse documentation. The MCP server and FastAPI application factories initialize content when constructing a runnable server. The prompt/docs registry reads packaged resources through importlib.resources.files(...) and Traversable APIs; the native skills provider receives the packaged personal_mcp/docs/skills filesystem path.

Loader responsibilities:

1. Parse and validate prompt frontmatter.
2. Build the prompt catalog and MCP prompt objects.
3. Index authored Markdown for resource://docs/{path*}.

Skill loading is owned by SkillsDirectoryProvider, which scans the packaged skills directory and constructs native resources before the server starts serving requests.

The immutable registry is cached for the process lifetime. Each Uvicorn worker constructs and retains its own registry because worker processes do not share Python objects. Registry load failure is a server-factory startup error, not a package-import error or partial runtime warning.

Content Sources

Content is authored in markdown under docs/ and managed as long-form reference material. Skill documents and companion references now live under docs/skills/, while project-authored pages remain alongside them in the docs tree. Resource handlers expose the same authored documents through stable resource URIs.

The repository root docs/ directory is the only authored source. The src/personal_mcp/docs path is a relative symlink to that directory for source-checkout and editable-install workflows; it is not a second content tree and packaging does not depend on traversing it.

For wheel builds, Hatchling's normal src/personal_mcp package traversal follows the relative docs symlink and archives its targets as regular files under personal_mcp/docs/. No force-include mapping is used because that would add the same archive paths twice. The prompt/docs registry uses importlib.resources.files, while SkillsDirectoryProvider scans the package-relative filesystem path. Neither path depends on the current working directory.

Static Docs Surface

Static docs are built directly from two markdown source streams:

1. Project-authored docs pages
2. Skill and reference markdown pages

The merged docs tree is built by Zensical into static files and served by the FastAPI app.

Generated site/ files are deployment assets for the human-facing static site. They are separate from the authored Markdown resources packaged under personal_mcp/docs/.

Data Flow

flowchart TD
    A[Authored Skill Directories] --> B[SkillsDirectoryProvider]
    B --> C[Native Skill Resources]
    D[Authored Prompts and Docs] --> E[Prompt and Docs Registry]
    E --> F[Prompt Catalog and Docs Resources]
    A --> G[Zensical Static Build]
    D --> G
    G --> H[FastAPI Static Mount]

Contracts

Metadata Contract

Each skill declares standard frontmatter in docs/skills/<skill-id>/SKILL.md.

For the full field-level contract, validation model, and FastMCP metadata mapping, see Frontmatter Contract.

Required fields:

1. name
2. description

The directory name is the provider identity and must match name. There is no skill catalog metadata or sidecar.

URI Contract

Canonical resource URIs are:

For the full URI semantics, parameter validation rules, and compatibility policy, see URI Contract.

1. skill://<skill_name>/SKILL.md
2. skill://<skill_name>/_manifest
3. skill://<skill_name>/<supporting_path>
4. resource://docs/{path*}
5. resource://catalog/prompts_index
6. resource://catalog/prompts_index{?q,tag,cursor,limit}
7. resource://catalog/prompts/{prompt_id}
8. resource://prompts/{prompt_id}/document

Validation rules:

1. skill_name is the lowercase kebab-case skill directory name.
2. supporting_path is a provider-validated relative path within that skill.
3. Docs path* resolves only to normalized Markdown paths under docs/.

Resource Registration Contract

Skill resources are registered by one SkillsDirectoryProvider; prompt and docs resources remain registered from the validated registry.

Registration rules:

1. Use RFC6570 URI templates where appropriate.
2. Mark documentation resources as read-only and idempotent.
3. Set explicit mime types for resource responses.
4. Configure duplicate URI handling with on_duplicate="error" for startup safety.

This keeps runtime behavior deterministic and prevents accidental URI collisions.

Versioning Rule

URIs are unversioned and canonical in this phase.

1. Breaking URI changes are handled as direct replacement.
2. No compatibility aliases or dual URI families are maintained.

Static Hosting Pattern

The docs site is pre-built and served by the same FastAPI runtime process used by the MCP app.

Runtime behavior:

1. App starts.
2. FastAPI mounts the static docs output directory.
3. Requests to docs paths are served as static assets.

This provides a single deployment artifact with no runtime markdown rendering dependency.

Advantages

Single Source of Truth

Methodology is authored once and reused in both MCP resources and docs pages.

High-Fidelity Agent Context

Resources expose the same canonical Markdown that humans author and review.

Operational Simplicity

A single app process serves MCP and docs surfaces.

Long-Term Maintainability

Markdown remains easy to review, while contracts remain stable for clients.

Client Independence

Clients can use Ask, Edit, or Agent modes without requiring prompt-first orchestration. Prompt objects are available as an additive MCP surface, while resource retrieval remains the canonical source path. MCP affordances are still chat-surface-dependent: some clients or sessions expose resource attachment directly, while others make tool invocation the more reliable retrieval path.

Authoring and Publishing Lifecycle

1. Update markdown reference content.
2. Keep skill name and directory identity aligned.
3. Build static docs with Zensical and run provider tests.
4. Package authored docs into personal_mcp/docs/.
5. Serve native MCP resources and the static docs mount.

Scope and Non-Goals

In-scope:

1. Resource-first methodology delivery
2. Native FastMCP skill discovery
3. Pre-built static docs hosting in app runtime

Out-of-scope:

1. Prompt-first orchestration as the primary interface
2. Large tool inventories duplicating static guidance across skill modules
3. Separate dynamic docs service at runtime

The prompt catalog remains an independent surface. Tool-only skill clients use generic resource tools rather than a skill-specific compatibility layer.

Example Content Inputs

Existing markdown reference sets are valid examples of authored source material for this architecture:

1. docs/skills/pytesting/references/pytest-docs.md
2. docs/skills/python-logging/references/python-logging-docs.md
3. docs/skills/python-logging/references/json-file-logging.md
4. docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md

These inputs are treated as content sources, while native skill URIs and generated manifests form the machine-facing skill contract.