proteum 2.2.9 → 2.4.1

package/docs/mcp.md

@@ -0,0 +1,206 @@
+# Proteum MCP
+
+Proteum exposes MCP through two coordinated surfaces:
+
+- `proteum mcp`: one machine-scope router for live Proteum dev projects.
+- `proteum dev`: one app-root runtime endpoint at `http://localhost:<port>/__proteum/mcp`.
+
+Agents should normally connect to `proteum mcp`. The router discovers live `proteum dev` sessions from the machine registry, can resolve offline Proteum app roots from a supplied `cwd`, returns stable `projectId` values for live projects, and forwards app-bound reads to the selected dev-hosted endpoint.
+
+## Machine Router
+
+Start the router from any directory:
+
+```bash
+proteum mcp
+```
+
+When run from a terminal, `proteum mcp` starts or reuses the managed local daemon at `http://127.0.0.1:3769/mcp`. When an MCP client launches it over pipes, use stdio:
+
+```bash
+proteum mcp --stdio
+```
+
+`proteum dev` ensures the managed machine MCP daemon is running before the dev loop starts. Only one managed daemon may run at a time. Stale daemon records are cleaned automatically.
+
+The router is read-only. It does not start or stop dev servers, mutate files, refresh generated code, run migrations, or execute commands.
+
+Use this flow:
+
+1. Call MCP `workflow_start` with `cwd` or a known `projectId`.
+2. If the result is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, pick the intended app root, start exactly one `proteum dev` server from that app root when needed, then retry `workflow_start`.
+3. Pass the returned live `projectId` to every follow-up app-bound MCP call.
+4. After an MCP read succeeds, do not run the equivalent CLI command or broad source search for the same state; keep CLI for fallback, validation, and final terminal evidence.
+
+Example tool calls:
+
+```json
+{"tool":"workflow_start","arguments":{"cwd":"/repo/apps/product","task":"read-only runtime health pass","route":"/dashboard"}}
+{"tool":"projects_list","arguments":{}}
+{"tool":"project_resolve","arguments":{"cwd":"/repo/apps/product/client/pages"}}
+{"tool":"workflow_start","arguments":{"projectId":"prj_0123abcd4567","route":"/dashboard"}}
+{"tool":"runtime_status","arguments":{"projectId":"prj_0123abcd4567"}}
+{"tool":"orient","arguments":{"projectId":"prj_0123abcd4567","query":"/dashboard"}}
+{"tool":"route_candidates","arguments":{"projectId":"prj_0123abcd4567","query":"dashboard","limit":8}}
+{"tool":"explain_summary","arguments":{"projectId":"prj_0123abcd4567","query":"/dashboard"}}
+{"tool":"diagnose","arguments":{"projectId":"prj_0123abcd4567","path":"/dashboard"}}
+```
+
+`workflow_start` is the only app-bound bootstrap tool that may resolve from `cwd` when `projectId` is not known. It may return offline app candidates when no matching dev server is running yet. Other app-bound tools require a live `projectId`; if they omit it, the router returns a compact error that tells the agent to call `projects_list` or `project_resolve`. There is no single-project fallback, because wrong-project reads are worse than an explicit routing retry.
+
+## Dev Runtime Endpoint
+
+During `proteum dev`, the app exposes the same app-level MCP contract through the official streamable HTTP transport:
+
+```text
+POST /__proteum/mcp
+GET /__proteum/mcp
+DELETE /__proteum/mcp
+```
+
+This endpoint is dev-only and local-tooling-only. It is already rooted to the running app, so its tools do not require `projectId` or `cwd`. The machine router strips routing fields before forwarding a call here.
+
+The dev session UI and ready banner print:
+
+```text
+mcp  http://localhost:<port>/__proteum/mcp
+MCP: http://localhost:<port>/__proteum/mcp
+```
+
+`proteum dev` also writes a machine registry record under `~/.proteum/dev-sessions/`. The stable `projectId` is derived from the canonical app root, so it remains stable across port or session-file changes.
+
+## Discovery And Recovery
+
+If machine MCP routing fails:
+
+1. Run `proteum mcp status`.
+2. Run `proteum runtime status` from the intended app root. If you are in a monorepo wrapper, use the returned app candidates and exact next action instead of starting dev from the wrapper.
+3. If no live app session exists, use the exact Start Dev next action returned by runtime status. It checks the configured router/HMR ports and suggests an alternate free port when the manifest default is occupied.
+4. If a live session exists but runtime/MCP is unreachable, stop the listed session file with `proteum dev stop --session-file <path>`, then start dev again.
+5. Retry MCP `workflow_start` and use the returned `projectId`.
+
+Offline `project_resolve` and `workflow_start` candidates also inspect configured router/HMR ports before returning `nextAction`. If the configured port already serves the same app but no live machine project is registered, the next action is runtime tracking repair, not starting a second dev server.
+
+`proteum runtime status` refreshes the machine registry for live tracked sessions, so this recovery path also repairs missing router records after an upgrade.
+
+Do not start a second `proteum dev` server in the same worktree. `proteum dev` fails fast when another live tracked session already exists for the same app root.
+Do not start a second managed `proteum mcp` daemon. `proteum mcp` reuses the live daemon or reports its current URL.
+Do not call `diagnose`, `trace_*`, or `perf_*` while runtime health is unreachable; repair or start dev first.
+Do not `curl` normal page routes to identify port ownership; use `proteum runtime status` or Proteum dev-only `/__proteum/*` endpoints so wrong-app HTML is never dumped into agent context.
+
+## Output Contract
+
+MCP tool payloads are compact single-line JSON strings in this shape:
+
+```json
+{"ok":true,"format":"proteum-mcp-v1","summary":"...","data":{},"nextActions":[],"omitted":[]}
+```
+
+Outputs are capped by default:
+
+- trace output shows counts, failed calls, error events, hot calls, and hot SQL first
+- logs are limited and truncated
+- diagnostics and perf rows are capped
+- full trace detail is paginated with `detail: "full"`, `limit`, and `offset`
+
+Do not make MCP tools return pretty-printed JSON or raw trace/log dumps by default. Pretty output belongs to human CLI/UI surfaces; MCP output is optimized for agent context.
+
+## Tools
+
+Machine-only tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `projects_list` | List live Proteum dev projects and stable `projectId` values |
+| `project_resolve` | Resolve a live project or offline app candidate by `projectId`, `cwd`, app root, or app-root substring |
+
+App-bound tools require `projectId` when called through `proteum mcp`:
+
+| Tool | Purpose |
+| --- | --- |
+| `workflow_start` | One-call bootstrap with resolved project, runtime, selected instruction previews, owner summary, doctor summaries, duplicate-avoidance rules, and next actions |
+| `runtime_status` | Manifest summary, selected runtime, tracked sessions, health, and MCP URL |
+| `orient` | Owner, instruction routing, connected boundaries, and next actions |
+| `instructions_resolve` | Selected instruction files for a query, with short previews and full-read policy |
+| `route_candidates` | Compact route/controller/page matches for a query without dumping the raw route table |
+| `explain_summary` | Compact manifest summary or owner lookup |
+| `doctor` | Compact manifest and optional contract diagnostics |
+| `diagnose` | Composite diagnosis for an existing route, query, or request trace |
+| `trace_latest` | Compact latest trace summary, with optional paginated detail |
+| `trace_show` | Compact or paginated detail for a specific request trace |
+| `perf_top` | Hot-path perf rollup |
+| `perf_request` | One-request waterfall and attribution |
+| `logs_tail` | Capped recent server logs |
+
+## CLI Boundary
+
+Use CLI commands when the result must be reproducible as a terminal step, CI-like validation, or human-shareable command output:
+
+```bash
+proteum dev --session-file var/run/proteum/dev/agents/task.json --port 3101
+proteum build --prod
+proteum check
+proteum refresh
+proteum diagnose /dashboard --port 3101
+proteum verify request /dashboard --port 3101
+proteum trace show <requestId> --events --port 3101
+proteum explain owner /dashboard
+proteum explain --routes --controllers --full # only when the raw route/controller arrays are required
+```
+
+Use MCP when an agent is asking a running app for repeated state:
+
+```text
+workflow_start { cwd, task, route? }
+runtime_status { projectId }
+instructions_resolve { projectId, query }
+orient { projectId, query }
+route_candidates { projectId, query }
+explain_summary { projectId, query }
+doctor { projectId }
+diagnose { projectId, path }
+trace_show { projectId, requestId }
+trace_latest { projectId }
+perf_request { projectId, query }
+logs_tail { projectId }
+```
+
+After an MCP read succeeds, do not run the equivalent CLI command for the same state, and do not run broad source searches for ownership that MCP already returned. CLI output is for fallback, validation, command evidence, and human-shareable reproductions.
+
+## Benchmark
+
+The Product `/domains` diagnostic loop measured on May 7, 2026 used `ceil(UTF-8 bytes / 4)` as an output-token estimate:
+
+| Workflow | Approx output tokens | Elapsed |
+| --- | ---: | ---: |
+| Compact CLI single loop | 6,286 | 4,809 ms |
+| Dev-hosted HTTP MCP single loop | 5,211 | 232 ms |
+| Compact CLI repeated reads x3 | 11,660 | 9,572 ms |
+| Dev-hosted HTTP MCP repeated reads x3 | 10,537 | 214 ms |
+
+Machine routing adds one lightweight `projects_list` lookup but keeps repeated app reads on the dev-hosted runtime endpoint. The practical rule is: use CLI for reproducible checks and final evidence, then use MCP with `projectId` for repeated reads against the same app/runtime.
+
+## Codex Usage Test
+
+Proteum core uses Vitest for framework tests. The live Codex MCP usage test is opt-in because it runs the real Codex CLI, may spend model tokens, and depends on the developer machine's Codex auth plus MCP registration.
+
+```bash
+PROTEUM_CODEX_MCP_USAGE_CWD=/absolute/path/to/proteum/app npm run test:codex-mcp
+```
+
+The test sends a read-only runtime health prompt to `codex exec --json`, stores the JSONL transcript, stderr, last message, and `summary.json`, then asserts:
+
+- token usage was reported and quantified
+- at least one Proteum MCP `workflow_start` call happened
+- total Proteum MCP calls meet `PROTEUM_CODEX_MCP_MIN_MCP_CALLS` (`4` by default)
+- Proteum CLI fallback calls stay under `PROTEUM_CODEX_MCP_MAX_CLI_CALLS` (`4` by default)
+
+Useful optional variables:
+
+```bash
+CODEX_CLI=/path/to/codex
+PROTEUM_CODEX_MCP_USAGE_OUTPUT_DIR=/tmp/proteum-codex-mcp-usage
+PROTEUM_CODEX_MCP_USAGE_TIMEOUT_MS=1200000
+PROTEUM_CODEX_MCP_MIN_MCP_CALLS=4
+PROTEUM_CODEX_MCP_MAX_CLI_CALLS=4
+```

