PARACELSUS

DOC 02 · ARCHITECTURE

The Four-Layer Engine: Inside paracelsus-mcp v1.0.0

Architectural specification of the Plugin installer, 12-tool MCP server, empirical companion Skill, deterministic Gates A/B/C, and zero-residue temporary hooks

Research & Systems Engineering2026-11-218 min read6 primary sources

The Four-Layer Engine: Inside paracelsus-mcp v1.0.0

Most AI documentation tools collapse everything into a single prompt template or a loose collection of scripts. Prompts alone are advisory: under context pressure, an agent skips verification, drops metadata fields, or writes 400-line walls of prose. Permanent repository hooks solve enforcement at the cost of workspace pollution, leaving custom scripts, lockfiles, and modified hook manifests inside user repositories long after the task finishes.

paracelsus-mcp v1.0.0 (paracelsos-mcp Python package, published under io.github.brontesiastudio/paracelsos-mcp in Open Free Mode) resolves that tension through a strict four-layer architecture. Each layer owns one non-overlapping responsibility: multi-harness installation (Layer 1), deterministic state and protocol tools (Layer 2), workflow sequencing (Layer 3), and ephemeral write-time enforcement with guaranteed cleanup (Layer 4).

Layer 1: Multi-Harness Plugin and Node-to-Python Packaging

Adoption fails when installing an MCP server requires hand-editing JSON or TOML files across incompatible agent harnesses. Layer 1 abstracts installation through paracelsos-mcp install, supporting three primary coding harnesses (antigravity, claude, and codex, or all) across both stdio and streamable-http transports (Paracelsus MCP Repository, 2026).

Target Harness MCP Configuration Path Plugin Manifest Path Companion Skill Path
Antigravity (Global Mode) ~/.gemini/config/mcp_config.json ~/.gemini/config/plugins/paracelsos/plugin.json ~/.gemini/config/skills/paracelsos-doc-pipeline/SKILL.md
Antigravity (Project Mode) <dir>/mcp_config.json <dir>/.agents/plugins/paracelsos/plugin.json <dir>/.agents/skills/paracelsos-doc-pipeline/SKILL.md
Claude Code <dir>/.mcp.json <dir>/.claude-plugin/plugin.json <dir>/.claude/skills/paracelsos-doc-pipeline/SKILL.md
OpenAI Codex <dir>/config.toml <dir>/.codex-plugin/plugin.json <dir>/.agents/skills/paracelsos-doc-pipeline/SKILL.md

The Python installer (paracelsos_mcp/installer.py) performs zero network calls and zero shell execution. Before writing any existing file, it creates a deterministic .bak backup copy via shutil.copy2. For Codex config.toml, it parses the merged result with Python’s standard library tomllib.loads before touching disk, preventing malformed configuration writes. A --dry-run flag previews every planned file mutation without writing bytes.

To enable one-line installation for JavaScript and TypeScript teams without manual Python environment setup, the paracelsus-mcp@1.0.0 npm package embeds the pinned Python wheel (paracelsos_mcp-1.0.0-py3-none-any.whl, locked to mcp==2.3.0 and pydantic==2.14.3 on Python >= 3.11). When bin/cli.js executes, it computes the SHA-256 digest of the embedded wheel and compares it against ~/.local/share/paracelsus-mcp/wheel.sha256. On a first run or version upgrade, it installs via uv tool install --force (falling back to an isolated venv under ~/.local/share/paracelsus-mcp/venv if uv is unavailable), redirecting all installer output to stderr so MCP stdio JSON-RPC framing on stdout is never corrupted. In the 2026-11-21 Docker audit, pnpm add -g paracelsus-mcp followed by paracelsus-mcp install --client antigravity completed in 3s while modifying 0 files inside /workspace (Paracelsus Empirical A/B Report, 2026).

Layer 2: The 12-Tool Typed MCP Server

