@stone-js/mcp-dev 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2026 Stone Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# Stone.js · MCP dev server
+
+[![npm](https://img.shields.io/npm/v/@stone-js/mcp-dev)](https://www.npmjs.com/package/@stone-js/mcp-dev)
+[![CI](https://github.com/stone-foundation/stone-js-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/stone-foundation/stone-js-framework/actions/workflows/ci.yml)
+[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=stone-foundation_stone-js-framework&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-framework)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
+
+> Serve Stone.js's knowledge to your coding agent. One command — `stone mcp` — starts an MCP server exposing the framework's concepts, modules and best-practices (plus your own tools), so the LLM masters the context while you master the domain.
+
+Part of **[Stone.js](https://stonejs.dev)**, the reference implementation of the
+[Continuum Architecture](https://evens-stone.github.io/continuum-manifesto/manifesto): write your
+domain once, and the context (runtime, protocol, caller) applies to it at run time.
+
+## Install
+
+```bash
+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 {}
+```
+
+Then start the server from your project:
+
+```bash
+stone mcp
+```
+
+`stone mcp` starts an MCP server over **stdio** and keeps running until you press `Ctrl+C`, exactly
+like `stone dev`. It hands the [MCP SDK](https://github.com/modelcontextprotocol) the built-in
+framework-knowledge tools and lets the SDK own the protocol and run the handlers — these are dev and
+knowledge helpers, not your domain, so they do not need to traverse the kernel. Every tool call is
+logged to **stderr** (stdout is reserved for the JSON-RPC protocol) so you watch the agent think in
+real time.
+
+### Register it for your agent
+
+Let `stone mcp` write `.mcp.json` for you (create or merge, never clobbering your own config):
+
+```bash
+stone mcp --init
+```
+
+Or add the entry yourself (Claude Code, Cursor, Claude Desktop, …):
+
+```jsonc
+{ "mcpServers": {
+  "stone": { "command": "stone", "args": ["mcp"] }
+} }
+```
+
+`.mcp.json` can be committed or `.gitignore`d per developer.
+
+### Framework-knowledge tools
+
+| Tool | What it returns |
+|---|---|
+| `stone_search` | Search the knowledge base (concepts, modules, best-practices, gaps). |
+| `stone_concept` | Explain a core concept by id (omit id to list them all). |
+| `stone_docs` | Links to the authoritative documentation. |
+| `stone_modules` | The ecosystem modules and what each does. |
+| `stone_best_practices` | Conventions and anti-patterns, each with its rationale. |
+| `stone_gaps` | What the framework does not (yet) provide, and what to reach for. |
+| `stone_brief` | The full agent brief (`llms-full.txt`). |
+
+### 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:
+
+| Tool | What it returns |
+|---|---|
+| `stone_app` | App name, env, active platform, and counts of routes/commands/providers/adapters. |
+| `stone_routes` | The route tree (path, methods, name, handler, middleware). |
+| `stone_commands` | The CLI commands (name, alias, args, description). |
+| `stone_adapters` | Registered adapters (platform, alias, default/current) and the active platform. |
+| `stone_providers` | The service providers. |
+| `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. |
+
+### Your own tools
+
+Add project-specific tools (they run in-process, so they receive their arguments directly). Set the
+server name, `instructions`, or enable the GitHub report tools under `stone.mcpDev`:
+
+```ts
+import { McpDev } from '@stone-js/mcp-dev'
+
+@McpDev({
+  name: 'my-app-dev',
+  tools: [
+    { name: 'db_schema', description: 'Return the current DB schema', handler: () => readSchema() }
+  ],
+  report: { token: process.env.GITHUB_TOKEN!, repo: 'my-org/my-app' }
+})
+@StoneApp({ name: 'my-app' })
+export class Application {}
+```
+
+The knowledge base and `llms.txt` helpers are also exported directly (`stoneMcpTools`,
+`searchKnowledge`, `generateLlmsTxt`, `generateLlmsFullTxt`) if you want to serve them elsewhere.
+
+## Agent Skills
+
+The package ships [Agent Skills](https://agentskills.io) (`stone-js`, `stone-js-routing`,
+`stone-js-adapters`) under [`skills/`](./skills): portable `SKILL.md` folders that teach a
+skills-compatible agent the framework's conventions on demand. They complement the MCP tools (the
+tools introspect the app; the skills say how to build it). Copy the ones you want into your agent's
+skills directory:
+
+```bash
+mkdir -p .claude/skills
+cp -R node_modules/@stone-js/mcp-dev/skills/stone-js* .claude/skills/
+```
+
+## Documentation
+
+Full documentation: **[stonejs.dev/docs/extensions/mcp](https://stonejs.dev/docs/extensions/mcp)**.
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT) © Evens Pierre ("Mr. Stone") and the Stone.js contributors.

package/dist/McpDevServer.d.ts

@@ -0,0 +1,62 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpDevLogger, McpDevOptions, McpToolDef } from './declarations';
+/**
+ * An MCP tool result payload (the SDK content shape).
+ */
+export interface McpToolResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * 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.
+ */
+export declare function toToolContent(result: unknown): McpToolResult;
+/**
+ * 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.
+ */
+export declare function createStderrLogger(quiet?: boolean): McpDevLogger;
+/**
+ * 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.
+ */
+export declare function resolveTools(options: McpDevOptions): McpToolDef[];
+/**
+ * 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.
+ */
+export declare function createToolCallback(tool: McpToolDef, log: McpDevLogger): (args: Record<string, unknown>) => Promise<McpToolResult>;
+/**
+ * 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.
+ */
+export declare function buildMcpServer(options: McpDevOptions, log: McpDevLogger): McpServer;
+/**
+ * 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.
+ */
+export declare function startMcpDevServer(options: McpDevOptions): Promise<void>;

package/dist/browser/decorators/McpDev.d.ts

@@ -0,0 +1,19 @@
+import { McpDevOptions } from '../../declarations';
+import { ClassType } from '@stone-js/core';
+/**
+ * Options for the `McpDev` decorator.
+ */
+export interface McpDevDecoratorOptions extends McpDevOptions {
+}
+/**
+ * Browser stub of `@McpDev()`: a no-op.
+ *
+ * The dev MCP server (`stone mcp`) is a Node-only, development concern. Stubbing the decorator for
+ * the browser keeps an isomorphic app compiling and inert there, without dragging the CLI command,
+ * the MCP SDK server, or `node:fs` into the browser bundle (which would break a SPA). The real
+ * decorator lives in the Node build.
+ *
+ * @param _options - Ignored in the browser.
+ * @returns A no-op class decorator.
+ */
+export declare const McpDev: <T extends ClassType = ClassType>(_options?: McpDevDecoratorOptions) => ClassDecorator;

package/dist/browser/options/McpDevBlueprint.d.ts

@@ -0,0 +1,18 @@
+import { McpDevOptions } from '../../declarations';
+import { McpDevBlueprint } from '../../options/McpDevBlueprint';
+/**
+ * Browser stub of the MCP dev blueprint.
+ *
+ * It carries the config bucket but wires **no** blueprint middleware, so importing it into a browser
+ * bundle never pulls the Node-only `stone mcp` command, its server (`@modelcontextprotocol/sdk`,
+ * stdio) or the filesystem. The `stone mcp` command is a development, Node-only concern; in the
+ * browser this keeps the app compiling and inert.
+ */
+export declare const mcpDevBlueprint: McpDevBlueprint;
+/**
+ * Browser stub of `defineMcpDev`: returns the config bucket with no Node wiring.
+ *
+ * @param options - The MCP dev options.
+ * @returns The (inert) blueprint.
+ */
+export declare function defineMcpDev(options?: McpDevOptions): McpDevBlueprint;

package/dist/browser.js

@@ -0,0 +1,37 @@
+import { classDecoratorLegacyWrapper } from '@stone-js/core';
+
+/**
+ * Browser stub of `@McpDev()`: a no-op.
+ *
+ * The dev MCP server (`stone mcp`) is a Node-only, development concern. Stubbing the decorator for
+ * the browser keeps an isomorphic app compiling and inert there, without dragging the CLI command,
+ * the MCP SDK server, or `node:fs` into the browser bundle (which would break a SPA). The real
+ * decorator lives in the Node build.
+ *
+ * @param _options - Ignored in the browser.
+ * @returns A no-op class decorator.
+ */
+const McpDev = (_options = {}) => {
+    return classDecoratorLegacyWrapper((_target, _context) => { });
+};
+
+/**
+ * Browser stub of the MCP dev blueprint.
+ *
+ * It carries the config bucket but wires **no** blueprint middleware, so importing it into a browser
+ * bundle never pulls the Node-only `stone mcp` command, its server (`@modelcontextprotocol/sdk`,
+ * stdio) or the filesystem. The `stone mcp` command is a development, Node-only concern; in the
+ * browser this keeps the app compiling and inert.
+ */
+const mcpDevBlueprint = { stone: { mcpDev: {} } };
+/**
+ * Browser stub of `defineMcpDev`: returns the config bucket with no Node wiring.
+ *
+ * @param options - The MCP dev options.
+ * @returns The (inert) blueprint.
+ */
+function defineMcpDev(options = {}) {
+    return { stone: { mcpDev: options } };
+}
+
+export { McpDev, defineMcpDev, mcpDevBlueprint };

package/dist/commands/McpCommand.d.ts

@@ -0,0 +1,27 @@
+import { IContainer, IncomingEvent } from '@stone-js/core';
+import { CommandOptions } from '../declarations';
+/**
+ * Configuration for the `mcp` command.
+ */
+export declare const mcpCommandOptions: CommandOptions;
+/**
+ * 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.
+ */
+export declare class McpCommand {
+    private readonly container;
+    /**
+     * @param container - The dependency injection container.
+     * @throws {McpDevError} If the container is not provided.
+     */
+    constructor(container: IContainer);
+    /**
+     * Handle the `mcp` command: start the server and keep it running until interrupted.
+     *
+     * @param event - The incoming CLI event carrying the parsed flags.
+     */
+    handle(event: IncomingEvent): Promise<void>;
+}

package/dist/constants.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+export declare const NODE_CONSOLE_PLATFORM: string;
+/** The default MCP server name when the app declares none. */
+export declare const DEFAULT_MCP_SERVER_NAME: string;
+/** The default MCP server version. */
+export declare const DEFAULT_MCP_SERVER_VERSION: string;
+/**
+ * The default `instructions` advertised to the agent: what this server is and how to use it.
+ */
+export declare const DEFAULT_MCP_INSTRUCTIONS: string;

package/dist/declarations.d.ts

@@ -0,0 +1,115 @@
+/** A core architectural concept of Stone.js. */
+export interface Concept {
+    /** Slug id (e.g. `continuum`). */
+    id: string;
+    /** Human title. */
+    title: string;
+    /** One-paragraph explanation. */
+    summary: string;
+}
+/** A module of the ecosystem. */
+export interface ModuleInfo {
+    /** npm package name. */
+    package: string;
+    /** One-line description. */
+    summary: string;
+    /** Where it sits in the architecture. */
+    tier: 'primitive' | 'core' | 'crosscutting' | 'adapter' | 'frontend' | 'extension' | 'tooling';
+}
+/** A framework convention (with its rationale). */
+export interface BestPractice {
+    /** The rule. */
+    rule: string;
+    /** Why it exists. */
+    why: string;
+}
+/** Something the framework does not (yet) provide. */
+export interface Gap {
+    /** The capability. */
+    name: string;
+    /** `planned` (on the roadmap) or `missing` (integrate a third party). */
+    status: 'planned' | 'missing';
+    /** Guidance. */
+    note: string;
+}
+/** The machine-readable map of Stone.js. */
+export interface KnowledgeBase {
+    name: string;
+    tagline: string;
+    version: string;
+    concepts: Concept[];
+    modules: ModuleInfo[];
+    bestPractices: BestPractice[];
+    gaps: Gap[];
+}
+/**
+ * A tool definition exposed to the agent over MCP. The `handler` runs in-process (the dev server
+ * hands the SDK the callback directly): these are framework-knowledge and dev helpers, not your
+ * domain, so they do not traverse the kernel.
+ */
+export interface McpToolDef {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    handler: (args: Record<string, unknown>) => unknown | Promise<unknown>;
+}
+/**
+ * Options for the GitHub report tools: open a bug/feature issue straight from the dev loop.
+ */
+export interface ReportToolsOptions {
+    /** GitHub token with `issues:write` on the target repo. */
+    token: string;
+    /** Target repository as `owner/repo`. */
+    repo: string;
+    /** Injectable fetch (defaults to the global). Mainly for testing. */
+    fetch?: typeof fetch;
+}
+/**
+ * A logger for the dev server's activity. It writes to **stderr** so stdout stays reserved for the
+ * MCP protocol (stdio transport speaks JSON-RPC on stdout — any other write there corrupts it).
+ */
+export type McpDevLogger = (message: string) => void;
+/**
+ * Minimal yargs builder surface used to declare the command's options. Re-declared locally so the
+ * package stays decoupled from `@stone-js/node-cli-adapter` (the CLI adapter passes the real
+ * yargs builder at run time; this only shapes the callback).
+ */
+export interface IArgv {
+    option: (name: string, options: {
+        type?: string;
+        alias?: string;
+        desc?: string;
+        default?: unknown;
+    }) => IArgv;
+    positional: (name: string, options: Record<string, unknown>) => IArgv;
+}
+/**
+ * CLI command options, structurally compatible with `@stone-js/node-cli-adapter`'s `CommandOptions`.
+ */
+export interface CommandOptions {
+    name: string;
+    alias?: string | string[];
+    args?: string | string[];
+    desc?: string;
+    options?: (yargs: IArgv) => IArgv;
+}
+/**
+ * Options for the MCP dev server, exposed on the blueprint under `stone.mcpDev`.
+ *
+ * `stone mcp` starts an MCP server (stdio) that hands the SDK the built-in framework-knowledge
+ * tools merged with yours, and logs every tool call to stderr so you watch the agent think.
+ */
+export interface McpDevOptions {
+    /** The MCP server name advertised to the agent. */
+    name?: string;
+    /** The MCP server version. */
+    version?: string;
+    /** The `instructions` string advertised to the agent (the Continuum contract). */
+    instructions?: string;
+    /** Your own tools, merged with the built-in framework-knowledge tools. */
+    tools?: McpToolDef[];
+    /** Enable the GitHub bug/feature report tools by passing a token + repo. */
+    report?: ReportToolsOptions;
+    /** Silence the stderr activity log. */
+    quiet?: boolean;
+}

package/dist/decorators/McpDev.d.ts

@@ -0,0 +1,24 @@
+import { McpDevOptions } from '../declarations';
+import { ClassType } from '@stone-js/core';
+/**
+ * Options for the `McpDev` decorator.
+ */
+export interface McpDevDecoratorOptions extends McpDevOptions {
+}
+/**
+ * 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 {}
+ * ```
+ */
+export declare const McpDev: <T extends ClassType = ClassType>(options?: McpDevDecoratorOptions) => ClassDecorator;

package/dist/errors/McpDevError.d.ts

@@ -0,0 +1,7 @@
+import { ErrorOptions, RuntimeError } from '@stone-js/core';
+/**
+ * Custom error for the MCP dev module.
+ */
+export declare class McpDevError extends RuntimeError {
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+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';