package/docs/migrate-from-2.1.3.md

@@ -307,13 +307,18 @@ This is usually only needed for workspace or hoisted installs. Standalone apps w
 
 These are worth updating even though they are not core app-code migrations.
 
-### Use `--json` for automation
+### Use compact CLI output for automation
 
-Only bare `proteum build` and bare `proteum dev` runs print a banner. For scripts, CI helpers, or editor tooling, prefer:
+Only bare `proteum build` and bare `proteum dev` runs print a banner. Other CLI diagnostics are optimized for agents and return compact machine-readable output by default. For scripts, CI helpers, or editor tooling, prefer:
 
-- `npx proteum explain --json`
-- `npx proteum doctor --json`
-- `npx proteum connect --json`
+- `npx proteum orient <query>`
+- `npx proteum runtime status`
+- `npx proteum explain`
+- `npx proteum doctor`
+- `npx proteum connect`
+- `npx proteum mcp` as the managed machine-scope MCP router; `proteum dev` ensures one daemon is running, agents call `workflow_start` first, use offline candidates to choose the correct app root when needed, then pass the returned live `projectId` to repeated reads against a live dev app
+
+CLI output uses compact `proteum-agent-v1` JSON for reproducible command evidence. MCP output uses compact `proteum-mcp-v1` JSON for repeated runtime reads. Use `npx proteum explain --manifest`, `npx proteum diagnose <target> --full`, or `npx proteum trace show <requestId> --events` only when the compact output is insufficient.
 
 ### Use tracked dev sessions
 
