@stone-js/mcp-dev 0.8.0

package/dist/index.js

@@ -0,0 +1,786 @@
+import { join } from 'node:path';
+import { writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { RuntimeError, classDecoratorLegacyWrapper, addBlueprint } from '@stone-js/core';
+
+/* 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.
+ *
+ * @param command - The launcher command (defaults to `stone`).
+ * @returns The MCP server entry.
+ */
+function mcpServerEntry(command = 'stone') {
+    return { command, args: ['mcp'] };
+}
+/**
+ * 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'));
+}
+
+const concepts = [
+    { id: 'continuum', title: 'Continuum Architecture', summary: 'An application is not an object 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/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: 'queue/jobs', status: 'planned', note: 'Background jobs (in-memory, Redis/BullMQ, SQS, Cloud Tasks).' },
+    { name: 'cache', status: 'planned', note: 'Agnostic cache (memory, Redis, CF KV) — the legitimate shared scope.' },
+    { name: 'mail/notifications', status: 'planned', note: 'Multi-channel notifications.' },
+    { name: 'rate-limiting', status: 'planned', note: 'Edge-friendly throttling.' },
+    { name: 'i18n', status: 'planned', note: 'Runtime localization.' },
+    { name: 'websocket/realtime', status: 'planned', note: 'Channels/rooms/presence, agnostic drivers.' },
+    { name: 'cloud file drivers', status: 'planned', note: 'S3/R2/GCS drivers extending @stone-js/filesystem.' },
+    { 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).',
+        handler: (args) => searchKnowledge(String(args.query ?? ''))
+    },
+    {
+        name: 'stone_concept',
+        description: 'Explain a core Stone.js concept by id (omit id to list them all).',
+        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.',
+            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.',
+            handler: async (args) => await openIssue(String(args.title ?? 'Feature request'), String(args.body ?? ''), 'enhancement')
+        }
+    ];
+}
+
+/**
+ * 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(' ');
+
+/**
+ * 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)) {
+        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 */
+
+/** 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);
+}
+/**
+ * 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) {
+    const routes = () => blueprint.get('stone.router.definitions', []);
+    const commands = () => blueprint.get('stone.adapter.commands', []);
+    return [
+        {
+            name: 'stone_app',
+            description: 'Summarize the current Stone.js app: name, env, active platform, and counts of routes/commands/providers/adapters.',
+            handler: () => clean({
+                name: blueprint.get('stone.name'),
+                env: blueprint.get('stone.env'),
+                platform: blueprint.get('stone.adapter.platform'),
+                counts: {
+                    routes: countRoutes(routes()),
+                    commands: commands().length,
+                    providers: blueprint.get('stone.providers', []).length,
+                    adapters: blueprint.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: blueprint.get('stone.adapter.platform'),
+                adapters: blueprint.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: () => blueprint.get('stone.providers', []).map(moduleName)
+        },
+        {
+            name: 'stone_kernel',
+            description: 'Show the kernel pipeline: the event handler, middleware, and registered error handlers.',
+            handler: () => {
+                const kernel = blueprint.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: () => blueprint.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.',
+            handler: (args) => {
+                const key = String(args.key ?? '');
+                if (key.length === 0) {
+                    return Object.keys(blueprint.get('stone', {}));
+                }
+                return sanitize(blueprint.get(key));
+            }
+        }
+    ];
+}
+
+/**
+ * Custom error for the MCP dev module.
+ */
+class McpDevError extends RuntimeError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = 'McpDevError';
+    }
+}
+
+/**
+ * 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.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 });
+    }
+}
+
+/**
+ * Middleware that registers the `mcp` command when the app runs on the Node CLI adapter.
+ *
+ * It mirrors the router's command registration: contribute a `MetaCommandHandler` to
+ * `stone.adapter.commands` so the CLI (itself a Stone.js app on the Node CLI adapter) discovers
+ * `stone mcp` by introspection, no hard-coding.
+ *
+ * @param context - The blueprint context.
+ * @param next - The next pipeline function.
+ * @returns The updated 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 contributed by the MCP dev module.
+ */
+const metaMcpDevBlueprintMiddleware = [
+    { module: SetMcpCommandsMiddleware, priority: 5 }
+];
+
+/**
+ * Opt-in blueprint: import and register it to add the `stone mcp` command.
+ *
+ * It contributes a blueprint middleware that registers the command on the Node CLI adapter. Add
+ * your own tools and the server name/instructions under `stone.mcpDev` (or via `@McpDev()` /
+ * `defineMcpDev()`).
+ */
+const mcpDevBlueprint = {
+    stone: {
+        blueprint: {
+            middleware: metaMcpDevBlueprintMiddleware
+        },
+        mcpDev: {
+            tools: []
+        }
+    }
+};
+/**
+ * Imperative helper: build an MCP dev blueprint with the given options.
+ *
+ * @param options - The MCP dev options (server name, instructions, your tools, report tools).
+ * @returns The blueprint to register in your app.
+ */
+function defineMcpDev(options = {}) {
+    return {
+        stone: {
+            blueprint: {
+                middleware: metaMcpDevBlueprintMiddleware
+            },
+            mcpDev: options
+        }
+    };
+}
+
+/**
+ * A class decorator that adds the `stone mcp` command to your app.
+ *
+ * Declarative counterpart of registering {@link mcpDevBlueprint}: apply it to your app class to
+ * expose the framework-knowledge tools (plus any you declare) to a coding agent over MCP.
+ *
+ * @param options - The MCP dev options (server name, instructions, your tools).
+ * @returns A class decorator.
+ *
+ * @example
+ * ```typescript
+ * @McpDev({ tools: [myTool] })
+ * @StoneApp({ name: 'my-app' })
+ * export class Application {}
+ * ```
+ */
+const McpDev = (options = {}) => {
+    return classDecoratorLegacyWrapper((target, context) => {
+        addBlueprint(target, context, mcpDevBlueprint, { stone: { mcpDev: options } });
+    });
+};
+
+export { DEFAULT_MCP_INSTRUCTIONS, DEFAULT_MCP_SERVER_NAME, DEFAULT_MCP_SERVER_VERSION, McpCommand, McpDev, McpDevError, NODE_CONSOLE_PLATFORM, SetMcpCommandsMiddleware, buildMcpServer, createIntrospectionTools, createReportTools, createStderrLogger, createToolCallback, defineMcpDev, generateLlmsFullTxt, generateLlmsTxt, getConcept, hasMcpJson, initMcpJson, knowledgeBase, mcpCommandOptions, mcpDevBlueprint, mcpServerEntry, mergeMcpJson, metaMcpDevBlueprintMiddleware, moduleName, resolveTools, sanitize, searchKnowledge, startMcpDevServer, stoneMcpTools, toToolContent };