proteum 2.2.9 → 2.3.0

package/cli/mcp/provider.ts

@@ -0,0 +1,365 @@
+import fs from 'fs-extra';
+import got from 'got';
+import path from 'path';
+
+import { buildContractsDoctorResponse } from '../../common/dev/contractsDoctor';
+import { buildDoctorResponse, type TDoctorResponse } 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, TDevConsoleLogsResponse } from '../../common/dev/console';
+import type { TDiagnoseResponse } from '../../common/dev/inspection';
+import type { TPerfRequestResponse, TPerfTopResponse } from '../../common/dev/performance';
+import type { TProteumManifest } from '../../common/dev/proteumManifest';
+import type { TRequestTraceResponse } from '../../common/dev/requestTrace';
+import { readProteumManifest } from '../compiler/common/proteumManifest';
+import { listDevSessionInspections, type TDevSessionInspection } from '../runtime/devSessions';
+
+type TCliProteumMcpProviderArgs = {
+    appRoot: string;
+    sessionFilePath?: string;
+    url?: string;
+};
+
+type TRequestOptions = {
+    method?: 'GET' | 'POST';
+    searchParams?: Record<string, string>;
+};
+
+const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
+const dedupe = <TValue>(values: TValue[]) => [...new Set(values)];
+
+const buildBaseUrlCandidates = (value: string) => {
+    const normalized = normalizeBaseUrl(value);
+
+    try {
+        const parsed = new URL(normalized);
+        const port = parsed.port;
+        const pathname = parsed.pathname === '/' ? '' : parsed.pathname;
+        const search = parsed.search;
+        const hash = parsed.hash;
+        const buildUrl = (hostname: string) => `${parsed.protocol}//${hostname}${port ? `:${port}` : ''}${pathname}${search}${hash}`;
+
+        if (parsed.hostname === '127.0.0.1') return dedupe([normalized, buildUrl('localhost'), buildUrl('[::1]')]);
+        if (parsed.hostname === 'localhost') return dedupe([normalized, buildUrl('127.0.0.1'), buildUrl('[::1]')]);
+        if (parsed.hostname === '[::1]' || parsed.hostname === '::1') return dedupe([normalized, buildUrl('localhost'), buildUrl('127.0.0.1')]);
+    } catch (_error) {}
+
+    return [normalized];
+};
+
+const compactSession = (inspection: TDevSessionInspection) => ({
+    sessionFilePath: inspection.sessionFilePath,
+    live: inspection.live,
+    stale: inspection.stale,
+    invalid: inspection.invalid,
+    parseError: inspection.parseError,
+    pid: inspection.record?.pid,
+    routerPort: inspection.record?.routerPort,
+    publicUrl: inspection.record?.publicUrl,
+    state: inspection.record?.state,
+    startedAt: inspection.record?.startedAt,
+    updatedAt: inspection.record?.updatedAt,
+});
+
+const getSessionUrl = (inspection: TDevSessionInspection) => {
+    if (!inspection.record) return '';
+    if (inspection.record.publicUrl) return inspection.record.publicUrl.replace(/\/+$/, '');
+    return `http://localhost:${inspection.record.routerPort}`;
+};
+
+export class CliProteumMcpProvider implements TProteumMcpProvider {
+    private sessionsPromise?: Promise<TDevSessionInspection[]>;
+
+    public constructor(private args: TCliProteumMcpProviderArgs) {}
+
+    private readManifestIfAvailable() {
+        const manifestFilepath = path.join(this.args.appRoot, '.proteum', 'manifest.json');
+        if (!fs.existsSync(manifestFilepath)) return undefined;
+
+        try {
+            return readProteumManifest(this.args.appRoot);
+        } catch (_error) {
+            return undefined;
+        }
+    }
+
+    private readLocalManifest() {
+        const manifest = this.readManifestIfAvailable();
+        if (!manifest) {
+            throw new Error(
+                `Proteum manifest was not found in ${this.args.appRoot}. Run \`proteum refresh\`, \`proteum dev\`, or pass --url for a running dev server.`,
+            );
+        }
+
+        return manifest;
+    }
+
+    private async readSessions() {
+        this.sessionsPromise ??= listDevSessionInspections({
+            appRoot: this.args.appRoot,
+            sessionFilePath: this.args.sessionFilePath,
+        });
+        return await this.sessionsPromise;
+    }
+
+    private async selectSession() {
+        const sessions = await this.readSessions();
+        const liveSessions = sessions.filter((inspection) => inspection.live && inspection.record);
+
+        return (
+            liveSessions.find((inspection) => inspection.record?.state === 'ready') ||
+            liveSessions[0] ||
+            sessions.find((inspection) => inspection.record)
+        );
+    }
+
+    private async getBaseUrlCandidates() {
+        if (this.args.url?.trim()) return buildBaseUrlCandidates(this.args.url.trim());
+
+        const selectedSession = await this.selectSession();
+        const selectedBaseUrl = selectedSession ? getSessionUrl(selectedSession) : '';
+        if (selectedBaseUrl) return buildBaseUrlCandidates(selectedBaseUrl);
+
+        const manifest = this.readManifestIfAvailable();
+        const routerPort = manifest?.env.resolved.routerPort;
+        if (typeof routerPort === 'number' && routerPort > 0) {
+            return dedupe([`http://localhost:${routerPort}`, `http://127.0.0.1:${routerPort}`, `http://[::1]:${routerPort}`]);
+        }
+
+        return [];
+    }
+
+    private async requestJson<TResponse>(pathname: string, options: TRequestOptions = {}) {
+        const attempts: string[] = [];
+        const baseUrls = await this.getBaseUrlCandidates();
+
+        for (const baseUrl of baseUrls) {
+            const url = `${baseUrl}${pathname}${options.searchParams ? `?${new URLSearchParams(options.searchParams).toString()}` : ''}`;
+
+            try {
+                const response = await got(url, {
+                    method: options.method || 'GET',
+                    responseType: 'json',
+                    retry: { limit: 0 },
+                    throwHttpErrors: false,
+                    timeout: { request: 2_500 },
+                });
+
+                if (response.statusCode >= 400) {
+                    const body = response.body as { error?: string } | undefined;
+                    throw new Error(body?.error || `Proteum dev endpoint returned HTTP ${response.statusCode}.`);
+                }
+
+                return { baseUrl, body: response.body as TResponse };
+            } catch (error) {
+                attempts.push(`${url}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+
+        throw new Error(
+            [
+                'Could not reach a Proteum dev MCP data source.',
+                ...attempts.map((attempt) => `- ${attempt}`),
+                'Start `proteum dev`, pass --url, or use tools that can read the local manifest from disk.',
+            ].join('\n'),
+        );
+    }
+
+    private async readManifestPreferRuntime() {
+        if (this.args.url?.trim()) {
+            return (await this.requestJson<TProteumManifest>('/__proteum/explain')).body;
+        }
+
+        const localManifest = this.readManifestIfAvailable();
+        if (localManifest) return localManifest;
+
+        return (await this.requestJson<TProteumManifest>('/__proteum/explain')).body;
+    }
+
+    private async probeRuntimeHealth() {
+        try {
+            const response = await this.requestJson<TDoctorResponse>('/__proteum/doctor');
+            return {
+                reachable: true,
+                baseUrl: response.baseUrl,
+                doctor: response.body.summary,
+            };
+        } catch (error) {
+            return {
+                reachable: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+
+    public async runtimeStatus(_input: Record<string, never> = {}) {
+        const manifest = this.readManifestIfAvailable();
+        const sessions = await this.readSessions();
+        const selectedSession = await this.selectSession();
+        const health = await this.probeRuntimeHealth();
+        const runtime =
+            health.reachable && 'baseUrl' in health
+                ? {
+                      publicUrl: health.baseUrl,
+                      routerPort: selectedSession?.record?.routerPort || manifest?.env.resolved.routerPort,
+                      source: this.args.url?.trim() ? 'explicit-url' : selectedSession?.record ? 'tracked-session' : 'manifest-port',
+                      session: selectedSession ? compactSession(selectedSession) : undefined,
+                      mcpUrl: `${health.baseUrl}/__proteum/mcp`,
+                  }
+                : selectedSession
+                  ? {
+                        routerPort: selectedSession.record?.routerPort,
+                        publicUrl: selectedSession.record?.publicUrl,
+                        source: 'tracked-session',
+                        session: compactSession(selectedSession),
+                    }
+                  : undefined;
+
+        return buildRuntimeStatusPayload({
+            appRoot: this.args.appRoot,
+            health,
+            manifest,
+            runtime,
+            sessions: sessions.map(compactSession),
+        });
+    }
+
+    public async orient({ query }: { query: string }) {
+        return compactOrientationResponse(buildOrientationResponse(await this.readManifestPreferRuntime(), query));
+    }
+
+    public async instructionsResolve({ query }: { query?: string }) {
+        return resolveInstructionRouting({ appRoot: this.args.appRoot, query });
+    }
+
+    public async explainSummary({ query }: { query?: string }) {
+        const manifest = await this.readManifestPreferRuntime();
+        const normalizedQuery = query?.trim();
+
+        return compactExplainSummary({
+            manifest,
+            owner: normalizedQuery ? explainOwner(manifest, normalizedQuery) : undefined,
+            query: normalizedQuery,
+        });
+    }
+
+    public async doctor({ contracts = true }: { contracts?: boolean }) {
+        if (this.args.url?.trim()) {
+            const doctor = (await this.requestJson<TDoctorResponse>('/__proteum/doctor')).body;
+            const contractDoctor = contracts
+                ? (await this.requestJson<TDoctorResponse>('/__proteum/doctor/contracts')).body
+                : undefined;
+            return compactDoctorResponse({ contracts: contractDoctor, doctor });
+        }
+
+        const manifest = this.readManifestIfAvailable();
+        if (manifest) {
+            return compactDoctorResponse({
+                contracts: contracts ? buildContractsDoctorResponse(manifest) : undefined,
+                doctor: buildDoctorResponse(manifest),
+            });
+        }
+
+        const doctor = (await this.requestJson<TDoctorResponse>('/__proteum/doctor')).body;
+        const contractDoctor = contracts
+            ? (await this.requestJson<TDoctorResponse>('/__proteum/doctor/contracts')).body
+            : undefined;
+        return compactDoctorResponse({ contracts: contractDoctor, doctor });
+    }
+
+    public async diagnose(input: {
+        logsLevel?: TDevConsoleLogLevel;
+        logsLimit?: number;
+        path?: string;
+        query?: string;
+        requestId?: string;
+    }) {
+        const searchParams: Record<string, string> = {};
+        if (input.logsLevel) searchParams.logsLevel = input.logsLevel;
+        if (typeof input.logsLimit === 'number') searchParams.logsLimit = String(input.logsLimit);
+        if (input.path) searchParams.path = input.path;
+        if (input.query) searchParams.query = input.query;
+        if (input.requestId) searchParams.requestId = input.requestId;
+
+        return compactDiagnoseResponse((await this.requestJson<TDiagnoseResponse>('/__proteum/diagnose', { searchParams })).body);
+    }
+
+    public async traceLatest(input: { detail?: 'compact' | 'full'; limit?: number; offset?: number }) {
+        const response = (await this.requestJson<TRequestTraceResponse>('/__proteum/trace/latest')).body;
+        return compactTraceResponse({
+            detail: input.detail,
+            limit: input.limit,
+            offset: input.offset,
+            request: response.request,
+        });
+    }
+
+    public async traceShow(input: { detail?: 'compact' | 'full'; limit?: number; offset?: number; requestId: string }) {
+        const response = (await this.requestJson<TRequestTraceResponse>(`/__proteum/trace/requests/${encodeURIComponent(input.requestId)}`))
+            .body;
+        return compactTraceResponse({
+            detail: input.detail,
+            limit: input.limit,
+            offset: input.offset,
+            request: response.request,
+        });
+    }
+
+    public async perfTop(input: { groupBy?: 'path' | 'route' | 'controller'; limit?: number; since?: string }) {
+        return compactPerfTopResponse(
+            (
+                await this.requestJson<TPerfTopResponse>('/__proteum/perf/top', {
+                    searchParams: {
+                        groupBy: input.groupBy || 'path',
+                        limit: String(input.limit || 12),
+                        since: input.since || 'today',
+                    },
+                })
+            ).body,
+        );
+    }
+
+    public async perfRequest({ query }: { query: string }) {
+        return compactPerfRequestResponse(
+            (
+                await this.requestJson<TPerfRequestResponse>('/__proteum/perf/request', {
+                    searchParams: { query },
+                })
+            ).body,
+        );
+    }
+
+    public async logsTail({ level = 'warn', limit = 40 }: { level?: TDevConsoleLogLevel; limit?: number }) {
+        return compactLogsResponse({
+            level,
+            limit,
+            response: (
+                await this.requestJson<TDevConsoleLogsResponse>('/__proteum/logs', {
+                    searchParams: { level, limit: String(limit) },
+                })
+            ).body,
+        });
+    }
+
+    public async readResource(uri: string) {
+        if (uri === 'proteum://runtime/status') return await this.runtimeStatus({});
+        if (uri === 'proteum://instructions/router') return await this.instructionsResolve({});
+        if (uri === 'proteum://manifest/summary') return await this.explainSummary({});
+        if (uri === 'proteum://trace/latest/summary') return await this.traceLatest({});
+        if (uri === 'proteum://perf/top') return await this.perfTop({});
+
+        throw new Error(`Unknown Proteum MCP resource: ${uri}`);
+    }
+}

package/cli/mcp/stdio.ts

@@ -0,0 +1,16 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { createProteumMcpServer, type TProteumMcpProvider } from '../../common/dev/mcpServer';
+
+export const startProteumMcpStdioServer = async ({
+    provider,
+    version,
+}: {
+    provider: TProteumMcpProvider;
+    version: string;
+}) => {
+    const server = createProteumMcpServer({ provider, version });
+    const transport = new StdioServerTransport();
+
+    await server.connect(transport);
+};

package/cli/presentation/commands.ts

@@ -21,6 +21,8 @@ export const proteumCommandNames = [
     'orient',
     'diagnose',
     'perf',
+    'runtime',
+    'mcp',
     'trace',
     'command',
     'session',
@@ -49,7 +51,7 @@ export type TProteumCommandDoc = {
 
 export const proteumRecommendedFlow: TRow[] = [
     { label: '1. proteum orient <query>', value: 'Start here for multi-repo, generated, or connected work before reading code.' },
-    { label: '2. proteum dev', value: 'Start the compiler, SSR server, and hot reload loop.' },
+    { label: '2. proteum runtime status', value: 'Reuse an existing tracked dev session before starting a new one.' },
     { label: '3. proteum diagnose <path> --hit <path>', value: 'Validate the smallest trustworthy request surface before broader checks.' },
     { label: '4. proteum check', value: 'Refresh, typecheck, and lint before you commit or push.' },
 ];
@@ -57,7 +59,7 @@ export const proteumRecommendedFlow: TRow[] = [
 export const proteumCommandGroups: Array<{ title: string; names: TProteumCommandName[] }> = [
     { title: 'Daily workflow', names: ['dev', 'refresh', 'build'] },
     { title: 'Quality gates', names: ['typecheck', 'lint', 'check', 'e2e'] },
-    { title: 'Manifest and contracts', names: ['connect', 'doctor', 'explain', 'orient', 'diagnose', 'perf', 'trace', 'command', 'session', 'verify'] },
+    { title: 'Manifest and contracts', names: ['connect', 'doctor', 'explain', 'orient', 'diagnose', 'perf', 'runtime', 'mcp', 'trace', 'command', 'session', 'verify'] },
     { title: 'Project scaffolding', names: ['init', 'configure', 'create', 'migrate'] },
 ];
 
@@ -310,16 +312,17 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         name: 'connect',
         category: 'Manifest and contracts',
         summary: 'Inspect connected-project config, cached contracts, and imported controllers.',
-        usage: 'proteum connect [--controllers] [--json] [--strict]',
+        usage: 'proteum connect [--controllers] [--full|--human] [--strict]',
         bestFor:
             'Auditing the current app connect setup without manually stitching together refresh, explain, env inspection, and contract checks.',
         examples: [
-            { description: 'Print a human-readable connected-project summary', command: 'proteum connect' },
+            { description: 'Print a compact connected-project summary', command: 'proteum connect' },
             { description: 'Include imported connected controllers', command: 'proteum connect --controllers' },
-            { description: 'Emit machine-readable connect output', command: 'proteum connect --json' },
+            { description: 'Emit the full connect payload', command: 'proteum connect --full' },
             { description: 'Fail when connect diagnostics exist', command: 'proteum connect --strict' },
         ],
         notes: [
+            'Default output is compact `proteum-agent-v1` JSON.',
             'Proteum refreshes generated typings before reading the connect manifest state.',
             'This command inspects explicit `proteum.config.ts` connected sources and URLs, cached `.proteum/connected/*.json` files, and imported connected controllers.',
             '`--strict` is intended for CI or framework validation when connected contracts must be present and usable.',
@@ -330,27 +333,31 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         name: 'doctor',
         category: 'Manifest and contracts',
         summary: 'Inspect the generated Proteum manifest diagnostics.',
-        usage: 'proteum doctor [--contracts] [--json] [--strict]',
+        usage: 'proteum doctor [--contracts] [--full|--human] [--strict]',
         bestFor:
             'Auditing manifest warnings and errors, especially in CI or when route/controller generation behaves unexpectedly.',
         examples: [
-            { description: 'Print a human-readable diagnostic summary', command: 'proteum doctor' },
+            { description: 'Print a compact diagnostic summary', command: 'proteum doctor' },
             { description: 'Inspect missing generated contracts and source files', command: 'proteum doctor --contracts' },
             { description: 'Fail if any diagnostics exist', command: 'proteum doctor --strict' },
-            { description: 'Emit machine-readable diagnostics', command: 'proteum doctor --json' },
+            { description: 'Emit the full diagnostic payload', command: 'proteum doctor --full' },
+        ],
+        notes: [
+            'Default output is compact `proteum-agent-v1` JSON.',
+            '`--strict` is intended for CI and pre-release verification.',
+            '`--contracts` checks manifest-owned source files and expected generated artifacts on disk.',
         ],
-        notes: ['`--strict` is intended for CI and pre-release verification.', '`--contracts` checks manifest-owned source files and expected generated artifacts on disk.'],
         status: 'stable',
     },
     explain: {
         name: 'explain',
         category: 'Manifest and contracts',
         summary: 'Explain the generated Proteum manifest.',
-        usage: 'proteum explain [owner <query>] [--all|--app|--conventions|--env|--connected|--services|--controllers|--commands|--routes|--layouts|--diagnostics] [--json]',
+        usage: 'proteum explain [owner <query>] [--manifest|--full|--human|--all|--app|--conventions|--env|--connected|--services|--controllers|--commands|--routes|--layouts|--diagnostics]',
         bestFor:
-            'Inspecting how source files became generated routes, controllers, commands, layouts, services, and diagnostics without reading compiler internals.',
+            'Inspecting the compact generated-app summary first, then opening selected manifest sections only when needed.',
         examples: [
-            { description: 'Show the default human summary', command: 'proteum explain' },
+            { description: 'Show the default compact agent summary', command: 'proteum explain' },
             {
                 description: 'Inspect generated routes, controllers, and commands together',
                 command: 'proteum explain --routes --controllers --commands',
@@ -360,9 +367,11 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
                 command: 'proteum explain --connected --controllers',
             },
             { description: 'Resolve the most likely manifest owner for a path or file', command: 'proteum explain owner /api/Auth/CurrentUser' },
-            { description: 'Emit the selected manifest sections as JSON', command: 'proteum explain --routes --json' },
+            { description: 'Emit the full manifest only when needed', command: 'proteum explain --manifest' },
         ],
         notes: [
+            'Default output is compact `proteum-agent-v1` JSON because the CLI is optimized for agents.',
+            '`--full`, `--manifest`, or explicit section flags are the escape hatch for large details.',
             'Legacy positional section selection remains supported, for example `proteum explain routes services`.',
             '`proteum explain owner <query>` ranks matching routes, controllers, services, commands, layouts, and diagnostics from the manifest.',
             'Connected projects are emitted from explicit `proteum.config.ts` `connect.<Namespace>.*` values plus the resolved connected contract.',
@@ -373,17 +382,17 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         name: 'orient',
         category: 'Manifest and contracts',
         summary: 'Resolve owners, guidance files, connected boundaries, and next steps before opening code.',
-        usage: 'proteum orient <query> [--port <port>|--url <baseUrl>] [--json]',
+        usage: 'proteum orient <query> [--port <port>|--url <baseUrl>] [--full|--human]',
         bestFor:
             'Starting multi-repo, generated-artifact, or connected-project work with one explicit orientation step instead of guessing the first files to read.',
         examples: [
             { description: 'Orient around a generated controller path', command: 'proteum orient /api/Auth/CurrentUser' },
             { description: 'Orient around a connected namespace or route', command: 'proteum orient Product.Stats.general' },
-            { description: 'Use a running dev server when the local manifest is unavailable', command: 'proteum orient /domains --port 3101 --json' },
+            { description: 'Use a running dev server when the local manifest is unavailable', command: 'proteum orient /domains --port 3101' },
         ],
         notes: [
-            'This command combines manifest owner lookup, local or fallback guidance resolution, connected-boundary hints, and three recommended next commands.',
-            'Use it before reading source when the query might map to generated code, connected imports, or framework-owned files.',
+            'Default output is compact `proteum-agent-v1` JSON with `mustRead`, conditional docs, owner matches, and next commands.',
+            'Use it before reading source when the query might map to generated code, connected imports, framework-owned files, or area instructions.',
             'When `--port` or `--url` is provided, Proteum can read the manifest from a running dev server instead of only from disk.',
         ],
         status: 'experimental',
@@ -392,7 +401,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         name: 'diagnose',
         category: 'Manifest and contracts',
         summary: 'Combine owner lookup, doctor output, contract checks, traces, and server logs into one report.',
-        usage: 'proteum diagnose [<query>] [--hit <path>] [--method <verb>] [--data-json <json>] [--session-email <email>] [--session-role <role>] [--port <port>|--url <baseUrl>] [--json]',
+        usage: 'proteum diagnose [<query>] [--hit <path>] [--method <verb>] [--data-json <json>] [--session-email <email>] [--session-role <role>] [--port <port>|--url <baseUrl>] [--full|--human]',
         bestFor:
             'Collapsing the usual explain + doctor + trace + session + server log loop into one structured debugging pass.',
         examples: [
@@ -401,6 +410,8 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             { description: 'Diagnose an API call with a JSON payload', command: 'proteum diagnose /api/Auth/CurrentUser --hit /api/Auth/CurrentUser --method POST --data-json "{}"' },
         ],
         notes: [
+            'Default output is compact `proteum-agent-v1` JSON and omits raw request events, payloads, and SQL text.',
+            'Use `--full` only when the compact response says lower-level detail is required.',
             'This command talks to the running app over the dev-only diagnostics, trace, and session endpoints.',
             'When `--hit` is omitted, Proteum diagnoses the latest matching request trace if one already exists.',
         ],
@@ -410,7 +421,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         name: 'perf',
         category: 'Manifest and contracts',
         summary: 'Inspect shared performance rollups built from live request traces on a running Proteum dev server.',
-        usage: 'proteum perf [top|request <requestId|path>|compare|memory] [--since <window>] [--baseline <window>] [--target <window>] [--group-by <path|route|controller>] [--limit <n>] [--port <port>|--url <baseUrl>] [--json]',
+        usage: 'proteum perf [top|request <requestId|path>|compare|memory] [--since <window>] [--baseline <window>] [--target <window>] [--group-by <path|route|controller>] [--limit <n>] [--port <port>|--url <baseUrl>] [--full|--human]',
         bestFor:
             'Finding the routes or controllers with the biggest response-time, CPU, SQL, render, and memory impact without manually stitching traces together.',
         examples: [
@@ -426,17 +437,61 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             },
         ],
         notes: [
+            'Default output is compact `proteum-agent-v1` JSON with capped rows and next commands.',
             'Perf data is derived from the same dev-only request trace buffer used by `proteum trace` and the profiler.',
             'Window values accept `1h`, `6h`, `24h`, `today`, `yesterday`, or an ISO timestamp.',
             'Older traces captured before the perf runtime metrics were added may not include CPU or memory deltas.',
         ],
         status: 'experimental',
     },
+    runtime: {
+        name: 'runtime',
+        category: 'Manifest and contracts',
+        summary: 'Inspect the current app manifest, tracked dev sessions, and runtime health in one compact response.',
+        usage: 'proteum runtime status [--session-file <path>] [--full]',
+        bestFor:
+            'Reusing a live dev session and avoiding repeated dev-list, manifest, and health-check commands before request diagnostics.',
+        examples: [
+            { description: 'Resolve the current runtime status', command: 'proteum runtime status' },
+            { description: 'Inspect one explicit session file', command: 'proteum runtime status --session-file var/run/proteum/dev/agents/task.json' },
+        ],
+        notes: [
+            'Default output is compact `proteum-agent-v1` JSON with the selected session, health, and next command.',
+            'Use `--full` to include every tracked session field.',
+        ],
+        status: 'experimental',
+    },
+    mcp: {
+        name: 'mcp',
+        category: 'Manifest and contracts',
+        summary: 'Start a read-only Proteum MCP server for compact agent diagnostics and runtime data.',
+        usage: 'proteum mcp [--cwd <path>] [--url <baseUrl>] [--session-file <path>]',
+        bestFor:
+            'Agent integrations that need repeated low-token access to Proteum manifest, instruction routing, runtime status, trace, perf, diagnose, and log summaries.',
+        examples: [
+            { description: 'Start the MCP server for the current app over stdio', command: 'proteum mcp' },
+            {
+                description: 'Point the MCP server at a running dev server',
+                command: 'proteum mcp --url http://localhost:3101',
+            },
+            {
+                description: 'Resolve runtime data from an explicit tracked session file',
+                command: 'proteum mcp --session-file var/run/proteum/dev/agents/task.json',
+            },
+        ],
+        notes: [
+            '`proteum mcp` is read-only in v1 and does not start/stop dev servers, refresh generated code, write files, or mutate traces.',
+            'Tool and resource payloads are compact single-line `proteum-mcp-v1` JSON for low-token agent reads.',
+            'Use the CLI for reproducible build/dev/check workflows; use MCP for repeated agent reads and progressive detail loading.',
+            'A running `proteum dev` server also exposes the same tool contract at `/__proteum/mcp` for runtime-adjacent access.',
+        ],
+        status: 'experimental',
+    },
     trace: {
         name: 'trace',
         category: 'Manifest and contracts',
         summary: 'Inspect live in-memory request traces from a running Proteum dev server.',
-        usage: 'proteum trace [latest|show <requestId>|requests|arm|export <requestId>] [--port <port>|--url <baseUrl>] [--json]',
+        usage: 'proteum trace [latest|show <requestId>|requests|arm|export <requestId>] [--port <port>|--url <baseUrl>] [--events|--full|--human]',
         bestFor:
             'Debugging route resolution, context creation, SSR payloads, renders, and runtime errors without attaching a debugger.',
         examples: [
@@ -447,6 +502,8 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             { description: 'Target a custom dev base URL directly', command: 'proteum trace latest --url http://127.0.0.1:3010' },
         ],
         notes: [
+            'Default output is compact `proteum-agent-v1` JSON with counts, errors, hot calls, and hot SQL only.',
+            'Use `--events` or `--full` to print the raw event stream, payload summaries, and SQL text.',
             'This command talks to the running app over the dev-only `__proteum/trace` HTTP endpoints.',
             'Traces are stored in a bounded in-memory buffer with payload summarization and sensitive-field redaction.',
             'Use `--port` when the app is not running on the router port declared in `PORT`, or `--url` when the host itself is non-standard.',

package/cli/presentation/devSession.ts

@@ -35,6 +35,7 @@ export const renderDevSession = async ({
                 { label: 'root', value: appRoot },
                 { label: 'router', value: `http://localhost:${routerPort}` },
                 { label: 'hmr', value: `http://localhost:${devEventPort}/__proteum_hmr` },
+                { label: 'mcp', value: `http://localhost:${routerPort}/__proteum/mcp` },
                 ...(connectedProjects && connectedProjects.length > 0
                     ? connectedProjects.map((connectedProject) => ({
                           label: `connect ${connectedProject.namespace}`,
@@ -91,6 +92,7 @@ export const renderServerReadyBanner = async ({
             createElement(Text, { dimColor: true }, `Diagnose /: proteum diagnose / --port ${routerPort}`),
             createElement(Text, { dimColor: true }, `Perf top: proteum perf top --port ${routerPort}`),
             createElement(Text, { dimColor: true }, `Trace latest: proteum trace latest --port ${routerPort}`),
+            createElement(Text, { dimColor: true }, `MCP: ${publicUrl}/__proteum/mcp`),
         );
     });