@@ -323,7 +328,7 @@ Current `proteum dev` supports tracked session management:
 - `npx proteum dev list --json`
 - `npx proteum dev stop --session-file var/run/proteum/dev/app.json`
 
-If your local workflow starts multiple dev servers, this is the current supported model.
+`proteum dev` fails fast when another live tracked session already exists for the same app root. If runtime/MCP is unreachable, stop the listed session file first, then start dev again instead of launching a second server in the same worktree.
 
 ### New diagnostics are available
 
@@ -331,6 +336,8 @@ These are new capabilities, not migration requirements, but they are the fastest
 
 - `npx proteum connect --strict`
 - `npx proteum explain --connected --controllers`
+- `npx proteum runtime status`
+- `npx proteum mcp status` plus MCP `workflow_start`, `project_resolve`, or `projects_list`
 - `npx proteum diagnose / --port <port>`
 - `npx proteum perf top --port <port>`
 - `npx proteum trace latest --port <port>`
@@ -370,6 +377,7 @@ Then boot the app and verify the live runtime:
 
 ```bash
 npx proteum dev --port 3010
+npx proteum runtime status
 npx proteum diagnose / --port 3010
 npx proteum trace latest --port 3010
 ```

package/docs/request-tracing.md

@@ -10,7 +10,7 @@ The same API and SQL instrumentation feeds both shapes. Dev trace keeps the in-m
 ## Scope
 
 - retained dev tracing is available only when the app runs with `profile: dev`
