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:
- Activate temporary per-run hook via
doc_session_hook(action="activate", workspace_dir=..., doc_type=...)and store the returnedsession_id. - Translate intent, horizon goals, and role routing via
doc_check_trigger. Forinternal-commsandsop, ifrole_routing.status == "clarification_required", resolve exactCargo Y -> Cargo Xroles before drafting. - Satisfy Gate A or reuse fresh pack: if
freshness_status == "fresh", loaddoc_get_pack(detail="summary"); otherwise download and register>= 5real primary documents across>= 5distinct organizations viadoc_register_sourceand verifydoc_check_gate_a["passed"] == True. - Synthesize living pack and local rules via
doc_synthesize_pack, distilling empirical convergence intoindex.json,template.md,anti-patterns.md,profile.md,guide.md, and reusablelocal-rules.md. - Draft Document #1 and audit Gate C via
doc_evaluate_documentuntilverdict == "pass"andanti_patterns_hit == []. - Dismantle temporary hook via
doc_session_hook(action="teardown", workspace_dir=..., session_id=...)and confirmclean == Trueandresidual_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, mode0755, 5-second timeout) registered in<workspace>/.agents/hooks.jsonunder the prefixed keyparacelsos-temp-guard-<sid>matchingwrite_file|edit_file. - A lease ledger (
.paracelsos_hook_lease_<sid>.json) storingsession_id,doc_type,max_lines,requires_role_routing,pid,created_hooks_json,created_agents_dir, and the exact byte-for-byteoriginal_hooks_json_textcaptured 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
>= 5verifiedtier="real"entries incatalog.csv,>= 5distinct organizations, and0SHA-256 mismatches against captured raw files (NIST FIPS 180-4, 2015). - Gate B (Schema & Template Convergence): Confirms
index.jsondeclaresdoc_type,lifecycle_states, andsections, that every section marked"class": "core"appears intemplate.md, and thatanti-patterns.md,profile.md, andguide.mdexist on disk. - Gate C (Artifact Audit & CI Validation): Evaluates any target Markdown file via
doc_evaluate_document(or up to 50 files viadoc_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 earnspassonly when every check passes (score == max_score) andanti_patterns_hit == []; missing 1 to 2 checks yieldsneeds_revision, and missing 3 or more yieldsfail.
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
- Paracelsus MCP Repository (
brontesiastudio/paracelsos-mcp, 2026): https://github.com/brontesiastudio/paracelsos-mcp - Model Context Protocol Specification (2025): https://modelcontextprotocol.io/specification
- Model Context Protocol Server Schema (
2025-10-17): https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json - Python Standard Library Documentation (2026),
atexitExit handlers: https://docs.python.org/3/library/atexit.html - NIST FIPS 180-4 (2015), Secure Hash Standard (SHS): https://csrc.nist.gov/pubs/fips/180-4/upd1/final
- AWS Samples (2026), ADR-009: Host cloud personas on AgentCore Runtime Instances, not bare EC2: https://github.com/aws-samples/sample-agentstorming/blob/main/docs/adr/ADR-009-agentcore-runtime-instances-for-personas.md