255 lines
11 KiB
Markdown
255 lines
11 KiB
Markdown
---
|
|
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](./contracts/index.md#content-contract)
|
|
2. [Frontmatter Contract](./contracts/frontmatter.md)
|
|
3. [URI Contract](./contracts/uris.md)
|
|
|
|
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`](https://docs.python.org/3/library/importlib.resources.html#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
|
|
|
|
```mermaid
|
|
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](./contracts/frontmatter.md).
|
|
|
|
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](./contracts/uris.md).
|
|
|
|
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.
|