-- traces are exposed through `proteum trace`, `proteum perf`, and the dev-only `__proteum/trace` and `__proteum/perf` HTTP endpoints
+- traces are exposed through `proteum trace`, `proteum perf`, MCP `trace_*`/`perf_*` tools, and the dev-only `__proteum/trace`, `__proteum/perf`, and `/__proteum/mcp` HTTP endpoints
 - `proteum diagnose` is a separate composite surface that reads the same framework diagnostics plus one matching request trace and buffered server logs; see [diagnostics.md](diagnostics.md)
 - `ENABLE_PROFILER=true` enables reduced request-local profiling in any environment, including production
 
@@ -20,6 +20,7 @@ The same API and SQL instrumentation feeds both shapes. Dev trace keeps the in-m
 proteum trace requests
 proteum trace latest
 proteum trace show <requestId>
+proteum trace show <requestId> --events
 proteum trace arm --capture deep
 proteum trace export <requestId>
 proteum trace latest --url http://127.0.0.1:3010
@@ -30,26 +31,31 @@ proteum perf compare --baseline yesterday --target today --group-by route
 proteum perf memory --since 1h --group-by controller
 ```
 
+Default trace output is compact `proteum-agent-v1` JSON with counts, failed calls, error events, hot calls, and hot SQL. Use `--events` or `--full` only when raw event details, payload summaries, or SQL text are needed.
+
+When an MCP client is available, call `workflow_start` with `cwd` or a known `projectId`, then use the returned live `projectId` with MCP `trace_latest`, `trace_show`, `perf_top`, and `perf_request` for repeated reads against the same running app. If `workflow_start` returns offline app candidates or unreachable runtime health, start or repair exactly one `proteum dev` server from the intended app root before trace or perf reads. Keep the CLI commands for reproducible terminal evidence and final verification logs.
+
 Before reproducing a bug or starting a new test pass:
 
-- read the default port from `PORT` or `./.proteum/manifest.json`
-- check whether a dev server is already running on that port
-- if it is, inspect `proteum trace requests`, `proteum trace latest`, and `proteum trace show <requestId>` first so you can capture past errors and their context
+- run `proteum runtime status` to reuse a tracked dev session when possible and to get an exact Start Dev action when the configured router/HMR ports are occupied
+- use MCP `runtime_status` with the selected `projectId` for repeated status checks against the same running server
+- if a server is already running, inspect `proteum trace requests`, `proteum trace latest`, and compact `proteum diagnose <path>` first so you can capture past errors without dumping raw events
 
 Typical debugging flow:
 
 ```bash
 proteum orient /dashboard
+proteum runtime status
 proteum diagnose /dashboard --hit /dashboard --port 3103
 proteum perf request /dashboard --port 3103
-proteum trace show <requestId> --port 3103
+proteum trace show <requestId> --events --port 3103
 ```
 
 Use `--url http://host:port` when the dev server is reachable on a non-standard host and `--port` is not enough.
 
 If the request under test is protected and login UX is not the feature under test, mint an auth cookie with `proteum session <email> --role <role>` before reproducing the request. This keeps the trace focused on the protected behavior instead of the login flow.
 