Layer 2 (paracelsos_mcp/server.py) implements the Model Context Protocol server (doc_pipeline_mcp) using Pydantic v2 strict models (extra="forbid", str_strip_whitespace=True) and complete ToolAnnotations metadata across all 12 tools (Model Context Protocol Specification, 2025). By default, the server runs in Open Free Mode (tier: "free", mode: "open_free"), unlocking every research, synthesis, evaluation, and session-hook tool locally with zero API keys. Optional HMAC-SHA256 license enforcement activates only when PARACELSOS_ENFORCE_LICENSE=1 is explicitly exported.

MCP Tool Read-Only Primary Responsibility
doc_list_types Yes Lists synthesized workspace packs, official whitelist caps, freshness states, and entitlement mode
doc_get_pack Yes Loads index.json, template.md, anti-patterns.md, and local-rules.md (summary or full, capped at 60,000 chars)
doc_check_gate_a Yes Audits catalog.csv for >= 5 verified tier="real" sources across >= 5 distinct orgs with 0 SHA-256 mismatches
doc_check_gate_b Yes Verifies index.json schema fields, core section coverage in template.md, and companion framework files
doc_evaluate_document Yes Scores a Markdown artifact against its synthesized pack (or whitelist baseline) and lists triggered anti-patterns
doc_validate_directory Yes Batch-audits up to 50 Markdown documents in a directory for CI pipelines or repository onboarding
doc_check_trigger Yes Translates intent, sender/recipient roles, and short/medium/long-term goals into nomenclature and Big Tech queries
doc_get_state Yes Returns operational_procedures/execution_state/state.json and TTL freshness status
doc_bootstrap_type No Scaffolds standardized subtree (research_procedures/, templates/, operational_procedures/) for a document type
doc_register_source No Validates authority tier, public URL, and ISO date; writes raw source plus SHA-256 entry to catalog.csv
doc_synthesize_pack No Persists living pack plus reusable local-rules.md only after verifying Gate A and Gate B, stamping TTL
doc_session_hook No Manages Layer 4 temporary PreToolUse guard lifecycle (activate, status, teardown)

Workspace state resolves cleanly in priority order: explicit pipeline_root parameter, PARACELSOS_PIPELINE_ROOT environment variable, or ~/.cache/paracelsos/workspaces. Keeping synthesized packs inside the user cache rather than the Git repository prevents documentation infrastructure from polluting application diffs. Simultaneously, doc_get_pack enforces MAX_INLINE_CHARS = 60,000 (clamped between 2,000 and 60,000 characters), ensuring packs never overflow an agent’s working context.

Layer 3: Empirical Companion Skill Protocol

MCP tools expose deterministic capabilities, yet an LLM still needs an explicit operational order so it does not draft before researching or forget cleanup after Gate C passes. Layer 3 ships paracelsos-doc-pipeline (SKILL.md), which codifies the six-step execution contract:

  1. Activate temporary per-run hook via doc_session_hook(action="activate", workspace_dir=..., doc_type=...) and store the returned session_id.
  2. Translate intent, horizon goals, and role routing via doc_check_trigger. For internal-comms and sop, if role_routing.status == "clarification_required", resolve exact Cargo Y -> Cargo X roles before drafting.
  3. Satisfy Gate A or reuse fresh pack: if freshness_status == "fresh", load doc_get_pack(detail="summary"); otherwise download and register >= 5 real primary documents across >= 5 distinct organizations via doc_register_source and verify doc_check_gate_a["passed"] == True.
  4. Synthesize living pack and local rules via doc_synthesize_pack, distilling empirical convergence into index.json, template.md, anti-patterns.md, profile.md, guide.md, and reusable local-rules.md.
  5. Draft Document #1 and audit Gate C via doc_evaluate_document until verdict == "pass" and anti_patterns_hit == [].
  6. Dismantle temporary hook via doc_session_hook(action="teardown", workspace_dir=..., session_id=...) and confirm clean == True and residual_files == [].

Layer 4: Zero-Residue Temporary Hooks

Layer 4 (paracelsos_mcp/hooks.py) solves the hardest governance problem in agent tooling: enforcing deterministic write-time checks without leaving permanent configuration scars in the user’s workspace.

