proteum 2.2.8 → 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/eslint.js

@@ -14,6 +14,220 @@ const defaultIgnores = [
 const createZodTypeFactorySelector = (factoryName) =>
     `CallExpression[callee.type='MemberExpression'][callee.computed=false][callee.object.type='Identifier'][callee.object.name=/^(schema|z|zod)$/][callee.property.name='${factoryName}']`;
 
+const skippedTraversalKeys = new Set(['parent', 'loc', 'range', 'tokens', 'comments']);
+
+const traverseNode = (node, visit, parent = null, parentKey = null) => {
+    if (!node || typeof node !== 'object') return;
+
+    visit(node, parent, parentKey);
+
+    for (const key of Object.keys(node)) {
+        if (skippedTraversalKeys.has(key)) continue;
+
+        const value = node[key];
+        if (Array.isArray(value)) {
+            value.forEach((child) => {
+                if (child && typeof child.type === 'string') traverseNode(child, visit, node, key);
+            });
+            continue;
+        }
+
+        if (value && typeof value.type === 'string') traverseNode(value, visit, node, key);
+    }
+};
+
+const collectPatternNames = (node, names = []) => {
+    if (!node) return names;
+
+    if (node.type === 'Identifier') {
+        names.push(node.name);
+        return names;
+    }
+
+    if (node.type === 'RestElement') return collectPatternNames(node.argument, names);
+    if (node.type === 'AssignmentPattern') return collectPatternNames(node.left, names);
+    if (node.type === 'TSParameterProperty') return collectPatternNames(node.parameter, names);
+
+    if (node.type === 'ArrayPattern') {
+        node.elements.forEach((element) => collectPatternNames(element, names));
+        return names;
+    }
+
+    if (node.type === 'ObjectPattern') {
+        node.properties.forEach((property) => {
+            if (property.type === 'Property') collectPatternNames(property.value, names);
+            if (property.type === 'RestElement') collectPatternNames(property.argument, names);
+        });
+    }
+
+    return names;
+};
+
+const nodeReferencesName = (node, names) => {
+    let references = false;
+
+    traverseNode(node, (child, parent, parentKey) => {
+        if (child.type !== 'Identifier' || !names.includes(child.name)) return;
+        if (parent?.type === 'MemberExpression' && parentKey === 'property' && parent.computed === false) return;
+        if (parent?.type === 'Property' && parentKey === 'key' && parent.computed === false) return;
+        if (parent?.type === 'MethodDefinition' && parentKey === 'key' && parent.computed === false) return;
+        if (parent?.type === 'PropertyDefinition' && parentKey === 'key' && parent.computed === false) return;
+
+        references = true;
+    });
+
+    return references;
+};
+
+const collectDerivedErrorNames = (node, baseNames) => {
+    const names = [...baseNames];
+    let changed = true;
+
+    while (changed) {
+        changed = false;
+
+        traverseNode(node, (child) => {
+            if (child.type === 'VariableDeclarator' && child.id?.type === 'Identifier' && nodeReferencesName(child.init, names)) {
+                if (!names.includes(child.id.name)) {
+                    names.push(child.id.name);
+                    changed = true;
+                }
+            }
+
+            if (
+                child.type === 'AssignmentExpression' &&
+                child.left?.type === 'Identifier' &&
+                nodeReferencesName(child.right, names)
+            ) {
+                if (!names.includes(child.left.name)) {
+                    names.push(child.left.name);
+                    changed = true;
+                }
+            }
+        });
+    }
+
+    return names;
+};
+
+const getCalleePropertyName = (callee) => {
+    if (!callee) return null;
+    if (callee.type === 'Identifier') return callee.name;
+    if (callee.type === 'MemberExpression') {
+        if (callee.property.type === 'Identifier') return callee.property.name;
+        if (callee.property.type === 'Literal') return String(callee.property.value);
+    }
+
+    return null;
+};
+
+const preservingCallNames = new Set([
+    'captureError',
+    'captureException',
+    'consoleError',
+    'handleError',
+    'logError',
+    'onError',
+    'reject',
+    'reportError',
+    'setError',
+    'setErrorMessage',
+]);
+
+const preservingMemberNames = new Set(['captureException', 'error', 'handleError', 'reject', 'warn']);
+
+const isPreservingCall = (callExpression, names) => {
+    const propertyName = getCalleePropertyName(callExpression.callee);
+    if (!propertyName) return false;
+
+    const isKnownPreserver =
+        preservingCallNames.has(propertyName) ||
+        (callExpression.callee.type === 'MemberExpression' && preservingMemberNames.has(propertyName));
+
+    return isKnownPreserver && nodeReferencesName(callExpression, names);
+};
+
+const handlerPreservesCaughtError = (node, names) => {
+    let preserves = false;
+
+    traverseNode(node, (child) => {
+        if (child.type === 'ThrowStatement' && nodeReferencesName(child.argument, names)) preserves = true;
+        if (child.type === 'CallExpression' && isPreservingCall(child, names)) preserves = true;
+    });
+
+    return preserves;
+};
+
+const directPromiseCatchHandlers = new Set([
+    'captureError',
+    'captureException',
+    'consoleError',
+    'handleError',
+    'logError',
+    'reportError',
+]);
+
+const isDirectPromiseCatchHandler = (node) => {
+    const name = getCalleePropertyName(node);
+    if (name && directPromiseCatchHandlers.has(name)) return true;
+    return node?.type === 'MemberExpression' && node.object?.type === 'Identifier' && node.object.name === 'console';
+};
+
+const createSwallowedErrorRule = () => ({
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require caught errors to be preserved, reported, rethrown, or surfaced with original detail.',
+        },
+        messages: {
+            missingParam:
+                'Caught errors must be bound and preserved. Use `catch (error)` and rethrow, report, route, or surface original details.',
+            unusedParam:
+                'Caught error `{{name}}` is discarded. Rethrow it, report it, route it to app error handling, or surface its original details.',
+            unpreserved:
+                'Caught error `{{name}}` is used but not preserved. Rethrow it, report it, route it, or surface original error details.',
+        },
+        schema: [],
+    },
+    create(context) {
+        const reportHandler = (node, params, body) => {
+            const names = params.flatMap((param) => collectPatternNames(param));
+            if (names.length === 0) {
+                context.report({ node, messageId: 'missingParam' });
+                return;
+            }
+
+            const referencedName = names.find((name) => nodeReferencesName(body, [name]));
+            if (!referencedName) {
+                context.report({ node, messageId: 'unusedParam', data: { name: names[0] } });
+                return;
+            }
+
+            if (!handlerPreservesCaughtError(body, collectDerivedErrorNames(body, names))) {
+                context.report({ node, messageId: 'unpreserved', data: { name: referencedName } });
+            }
+        };
+
+        return {
+            CatchClause(node) {
+                reportHandler(node, node.param ? [node.param] : [], node.body);
+            },
+            "CallExpression[callee.type='MemberExpression'][callee.property.name='catch']"(node) {
+                const [handler] = node.arguments;
+                if (!handler) return;
+                if (isDirectPromiseCatchHandler(handler)) return;
+
+                if (handler.type !== 'ArrowFunctionExpression' && handler.type !== 'FunctionExpression') {
+                    context.report({ node: handler, messageId: 'missingParam' });
+                    return;
+                }
+
+                reportHandler(handler, handler.params, handler.body);
+            },
+        };
+    },
+});
+
 const createProteumEslintConfig = ({ ignores = [] } = {}) => [
     {
         ignores: [...defaultIgnores, ...ignores],
@@ -37,12 +251,18 @@ const createProteumEslintConfig = ({ ignores = [] } = {}) => [
         },
         plugins: {
             '@typescript-eslint': tseslint.plugin,
+            proteum: {
+                rules: {
+                    'no-swallowed-caught-error': createSwallowedErrorRule(),
+                },
+            },
             react: reactPlugin,
             'react-hooks': reactHooksPlugin,
             'jsx-a11y': jsxA11yPlugin,
         },
         rules: {
             '@typescript-eslint/no-explicit-any': 'error',
+            'proteum/no-swallowed-caught-error': 'error',
             'no-restricted-syntax': [
                 'error',
                 {

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.2.8",
+	"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;
+};