Initial libmcp 1.0.0

4 files changed, 187 insertions, 0 deletions

diff --git a/assets/codex-skills/mcp-bootstrap/SKILL.md b/assets/codex-skills/mcp-bootstrap/SKILL.md
new file mode 100644
index 0000000..19d59d9
--- /dev/null
+++ b/assets/codex-skills/mcp-bootstrap/SKILL.md
@@ -0,0 +1,60 @@
+---
+name: mcp-bootstrap
+description: Bootstrap or retrofit an industrial-grade MCP server with libmcp's host/worker posture, replay contracts, typed faults, porcelain-by-default output, telemetry, and regression tests. Use when creating a new MCP, hardening an existing one, or reviewing an MCP for long-lived session safety, hot rollout, crash recovery, model UX, or worktree/workspace correctness.
+---
+
+# MCP Bootstrap
+
+`libmcp` is the source of truth for the hard posture of long-lived MCPs.
+
+Use this skill when:
+
+- bootstrapping a new MCP
+- retrofitting an existing MCP onto `libmcp`
+- reviewing an MCP for operational hardening or model UX doctrine
+
+Start by classifying the target:
+
+- Fresh bootstrap: the project can adopt the architecture directly.
+- Retrofit: the project already has live behavior or ad hoc recovery logic that
+  must be tightened deliberately.
+
+## Fresh Bootstrap
+
+Read:
+
+- [references/bootstrap-fresh.md](references/bootstrap-fresh.md)
+- [references/checklist.md](references/checklist.md)
+
+Default posture:
+
+- let a stable host own the public MCP transport and session
+- let disposable workers own fragile runtime dependencies
+- make replay legality explicit per request surface
+- ship health, telemetry, and recovery tests before feature sprawl
+- default nontrivial tool output to porcelain
+- keep structured JSON output available where exact consumers need it
+
+## Retrofit
+
+Read:
+
+- [references/bootstrap-retrofit.md](references/bootstrap-retrofit.md)
+- [references/checklist.md](references/checklist.md)
+
+Retrofit in order:
+
+- separate durable transport ownership from fragile execution
+- define typed faults and replay contracts before adding retries
+- adopt the model UX doctrine, especially porcelain-by-default output
+- add rollout, telemetry, and recovery tests before claiming stability
+
+## Guardrails
+
+- Prefer a host/worker split for any long-lived MCP.
+- Do not auto-retry or auto-replay side-effecting requests without an explicit
+  proof of safety.
+- Treat `$mcp-bootstrap` as versioned `libmcp` collateral, not independent lore.
+- Re-open the reference docs when details matter; do not rely on memory.
+
+This skill is intentionally thin. The reference docs are the payload.
diff --git a/assets/codex-skills/mcp-bootstrap/references/bootstrap-fresh.md b/assets/codex-skills/mcp-bootstrap/references/bootstrap-fresh.md
new file mode 100644
index 0000000..bddbc53
--- /dev/null
+++ b/assets/codex-skills/mcp-bootstrap/references/bootstrap-fresh.md
@@ -0,0 +1,85 @@
+# Fresh Bootstrap
+
+Use this when the MCP can still adopt the hard posture directly.
+
+## 1. Durable host, disposable worker
+
+Long-lived MCPs should separate durable session ownership from fragile backend
+execution.
+
+- The host owns the MCP transport, initialization state, request IDs, replay
+  policy, rollout, and user-facing error shaping.
+- The worker owns backend runtimes, backend-specific retries, and tool
+  execution.
+
+If the worker dies, the session should survive.
+
+## 2. Replay as a typed contract
+
+Every request surface needs an explicit replay class:
+
+- `Convergent`
+- `ProbeRequired`
+- `NeverReplay`
+
+Do not add blanket retry or replay logic. The replay class belongs in code, not
+in scattered comments.
+
+## 3. Typed faults
+
+Represent failures as operational faults with recovery semantics.
+
+Baseline classes:
+
+- transport
+- process
+- protocol
+- timeout
+- downstream response
+- resource
+
+Faults should flow through health, telemetry, and user-facing shaping.
+
+## 4. Porcelain by default
+
+Nontrivial tools should default to `render=porcelain`.
+
+Porcelain should be:
+
+- line-oriented
+- deterministic
+- bounded
+- summary-first
+
+Structured `render=json` should remain available.
+
+## 5. Boundary normalization
+
+Normalize model-facing input where it is clearly safe:
+
+- field aliases
+- integer-like strings
+- `file://` URIs
+- stable path style controls
+
+The goal is to eliminate trivial friction, not to hide real ambiguity.
+
+## 6. Health and telemetry
+
+Ship explicit operational tooling:
+
+- health snapshot
+- telemetry snapshot
+- append-only event telemetry
+
+Do this before feature sprawl, not after the first outage.
+
+## 7. Test the failure posture
+
+Build fake runtimes and integration tests that exercise:
+
+- crash recovery
+- replay legality
+- rollout or restart churn
+- model-facing output shaping
+- routing correctness where the backend is root-sensitive
diff --git a/assets/codex-skills/mcp-bootstrap/references/bootstrap-retrofit.md b/assets/codex-skills/mcp-bootstrap/references/bootstrap-retrofit.md
new file mode 100644
index 0000000..5a766a6
--- /dev/null
+++ b/assets/codex-skills/mcp-bootstrap/references/bootstrap-retrofit.md
@@ -0,0 +1,27 @@
+# Retrofit
+
+Use this when the MCP already exists and cannot simply be reimagined from
+scratch.
+
+## Retrofit Order
+
+1. Separate session ownership from fragile execution.
+2. Define typed replay contracts and typed faults.
+3. Replace ad hoc backend dumps with porcelain-by-default output.
+4. Add health, telemetry, and recovery tests.
+5. Only then promise hot rollout or stronger operational guarantees.
+
+## Specific Warnings
+
+- Do not add retries before replay legality is explicit.
+- Do not hide routing bugs behind warm-up masking.
+- Do not call a worker self-healing if the host itself cannot roll forward.
+- Do not let the canonical skill drift away from the actual library contract.
+
+## Doctrine
+
+The retrofit is complete only when:
+
+- the hard posture lives in code
+- the model UX doctrine is visible at the tool surface
+- the skill, spec, and implementation agree
diff --git a/assets/codex-skills/mcp-bootstrap/references/checklist.md b/assets/codex-skills/mcp-bootstrap/references/checklist.md
new file mode 100644
index 0000000..b20a836
--- /dev/null
+++ b/assets/codex-skills/mcp-bootstrap/references/checklist.md
@@ -0,0 +1,15 @@
+# Checklist
+
+Use this checklist when reviewing a `libmcp` consumer.
+
+- Does a stable host own the public session?
+- Is worker fragility isolated behind an explicit replay policy?
+- Are replay contracts typed and local to the request surface?
+- Are faults typed and connected to recovery semantics?
+- Do nontrivial tools default to porcelain output?
+- Is structured JSON still available where exact consumers need it?
+- Are inputs normalized where the semantics are still unambiguous?
+- Are health and telemetry available?
+- Is event telemetry append-only and useful for postmortem analysis?
+- Does the recovery test matrix cover the failure modes actually observed?
+- Is the installed `$mcp-bootstrap` skill sourced from this repository?