When doc_session_hook(action="activate") runs for a workspace and document type, it generates a 12-character hex session_id (unless supplied) and creates two session-scoped artifacts inside <workspace>/.agents/:

  • An executable Python PreToolUse guard (.paracelsos_temp_hook_<sid>.py, mode 0755, 5-second timeout) registered in <workspace>/.agents/hooks.json under the prefixed key paracelsos-temp-guard-<sid> matching write_file|edit_file.
  • A lease ledger (.paracelsos_hook_lease_<sid>.json) storing session_id, doc_type, max_lines, requires_role_routing, pid, created_hooks_json, created_agents_dir, and the exact byte-for-byte original_hooks_json_text captured before Paracelsus touched the file.

During drafting, every full-document .md write (excluding standard repo meta-files such as README.md, SKILL.md, GEMINI.md, AGENTS.md, CHANGELOG.md, and internal paths like .agents/ or templates/) is intercepted before disk mutation. The guard deterministically checks five Gate C invariants: an H1 heading (# ) within the first 35 lines, an ISO 8601 date (YYYY-MM-DD) in the header slice, an explicit Status: field, total line count within MAX_LINES_BY_DOC_TYPE, and explicit From/De: plus To/Para: role-routing headers whenever requires_role_routing is true. Any violation returns {"decision": "deny", "reason": "..."} immediately, forcing correction before malformed prose is persisted.

Teardown is engineered for both normal completion and abrupt process termination. Calling doc_session_hook(action="teardown") deletes the session’s script and lease file, removes its key from hooks.json if concurrent sessions remain active, or else restores original_hooks_json_text verbatim (or deletes hooks.json entirely if Paracelsus created it). If Paracelsus created .agents/ and the directory is now empty, agents_dir.rmdir() removes it too. Finally, a post-teardown scan confirms residual_files == [] and returns clean: true.

To guard against crashed sessions or interrupted agents, activation also registers process-level emergency cleanup via Python’s atexit.register(_cleanup_all_active_leases) (Python Standard Library atexit, 2026) along with SIGTERM and SIGINT handlers on the main thread that chain cleanly to any previous signal handler after dismantling active leases.

Deterministic Quality Pipeline: Gates A, B, and C

Across Layers 2, 3, and 4, quality control operates as three chained deterministic gates rather than subjective LLM self-grading:

  • Gate A (Evidence Quorum & Integrity): Requires >= 5 verified tier="real" entries in catalog.csv, >= 5 distinct organizations, and 0 SHA-256 mismatches against captured raw files (NIST FIPS 180-4, 2015).
  • Gate B (Schema & Template Convergence): Confirms index.json declares doc_type, lifecycle_states, and sections, that every section marked "class": "core" appears in template.md, and that anti-patterns.md, profile.md, and guide.md exist on disk.
  • Gate C (Artifact Audit & CI Validation): Evaluates any target Markdown file via doc_evaluate_document (or up to 50 files via doc_validate_directory), computing exact pass/fail booleans for title identifier, ISO 8601 date, valid lifecycle status, core sections (or ADR-specific Context, Considered Options, Active Decision, and Balanced Positive/Negative Consequences), role routing, and calibrated line caps. A document earns pass only when every check passes (score == max_score) and anti_patterns_hit == []; missing 1 to 2 checks yields needs_revision, and missing 3 or more yields fail.

Known Limitations and Polishing Surface

Two architectural boundaries warrant transparent documentation. First, in the 2026-11-21 clean-container Antigravity verification, agy plugin validate ~/.gemini/config/plugins/paracelsos passed with one non-blocking warning: plugin.json: unknown field "mcpServers" is ignored, because global Antigravity installations read MCP server bindings from ~/.gemini/config/mcp_config.json rather than inside plugin.json (Paracelsus Empirical A/B Report, 2026). Removing the redundant key in global-mode plugin generation eliminates the warning in subsequent releases without affecting protocol behavior.

Second, Layer 4 temporary hooks rely on the host harness honoring <workspace>/.agents/hooks.json PreToolUse definitions (native in Antigravity). On harnesses without .agents/hooks.json interception, Layers 1, 2, and 3 remain fully operational, and Gate C enforcement still executes deterministically via doc_evaluate_document and doc_validate_directory.

Sources