@stone-js/mcp-dev 0.8.8 → 0.8.9

package/README.md

@@ -27,15 +27,23 @@ npm i -D @stone-js/mcp-dev
 
 ## Usage
 
-Add the command to your app with the `@McpDev()` decorator (or register `mcpDevBlueprint`):
-
-```ts
-import { McpDev } from '@stone-js/mcp-dev'
-import { StoneApp } from '@stone-js/core'
-
-@McpDev()
-@StoneApp({ name: 'my-app' })
-export class Application {}
+Installing it is the setup. This is dev tooling: the CLI auto-discovers the plugin from your
+devDependencies, which registers `stone mcp` — there is **nothing to declare in `app/`**, no decorator
+and no blueprint, because a development tool has no business in an application's module graph.
+
+Configure it, if you want to, in the file that already configures your build:
+
+```js
+// stone.config.mjs
+import { defineBuilderConfig } from '@stone-js/cli'
+
+export default defineBuilderConfig({
+  mcpDev: {
+    name: 'my-app',              // the server name your agent sees
+    tools: [myOwnTool],          // your own tools, defined outside app/
+    publishContext: true         // default outside production
+  }
+})
 ```
 
 ### Register it for your agent
@@ -66,7 +74,7 @@ Or add the entry yourself (Claude Code, Cursor, Claude Desktop, …):
 
 ```jsonc
 { "mcpServers": {
-  "stone": { "command": "stone", "args": ["mcp"] }
+  "stone": { "command": "npx", "args": ["stone", "mcp"] }
 } }
 ```
 
@@ -85,8 +93,8 @@ Or add the entry yourself (Claude Code, Cursor, Claude Desktop, …):
 
 ### App-introspection tools
 
-These read *your* app's resolved blueprint (read-only, secrets redacted), so the agent understands
-the app you are building, not just the framework:
+These read *your* app's resolved configuration (read-only, secrets redacted), so the agent
+understands the app you are building, not just the framework:
 
 | Tool | What it returns |
 |---|---|
@@ -98,6 +106,46 @@ the app you are building, not just the framework:
 | `stone_kernel` | The kernel pipeline: event handler, middleware, error handlers. |
 | `stone_key_routes` | Key-routing definitions (event-bus / realtime): key to handler. |
 | `stone_config` | A resolved `stone.*` config value by dotted key (secrets redacted); omit the key to list them. |
+| `stone_describes` | Which application the answers above describe, and how the server knows. |
+
+#### Which application, exactly
+
+`stone mcp` is a console command, so a blueprint it resolves itself is the one a **console** boot
+produces: its adapters, its response type and every platform-conditional contribution belong to a
+different application than the one you run under `stone dev`.
+
+The build arranges all of it — nothing is declared in your application:
+
+```bash
+npm i -D @stone-js/mcp-dev
+```
+
+That is the whole setup, and there is deliberately nothing to add to `app/`. Introspection is a
+development concern, so this package is **dev tooling only**: it ships a CLI plugin, the CLI
+auto-discovers first-party plugins from your direct dependencies, and the plugin both registers the
+`stone mcp` command and — on a development build (`dev`, `serve`, `preview`) — injects a hook that
+writes your running app's resolved configuration to `.stone/app-context.json`.
+
+Your application never imports this module, never declares it, and a production build carries none of
+it. There is no decorator and no blueprint to activate: a development tool has no business in an
+application's module graph, where it would make a production build depend on a package the app does
+not need.
+
+Run `stone dev` once and the agent sees the real thing: the platform you actually run, your adapters,
+your resolved config. Until then the MCP server answers from its own boot and says so through
+`stone_describes`, naming which answers not to trust rather than pretending.
+
+Configure it in `stone.config.mjs` under `mcpDev` (server name, instructions, your own tools).
+Opt out of publishing with `mcpDev: { publishContext: false }`: nothing is generated at all,
+rather than code that ships and decides not to run.
+
+A file rather than a dev endpoint, deliberately: the Blueprint is assembled once before the first
+event and then read, so publishing it at boot *is* the value, not a snapshot of something moving. It
+also needs no port to discover, adds no route to your application, and works for a CLI or an edge
+context that has no HTTP surface at all.
+
+Publishing is on outside production and off in it, since nothing there reads it. Override either way
+with `mcpDev: { publishContext: true | false }`.
 
 ### Your own tools
 

package/dist/McpDevServer.d.ts

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { McpDevLogger, McpDevOptions, McpToolDef } from './declarations';
+import { McpDevLogger, McpDevOptions, McpToolDef } from './declarations.js';
 /**
  * An MCP tool result payload (the SDK content shape).
  */

package/dist/appContext.d.ts

@@ -0,0 +1,60 @@
+import { IBlueprint } from '@stone-js/core';
+/** Where a running application leaves its resolved configuration for the MCP server to read. */
+export declare const APP_CONTEXT_FILE: string;
+/**
+ * What a running application publishes about itself.
+ */
+export interface AppContext {
+    /** The platform the application actually booted as. */
+    platform?: string;
+    /** The environment it booted in. */
+    env?: string;
+    /** Its name. */
+    name?: string;
+    /** The resolved `stone` configuration, with secret-looking values redacted. */
+    stone: Record<string, unknown>;
+}
+/**
+ * A duck-typed reader over a published context, shaped like the blueprint the tools already read.
+ *
+ * The introspection tools ask questions by dotted key, so a plain object answering `get` is all they
+ * need: the same tools then work against a file or against a live blueprint, and neither knows which.
+ */
+export interface ContextReader {
+    get: <T>(key: string, fallback?: T) => T;
+}
+/**
+ * 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.
+ */
+export declare function publishAppContext(blueprint: IBlueprint, cwd?: string): string;
+/**
+ * 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.
+ */
+export declare function readAppContext(cwd?: string): AppContext | undefined;
+/**
+ * A reader over a published context, answering the same dotted keys a blueprint answers.
+ *
+ * @param context - The published context.
+ * @returns The reader.
+ */
+export declare function contextReader(context: AppContext): ContextReader;

package/dist/cli.d.ts

@@ -0,0 +1,53 @@
+import { BlueprintContext, ClassType, IBlueprint, NextMiddleware } from '@stone-js/core';
+import type { StoneCliPlugin, StonePluginBlueprintMiddleware } from '@stone-js/cli';
+/**
+ * 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.
+ */
+export declare const SetMcpCommandsMiddleware: (context: BlueprintContext<IBlueprint, ClassType>, next: NextMiddleware<BlueprintContext<IBlueprint, ClassType>, IBlueprint>) => Promise<IBlueprint>;
+/** The blueprint middleware this plugin contributes. */
+export declare const mcpDevPluginMiddleware: StonePluginBlueprintMiddleware[];
+/** Where the plugin writes the module it injects, relative to the build's `.stone/tmp` directory. */
+export declare const GENERATED_MODULE: string;
+/** The commands that mean "a developer is working right now", and nothing else. */
+export declare const DEV_COMMANDS: string[];
+/**
+ * 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.
+ */
+export declare function generatedModule(): string;
+/**
+ * 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.
+ */
+export declare function mcpDevCliPlugin(): StoneCliPlugin;
+/**
+ * A ready-to-use plugin instance, used by first-party `package.json` auto-discovery.
+ */
+declare const plugin: StoneCliPlugin;
+export default plugin;