-If you already know the failing path and want a one-shot suspect list before reading raw events, start with `proteum diagnose <path> --port <port>` and `proteum perf request <path> --port <port>` first, then drop into `proteum trace show <requestId>` only when the lower-level event stream is still needed.
+If you already know the failing path and want a one-shot suspect list before reading raw events, start with `proteum diagnose <path> --port <port>` and `proteum perf request <path> --port <port>` first, then drop into `proteum trace show <requestId> --events` only when the lower-level event stream is still needed.
 
 Use ad hoc database queries or one-off scripts only after `orient`, `diagnose`, `perf request`, and `trace show` still leave the request chain unclear.
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.2.9",
+	"version": "2.4.1",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",
@@ -12,6 +12,12 @@
 	"keywords": [
 		"framework"
 	],
+	"scripts": {
+		"test": "vitest run",
+		"test:codex-mcp": "PROTEUM_RUN_CODEX_MCP_USAGE_TEST=1 vitest run tests/codex-mcp-usage.test.cjs",
+		"test:integration": "vitest run tests/dev-transpile-watch.test.cjs",
+		"test:unit": "vitest run --exclude tests/dev-transpile-watch.test.cjs"
+	},
 	"bin": {
 		"proteum": "cli/bin.js"
 	},
@@ -21,6 +27,7 @@
 		"@babel/traverse": "^7.29.0",
 		"@babel/types": "^7.29.0",
 		"@inkjs/ui": "^2.0.0",
+		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@prisma/adapter-mariadb": "7.2.0",
 		"@prisma/client": "7.2.0",
 		"@rspack/core": "^1.7.9",
@@ -103,13 +110,14 @@
 		"@types/fs-extra": "^9.0.12",
 		"@types/markdown-it": "^12.2.3",
 		"@types/mime-types": "^2.1.1",
-		"@types/node": "^16.9.1",
+		"@types/node": "^20.19.40",
 		"@types/nodemailer": "^6.4.4",
 		"@types/pg": "^8.6.1",
 		"@types/pg-escape": "^0.2.1",
 		"@types/prompts": "^2.0.14",
 		"@types/sharp": "^0.31.1",
 		"@types/universal-analytics": "^0.4.5",
-		"schema-dts": "^1.1.2"
+		"schema-dts": "^1.1.2",
+		"vitest": "^4.1.5"
 	}
 }

package/server/app/devMcp.ts

