John Lancaster
239 lines
8.3 KiB
Markdown
239 lines
8.3 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.
|
|
|
|
This architecture is anchored by three contracts:
|
|
|
|
1. Docs-first authored content contract under `docs/` with strict per-skill ownership.
|
|
2. `SKILL.md` frontmatter contract with Anthropic fields plus `x-personal-mcp` metadata.
|
|
3. Canonical resource URI contract with break-and-replace policy for contract changes.
|
|
|
|
Detailed contract pages:
|
|
|
|
1. [Content Contract](./content.md)
|
|
2. [Frontmatter Contract](./frontmatter.md)
|
|
3. [URI Contract](./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 resource families:
|
|
|
|
1. document
|
|
|
|
The document resource returns canonical Markdown, while clients can perform any downstream section extraction they need.
|
|
|
|
### Catalog Module
|
|
|
|
The catalog is the canonical discovery layer and publishes normalized records for all modules. It may also expose a minimal set of read-only discovery tools that resolve back to the same canonical markdown content when a client chat surface does not expose MCP resource attachment.
|
|
|
|
Typical catalog resources:
|
|
|
|
1. resource://catalog/skills_index
|
|
2. resource://catalog/skills/{skill_id}
|
|
|
|
Only canonical catalog resources are part of the runtime contract in this phase.
|
|
|
|
### Registry Loader
|
|
|
|
The runtime composition includes a startup registry loader that reads packaged docs resources using `importlib.resources.files(...)` and `Traversable` APIs.
|
|
|
|
Loader responsibilities:
|
|
|
|
1. Parse SKILL.md frontmatter for each skill.
|
|
2. Validate schema and cross-field constraints before any resource registration.
|
|
3. Build an in-memory registry keyed by `skill_id`.
|
|
4. Fail fast for duplicate ids, missing markdown files, broken reference mappings, and invalid `depends_on` values.
|
|
|
|
Registry load failure is a startup error, not a 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.
|
|
|
|
### 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.
|
|
|
|
## Data Flow
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A[Authored Markdown] --> C[Resource Handlers]
|
|
B[Pattern Metadata] --> D[Catalog Resources]
|
|
A --> E[Zensical Static Build]
|
|
E --> H[FastAPI Static Mount]
|
|
H --> I[Served Docs Site]
|
|
D --> I
|
|
```
|
|
|
|
## Contracts
|
|
|
|
### Metadata Contract
|
|
|
|
Each skill declares frontmatter in `docs/skills/<skill-id>/SKILL.md`.
|
|
|
|
For the full field-level contract, validation model, and FastMCP metadata mapping, see [Frontmatter Contract](./frontmatter.md).
|
|
|
|
Anthropic-facing required fields:
|
|
|
|
1. name
|
|
2. description
|
|
|
|
Repository indexing metadata is declared in `x-personal-mcp`:
|
|
|
|
1. id
|
|
2. version
|
|
3. tags
|
|
4. capabilities
|
|
5. depends_on
|
|
6. optional references map (for nested entries, overrides, and aliases)
|
|
|
|
No `metadata.yaml` sidecar is part of the end-state contract.
|
|
|
|
### URI Contract
|
|
|
|
Canonical resource URIs are:
|
|
|
|
For the full URI semantics, parameter validation rules, and compatibility policy, see [URI Contract](./uris.md).
|
|
|
|
1. resource://skills/<skill_id>/document
|
|
2. resource://skills/<skill_id>/references/<ref_id>
|
|
3. resource://catalog/skills_index
|
|
4. resource://catalog/skills/{skill_id}
|
|
5. resource://docs/{path*}
|
|
|
|
Validation rules:
|
|
|
|
1. `skill_id` is lowercase kebab-case and must satisfy the stable skill id contract.
|
|
2. `ref_id` is lowercase kebab-case and must resolve from either:
|
|
- top-level auto-discovery of `references/*.md` filename stems, or
|
|
- an explicit `x-personal-mcp.references` entry.
|
|
3. `path*` resolves only to normalized markdown paths under `docs/`.
|
|
|
|
### Resource Registration Contract
|
|
|
|
Resources are registered from the validated registry, not by ad hoc per-skill hardcoding.
|
|
|
|
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 server-owned prompt orchestration. However, 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. Update metadata if capability surface changes.
|
|
3. Build static docs with Zensical.
|
|
4. Serve built output through FastAPI static mount.
|
|
|
|
## Scope and Non-Goals
|
|
|
|
In-scope:
|
|
|
|
1. Resource-first methodology delivery
|
|
2. Catalog-based 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
|
|
|
|
Allowed exception:
|
|
|
|
1. A small catalog-level tool layer is acceptable when it improves client interoperability without creating a second source of truth for skill content.
|
|
|
|
## Example Content Inputs
|
|
|
|
Existing markdown reference sets are valid examples of authored source material for this architecture:
|
|
|
|
1. docs/skills/pytest-scaffolding/references/pytest-docs.md
|
|
2. docs/skills/python-logging-dictconfig/references/python-logging-docs.md
|
|
3. docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md
|
|
|
|
These inputs are treated as content sources, while resource URIs and catalog payloads remain the machine-facing contracts.
|