@stone-js/mcp-dev 0.8.7 → 0.8.9

package/dist/commands/McpCommand.d.ts

@@ -1,5 +1,5 @@
 import { IContainer, IncomingEvent } from '@stone-js/core';
-import { CommandOptions } from '../declarations';
+import { CommandOptions } from '../declarations.js';
 /**
  * Configuration for the `mcp` command.
  */

package/dist/declarations.d.ts

@@ -1,3 +1,4 @@
+import type { ZodRawShape } from 'zod';
 /** A core architectural concept of Stone.js. */
 export interface Concept {
     /** Slug id (e.g. `continuum`). */
@@ -50,7 +51,14 @@ export interface KnowledgeBase {
 export interface McpToolDef {
     name: string;
     description?: string;
-    inputSchema?: Record<string, unknown>;
+    /**
+     * The arguments the tool accepts, as a Zod shape (`{ query: z.string() }`).
+     *
+     * Required for any tool whose handler reads `args`: a tool that publishes no schema is advertised
+     * as taking none, and an MCP client drops the arguments before sending them, so the handler runs
+     * with `{}` and there is no error anywhere to say so.
+     */
+    inputSchema?: ZodRawShape;
     handler: (args: Record<string, unknown>) => unknown;
 }
 /**
@@ -112,4 +120,11 @@ export interface McpDevOptions {
     report?: ReportToolsOptions;
     /** Silence the stderr activity log. */
     quiet?: boolean;
+    /**
+     * Whether a running application publishes its resolved configuration for the MCP server to read.
+     *
+     * Defaults to on outside production. It is what lets `stone mcp` describe the application actually
+     * running rather than the one the console command boots, so leave it on while developing.
+     */
+    publishContext?: boolean;
 }

package/dist/index.d.ts

@@ -1,13 +1,11 @@
-export * from './McpDevServer';
-export * from './commands/McpCommand';
-export * from './constants';
-export * from './declarations';
-export * from './decorators/McpDev';
-export * from './errors/McpDevError';
-export * from './introspection';
-export * from './knowledge';
-export * from './llms';
-export * from './mcpJson';
-export * from './middleware/BlueprintMiddleware';
-export * from './options/McpDevBlueprint';
-export * from './tools';
+export * from './McpDevServer.js';
+export * from './appContext.js';
+export * from './commands/McpCommand.js';
+export * from './constants.js';
+export * from './declarations.js';
+export * from './errors/McpDevError.js';
+export * from './introspection.js';
+export * from './knowledge.js';
+export * from './llms.js';
+export * from './mcpJson.js';
+export * from './tools.js';

package/dist/index.js

@@ -1,8 +1,9 @@
-import { join } from 'node:path';
-import { writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { RuntimeError, classDecoratorLegacyWrapper, addBlueprint } from '@stone-js/core';
+import { RuntimeError } from '@stone-js/core';
 
 /* v8 ignore start -- thin filesystem defaults */
 const defaultIo = {
@@ -14,11 +15,17 @@ const defaultIo = {
 /**
  * The `.mcp.json` server entry that launches this dev server.
  *
- * @param command - The launcher command (defaults to `stone`).
+ * 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 = 'stone') {
-    return { command, args: ['mcp'] };
+function mcpServerEntry(command = 'npx', args = ['stone', 'mcp']) {
+    return { command, args };
 }
 /**
  * Merge the `stone` server into an existing `.mcp.json` object without clobbering anything.
@@ -96,6 +103,11 @@ const modules = [
     { 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' },
@@ -128,13 +140,8 @@ const bestPractices = [
     { 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.' }
 ];
 /**
@@ -248,11 +255,17 @@ 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) {
@@ -311,11 +324,19 @@ function createReportTools(options) {
         {
             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')
         }
     ];
@@ -413,7 +434,10 @@ function createToolCallback(tool, log) {
 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));
+        // 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;
 }
@@ -543,6 +567,52 @@ function countRoutes(defs) {
         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.
  *
@@ -553,22 +623,28 @@ function countRoutes(defs) {
  * @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', []);
+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: blueprint.get('stone.name'),
-                env: blueprint.get('stone.env'),
-                platform: blueprint.get('stone.adapter.platform'),
+                name: source.get('stone.name'),
+                env: source.get('stone.env'),
+                platform: source.get('stone.adapter.platform'),
                 counts: {
                     routes: countRoutes(routes()),
                     commands: commands().length,
-                    providers: blueprint.get('stone.providers', []).length,
-                    adapters: blueprint.get('stone.adapters', []).length
+                    providers: source.get('stone.providers', []).length,
+                    adapters: source.get('stone.adapters', []).length
                 }
             })
         },
@@ -591,8 +667,8 @@ function createIntrospectionTools(blueprint) {
             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({
+                active: source.get('stone.adapter.platform'),
+                adapters: source.get('stone.adapters', []).map((a) => clean({
                     platform: a.platform,
                     alias: a.alias,
                     current: a.current,
@@ -603,13 +679,13 @@ function createIntrospectionTools(blueprint) {
         {
             name: 'stone_providers',
             description: 'List the app\'s service providers.',
-            handler: () => blueprint.get('stone.providers', []).map(moduleName)
+            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 = blueprint.get('stone.kernel', {});
+                const kernel = source.get('stone.kernel', {});
                 return clean({
                     eventHandler: kernel.eventHandler !== undefined ? moduleName(kernel.eventHandler) : undefined,
                     middleware: (kernel.middleware ?? []).map(moduleName),
@@ -620,7 +696,7 @@ function createIntrospectionTools(blueprint) {
         {
             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({
+            handler: () => source.get('stone.keyRouting.definitions', []).map((d) => clean({
                 key: d.key,
                 action: d.action,
                 handler: d.module !== undefined ? moduleName(d.module) : undefined
@@ -629,17 +705,91 @@ function createIntrospectionTools(blueprint) {
         {
             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(blueprint.get('stone', {}));
+                    return Object.keys(source.get('stone', {}));
                 }
-                return sanitize(blueprint.get(key));
+                return sanitize(source.get(key));
             }
         }
     ];
 }
 
+/** Where a running application leaves its resolved configuration for the MCP server to read. */
+const APP_CONTEXT_FILE = join('.stone', 'app-context.json');
+/**
+ * Publish an application's resolved configuration.
+ *
+ * This is what makes `stone mcp` describe the application a developer is actually running. The MCP
+ * server is a console command: booting the app itself gives it the *console* platform, so its
+ * adapters, its response type and every platform-conditional contribution belong to a different
+ * application than the one under `stone dev`. The running app knows the truth, so the running app
+ * says it.
+ *
+ * A file rather than an endpoint, deliberately. The Blueprint is the Setup dimension: assembled once
+ * before the first event and then read, so publishing it once at boot is not a snapshot of something
+ * moving — it *is* the value. A file also needs no port to discover, no dev-only route in someone's
+ * application, no token to protect, and it works for a CLI or an edge context that has no HTTP
+ * surface at all. What genuinely moves at run time (a `live` configuration, metrics) is a different
+ * question, and belongs to a different tool.
+ *
+ * @param blueprint - The running application's blueprint.
+ * @param cwd - The project root.
+ * @returns The file it wrote.
+ */
+function publishAppContext(blueprint, cwd = process.cwd()) {
+    const path = join(cwd, APP_CONTEXT_FILE);
+    const context = {
+        platform: blueprint.get('stone.adapter.platform'),
+        env: blueprint.get('stone.env'),
+        name: blueprint.get('stone.name'),
+        stone: sanitize(blueprint.get('stone', {}))
+    };
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(context, null, 2), 'utf-8');
+    return path;
+}
+/**
+ * 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);
+        }
+    };
+}
+
 /**
  * Custom error for the MCP dev module.
  */
@@ -695,7 +845,7 @@ class McpCommand {
             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 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 ?? [])];
@@ -703,84 +853,4 @@ class McpCommand {
     }
 }
 
-/**
- * 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 };
+export { APP_CONTEXT_FILE, DEFAULT_MCP_INSTRUCTIONS, DEFAULT_MCP_SERVER_NAME, DEFAULT_MCP_SERVER_VERSION, McpCommand, McpDevError, NODE_CONSOLE_PLATFORM, buildMcpServer, contextReader, createIntrospectionTools, createReportTools, createStderrLogger, createToolCallback, generateLlmsFullTxt, generateLlmsTxt, getConcept, hasMcpJson, initMcpJson, knowledgeBase, mcpCommandOptions, mcpServerEntry, mergeMcpJson, moduleName, publishAppContext, readAppContext, resolveSource, resolveTools, sanitize, searchKnowledge, startMcpDevServer, stoneMcpTools, toToolContent };

package/dist/introspection.d.ts

@@ -1,5 +1,6 @@
 import { IBlueprint } from '@stone-js/core';
-import { McpToolDef } from './declarations';
+import { McpToolDef } from './declarations.js';
+import { ContextReader } from './appContext.js';
 /**
  * Best-effort name of a module reference (class, function, or meta-module `{ module }`).
  *
@@ -16,6 +17,24 @@ export declare function moduleName(value: unknown): string;
  * @returns A serializable value.
  */
 export declare function sanitize(value: unknown, depth?: number): unknown;
+/**
+ * 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.
+ */
+export declare function resolveSource(blueprint: IBlueprint, cwd?: string): {
+    source: ContextReader;
+    describes: Record<string, unknown>;
+};
 /**
  * Build the read-only introspection tools bound to the app's resolved blueprint.
  *
@@ -26,4 +45,4 @@ export declare function sanitize(value: unknown, depth?: number): unknown;
  * @param blueprint - The resolved application blueprint.
  * @returns The introspection tools.
  */
-export declare function createIntrospectionTools(blueprint: IBlueprint): McpToolDef[];
+export declare function createIntrospectionTools(blueprint: IBlueprint, cwd?: string): McpToolDef[];

package/dist/knowledge.d.ts

@@ -1,4 +1,4 @@
-import { Concept, KnowledgeBase } from './declarations';
+import { Concept, KnowledgeBase } from './declarations.js';
 /**
  * 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.

package/dist/llms.d.ts

@@ -1,4 +1,4 @@
-import { KnowledgeBase } from './declarations';
+import { KnowledgeBase } from './declarations.js';
 /**
  * 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.

package/dist/mcpJson.d.ts

@@ -9,10 +9,16 @@ export interface McpJsonIo {
 /**
  * The `.mcp.json` server entry that launches this dev server.
  *
- * @param command - The launcher command (defaults to `stone`).
+ * 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.
  */
-export declare function mcpServerEntry(command?: string): {
+export declare function mcpServerEntry(command?: string, args?: string[]): {
     command: string;
     args: string[];
 };

package/dist/tools.d.ts

@@ -1,4 +1,4 @@
-import { McpToolDef, ReportToolsOptions } from './declarations';
+import { McpToolDef, ReportToolsOptions } from './declarations.js';
 /**
  * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stone-js/mcp-dev",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "description": "Serve Stone.js's knowledge to your coding agent. A single `stone mcp` command starts an MCP server (stdio) exposing the framework's concepts, modules and best-practices plus your own tools, so the LLM masters the context while you master the domain.",
   "author": "Mr. Stone <evensstone@gmail.com>",
   "license": "MIT",
@@ -33,24 +33,23 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "browser": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/browser.js"
-      },
-      "default": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      }
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
     }
   },
   "engines": {
     "node": ">=18.17.0"
   },
   "peerDependencies": {
-    "@stone-js/core": "0.8.7"
+    "@stone-js/core": "0.8.9"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@commitlint/cli": "^19.8.1",
@@ -70,7 +69,8 @@
     "typedoc": "^0.28.6",
     "typedoc-plugin-markdown": "^4.7.0",
     "typescript": "^5.6.3",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "@stone-js/cli": "0.8.9"
   },
   "ts-standard": {
     "globals": [
@@ -82,6 +82,9 @@
       "beforeEach"
     ]
   },
+  "stone": {
+    "cliPlugin": "./dist/cli.js"
+  },
   "scripts": {
     "lint": "ts-standard src",
     "lint:fix": "ts-standard --fix src tests",

package/skills/stone-js/SKILL.md

@@ -47,7 +47,7 @@ The same class can be served over HTTP, in a Lambda, in the browser, or on the e
 ## Workflow
 
 1. **Before writing code, query the framework.** Call the `stone_search`, `stone_concept`,
-   `stone_modules`, and `stone_docs` MCP tools (served by `stone mcp`) to confirm the current
+   `stone_modules`, and `stone_brief` MCP tools (served by `stone mcp`) to confirm the current
    conventions and the right module for the job, instead of guessing from generic Node knowledge.
 2. **Inspect the app** with `stone_app`, `stone_routes`, `stone_commands`, `stone_adapters`,
    `stone_providers`, `stone_kernel`, and `stone_config` to see what it actually declares.

package/skills/stone-js-adapters/SKILL.md

@@ -53,5 +53,5 @@ platforms, and the environment decides which context applies.
 ## Verify with the MCP tools
 
 Call `stone_adapters` to list registered adapters (platform, alias, default/current) and the active
-platform. Use `stone_app` for a quick summary, and `stone_docs` for the adapter guides. `stone_search`
+platform. Use `stone_app` for a quick summary, and `stone_adapters` for what is registered. `stone_search`
 the knowledge base when picking a target or debugging selection.

package/skills/stone-js-routing/SKILL.md

@@ -57,7 +57,7 @@ class UserController {
 
 After adding routes, call `stone_routes` to confirm the resolved tree (path, methods, name,
 handler, middleware). Use `stone_kernel` to see the middleware pipeline that every route traverses.
-When unsure of an option, `stone_search` the knowledge base or `stone_docs` for the routing guide.
+When unsure of an option, `stone_search` the knowledge base or read `stone_brief` for the full brief.
 
 ## Do not