@@ -0,0 +1,204 @@
+import { buildContractsDoctorResponse } from '@common/dev/contractsDoctor';
+import { buildDoctorResponse } from '@common/dev/diagnostics';
+import { buildOrientationResponse, explainOwner } from '@common/dev/inspection';
+import {
+    buildRuntimeStatusPayload,
+    compactDiagnoseResponse,
+    compactDoctorResponse,
+    compactExplainSummary,
+    compactLogsResponse,
+    compactOrientationResponse,
+    compactPerfRequestResponse,
+    compactPerfTopResponse,
+    compactRouteCandidatesResponse,
+    compactTraceResponse,
+    compactWorkflowStartResponse,
+    resolveInstructionRouting,
+} from '@common/dev/mcpPayloads';
+import type { TProteumMcpProvider } from '@common/dev/mcpServer';
+import type { TDevConsoleLogLevel } from '@common/dev/console';
+import type { TPerfGroupBy } from '@common/dev/performance';
+
+import type { Application } from './index';
+
+export const createRuntimeProteumMcpProvider = ({
+    app,
+    publicUrl,
+    routerPort,
+}: {
+    app: Application;
+    publicUrl: string;
+    routerPort: number;
+}): TProteumMcpProvider => {
+    const diagnostics = () => app.getDevDiagnostics();
+    const readManifest = () => diagnostics().readManifest();
+    const assertTraceEnabled = () => {
+        if (!app.container.Trace.isDevTraceEnabled()) {
+            throw new Error('Proteum dev trace is not enabled for this runtime.');
+        }
+    };
+
+    const provider: TProteumMcpProvider = {
+        async runtimeStatus(_input: Record<string, never> = {}) {
+            const manifest = readManifest();
+            const doctor = buildDoctorResponse(manifest);
+            const contracts = buildContractsDoctorResponse(manifest);
+
+            return buildRuntimeStatusPayload({
+                appRoot: app.container.path.root,
+                health: {
+                    reachable: true,
+                    doctor: doctor.summary,
+                    contracts: contracts.summary,
+                },
+                manifest,
+                runtime: {
+                    publicUrl,
+                    routerPort,
+                    source: 'proteum-dev-runtime',
+                    mcpUrl: `${publicUrl}/__proteum/mcp`,
+                    traceEnabled: app.container.Trace.isDevTraceEnabled(),
+                    profilerEnabled: app.container.Trace.isProfilingEnabled(),
+                    connectedProjects: Object.entries(app.connectedProjects || {}).map(([namespace, project]) => ({
+                        namespace,
+                        urlInternal: (project as { urlInternal?: string }).urlInternal,
+                    })),
+                },
+            });
+        },
+        async workflowStart({ file, query, route, task }) {
+            const manifest = readManifest();
+            const doctor = buildDoctorResponse(manifest);
+            const contracts = buildContractsDoctorResponse(manifest);
+            const ownerQuery = [route, file, query]
+                .map((value) => value?.trim())
+                .find((value): value is string => Boolean(value));
+
+            return compactWorkflowStartResponse({
+                contracts,
+                doctor,
+                file,
+                health: {
+                    reachable: true,
+                    doctor: doctor.summary,
+                    contracts: contracts.summary,
+                },
+                manifest,
+                owner: ownerQuery ? explainOwner(manifest, ownerQuery) : undefined,
+                query,
+                route,
+                runtime: {
+                    publicUrl,
+                    routerPort,
+                    source: 'proteum-dev-runtime',
+                    mcpUrl: `${publicUrl}/__proteum/mcp`,
+                    traceEnabled: app.container.Trace.isDevTraceEnabled(),
+                    profilerEnabled: app.container.Trace.isProfilingEnabled(),
+                    connectedProjects: Object.entries(app.connectedProjects || {}).map(([namespace, project]) => ({
+                        namespace,
+                        urlInternal: (project as { urlInternal?: string }).urlInternal,
+                    })),
+                },
+                task,
+            });
+        },
+        async orient({ query }) {
+            return compactOrientationResponse(buildOrientationResponse(readManifest(), query));
+        },
+        async instructionsResolve({ query }) {
+            return resolveInstructionRouting({ appRoot: app.container.path.root, query });
+        },
+        async explainSummary({ query }) {
+            const manifest = readManifest();
+            const normalizedQuery = query?.trim();
+
+            return compactExplainSummary({
+                manifest,
+                owner: normalizedQuery ? explainOwner(manifest, normalizedQuery) : undefined,
+                query: normalizedQuery,
+            });
+        },
+        async routeCandidates({ limit, query }) {
+            return compactRouteCandidatesResponse({
+                limit,
+                manifest: readManifest(),
+                query,
+            });
+        },
+        async doctor({ contracts = true }) {
+            const manifest = readManifest();
+
+            return compactDoctorResponse({
+                contracts: contracts ? buildContractsDoctorResponse(manifest) : undefined,
+                doctor: buildDoctorResponse(manifest),
+            });
+        },
+        async diagnose({
+            logsLevel = 'warn',
+            logsLimit = 40,
+            path,
+            query,
+            requestId,
+        }: {
+            logsLevel?: TDevConsoleLogLevel;
+            logsLimit?: number;
+            path?: string;
+            query?: string;
+            requestId?: string;
+        }) {
+            return compactDiagnoseResponse(
+                diagnostics().diagnose({
+                    logsLevel,
+                    logsLimit,
+                    path,
+                    query,
+                    requestId,
+                }),
+            );
+        },
+        async traceLatest({ detail, limit, offset }) {
+            assertTraceEnabled();
+            const request = app.container.Trace.getLatestRequest();
+            if (!request) throw new Error('No request trace is available yet.');
+
+            return compactTraceResponse({ detail, limit, offset, request });
+        },
+        async traceShow({ detail, limit, offset, requestId }) {
+            assertTraceEnabled();
+            const request = app.container.Trace.getRequest(requestId);
+            if (!request) throw new Error(`Trace ${requestId} was not found.`);
+
+            return compactTraceResponse({ detail, limit, offset, request });
+        },
+        async perfTop({ groupBy = 'path', limit = 12, since = 'today' }) {
+            return compactPerfTopResponse(
+                diagnostics().perfTop({
+                    groupBy: groupBy as TPerfGroupBy,
+                    limit,
+                    since,
+                }),
+            );
+        },
+        async perfRequest({ query }) {
+            return compactPerfRequestResponse(diagnostics().perfRequest(query));
+        },
+        async logsTail({ level = 'warn', limit = 40 }) {
+            return compactLogsResponse({
+                level,
+                limit,
+                response: diagnostics().readLogs(limit, level),
+            });
+        },
+        async readResource(uri) {
+            if (uri === 'proteum://runtime/status') return await provider.runtimeStatus({});
+            if (uri === 'proteum://instructions/router') return await provider.instructionsResolve({});
+            if (uri === 'proteum://manifest/summary') return await provider.explainSummary({});
+            if (uri === 'proteum://trace/latest/summary') return await provider.traceLatest({});
+            if (uri === 'proteum://perf/top') return await provider.perfTop({});
+
+            throw new Error(`Unknown Proteum MCP resource: ${uri}`);
+        },
+    };
+
+    return provider;
+};

