@lovehlmmm/primekit 1.0.0

package/skills/agentize/references/agent-centric-design.md

@@ -0,0 +1,134 @@
+# Agent-Centric Design Rules
+
+Rules for choosing what to expose and how to shape it when wrapping code for CLI + MCP consumption by AI agents.
+
+## Select capabilities
+
+Keep a capability if **at least one** is true:
+- An agent can accomplish a user task by calling it
+- It's a workflow step that is awkward or error-prone to express in prose
+- It's idempotent or easily made so
+
+Drop a capability if **all** are true:
+- It's a thin passthrough over another capability
+- It's purely internal plumbing
+- Its output is too large to be useful in context
+
+## Consolidate workflows
+
+Bad: `list_items`, `get_item`, `check_quota`, `create_item` (4 tools, agent has to orchestrate).
+Good: `create_item(name, …)` that internally checks quota, deduplicates by name, and returns the created record.
+
+Rule: if the README's "how to use" says "first call X, then Y, then Z" — that's one tool, not three.
+
+## Optimize for context
+
+- Default responses are **concise**. Return IDs + names + status, not full payloads.
+- Offer `format: "detailed"` / `--detailed` opt-in for full data.
+- Paginate. Default page size small (10–25).
+- Prefer names over IDs in responses: `{ "project": "acme-web" }` beats `{ "project_id": "prj_7f3c2…" }`.
+- Truncate long fields with a `…` marker + length hint.
+
+## Actionable errors
+
+Every error must answer: what failed, why, and what to try next.
+
+Bad:
+```
+Error: 400 Bad Request
+```
+
+Good:
+```
+Error: rate_limited
+Message: Exceeded 60 requests/minute. Retry after 12s, or pass --concurrency 2.
+```
+
+Include an `error_code` machine field for agent branching.
+
+## Safe vs mutating
+
+- Read-only tools: no confirmation semantics, safe to call speculatively.
+- Mutating tools: describe the mutation in the tool `description`; prefer `dry_run: true` support; return the diff/preview when dry-running.
+- Destructive tools (`delete_*`): require an explicit `confirm: true` or a unique token returned from a preceding `plan_*` tool.
+
+## Naming
+
+- Tools: `verb_noun`, snake_case: `list_projects`, `create_project`, `search_logs`.
+- CLI commands: `noun verb` or `verb`, kebab-case: `project list`, `project create`, `search`.
+- Flags: long-form kebab-case, short-form single-letter where universal (`-v`, `-h`).
+
+## Idempotency
+
+Where possible:
+- Creates accept a client-supplied idempotency key
+- Updates are PATCH-shaped (only send changed fields)
+- Deletes succeed if the target is already absent
+
+## Output shape
+
+JSON output (default when `--json` or MCP structured content):
+
+```json
+{
+  "ok": true,
+  "data": { … },
+  "warnings": [],
+  "next_actions": ["optional hints for the agent"]
+}
+```
+
+Errors:
+
+```json
+{
+  "ok": false,
+  "error": { "code": "rate_limited", "message": "…", "retry_after_s": 12 }
+}
+```
+
+## Schema-driven dynamic CLI design
+
+When wrapping API docs into a CLI package, derive commands from a machine-readable manifest (OpenAPI / JSON Schema) at **build or runtime** instead of hand-authoring one command per endpoint.
+
+Pattern:
+- **Generic resource/action dispatch** — `cli <resource> <action> [flags]` maps to OpenAPI `paths` + `operationId` (or `x-cli` extensions).
+- **Generated per-command help** — descriptions, required flags, enums, and examples come from the schema; `--help` stays accurate without editing command files.
+- **Extension without edits** — new endpoints or doc changes regenerate the surface; existing dispatch code stays put.
+
+Example layout:
+
+```
+packages/cli/
+  src/
+    dispatch.ts          # generic resource/action router
+    codegen/
+      from-openapi.ts    # OpenAPI → command manifest
+    generated/
+      commands.json      # checked-in or build artifact
+  openapi.yaml           # source of truth (or fetched)
+```
+
+Regeneration workflow:
+1. Update `openapi.yaml` (or bump the remote doc URL).
+2. `pnpm -C packages/cli gen` → refreshes `generated/commands.json` + typed flag map.
+3. Smoke: `cli --help`, `cli <resource> --help`, one read + one write against staging.
+4. Ship; no new hand-written command modules for additive API changes.
+
+Prefer build-time generation for publishable CLIs (reproducible installs). Runtime fetch is fine for internal tools that always pin a live schema URL with caching + checksum.
+
+**Sources:** [Speakeasy OpenAPI → tools](https://speakeasy.com/mcp/tool-design/generate-mcp-tools-from-openapi/), OpenAPI 3.1
+
+## Runtime package criteria
+
+Ship CLI/MCP packages that agents can install safely and cheaply:
+
+| Criterion | Rule |
+| --- | --- |
+| **Minimal dependencies** | Prefer language stdlib; every dep needs a reason. Audit transitive trees (`pnpm why` / `npm ls`). |
+| **Security** | No `postinstall` / `preinstall` scripts that fetch or exec. Prefer packages with npm provenance. Redact secrets in logs, errors, and `--debug` dumps. |
+| **Small install size** | Avoid bundling browsers, full AWS SDKs, or unused locales. Tree-shake; publish only `dist/`. |
+| **Cross-platform** | Use `node:path` / `pathlib`; never assume `/` or bash. Test Windows path + shell quoting. Prefer `cross-spawn` / Node APIs over `/bin/sh`. |
+| **Graceful degradation** | Optional native addons (keytar, etc.) fail soft with a clear message and env-file fallback. Missing optional peers must not crash import. |
+
+Checklist before publish: clean install on Linux/macOS/Windows CI, no network during `postinstall`, `npm pack` size reviewed, secrets never printed by `doctor` / `auth status`.

package/skills/agentize/references/auth-resolution-chain.md

@@ -0,0 +1,95 @@
+# Auth Resolution Chain
+
+One chain, used by both CLI and MCP-stdio. MCP-HTTP/SSE uses bearer tokens at transport layer, but tools may still need per-request values pulled from the chain.
+
+## Resolution chain (first hit wins)
+
+1. **Explicit flag** — `--api-key <v>`, `--token <v>`, etc. Never logged, never echoed.
+2. **Process env vars** — convention: `<TOOL>_<KEY>` (e.g. `ACME_API_KEY`).
+3. **dotenv files**, in this order:
+   - `.env.local` (git-ignored, highest priority)
+   - `.env.<NODE_ENV>` (e.g. `.env.production`)
+   - `.env`
+   Search starts in CWD and walks up to the nearest package root or repo root.
+4. **User config JSON**:
+   - Linux/macOS: `$XDG_CONFIG_HOME/<tool>/config.json` or `~/.config/<tool>/config.json`
+   - Windows: `%APPDATA%\<tool>\config.json`
+5. **Project config JSON**: `./.<tool>rc.json` or `./<tool>.config.json` in CWD.
+6. **OS keychain** via `keytar` — stored by the `login` command:
+   - macOS Keychain, Windows Credential Vault, libsecret on Linux
+   - Service name: `<tool>`, account = profile name
+
+Document the chain in `docs/cli.md`. `doctor` command reports which layer supplied each value without revealing the value itself.
+
+## Config file shape
+
+```json
+{
+  "$schema": "https://<tool>.dev/schema/config.json",
+  "profiles": {
+    "default": {
+      "apiKey": "env:ACME_API_KEY",
+      "baseUrl": "https://api.acme.dev",
+      "timeoutMs": 30000
+    },
+    "staging": {
+      "apiKey": "keychain:acme/staging",
+      "baseUrl": "https://staging.api.acme.dev"
+    }
+  },
+  "activeProfile": "default"
+}
+```
+
+Resolver supports indirection:
+- `env:NAME` → read from process env
+- `keychain:<service>/<account>` → read from OS keychain
+- `file:/absolute/path` → read file contents (for mounted files)
+- plain string → literal value
+
+## `login` and `logout`
+
+```
+<tool> login [--profile <name>]
+<tool> logout [--profile <name>]
+```
+
+`login` prompts interactively, writes to OS keychain, updates `activeProfile`. Never writes the value to a config file on disk unless the user passes `--save-plaintext` (explicit, discouraged).
+
+## Redaction
+
+- Log redactor masks anything that looks sensitive: long entropy strings, `*key*`, `*token*`, `Authorization:` headers.
+- JSON output of `doctor`:
+
+```json
+{
+  "apiKey":   { "resolved": true, "source": "keychain:acme/default" },
+  "baseUrl":  { "resolved": true, "source": "config:~/.config/acme/config.json", "value": "https://api.acme.dev" }
+}
+```
+
+Sensitive entries have `resolved` + `source` but never `value`. Non-sensitive config includes `value`.
+
+## Precedence rules
+
+- A value present at a higher layer fully overrides lower layers (no merging per-field for scalars).
+- Structured config objects merge shallowly: later layers replace keys they define.
+- `--profile <name>` selects the active profile before resolution runs; env-only values still win over profile values.
+
+## MCP-HTTP context
+
+Tools receive a per-request `ctx.auth` built by the transport's auth handler. Inside tool handlers:
+
+```ts
+const resolved = await resolveAuth({ token: ctx.auth.token, profile: ctx.auth.profile });
+```
+
+`resolveAuth` uses the same chain, but layer 1 is the transport-provided token instead of a CLI flag. Layer 6 (keychain) is disabled in non-local deployments.
+
+## Anti-patterns
+
+- Storing API keys in plain JSON by default.
+- Logging full request/response bodies.
+- `postinstall` scripts that touch the keychain.
+- Baking values into Docker images.
+- Reading `.env` from unbounded parent directories (limit to package/repo root).

package/skills/agentize/references/challenge-framework.md

@@ -0,0 +1,68 @@
+# Challenge Framework (`--ask` mode)
+
+Use after scout + analyze, before scaffolding. Goal: pressure-test assumptions
+and surface constraints. Cut requested scope only when the user passed
+`--yagni`.
+
+## Core questions (always ask)
+
+1. **Why agentize this?** What unlocks when an AI agent (not a human) calls these operations? If the answer is "it'd be cool," stop.
+2. **Who's the primary consumer?** AI agent, human via CLI, or both equally? This drives shape of outputs, error messages, verbosity.
+3. **What's requested for v1?** Confirm the requested capabilities and separate
+   them from additions discovered during analysis. Do not defer requested work
+   unless the user passed `--yagni` or explicitly chooses to defer it.
+4. **Read vs write split.** Which capabilities are read-only? Which mutate? Which are destructive? (affects auth, confirmation, MCP tool design)
+5. **Where do values come from today?** Env? Vault? Hardcoded? This pins the resolution chain defaults.
+6. **Deployment target.** Local-only (stdio + CLI), remote (Cloudflare), self-host (Docker), or all? Cost + ops implications differ.
+7. **Package name and scope.** `@org/tool`? Public npm scope? License?
+8. **Maintenance.** Who owns this after release? Release cadence? Deprecation policy?
+
+## Architectural challenges
+
+| Question | Red Flag | Green Flag |
+| --- | --- | --- |
+| Core extractable? | Business logic tangled with HTTP/CLI | Clear function boundaries |
+| Side effects localized? | Scattered across modules | Isolated into clients |
+| Async/long-running ops? | 30+ sec calls, no cancel | Quick calls or streaming progress |
+| Auth complexity? | Multi-step OAuth dance per call | Static token or one-time login |
+| Large outputs? | Megabyte responses typical | Pageable, filterable |
+| Stateful workflows? | Requires client-side state machine | Each call self-contained |
+
+## Cut-scope challenges (`--yagni` only)
+
+Skip this section unless the user passed `--yagni`. Without the flag, use these
+questions only to reject unrequested additions, never to remove requested work.
+
+Ask for each proposed capability:
+- Can an agent accomplish the user's goal without this one?
+- Is this 80% covered by another capability?
+- Does this leak internal model details the agent doesn't need?
+- Is this a debug/admin op that does not belong on the public surface?
+
+## Design challenges
+
+- Are we mirroring HTTP endpoints instead of designing workflows?
+- Is the concise response actually concise (<1 KB typical)?
+- Do errors tell the agent what to do next, not just what broke?
+- Are identifiers agent-friendly (names) or DB-friendly (UUIDs)?
+- Would a human reading the tool description know when to use it?
+
+## Decision matrix template
+
+```markdown
+| # | Decision            | Option A       | Option B       | Chosen | Why |
+| - | ------------------- | -------------- | -------------- | ------ | --- |
+| 1 | Transport           | stdio only     | all three      | all    | remote deploy planned |
+| 2 | Credential storage  | env only       | keychain+env   | both   | dev UX + prod safety |
+| 3 | CLI framework       | commander      | cac            | commander | wider adoption |
+| 4 | Test runner         | vitest         | jest           | vitest | speed + TS native |
+| 5 | Deploy target v1    | Cloudflare     | Docker         | both   | CI cost is low |
+```
+
+## Stop conditions
+
+Abort and propose an alternative if:
+- Core cannot be extracted without significant refactor the user hasn't scoped
+- With `--yagni`, no capabilities survive the cut-scope pass
+- Legal/compliance blocks publishing (licensing of upstream deps, etc.)
+- Credentials model requires interactive OAuth that can't run in the MCP transports

package/skills/agentize/references/code-mode.md

@@ -0,0 +1,106 @@
+# Code Mode
+
+Agents write code that calls MCP tools through generated TypeScript APIs, executed in a sandbox. Only the final result returns to the model — not intermediate payloads or full tool schemas.
+
+Introduced by Cloudflare (September 2025) to fix tool bloat: classic MCP injects every tool schema into context, which can consume hundreds of thousands of tokens before work starts.
+
+**Sources:** [Cloudflare Code Mode](https://blog.cloudflare.com/code-mode-mcp/), [Agents SDK codemode](https://developers.cloudflare.com/agents/tools/codemode/how-it-works/)
+
+## How it works
+
+1. **Schemas → generated API** — Tool schemas become typed TypeScript method stubs. The agent sees a minimal meta-surface (often `search` / `execute`) plus clean API signatures, not verbose JSON schemas.
+2. **Agent writes code** — Typically an async TypeScript function that chains list → filter → transform locally.
+3. **Sandboxed execution** — Code runs in an isolate or microVM (no host FS, CPU/memory limits, egress allowlists). Credentials are injected via a network proxy, never as env vars the code can print.
+4. **Final result only** — Intermediate rows stay inside the sandbox; the LLM receives the compact return value.
+
+```ts
+const result = await (async () => {
+  const users = await api.users.list({ limit: 100, status: "active" });
+  const filtered = users.filter((u) => u.created > "2025-01-01");
+  return { count: filtered.length, users: filtered };
+})();
+```
+
+**Sources:** [MCP spec](https://modelcontextprotocol.io/specification/2025-06-18), [Dynamic Workers](https://developers.cloudflare.com/dynamic-workers/)
+
+## When to use vs classic tool calls
+
+| Factor | Classic tool calls | Code Mode |
+| --- | --- | --- |
+| Tool count | < 5 tools | Many tools / 3+ servers |
+| Task shape | 1–2 steps | Multi-step chains (4+) |
+| Intermediate results | Small | Large result sets, local filtering |
+| Context pressure | Acceptable | High (schemas dominate context) |
+| Latency | Prefer single round-trips | Tolerate code-exec overhead |
+| Setup | Minimal | Needs sandbox infrastructure |
+
+### Published token-savings figures
+
+| Scale | Reported savings | Source |
+| --- | --- | --- |
+| Large (~500 APIs) | ~1.15M → ~83K tokens (~14× / ~93%) | [WorkOS on Cloudflare](https://workos.com/blog/cloudflare-code-mode-cuts-token-usage-by-81) |
+| Across scales | ~58–99% depending on tool count | [Dev.to benchmarks](https://dev.to/anthonymax/how-to-cut-mcp-token-costs-save-up-to-92-at-scale-with-code-mode-3fco) |
+| Stripe-style workflows | ~2.4× more efficient than raw MCP | [CLI vs MCP vs Code Mode](https://portofcontext.com/blog/cli-vs-mcp-vs-code-mode) |
+| Medium (50–100 tools) | ~65–80% reduction | Same benchmarks |
+
+Skip Code Mode when the task is 1–2 calls, human approval is required between steps, or the toolset is small and stable.
+
+## Deployment recipes
+
+### Cloudflare Workers / isolates
+
+Agents SDK `codemode` + Dynamic Worker Loaders. V8 isolates on the edge; millisecond cold start; JS/TS/Wasm only.
+
+```bash
+npm install @cloudflare/codemode wrangler zod
+```
+
+**Tradeoffs:** Fastest to ship, global scale, experimental API (breaking changes expected). No arbitrary binaries.
+
+**Sources:** [codemode API](https://developers.cloudflare.com/agents/tools/codemode/api-reference/), [cloudflare/agents](https://github.com/cloudflare/agents)
+
+### Self-hosted VPS
+
+Run Anthropic `@anthropic-ai/sandbox-runtime` (Seatbelt / bubblewrap) or Deno Sandbox on a VPS beside the MCP server. Good for local/dev and small fleets.
+
+**Tradeoffs:** Process-level isolation is weaker than microVMs; keep runtime ≥0.0.16 (CVE-2025-66479). Ops burden is yours.
+
+**Sources:** [anthropic-ai/sandbox-runtime](https://www.npmjs.com/package/@anthropic-ai/sandbox-runtime), [Deno Sandbox](https://docs.deno.com/sandbox/)
+
+### Docker / Kubernetes with gVisor or Firecracker
+
+Package the Code Mode executor in Docker; on Kubernetes prefer `RuntimeClass` with gVisor or Kata/Firecracker microVMs.
+
+| Option | Isolation | Overhead |
+| --- | --- | --- |
+| gVisor | Userspace syscall intercept | ~10–30% |
+| Firecracker / Kata | Hardware microVM | Higher resources, strongest boundary |
+
+**Tradeoffs:** Full language support and air-gapped friendly; highest ops cost.
+
+**Sources:** [gVisor](https://gvisor.dev/), [K8s agent sandbox](https://kubernetes.io/blog/2026/03/20/running-agents-on-kubernetes-with-agent-sandbox/)
+
+## Security checklist
+
+- [ ] Never run agent code on the host without a sandbox layer
+- [ ] Prefer microVMs (Firecracker/Kata) for sensitive workloads; keep runtimes patched
+- [ ] No secrets in sandbox env vars — proxy-injected credentials only
+- [ ] Default-deny egress; allowlist required domains at the sandbox/VM boundary
+- [ ] Audit tool invocations and outbound calls; short-lived scoped tokens
+- [ ] Human approval for destructive / exfil-risk actions
+
+**Sources:** [MCP security best practices](https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices), [Deno sandbox security](https://docs.deno.com/sandbox/security/)
+
+## Available SDKs
+
+| SDK | Package | Notes |
+| --- | --- | --- |
+| Cloudflare Agents | `@cloudflare/codemode` | `createCodeTool`, `DynamicWorkerExecutor`; experimental |
+| Anthropic | `@anthropic-ai/sandbox-runtime` | Local/VPS process sandbox; research preview |
+| Deno | `@deno/sandbox` | Firecracker microVMs; proxy secret injection |
+
+## Related
+
+- `mcp-transports.md` — Streamable HTTP / stdio wiring
+- `deployment-guide.md` — Cloudflare Workers / Docker targets
+- `oauth-streamable-http.md` — OAuth for remote HTTP MCP

package/skills/agentize/references/deployment-guide.md

@@ -0,0 +1,94 @@
+# Deployment Guide (MCP)
+
+Three primary targets. Pick one (or ship all) based on Phase 3 decisions.
+
+## Cloudflare Workers
+
+Best for: global edge, low ops, per-session state via Durable Objects. For agent-written tool orchestration in isolates, see `code-mode.md`.
+
+`wrangler.toml`:
+
+```toml
+name = "<tool>-mcp"
+main = "dist/worker.js"
+compatibility_date = "2025-01-01"
+compatibility_flags = ["nodejs_compat"]
+
+[[durable_objects.bindings]]
+name = "MCP_SESSION"
+class_name = "McpSession"
+
+[[migrations]]
+tag = "v1"
+new_classes = ["McpSession"]
+
+[vars]
+MCP_TRANSPORT = "http"
+```
+
+Worker entry wires Streamable HTTP onto `/mcp`, routes to a `McpSession` Durable Object keyed by `mcp-session-id`. Secrets via `wrangler secret put MCP_TOKEN`.
+
+Deploy: `wrangler deploy`.
+
+Notes:
+- SSE works but Streamable HTTP is preferred.
+- stdio cannot run on Workers — build it, test it locally, skip it from this target.
+- Do not import Node-only modules; rely on `nodejs_compat` sparingly and prefer web APIs.
+
+## Docker
+
+Best for: self-host, air-gapped, or full control.
+
+`Dockerfile`:
+
+```dockerfile
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm i --frozen-lockfile
+COPY . .
+RUN pnpm -C packages/mcp build
+
+FROM node:20-alpine
+WORKDIR /app
+RUN addgroup -S app && adduser -S app -G app
+COPY --from=build --chown=app:app /app/packages/mcp/dist ./dist
+COPY --from=build --chown=app:app /app/packages/mcp/package.json ./
+COPY --from=build --chown=app:app /app/node_modules ./node_modules
+USER app
+EXPOSE 8080
+ENV MCP_TRANSPORT=http PORT=8080
+HEALTHCHECK --interval=30s --timeout=5s CMD wget -qO- http://127.0.0.1:8080/healthz || exit 1
+CMD ["node", "dist/bin.js"]
+```
+
+`docker-compose.yml` sample with env file, port, restart policy. Document passing `MCP_TOKEN` via a secrets manager, never hardcoded in compose.
+
+Publish image to GHCR (`ghcr.io/<org>/<tool>-mcp`) from `release.yml`.
+
+## PaaS (Fly.io, Railway, Render)
+
+Any Node-capable PaaS works with the Streamable HTTP transport.
+
+- **Fly.io**: `fly launch` with the Dockerfile, set secrets via `fly secrets set`.
+- **Railway**: connect repo, set `MCP_TRANSPORT=http`, inject secrets as env vars.
+- **Render**: Web Service, Docker runtime, health check path `/healthz`.
+
+All three: bind `0.0.0.0`, read `PORT` from env, emit logs to stdout/stderr, no local filesystem writes.
+
+## Cross-cutting
+
+- **TLS** is terminated by the PaaS or by a reverse proxy you run — do not ship TLS in the app.
+- **Rate limits** at the app layer (per token), regardless of PaaS rate limits.
+- **Session storage**: Cloudflare → Durable Objects; Docker/PaaS → in-memory with sticky sessions or Redis if horizontal scaling.
+- **Config hot-reload**: not required; prefer redeploy.
+- **Secrets rotation**: support at least two valid tokens during rotation window (`MCP_TOKEN`, `MCP_TOKEN_PREV`).
+
+## Local dev
+
+```
+pnpm -C packages/mcp dev          # stdio, for Claude Code integration
+pnpm -C packages/mcp dev -- --transport http --port 8080
+```
+
+Add an `mcp.json` example in `docs/mcp.md` showing how to register the server in Claude Code, Cursor, and similar clients.

package/skills/agentize/references/mcp-transports.md

@@ -0,0 +1,139 @@
+# MCP Transports
+
+Ship **stdio** (local) and **Streamable HTTP** (remote). Treat SSE as deprecated/legacy during the offramp. One core `Server`, thin transport adapters.
+
+**Sources:** [MCP transports](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports), [2026-07-28 blog](https://blog.modelcontextprotocol.io/posts/2026-07-28/)
+
+## Transport selection
+
+```ts
+const transport = process.env.MCP_TRANSPORT ?? flag("--transport") ?? "stdio";
+switch (transport) {
+  case "stdio": await startStdio(server); break;
+  case "sse": await startSse(server, { port }); break; // legacy only
+  case "http": await startStreamableHttp(server, { port }); break;
+  default: die(`unknown transport: ${transport}`);
+}
+```
+
+## stdio
+
+Unchanged. Default for local agents (Claude Code, Cursor, etc.).
+
+```ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+const t = new StdioServerTransport();
+await server.connect(t);
+```
+
+- No transport-layer OAuth — trust the parent; credentials from env/config
+- Never write non-protocol bytes to stdout; logs → stderr
+
+## Streamable HTTP (primary remote)
+
+Preferred remote transport. Single endpoint handles POST (JSON-RPC) and optional GET (stream). Required for Cloudflare Workers and most PaaS.
+
+```ts
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+app.all("/mcp", async (c) => {
+  const t = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => crypto.randomUUID(), // omit / undefined for stateless
+  });
+  await server.connect(t);
+  return t.handleRequest(c.req.raw, c.res);
+});
+```
+
+### Stateless vs stateful modes
+
+| Mode | Behavior | When |
+| --- | --- | --- |
+| **stateless** | Every request is self-describing; any replica can serve it; no sticky sessions | Serverless, horizontal scale (preferred for new servers) |
+| **stateful** | Server issues `Mcp-Session-Id` (or `mcp-session-id`); client echoes it; resumable streams | Per-session memory, Durable Objects, long SSE-like streams |
+
+**stateless (2026-07-28 direction):** Prefer no protocol session. Newer stacks may route with `Mcp-Method` / `Mcp-Name` headers so gateways avoid body inspection. Round-robin LBs work without affinity.
+
+**stateful:** Keep `sessionIdGenerator` and store session keyed by `Mcp-Session-Id`. On Cloudflare Workers use Durable Objects; on Docker/Node use sticky sessions or Redis. Support resumability via last-event / stream cursors when exposing GET streams.
+
+**Sources:** [MCP goes stateless](https://blog.modelcontextprotocol.io/posts/2026-07-28/), [InfoQ](https://infoq.com/news/2026/08/mcp-stateless-gateway/)
+
+## tasks (long-running)
+
+Experimental since **2025-11-25**; still experimental under `io.modelcontextprotocol/tasks` as of **2026-07-28**. Use for work longer than ~30s (ETL, batch export, human-in-the-loop). Short ops stay ordinary tools.
+
+Lifecycle: `working` → optional `input_required` → terminal `completed` | `failed` | `cancelled`.
+
+| Method | Purpose |
+| --- | --- |
+| `tasks/get` | Poll status / progress |
+| `tasks/list` | Active tasks |
+| `tasks/update` | Supply input when `input_required` |
+| `tasks/cancel` | Graceful cancel |
+| `tasks/result` | Final output |
+
+**Sources:** [Tasks utility](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks), [Tasks extension](https://modelcontextprotocol.io/extensions/tasks/overview)
+
+## Structured tool output
+
+Return dual content: human `content` summary + machine `structuredContent` validated by an output schema (JSON Schema / Zod). FastMCP / modern SDKs expose `result_type` for typed results.
+
+```ts
+server.tool(
+  "list_projects",
+  "List projects. Concise by default; `format: detailed` for full data.",
+  {
+    format: z.enum(["concise", "detailed"]).default("concise"),
+    limit: z.number().int().min(1).max(100).default(25),
+  },
+  async (args, ctx) => core.listProjects({ ...args, auth: ctx.auth }),
+);
+```
+
+Register tools once on the core `Server`; all transports expose the same set.
+
+## SSE (deprecated / legacy)
+
+Deprecated per the [2026-07-28 announcement](https://blog.modelcontextprotocol.io/posts/2026-07-28/) with a ~12-month offramp (~through August 2027). Some vendors (e.g. Atlassian) already sunsetting HTTP+SSE. Keep a thin adapter only for old clients; document Streamable HTTP as the migration target.
+
+```ts
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+app.get("/sse", async (c) => {
+  const t = new SSEServerTransport("/messages", c.res);
+  await server.connect(t);
+});
+app.post("/messages", (c) => t.handlePostMessage(c.req, c.res));
+```
+
+**Sources:** [SSE sunset notes](https://sunny34.com/blog/posts/mcp-sse-transport-sunset-ops.en), [Cloudflare MCP v2](https://blog.cloudflare.com/mcp-v2/)
+
+## Auth (HTTP only)
+
+Prefer OAuth 2.1 for public remote servers — see `oauth-streamable-http.md`. Simple bearer still fine for private tokens:
+
+```
+Authorization: Bearer <token>
+```
+
+Reject with `401` early. Cloudflare: Workers Secrets; Docker: secret manager → env; never bake into images.
+
+## SDK support tiers (2026-07-28)
+
+| SDK | Tier | Notes |
+| --- | --- | --- |
+| TypeScript SDK v2 | Tier 1 | `@modelcontextprotocol/server` / `client`; Streamable HTTP, OAuth helpers, tasks |
+| Python SDK v2 | Tier 1 | `pip install mcp[cli]`; TokenVerifier / AuthSettings; serverless-friendly |
+| v1.x | Security patches only | Do not start new work on v1 |
+
+**Sources:** [TS SDK](https://github.com/modelcontextprotocol/typescript-sdk), [Python SDK](https://github.com/modelcontextprotocol/python-sdk)
+
+## Health & observability
+
+- `GET /healthz` → 200 when up
+- `GET /readyz` → 200 when ready
+- JSON logs on stderr: `trace_id`, `session_id`, `tool_name`, `duration_ms` — never args/secrets
+
+## Related
+
+- `oauth-streamable-http.md` — OAuth 2.1 + PKCE for Streamable HTTP
+- `code-mode.md` — sandboxed code orchestration over MCP tools
+- `deployment-guide.md` — Workers / Docker wiring