proteum 2.2.9 → 2.3.0

package/docs/mcp.md

@@ -0,0 +1,149 @@
+# Proteum MCP
+
+Proteum exposes read-only MCP surfaces for agents that need repeated, compact access to project and runtime state.
+
+There are two entrypoints:
+
+- `proteum mcp`: a stdio MCP server launched from an app or worktree.
+- `proteum dev`: a dev-hosted MCP endpoint at `/__proteum/mcp`.
+
+Both entrypoints expose the same tool/resource contract. The CLI remains the source of truth for `dev`, `build`, `check`, `refresh`, migrations, and reproducible terminal validation. MCP is for low-token reads, runtime snapshots, trace/perf/log summaries, and progressive detail loading.
+
+## Stdio Server
+
+Configure an MCP client to launch the server from the app root:
+
+```bash
+proteum mcp
+```
+
+Useful options:
+
+```bash
+proteum mcp --cwd /path/to/app
+proteum mcp --url http://localhost:3101
+proteum mcp --session-file var/run/proteum/dev/agents/task.json
+```
+
+The stdio server reads manifest, instruction, and tracked-session data from disk. When a live dev server is known through `--url`, a tracked session file, or the manifest router port, runtime tools read the dev endpoints directly instead of spawning CLI commands.
+
+Use stdio MCP when the agent environment can launch a long-lived tool server but does not already have direct access to the running `proteum dev` HTTP transport.
+
+## Dev Runtime Endpoint
+
+During `proteum dev`, the app exposes the same 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 uses the running app's in-memory diagnostics, trace, perf, and log stores where possible, so runtime tools avoid process startup and avoid dumping full trace payloads by default.
+
+The dev session UI and ready banner print:
+
+```text
+mcp  http://localhost:<port>/__proteum/mcp
+MCP: http://localhost:<port>/__proteum/mcp
+```
+
+Use dev-hosted MCP when an agent is iterating against an already running app. It is the fastest path for repeated `runtime_status`, `orient`, `diagnose`, `trace_*`, `perf_*`, and `logs_tail` reads.
+
+## Output Contract
+
+MCP tool and resource 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
+
+The v1 tools are read-only:
+
+| Tool | Purpose |
+| --- | --- |
+| `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 |
+| `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 |
+
+MCP v1 intentionally does not start/stop dev servers, refresh generated files, arm traces, export traces, write files, run migrations, or execute app commands.
+
+## Resources
+
+Static resources expose common compact reads:
+
+- `proteum://runtime/status`
+- `proteum://instructions/router`
+- `proteum://manifest/summary`
+- `proteum://trace/latest/summary`
+- `proteum://perf/top`
+
+## 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
+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
+```
+
+Use MCP when an agent is asking the same running app for repeated state:
+
+```text
+runtime_status
+instructions_resolve
+orient
+diagnose
+trace_latest
+perf_request
+logs_tail
+```
+
+## Routing Guidance
+
+Use these surfaces in this order:
+
+1. Agent instructions for hard safety policy and routing rules.
+2. MCP for repeated reads, runtime status, instruction selection, traces, perf, and logs.
+3. Compact CLI for reproducible terminal validation and CI-like checks.
+4. Full CLI escape hatches only after compact MCP/CLI output identifies the missing detail.
+
+## 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 |
+| Stdio MCP single loop | 5,526 | 900 ms |
+| Compact CLI repeated reads x3 | 11,660 | 9,572 ms |
+| Dev-hosted HTTP MCP repeated reads x3 | 10,537 | 214 ms |
+
+The benchmark included the routed instruction docs separately. Reading the four selected instruction files once was about 4,881 estimated output tokens; refreshing the instruction routing through MCP `instructions_resolve` was about 722 estimated output tokens.
+
+The practical rule from the benchmark is: use CLI for the first reproducible check and validation record, then use MCP for repeated reads against the same app/runtime.

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 --url http://localhost:<port>` for repeated agent reads against a running 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
 
@@ -331,6 +336,9 @@ 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`
+- `npx proteum mcp --url http://localhost:<port>`
 - `npx proteum diagnose / --port <port>`
 - `npx proteum perf top --port <port>`
 - `npx proteum trace latest --port <port>`
@@ -370,6 +378,8 @@ Then boot the app and verify the live runtime:
 
 ```bash
 npx proteum dev --port 3010
+npx proteum runtime status
+npx proteum mcp --url http://localhost:3010
 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, use MCP `trace_latest`, `trace_show`, `perf_top`, and `perf_request` for repeated reads against the same running app. 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
+- use MCP `runtime_status` 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.3.0",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",
@@ -21,6 +21,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",

package/server/app/devMcp.ts

@@ -0,0 +1,159 @@
+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,
+    compactTraceResponse,
+    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 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 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;
+};