chore: import upstream snapshot with attribution

2026-07-13 12:10:27 +08:00
commit 49b9bb6724
992 changed files with 161690 additions and 0 deletions
@@ -0,0 +1,53 @@
+# lifespan
+
+Process-scoped dependency injection. Pass an `@asynccontextmanager` as
+`lifespan=` to acquire resources (a database pool, an HTTP client) once at
+startup and release them at shutdown; tool bodies read the yielded state via
+the injected `Context` — no module-level globals.
+
+## Run it
+
+```bash
+# stdio (default — the client spawns the server as a subprocess)
+uv run python -m stories.lifespan.client
+
+# HTTP — the client self-hosts the server on a free port, runs, then tears it down
+uv run python -m stories.lifespan.client --http
+# same, against the lowlevel-API server variant
+uv run python -m stories.lifespan.client --http --server server_lowlevel
+```
+
+## What to look at
+
+- `client.py` `main` — opens with `Client(target, mode=mode)`; the story owns
+  the construction, the harness only chooses the target and era. Lifespan is
+  invisible from here: the client speaks plain MCP, and the `lookup` results
+  are the only proof the yielded state was wired through.
+- `app_lifespan` in `server.py` — the `try / yield / finally` shape is the
+  startup/shutdown contract; the `finally` block runs once on process exit, not
+  per request.
+- `ctx.request_context.lifespan_context.db` in the `lookup` tool — the interim
+  3-hop access path on `MCPServer`'s `Context`.
+- `server_lowlevel.py` reaches the same state via `ctx.lifespan_context.db` —
+  one hop, because lowlevel handlers receive `ServerRequestContext` directly.
+
+## Caveats
+
+- `ctx.request_context.lifespan_context` is the interim path; a later release
+  will shorten this to `ctx.state.*`. The lowlevel `ctx.lifespan_context` path
+  is unaffected.
+- **v1 → v2 scope change** — in v1.x, `lifespan` was entered once per
+  `Server.run()` call: once per *session* for stateful streamable HTTP and once
+  per *request* under `stateless_http=True` (stdio was already per-process). In
+  v2 it is entered once per process regardless of transport. See
+  `docs/migration.md` ("Streamable HTTP: lifespan now entered once at manager
+  startup").
+
+## Spec
+
+[Lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle)
+
+## See also
+
+`stickynotes/` (lifespan-held mutable state with change notifications),
+`serve_one/` (threading `lifespan_state` into the kernel by hand).