package/server/services/router/http/cache.ts

@@ -0,0 +1,116 @@
+import path from 'path';
+
+export type THttpCacheHeadersConfig = {
+    cacheControl?: string;
+    surrogateControl?: string | false;
+};
+
+export type TPublicAssetsCacheConfig = {
+    dev?: string;
+    versioned?: string;
+    unversioned?: string;
+    etag?: boolean;
+    lastModified?: boolean;
+};
+
+export type THttpCacheConfig = {
+    html?: {
+        dynamic?: THttpCacheHeadersConfig;
+        static?: THttpCacheHeadersConfig;
+    };
+    publicAssets?: TPublicAssetsCacheConfig;
+};
+
+export type TResolvedHttpCacheHeadersConfig = {
+    cacheControl: string;
+    surrogateControl: string | false;
+};
+
+export type TResolvedPublicAssetsCacheConfig = {
+    dev: string;
+    versioned: string;
+    unversioned: string;
+    etag?: boolean;
+    lastModified?: boolean;
+};
+
+export type TResolvedHttpCacheConfig = {
+    html: {
+        dynamic: TResolvedHttpCacheHeadersConfig;
+        static: TResolvedHttpCacheHeadersConfig;
+    };
+    publicAssets: TResolvedPublicAssetsCacheConfig;
+};
+
+export const defaultHttpCacheConfig = {
+    html: {
+        dynamic: {
+            cacheControl: 'no-store, no-cache, must-revalidate, proxy-revalidate',
+            surrogateControl: 'no-store',
+        },
+        static: {
+            cacheControl: 'public, max-age=0, must-revalidate',
+            surrogateControl: false,
+        },
+    },
+    publicAssets: {
+        dev: 'no-store',
+        versioned: 'public, max-age=31536000, immutable',
+        unversioned: 'public, max-age=0, must-revalidate',
+    },
+} satisfies TResolvedHttpCacheConfig;
+
+type TPublicAssetRequest = {
+    originalUrl?: string;
+    url?: string;
+};
+
+type TPublicAssetResponse = {
+    req?: TPublicAssetRequest;
+};
+
+const hashedPublicAssetPattern = /(^|[-_.])[a-f0-9]{6,}(?=(\.[^.]+)+$)/i;
+
+export const resolveHttpCacheConfig = (config?: THttpCacheConfig): TResolvedHttpCacheConfig => ({
+    html: {
+        dynamic: {
+            ...defaultHttpCacheConfig.html.dynamic,
+            ...(config?.html?.dynamic || {}),
+        },
+        static: {
+            ...defaultHttpCacheConfig.html.static,
+            ...(config?.html?.static || {}),
+        },
+    },
+    publicAssets: {
+        ...defaultHttpCacheConfig.publicAssets,
+        ...(config?.publicAssets || {}),
+    },
+});
+
+export const isVersionedPublicAssetRequest = (
+    res: undefined | TPublicAssetResponse,
+    filePath: string,
+) => {
+    const requestUrl = res?.req?.originalUrl || res?.req?.url || '';
+    const searchParams = new URL(requestUrl, 'http://proteum.local').searchParams;
+    if (searchParams.has('v')) return true;
+
+    return hashedPublicAssetPattern.test(path.basename(filePath));
+};
+
+export const resolvePublicAssetCacheControl = ({
+    res,
+    filePath,
+    profile,
+    cache,
+}: {
+    res: undefined | TPublicAssetResponse;
+    filePath: string;
+    profile: string;
+    cache: TResolvedPublicAssetsCacheConfig;
+}) => {
+    if (profile === 'dev') return cache.dev;
+
+    return isVersionedPublicAssetRequest(res, filePath) ? cache.versioned : cache.unversioned;
+};