@stone-js/mcp-dev 0.8.8 → 0.8.10

package/dist/cli.js

@@ -0,0 +1,915 @@
+import { join } from 'node:path';
+import { writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { RuntimeError } from '@stone-js/core';
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+/**
+ * The platform tag the CLI adapter runs under. Re-declared locally (rather than imported) to keep
+ * this package decoupled from `@stone-js/node-cli-adapter`; the value must match the adapter's.
+ */
+const NODE_CONSOLE_PLATFORM = 'node_console';
+/** The default MCP server name when the app declares none. */
+const DEFAULT_MCP_SERVER_NAME = 'stone-mcp-dev';
+/** The default MCP server version. */
+const DEFAULT_MCP_SERVER_VERSION = '0.0.0';
+/**
+ * The default `instructions` advertised to the agent: what this server is and how to use it.
+ */
+const DEFAULT_MCP_INSTRUCTIONS = [
+    'This MCP server exposes the Stone.js framework knowledge to help you build on it.',
+    'Use the `stone_*` tools to look up concepts, modules, best-practices, gaps and documentation',
+    'links before writing Stone.js code, so your answers match the framework\'s actual conventions.',
+    'Any additional tools are provided by the developer for this project.'
+].join(' ');
+
+/* v8 ignore start -- thin filesystem defaults */
+const defaultIo = {
+    exists: (path) => existsSync(path),
+    read: (path) => readFileSync(path, 'utf-8'),
+    write: (path, content) => writeFileSync(path, content, 'utf-8')
+};
+/* v8 ignore stop */
+/**
+ * The `.mcp.json` server entry that launches this dev server.
+ *
+ * It goes through `npx` because `@stone-js/cli` is a project dev dependency: a bare `stone` only
+ * resolves when the CLI is also installed globally, so the entry an agent spawns would fail with
+ * ENOENT on a normal project. `npx` resolves the project-local binary first, and still finds a
+ * global install, so the generated file works either way.
+ *
+ * @param command - The launcher command (defaults to `npx`).
+ * @param args - The launcher arguments (defaults to `stone mcp`).
+ * @returns The MCP server entry.
+ */
+function mcpServerEntry(command = 'npx', args = ['stone', 'mcp']) {
+    return { command, args };
+}
+/**
+ * Merge the `stone` server into an existing `.mcp.json` object without clobbering anything.
+ *
+ * It only adds the `stone` entry when absent, so a developer's own config (other servers, or a
+ * customized `stone` entry) is preserved.
+ *
+ * @param existing - The parsed `.mcp.json` (or undefined when the file does not exist).
+ * @returns The merged config and whether it changed.
+ */
+function mergeMcpJson(existing) {
+    const config = { ...existing };
+    const servers = { ...config.mcpServers };
+    const changed = servers.stone === undefined;
+    if (changed) {
+        servers.stone = mcpServerEntry();
+    }
+    config.mcpServers = servers;
+    return { config, changed };
+}
+/**
+ * Create or update `.mcp.json` at `cwd` so a coding agent discovers this server. Idempotent: it
+ * writes only when the `stone` entry is missing, and never overwrites the rest of the file.
+ *
+ * @param cwd - The project root.
+ * @param io - The filesystem surface (defaults to `node:fs`).
+ * @returns The file path and whether it was written.
+ */
+function initMcpJson(cwd, io = defaultIo) {
+    const file = join(cwd, '.mcp.json');
+    let existing;
+    if (io.exists(file)) {
+        try {
+            existing = JSON.parse(io.read(file));
+        }
+        catch {
+            existing = undefined;
+        }
+    }
+    const { config, changed } = mergeMcpJson(existing);
+    if (changed) {
+        io.write(file, `${JSON.stringify(config, null, 2)}\n`);
+    }
+    return { file, changed };
+}
+/**
+ * Whether a `.mcp.json` exists at `cwd`.
+ *
+ * @param cwd - The project root.
+ * @param io - The filesystem surface (defaults to `node:fs`).
+ * @returns True when the file exists.
+ */
+function hasMcpJson(cwd, io = defaultIo) {
+    return io.exists(join(cwd, '.mcp.json'));
+}
+
+/**
+ * Custom error for the MCP dev module.
+ */
+class McpDevError extends RuntimeError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = 'McpDevError';
+    }
+}
+
+const concepts = [
+    { id: 'continuum', title: 'Continuum Architecture', summary: 'An application is not an artefact but an act: Application = Domain × Context → Resolution. Stone.js IS the context: you write your domain once and the context applies to it at runtime. Focus on your domain during development; choose where to deploy at the end.' },
+    { id: 'domain-vs-context', title: 'Domain vs Context', summary: 'The domain is your business logic (handlers, services). The context is the execution environment (HTTP, CLI, browser, edge, MCP). Stone.js owns the context so a single domain runs in any of them — backend, frontend, and mobile later.' },
+    { id: 'blueprint', title: 'Blueprint (Setup)', summary: 'A single configuration manifest built once before any event, by introspecting decorators or via imperative meta-modules. All configuration lives under dotted `stone.*` keys.' },
+    { id: 'kernel', title: 'Kernel (Initialization)', summary: 'Applies the container (an ephemeral per-event execution context) and the domain to the intention; runs middleware, hooks and error handlers. The micro-kernel depends only on pipeline, service-container and config.' },
+    { id: 'adapter', title: 'Adapter (Integration)', summary: 'One package per platform. Captures raw causes, normalises them into intentions (IncomingEvent), and turns responses back into native effects. The adapter is the only long-lived, shared, launched-once thing.' },
+    { id: 'ephemeral-context', title: 'Ephemeral per-request context', summary: 'Each request creates a fresh container (a new ephemeral context) via the kernel — totally isolated, never shared between requests. App-lifetime state belongs in a shared scope (a module-level singleton, a cache, or the adapter), not the container.' },
+    { id: 'two-paradigms', title: 'Two paradigms at parity', summary: 'Declarative (TC39 stage-3 decorators, Symbol.metadata) and imperative (define* helpers → meta-modules). Both are first-class and 1:1. Three forms everywhere: class, factory, function (the function form never receives the container).' },
+    { id: 'service-container', title: 'Service container (DI)', summary: 'A Proxy-based container whose `get` auto-wires dependencies from a destructured constructor (`constructor ({ logger, telemetry })`). Register services as class, factory (singleton optional), never the function form for providers.' },
+    { id: 'service-provider', title: 'Service provider', summary: 'Registers services/bindings into the container during kernel init. Modules contribute providers via their blueprint; nothing depends back on the core (micro-kernel).' },
+    { id: 'middleware', title: 'Middleware & hooks', summary: 'A chain-of-responsibility pipeline wraps event handling (global > local priority). Lifecycle hooks (onInit, onEvent, onTerminate, …) let modules observe the flow without coupling.' }
+];
+const modules = [
+    { package: '@stone-js/pipeline', summary: 'Chain-of-responsibility primitive.', tier: 'primitive' },
+    { package: '@stone-js/service-container', summary: 'Proxy-based dependency-injection container.', tier: 'primitive' },
+    { package: '@stone-js/config', summary: 'Dotted-key blueprint store.', tier: 'primitive' },
+    { package: '@stone-js/core', summary: 'The micro-kernel: blueprint, kernel, adapter base, lifecycle.', tier: 'core' },
+    { package: '@stone-js/http-core', summary: 'Runtime-agnostic HTTP primitives (events, responses, cookies).', tier: 'crosscutting' },
+    { package: '@stone-js/router', summary: 'Universal router (node & browser).', tier: 'crosscutting' },
+    { package: '@stone-js/env', summary: 'Environment access with masking.', tier: 'crosscutting' },
+    { package: '@stone-js/filesystem', summary: 'Filesystem + file abstractions.', tier: 'crosscutting' },
+    { package: '@stone-js/cache', summary: 'Platform-agnostic caching with pluggable stores.', tier: 'crosscutting' },
+    { package: '@stone-js/cloud-file', summary: 'Cloud object-storage drivers extending the filesystem abstractions.', tier: 'crosscutting' },
+    { package: '@stone-js/i18n', summary: 'Runtime localization and translation services.', tier: 'crosscutting' },
+    { package: '@stone-js/queue', summary: 'Background job queues with pluggable drivers.', tier: 'crosscutting' },
+    { package: '@stone-js/realtime', summary: 'Realtime channels, rooms and presence.', tier: 'crosscutting' },
+    { package: '@stone-js/browser-core', summary: 'Browser-side primitives.', tier: 'crosscutting' },
+    { package: '@stone-js/node-http-adapter', summary: 'Node HTTP server adapter.', tier: 'adapter' },
+    { package: '@stone-js/node-cli-adapter', summary: 'Node CLI adapter.', tier: 'adapter' },
+    { package: '@stone-js/aws-lambda-adapter', summary: 'Generic AWS Lambda adapter.', tier: 'adapter' },
+    { package: '@stone-js/aws-lambda-http-adapter', summary: 'AWS Lambda HTTP (API GW v1/v2, ALB) adapter.', tier: 'adapter' },
+    { package: '@stone-js/browser-adapter', summary: 'Browser SPA adapter.', tier: 'adapter' },
+    { package: '@stone-js/fetch-adapter', summary: 'Web-standard (WinterCG) adapter: one build → Cloudflare/Deno/Bun/Vercel/Netlify edge.', tier: 'adapter' },
+    { package: '@stone-js/use-react', summary: 'React view engine (CSR/SSR/SSG).', tier: 'frontend' },
+    { package: '@stone-js/use-view', summary: 'Agnostic view-engine layer.', tier: 'frontend' },
+    { package: '@stone-js/telemetry', summary: 'Spans/counters/gauges via hooks + middleware, pluggable exporters.', tier: 'extension' },
+    { package: '@stone-js/validation', summary: 'One schema (Zod/Standard Schema) validated backend AND frontend.', tier: 'extension' },
+    { package: '@stone-js/auth', summary: 'Edge-native, stateless JWT/OAuth (jose).', tier: 'extension' },
+    { package: '@stone-js/authz', summary: 'Isomorphic RBAC+ABAC authorization (CASL).', tier: 'extension' },
+    { package: '@stone-js/resources', summary: 'API resources: shape the exposed output, decoupled from controllers.', tier: 'extension' },
+    { package: '@stone-js/openapi', summary: 'Derive an OpenAPI contract from Zod schemas + routes.', tier: 'extension' },
+    { package: '@stone-js/testing', summary: 'Boot an app in-memory and dispatch events through the kernel.', tier: 'extension' },
+    { package: '@stone-js/mcp-dev', summary: 'Serve the framework knowledge + your tools to a coding agent via `stone mcp` (MCP, stdio).', tier: 'tooling' },
+    { package: '@stone-js/cli', summary: 'Build tooling (Rollup+Babel backend, Vite+Babel frontend, codegen).', tier: 'tooling' },
+    { package: '@stone-js/create', summary: 'Scaffolder: npm create @stone-js.', tier: 'tooling' }
+];
+const bestPractices = [
+    { rule: 'Keep every module core platform-agnostic (no window/process/fs); add platform drivers/adapters around it.', why: 'A single domain must run backend, frontend and (later) mobile.' },
+    { rule: 'Use TC39 stage-3 decorators (Symbol.metadata). Never enable experimentalDecorators or reflect-metadata.', why: 'Setting experimentalDecorators flips esbuild/tsc to legacy decorators and breaks method decorators; the CLI builds with Babel stage-3.' },
+    { rule: 'Configure everything via dotted stone.* keys on the blueprint.', why: 'One uniform, introspectable configuration surface.' },
+    { rule: 'Expose class, factory and function forms; the function form never receives the container.', why: 'Two paradigms at parity, DI only where it makes sense.' },
+    { rule: 'Private/protected constructor + static create().', why: 'Controlled construction across the framework.' },
+    { rule: 'Declare internal @stone-js/* deps as workspace:* in the monorepo.', why: 'Avoids resolving stale published versions (a real source of breakage).' },
+    { rule: 'Put app-lifetime state in a shared scope (module-level singleton, cache, adapter), never in the per-request container.', why: 'The container is a fresh ephemeral context per request — it cannot and must not persist across requests.' },
+    { rule: 'Every bug fix earns a behavioural test (not a mock test); target 100% coverage.', why: 'Prove behaviour, not implementation.' },
+    { rule: 'Attach request-scoped state via setMetadataValue/getMetadataValue; the principal via setUserResolver.', why: 'The idiomatic per-event carriers.' }
+];
+const gaps = [
+    { name: 'mail/notifications', status: 'planned', note: 'Multi-channel notifications.' },
+    { name: 'rate-limiting', status: 'planned', note: 'Edge-friendly throttling.' },
+    { name: 'ORM', status: 'missing', note: 'By design: integrate Drizzle/Prisma/Kysely via providers — Stone.js will not ship an ORM.' }
+];
+/**
+ * The single, curated, machine-readable map of Stone.js. Kept concise and accurate so an agent
+ * can consult it in real time instead of scanning every package.
+ */
+const knowledgeBase = {
+    name: 'Stone.js',
+    tagline: 'Focus on your domain. Stone.js is the context. Build once, deploy anywhere.',
+    version: '0.8.0',
+    concepts,
+    modules,
+    bestPractices,
+    gaps
+};
+/**
+ * Find a concept by id (case-insensitive).
+ *
+ * @param id - The concept id.
+ * @returns The concept, or undefined.
+ */
+function getConcept(id) {
+    return knowledgeBase.concepts.find((concept) => concept.id === id.toLowerCase());
+}
+/**
+ * Full-text search across concepts, modules, best-practices and gaps.
+ *
+ * @param query - The search terms.
+ * @returns Matching entries with their kind.
+ */
+function searchKnowledge(query) {
+    const q = query.trim().toLowerCase();
+    if (q.length === 0) {
+        return [];
+    }
+    const results = [];
+    const match = (text) => text.toLowerCase().includes(q);
+    for (const c of knowledgeBase.concepts) {
+        if (match(c.id) || match(c.title) || match(c.summary)) {
+            results.push({ kind: 'concept', title: c.title, text: c.summary });
+        }
+    }
+    for (const m of knowledgeBase.modules) {
+        if (match(m.package) || match(m.summary)) {
+            results.push({ kind: 'module', title: m.package, text: m.summary });
+        }
+    }
+    for (const b of knowledgeBase.bestPractices) {
+        if (match(b.rule) || match(b.why)) {
+            results.push({ kind: 'best-practice', title: b.rule, text: b.why });
+        }
+    }
+    for (const g of knowledgeBase.gaps) {
+        if (match(g.name) || match(g.note)) {
+            results.push({ kind: 'gap', title: g.name, text: g.note });
+        }
+    }
+    return results;
+}
+
+/**
+ * Generates the concise `llms.txt` index (the emerging standard: a short, link-friendly Markdown
+ * map an agent can read in one shot). Serve it at `/llms.txt` from the docs site.
+ *
+ * @param base - The knowledge base (defaults to the built-in one).
+ * @returns The `llms.txt` content.
+ */
+function generateLlmsTxt(base = knowledgeBase) {
+    const concepts = base.concepts.map((c) => `- **${c.title}**: ${c.summary}`).join('\n');
+    const modules = base.modules.map((m) => `- \`${m.package}\` (${m.tier}): ${m.summary}`).join('\n');
+    return `# ${base.name}
+
+> ${base.tagline} (v${base.version})
+
+## Core concepts
+
+${concepts}
+
+## Modules
+
+${modules}
+`;
+}
+/**
+ * Generates the fuller `llms-full.txt` (adds best-practices and known gaps) — the complete brief
+ * for an agent building with Stone.js.
+ *
+ * @param base - The knowledge base (defaults to the built-in one).
+ * @returns The `llms-full.txt` content.
+ */
+function generateLlmsFullTxt(base = knowledgeBase) {
+    const bestPractices = base.bestPractices.map((b) => `- ${b.rule}\n  - Why: ${b.why}`).join('\n');
+    const gaps = base.gaps.map((g) => `- **${g.name}** (${g.status}): ${g.note}`).join('\n');
+    return `${generateLlmsTxt(base)}
+## Best practices
+
+${bestPractices}
+
+## Known gaps (what to reach for a third party or the roadmap)
+
+${gaps}
+`;
+}
+
+/**
+ * The Stone.js framework-knowledge tools served by `stone mcp`. They are registered on the MCP
+ * server automatically; point your coding agent at it and it can query the framework in real time
+ * (concepts, modules, best-practices, gaps) instead of scanning every package.
+ */
+const stoneMcpTools = [
+    {
+        name: 'stone_search',
+        description: 'Search the Stone.js knowledge base (concepts, modules, best-practices, gaps).',
+        inputSchema: {
+            query: z.string().describe('What to look for, matched against concepts, modules, best practices and gaps.')
+        },
+        handler: (args) => searchKnowledge(String(args.query ?? ''))
+    },
+    {
+        name: 'stone_concept',
+        description: 'Explain a core Stone.js concept by id (omit id to list them all).',
+        inputSchema: {
+            id: z.string().optional().describe('The concept id. Omit it to list every concept instead.')
+        },
+        handler: (args) => {
+            const id = String(args.id ?? '');
+            if (id.length === 0) {
+                return knowledgeBase.concepts.map((c) => ({ id: c.id, title: c.title }));
+            }
+            return getConcept(id) ?? { error: `Unknown concept: ${id}` };
+        }
+    },
+    {
+        name: 'stone_modules',
+        description: 'List the Stone.js ecosystem modules and what each does.',
+        handler: () => knowledgeBase.modules
+    },
+    {
+        name: 'stone_best_practices',
+        description: 'List Stone.js conventions and anti-patterns, each with its rationale.',
+        handler: () => knowledgeBase.bestPractices
+    },
+    {
+        name: 'stone_gaps',
+        description: 'List what Stone.js does not (yet) provide, and what to reach for instead.',
+        handler: () => knowledgeBase.gaps
+    },
+    {
+        name: 'stone_brief',
+        description: 'Return the full agent brief (llms-full.txt): concepts, modules, best-practices, gaps.',
+        handler: () => generateLlmsFullTxt()
+    }
+];
+/**
+ * Creates tools that let an agent (or the developer through it) report a bug or request a feature
+ * as a real GitHub issue, straight from the dev loop.
+ *
+ * @param options - The GitHub token and target repository.
+ * @returns The report tools.
+ */
+function createReportTools(options) {
+    const doFetch = options.fetch ?? fetch;
+    const openIssue = async (title, body, label) => {
+        const response = await doFetch(`https://api.github.com/repos/${options.repo}/issues`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${options.token}`,
+                accept: 'application/vnd.github+json',
+                'content-type': 'application/json'
+            },
+            body: JSON.stringify({ title, body, labels: [label] })
+        });
+        if (!response.ok) {
+            return { error: `GitHub API error: ${response.status}` };
+        }
+        const issue = await response.json();
+        return { number: issue.number, url: issue.html_url };
+    };
+    return [
+        {
+            name: 'stone_report_bug',
+            description: 'Open a bug report as a GitHub issue on the Stone.js repository.',
+            inputSchema: {
+                title: z.string().describe('One line naming the defect.'),
+                body: z.string().describe('What happens, what was expected, and how to reproduce it.')
+            },
+            handler: async (args) => await openIssue(String(args.title ?? 'Bug report'), String(args.body ?? ''), 'bug')
+        },
+        {
+            name: 'stone_request_feature',
+            description: 'Open a feature request as a GitHub issue on the Stone.js repository.',
+            inputSchema: {
+                title: z.string().describe('One line naming the feature.'),
+                body: z.string().describe('The problem it solves, and how it should behave.')
+            },
+            handler: async (args) => await openIssue(String(args.title ?? 'Feature request'), String(args.body ?? ''), 'enhancement')
+        }
+    ];
+}
+
+/**
+ * Wrap any handler return value as MCP text content (JSON for structured data).
+ *
+ * @param result - The value a tool handler returned.
+ * @returns The MCP content payload.
+ */
+function toToolContent(result) {
+    const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+    return { content: [{ type: 'text', text }] };
+}
+/**
+ * Create the activity logger. It writes to **stderr** (never stdout, which the stdio transport
+ * reserves for the JSON-RPC protocol); a no-op when `quiet` is set.
+ *
+ * @param quiet - Silence the log.
+ * @returns The logger.
+ */
+function createStderrLogger(quiet = false) {
+    return (message) => {
+        if (!quiet) {
+            process.stderr.write(`${message}\n`);
+        }
+    };
+}
+/**
+ * Resolve the full tool list: the built-in framework-knowledge tools, the optional GitHub report
+ * tools, then the app's own tools.
+ *
+ * @param options - The dev-server options.
+ * @returns The merged tool list.
+ */
+function resolveTools(options) {
+    return [
+        ...stoneMcpTools,
+        ...(options.report !== undefined ? createReportTools(options.report) : []),
+        ...(options.tools ?? [])
+    ];
+}
+/**
+ * Build the SDK callback for one tool: log the call to stderr, run the handler, log the outcome,
+ * and wrap the result (or the error) as MCP content.
+ *
+ * @param tool - The tool definition.
+ * @param log - The activity logger.
+ * @returns The SDK tool callback.
+ */
+function createToolCallback(tool, log) {
+    return async (args) => {
+        const input = args ?? {};
+        log(`→ ${tool.name}(${JSON.stringify(input)})`);
+        try {
+            const result = await tool.handler(input);
+            log(`← ${tool.name} ok`);
+            return toToolContent(result);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            log(`← ${tool.name} error: ${message}`);
+            return { ...toToolContent({ error: message }), isError: true };
+        }
+    };
+}
+/**
+ * Build a fully-configured MCP server: advertise the instructions and register every resolved tool
+ * with its logging callback. The handlers run in-process (dev/knowledge helpers, not the domain).
+ *
+ * @param options - The dev-server options.
+ * @param log - The activity logger.
+ * @returns The configured MCP server.
+ */
+function buildMcpServer(options, log) {
+    const server = new McpServer({ name: options.name ?? DEFAULT_MCP_SERVER_NAME, version: options.version ?? DEFAULT_MCP_SERVER_VERSION }, { instructions: options.instructions ?? DEFAULT_MCP_INSTRUCTIONS });
+    for (const tool of resolveTools(options)) {
+        // A tool with no schema is registered with none at all, rather than with an empty one: both are
+        // advertised as taking no arguments, but the empty shape reads like a declared contract when it
+        // is the absence of one.
+        server.registerTool(tool.name, { description: tool.description, inputSchema: tool.inputSchema }, createToolCallback(tool, log));
+    }
+    return server;
+}
+/**
+ * Start the MCP dev server over stdio and keep it alive until the process is interrupted.
+ *
+ * The stdio transport speaks JSON-RPC on stdout and keeps the event loop alive by reading stdin,
+ * so `Ctrl+C` (SIGINT) stops it, exactly like `stone dev`.
+ *
+ * @param options - The dev-server options.
+ */
+/* v8 ignore start -- process lifecycle: stdio transport + signal handling, not unit-testable */
+async function startMcpDevServer(options) {
+    const log = createStderrLogger(options.quiet);
+    const server = buildMcpServer(options, log);
+    const transport = new StdioServerTransport();
+    const shutdown = () => {
+        log('mcp: shutting down');
+        void server.close().finally(() => process.exit(0));
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+    if (!hasMcpJson(process.cwd())) {
+        log('mcp: no .mcp.json found — run `stone mcp --init` to register this server for your agent');
+    }
+    await server.connect(transport);
+    log(`mcp: ${resolveTools(options).length} tools ready on stdio — press Ctrl+C to stop`);
+}
+/* v8 ignore stop */
+
+/** Where a running application leaves its resolved configuration for the MCP server to read. */
+const APP_CONTEXT_FILE = join('.stone', 'app-context.json');
+/**
+ * Read what a running application published, if it published anything.
+ *
+ * @param cwd - The project root.
+ * @returns The context, or `undefined` when no application has run.
+ */
+function readAppContext(cwd = process.cwd()) {
+    const path = join(cwd, APP_CONTEXT_FILE);
+    if (!existsSync(path)) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        // A half-written or hand-edited file is not worth failing the whole MCP server for: the tools
+        // fall back to what the console boot knows, and say so.
+        return undefined;
+    }
+}
+/**
+ * A reader over a published context, answering the same dotted keys a blueprint answers.
+ *
+ * @param context - The published context.
+ * @returns The reader.
+ */
+function contextReader(context) {
+    return {
+        get: (key, fallback) => {
+            const value = key.split('.').reduce((current, segment) => (typeof current === 'object' && current !== null)
+                ? current[segment]
+                : undefined, { stone: context.stone });
+            return (value ?? fallback);
+        }
+    };
+}
+
+/** Keys whose values are redacted from any config dump (env secrets, credentials). */
+const SECRET_KEY = /(secret|token|password|passwd|api[_-]?key|credential|private|passphrase|auth)/i;
+/** How deep {@link sanitize} walks before bailing out. */
+const MAX_DEPTH = 6;
+/**
+ * Best-effort name of a module reference (class, function, or meta-module `{ module }`).
+ *
+ * @param value - The reference to name.
+ * @returns The resolved name.
+ */
+function moduleName(value) {
+    if (value === undefined || value === null) {
+        return 'unknown';
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'function') {
+        return value.name.length > 0 ? value.name : 'anonymous';
+    }
+    if (typeof value === 'object') {
+        const meta = value;
+        if (meta.module !== undefined) {
+            return moduleName(meta.module);
+        }
+        if (typeof meta.name === 'string') {
+            return meta.name;
+        }
+    }
+    return 'unknown';
+}
+/**
+ * Produce a JSON-safe, secret-redacted copy of a config value: functions/classes become a label,
+ * `RegExp` its source, secret-looking keys `[redacted]`, and recursion is depth-capped.
+ *
+ * @param value - The value to sanitize.
+ * @param depth - The current recursion depth.
+ * @returns A serializable value.
+ */
+function sanitize(value, depth = 0) {
+    if (depth > MAX_DEPTH) {
+        return '[max-depth]';
+    }
+    if (value === undefined || value === null) {
+        return value;
+    }
+    if (typeof value === 'function') {
+        return `[Function: ${value.name.length > 0 ? value.name : 'anonymous'}]`;
+    }
+    if (value instanceof RegExp) {
+        return value.toString();
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitize(item, depth + 1));
+    }
+    if (typeof value === 'object') {
+        const out = {};
+        for (const [key, val] of Object.entries(value)) {
+            out[key] = SECRET_KEY.test(key) ? '[redacted]' : sanitize(val, depth + 1);
+        }
+        return out;
+    }
+    return value;
+}
+/** Remove `undefined` and empty arrays from an object, so tool output stays terse. */
+function clean(obj) {
+    const out = {};
+    for (const [key, val] of Object.entries(obj)) {
+        if (val === undefined) {
+            continue;
+        }
+        if (Array.isArray(val) && val.length === 0) {
+            continue;
+        }
+        out[key] = val;
+    }
+    return out;
+}
+/** Map a route definition (and its children) to a terse, serializable shape. */
+function mapRoute(def) {
+    const methods = def.methods ?? (def.method !== undefined ? [def.method] : undefined);
+    const children = def.children ?? [];
+    const middleware = def.middleware ?? [];
+    return clean({
+        name: def.name,
+        methods,
+        path: def.path,
+        handler: def.handler !== undefined ? moduleName(def.handler) : undefined,
+        middleware: middleware.map(moduleName),
+        children: children.map(mapRoute)
+    });
+}
+/** Count routes across the definition tree. */
+function countRoutes(defs) {
+    return defs.reduce((total, def) => {
+        const children = def.children ?? [];
+        return total + 1 + countRoutes(children);
+    }, 0);
+}
+/**
+ * What the tools are describing, and how they know.
+ *
+ * The MCP server is a console command, so the blueprint it holds is the one a *console* boot resolves:
+ * its adapter, its response type and every platform-conditional contribution belong to a different
+ * application than the one running under `stone dev`. When the running application has published its
+ * own configuration, that is the better answer and it is used; otherwise the console boot still
+ * answers for everything platform-independent — routes, providers, the kernel handler — and says which
+ * of its answers not to trust, rather than pretending to be the running app.
+ *
+ * @param blueprint - The blueprint of the process the MCP server runs in.
+ * @param cwd - The project root.
+ * @returns The reader to introspect, and a description of it.
+ */
+function resolveSource(blueprint, cwd) {
+    const published = readAppContext(cwd);
+    if (published === undefined) {
+        return {
+            source: blueprint,
+            describes: {
+                source: 'console-boot',
+                platform: blueprint.get('stone.adapter.platform'),
+                accurate: ['stone_routes', 'stone_commands', 'stone_providers', 'stone_kernel', 'stone_key_routes'],
+                unreliable: ['stone_adapters', 'stone_config'],
+                why: 'No running application has published its configuration, so this describes what a console ' +
+                    'boot resolves. Anything platform-dependent therefore belongs to the console platform, not ' +
+                    'to the application you are running. Install `@stone-js/mcp-dev` as a devDependency and run ' +
+                    `the app once (\`stone dev\`): the build injects a publisher that writes ${APP_CONTEXT_FILE}, ` +
+                    'and these tools then describe that application.'
+            }
+        };
+    }
+    return {
+        source: contextReader(published),
+        describes: {
+            source: 'running-app',
+            platform: published.platform,
+            env: published.env,
+            name: published.name,
+            file: APP_CONTEXT_FILE,
+            why: 'This describes the application that actually ran, as it resolved itself: its platform, its ' +
+                'adapters and its configuration. Values that change after boot, such as a `live` ' +
+                'configuration, are as of that boot.'
+        }
+    };
+}
+/**
+ * Build the read-only introspection tools bound to the app's resolved blueprint.
+ *
+ * These expose what the app actually declares (routes, commands, adapters, providers, kernel
+ * pipeline, config) so a coding agent understands *this* app, not just the framework. They read
+ * only, never mutate, and redact secret-looking config values.
+ *
+ * @param blueprint - The resolved application blueprint.
+ * @returns The introspection tools.
+ */
+function createIntrospectionTools(blueprint, cwd) {
+    const { source, describes } = resolveSource(blueprint, cwd);
+    const routes = () => source.get('stone.router.definitions', []);
+    const commands = () => source.get('stone.adapter.commands', []);
+    return [
+        {
+            name: 'stone_describes',
+            description: 'Say which application the introspection tools are describing, and how they know.',
+            handler: () => describes
+        },
+        {
+            name: 'stone_app',
+            description: 'Summarize the current Stone.js app: name, env, active platform, and counts of routes/commands/providers/adapters.',
+            handler: () => clean({
+                name: source.get('stone.name'),
+                env: source.get('stone.env'),
+                platform: source.get('stone.adapter.platform'),
+                counts: {
+                    routes: countRoutes(routes()),
+                    commands: commands().length,
+                    providers: source.get('stone.providers', []).length,
+                    adapters: source.get('stone.adapters', []).length
+                }
+            })
+        },
+        {
+            name: 'stone_routes',
+            description: 'List the app\'s routes (path, methods, name, handler, middleware) as declared on the router.',
+            handler: () => routes().map(mapRoute)
+        },
+        {
+            name: 'stone_commands',
+            description: 'List the app\'s CLI commands (name, alias, args, description).',
+            handler: () => commands().map((c) => clean({
+                name: c.options?.name,
+                alias: c.options?.alias,
+                args: c.options?.args,
+                desc: c.options?.desc
+            }))
+        },
+        {
+            name: 'stone_adapters',
+            description: 'List the registered adapters (platform, alias, default/current) and the active platform.',
+            handler: () => ({
+                active: source.get('stone.adapter.platform'),
+                adapters: source.get('stone.adapters', []).map((a) => clean({
+                    platform: a.platform,
+                    alias: a.alias,
+                    current: a.current,
+                    default: a.default
+                }))
+            })
+        },
+        {
+            name: 'stone_providers',
+            description: 'List the app\'s service providers.',
+            handler: () => source.get('stone.providers', []).map(moduleName)
+        },
+        {
+            name: 'stone_kernel',
+            description: 'Show the kernel pipeline: the event handler, middleware, and registered error handlers.',
+            handler: () => {
+                const kernel = source.get('stone.kernel', {});
+                return clean({
+                    eventHandler: kernel.eventHandler !== undefined ? moduleName(kernel.eventHandler) : undefined,
+                    middleware: (kernel.middleware ?? []).map(moduleName),
+                    errorHandlers: Object.keys(kernel.errorHandlers ?? {})
+                });
+            }
+        },
+        {
+            name: 'stone_key_routes',
+            description: 'List the key-routing definitions (event-bus / realtime / keyed events): key to handler.',
+            handler: () => source.get('stone.keyRouting.definitions', []).map((d) => clean({
+                key: d.key,
+                action: d.action,
+                handler: d.module !== undefined ? moduleName(d.module) : undefined
+            }))
+        },
+        {
+            name: 'stone_config',
+            description: 'Read a resolved config value by dotted key under `stone.*` (secrets redacted). Omit `key` to list the top-level `stone` keys.',
+            inputSchema: {
+                key: z.string().optional().describe('A dotted key such as `stone.router`. Omit it to list the top-level `stone` keys instead.')
+            },
+            handler: (args) => {
+                const key = String(args.key ?? '');
+                if (key.length === 0) {
+                    return Object.keys(source.get('stone', {}));
+                }
+                return sanitize(source.get(key));
+            }
+        }
+    ];
+}
+
+/**
+ * Configuration for the `mcp` command.
+ */
+const mcpCommandOptions = {
+    name: 'mcp',
+    alias: 'm',
+    desc: 'Start an MCP server (stdio) exposing Stone.js knowledge + your app + your tools to a coding agent',
+    options: (yargs) => {
+        return yargs
+            .option('init', { type: 'boolean', desc: 'Register this server in .mcp.json (create/merge) and exit' })
+            .option('name', { type: 'string', desc: 'Override the MCP server name' })
+            .option('quiet', { type: 'boolean', desc: 'Silence the stderr activity log' });
+    }
+};
+/**
+ * Starts the MCP dev server from the `stone mcp` command.
+ *
+ * It reads `stone.mcpDev` from the blueprint (server name, instructions, your tools) and lets the
+ * MCP SDK own the protocol and tool execution: framework knowledge helpers do not need to traverse
+ * the kernel. `--name` / `--quiet` flags override the configured values.
+ */
+class McpCommand {
+    container;
+    /**
+     * @param container - The dependency injection container.
+     * @throws {McpDevError} If the container is not provided.
+     */
+    constructor(container) {
+        this.container = container;
+        if (container === undefined) {
+            throw new McpDevError('Container is required to create a McpCommand instance.');
+        }
+    }
+    /**
+     * Handle the `mcp` command: start the server and keep it running until interrupted.
+     *
+     * @param event - The incoming CLI event carrying the parsed flags.
+     */
+    async handle(event) {
+        const blueprint = this.container.make('blueprint');
+        if (event.getMetadataValue('init', false)) {
+            const { file, changed } = initMcpJson(process.cwd());
+            process.stderr.write(changed ? `mcp: registered this server in ${file}\n` : `mcp: ${file} already registers this server\n`);
+            return;
+        }
+        const options = blueprint.get('stone.builder.mcpDev', {});
+        const name = event.getMetadataValue('name', options.name);
+        const quiet = event.getMetadataValue('quiet', options.quiet ?? false);
+        const tools = [...createIntrospectionTools(blueprint), ...(options.tools ?? [])];
+        await startMcpDevServer({ ...options, name, quiet, tools });
+    }
+}
+
+/**
+ * Register the `mcp` command on the CLI.
+ *
+ * Contributed by the plugin rather than by the application, which is the whole point: introspection is
+ * a development concern, and an application should not have to declare a development tool to get one.
+ * The CLI runs plugin blueprint middleware in its own pipeline, and the CLI is itself a Stone.js app on
+ * the console platform, so the command lands exactly where every other command does.
+ *
+ * @param context - The blueprint context.
+ * @param next - The next middleware.
+ * @returns The blueprint.
+ */
+const SetMcpCommandsMiddleware = async (context, next) => {
+    if (context.blueprint.get('stone.adapter.platform') === NODE_CONSOLE_PLATFORM) {
+        context.blueprint.add('stone.adapter.commands', [{ options: mcpCommandOptions, isClass: true, module: McpCommand }]);
+    }
+    return await next(context);
+};
+/** The blueprint middleware this plugin contributes. */
+const mcpDevPluginMiddleware = [
+    { module: SetMcpCommandsMiddleware, priority: 5 }
+];
+/** Where the plugin writes the module it injects, relative to the build's `.stone/tmp` directory. */
+const GENERATED_MODULE = 'plugins/mcp-dev-context.mjs';
+/** The commands that mean "a developer is working right now", and nothing else. */
+const DEV_COMMANDS = ['dev', 'serve', 'preview'];
+/**
+ * The module injected into a development build.
+ *
+ * It contributes one lifecycle hook, and imports the publishing helper from the package rather than
+ * restating it, so the file format and the redaction rules keep living in one place.
+ *
+ * @returns The generated module's source.
+ */
+function generatedModule() {
+    return [
+        '// Generated by the @stone-js/mcp-dev CLI plugin, for development builds only.',
+        "import { publishAppContext } from '@stone-js/mcp-dev'",
+        '',
+        'export const mcpDevContextBlueprint = {',
+        '  stone: {',
+        '    lifecycleHooks: {',
+        '      onStart: [({ blueprint }) => { try { publishAppContext(blueprint) } catch {} }]',
+        '    }',
+        '  }',
+        '}',
+        ''
+    ].join('\n');
+}
+/**
+ * The MCP dev CLI plugin.
+ *
+ * Introspection is a development concern, so it belongs to the build rather than to the application.
+ * Declaring it in the app would put a development tool in the application's own module graph — and
+ * make a production build depend on a package the application does not need — for a feature nobody
+ * uses in production. The build already knows when a developer is working, which is exactly when this
+ * is wanted, so the build is where it is decided.
+ *
+ * What it does, in one sentence: on a development build it injects a hook that makes the running
+ * application publish its resolved configuration, so `stone mcp` describes **that** application
+ * instead of the console boot it can reach by itself.
+ *
+ * Nothing is injected into a production build, and nothing has to be imported by the app.
+ *
+ * @returns The plugin.
+ */
+function mcpDevCliPlugin() {
+    return {
+        name: '@stone-js/mcp-dev',
+        description: 'Adds `stone mcp`, and lets it introspect the app you are actually running',
+        blueprintMiddleware: mcpDevPluginMiddleware,
+        onPrepare: async (context) => {
+            // Only while developing: a production artifact must carry none of this.
+            if (!DEV_COMMANDS.includes(context.command)) {
+                return;
+            }
+            // The build decides presence, so the build is where turning it off belongs: an application that
+            // opts out gets nothing injected, rather than shipping code that decides not to run.
+            if (!context.blueprint.get('stone.builder.mcpDev.publishContext', true)) {
+                return;
+            }
+            context.writeFile(GENERATED_MODULE, generatedModule());
+            context.addModule(`./${GENERATED_MODULE}`);
+        }
+    };
+}
+/**
+ * A ready-to-use plugin instance, used by first-party `package.json` auto-discovery.
+ */
+const plugin = mcpDevCliPlugin();
+
+export { DEV_COMMANDS, GENERATED_MODULE, SetMcpCommandsMiddleware, plugin as default, generatedModule, mcpDevCliPlugin, mcpDevPluginMiddleware };