@stone-js/mcp-dev 0.8.0

package/dist/introspection.d.ts

@@ -0,0 +1,29 @@
+import { IBlueprint } from '@stone-js/core';
+import { McpToolDef } from './declarations';
+/**
+ * Best-effort name of a module reference (class, function, or meta-module `{ module }`).
+ *
+ * @param value - The reference to name.
+ * @returns The resolved name.
+ */
+export declare function moduleName(value: unknown): string;
+/**
+ * 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.
+ */
+export declare function sanitize(value: unknown, depth?: number): unknown;
+/**
+ * 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.
+ */
+export declare function createIntrospectionTools(blueprint: IBlueprint): McpToolDef[];

package/dist/knowledge.d.ts

@@ -0,0 +1,24 @@
+import { Concept, KnowledgeBase } from './declarations';
+/**
+ * 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.
+ */
+export declare const knowledgeBase: KnowledgeBase;
+/**
+ * Find a concept by id (case-insensitive).
+ *
+ * @param id - The concept id.
+ * @returns The concept, or undefined.
+ */
+export declare function getConcept(id: string): Concept | undefined;
+/**
+ * Full-text search across concepts, modules, best-practices and gaps.
+ *
+ * @param query - The search terms.
+ * @returns Matching entries with their kind.
+ */
+export declare function searchKnowledge(query: string): Array<{
+    kind: string;
+    title: string;
+    text: string;
+}>;

package/dist/llms.d.ts

@@ -0,0 +1,17 @@
+import { KnowledgeBase } from './declarations';
+/**
+ * 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.
+ */
+export declare function generateLlmsTxt(base?: KnowledgeBase): string;
+/**
+ * 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.
+ */
+export declare function generateLlmsFullTxt(base?: KnowledgeBase): string;

package/dist/mcpJson.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Injectable filesystem surface, so `.mcp.json` handling stays testable.
+ */
+export interface McpJsonIo {
+    exists: (path: string) => boolean;
+    read: (path: string) => string;
+    write: (path: string, content: string) => void;
+}
+/**
+ * The `.mcp.json` server entry that launches this dev server.
+ *
+ * @param command - The launcher command (defaults to `stone`).
+ * @returns The MCP server entry.
+ */
+export declare function mcpServerEntry(command?: string): {
+    command: string;
+    args: string[];
+};
+/**
+ * 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.
+ */
+export declare function mergeMcpJson(existing: Record<string, unknown> | undefined): {
+    config: Record<string, unknown>;
+    changed: boolean;
+};
+/**
+ * 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.
+ */
+export declare function initMcpJson(cwd: string, io?: McpJsonIo): {
+    file: string;
+    changed: boolean;
+};
+/**
+ * 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.
+ */
+export declare function hasMcpJson(cwd: string, io?: McpJsonIo): boolean;

package/dist/middleware/BlueprintMiddleware.d.ts

@@ -0,0 +1,17 @@
+import { BlueprintContext, IBlueprint, ClassType, MetaMiddleware, NextMiddleware } from '@stone-js/core';
+/**
+ * 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.
+ */
+export declare const SetMcpCommandsMiddleware: (context: BlueprintContext<IBlueprint, ClassType>, next: NextMiddleware<BlueprintContext<IBlueprint, ClassType>, IBlueprint>) => Promise<IBlueprint>;
+/**
+ * The blueprint middleware contributed by the MCP dev module.
+ */
+export declare const metaMcpDevBlueprintMiddleware: Array<MetaMiddleware<BlueprintContext<IBlueprint, ClassType>, IBlueprint>>;

package/dist/options/McpDevBlueprint.d.ts

@@ -0,0 +1,34 @@
+import { McpDevOptions } from '../declarations';
+import { AppConfig, StoneBlueprint } from '@stone-js/core';
+/**
+ * MCP dev configuration bucket (`stone.mcpDev`).
+ */
+export interface McpDevConfig extends McpDevOptions {
+}
+/**
+ * Application config augmented with the MCP dev bucket.
+ */
+export interface McpDevAppConfig extends Partial<AppConfig> {
+    mcpDev: Partial<McpDevConfig>;
+}
+/**
+ * Blueprint for the MCP dev module.
+ */
+export interface McpDevBlueprint extends StoneBlueprint {
+    stone: McpDevAppConfig;
+}
+/**
+ * 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()`).
+ */
+export declare const mcpDevBlueprint: McpDevBlueprint;
+/**
+ * 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.
+ */
+export declare function defineMcpDev(options?: McpDevOptions): McpDevBlueprint;

package/dist/tools.d.ts

@@ -0,0 +1,15 @@
+import { McpToolDef, ReportToolsOptions } from './declarations';
+/**
+ * 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.
+ */
+export declare const stoneMcpTools: McpToolDef[];
+/**
+ * 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.
+ */
+export declare function createReportTools(options: ReportToolsOptions): McpToolDef[];

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@stone-js/mcp-dev",
+  "version": "0.8.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stone-foundation/stone-js-framework.git",
+    "directory": "stone-js-mcp-dev"
+  },
+  "homepage": "https://stonejs.dev",
+  "bugs": {
+    "url": "https://github.com/stone-foundation/stone-js-framework/issues"
+  },
+  "keywords": [
+    "StoneJS",
+    "mcp",
+    "cli",
+    "ai",
+    "agent",
+    "llm",
+    "llms.txt",
+    "agentic",
+    "knowledge"
+  ],
+  "files": [
+    "/dist",
+    "/skills"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "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"
+      }
+    }
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "peerDependencies": {
+    "@stone-js/core": "0.8.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.8.1",
+    "@commitlint/config-conventional": "^19.8.1",
+    "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-multi-entry": "^6.0.1",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-typescript": "^12.1.4",
+    "@types/node": "^24.0.7",
+    "@vitest/coverage-v8": "^3.2.4",
+    "husky": "^9.1.7",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.44.1",
+    "rollup-plugin-node-externals": "^8.0.1",
+    "ts-standard": "^12.0.2",
+    "tslib": "^2.8.1",
+    "typedoc": "^0.28.6",
+    "typedoc-plugin-markdown": "^4.7.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "ts-standard": {
+    "globals": [
+      "it",
+      "test",
+      "vi",
+      "expect",
+      "describe",
+      "beforeEach"
+    ]
+  },
+  "scripts": {
+    "lint": "ts-standard src",
+    "lint:fix": "ts-standard --fix src tests",
+    "predoc": "rimraf docs",
+    "doc": "typedoc",
+    "clean": "rimraf dist",
+    "build": "rollup -c",
+    "test": "vitest run",
+    "test:cvg": "npm run test -- --coverage",
+    "test:text": "npm run test:cvg -- --coverage.reporter=text",
+    "test:html": "npm run test:cvg -- --coverage.reporter=html",
+    "test:clover": "npm run test:cvg -- --coverage.reporter=clover"
+  }
+}

package/skills/README.md

@@ -0,0 +1,31 @@
+# Stone.js Agent Skills
+
+These are [Agent Skills](https://agentskills.io) for building Stone.js apps: portable folders, each
+with a `SKILL.md` (name, description, instructions), that a skills-compatible agent (Claude Code,
+Cursor, Copilot, Gemini CLI, OpenCode, Goose, …) loads on demand via progressive disclosure. They
+are the framework's conventions, packaged so the agent applies them without you re-explaining them.
+
+They pair with the `stone mcp` server: the skills tell the agent *how* to build with Stone.js, and
+the `stone_*` MCP tools let it introspect *this* app (routes, commands, adapters, config) in real
+time.
+
+## Skills
+
+| Skill | Use it when |
+|---|---|
+| `stone-js` | Writing, structuring, or reviewing any Stone.js app (the core model + conventions). |
+| `stone-js-routing` | Adding or changing routes, controllers, or HTTP endpoints. |
+| `stone-js-adapters` | Choosing where the app runs or adding a deploy target. |
+
+## Install
+
+Skills are read from your agent's skills directory. Copy (or symlink) the ones you want:
+
+```bash
+# Claude Code (project scope)
+mkdir -p .claude/skills
+cp -R node_modules/@stone-js/mcp-dev/skills/stone-js* .claude/skills/
+```
+
+Other agents use their own directory (`.cursor/skills`, `.github/skills`, …); see your agent's
+docs. Each skill is a self-contained folder, so copying the folder is all that is needed.

package/skills/stone-js/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: stone-js
+description: Use when writing, structuring, or reviewing a Stone.js (@stone-js/*) application. Covers the Continuum model, StoneApp bootstrapping, the declarative/imperative paradigms, the three module forms, and blueprint configuration. Pair with the `stone_*` MCP tools from @stone-js/mcp-dev to introspect the live app.
+---
+
+# Building with Stone.js
+
+Stone.js is the reference implementation of the Continuum Architecture: an application is an
+**act**, `Application = Domain × Context → Resolution`. You write your domain once; the context
+(runtime, protocol, caller) applies to it at run time. Stone.js *is* the context.
+
+## Golden rules
+
+- **The domain never imports the platform.** No HTTP/CLI/browser vocabulary leaks into domain code.
+  A handler receives an `IncomingEvent` and returns a value; the adapter and kernel do the rest.
+- **Two paradigms, at parity.**
+  - *Declarative*: TC39 **stage-3** decorators (`@StoneApp`, `@Routing`, `@Get`, …) with
+    `Symbol.metadata`. **Never** use `reflect-metadata` or `experimentalDecorators`.
+  - *Imperative*: `define*` helpers producing meta-modules `{ module, isClass?, isFactory? }`.
+- **Three forms everywhere**: class, factory, and function. The **function form never receives the
+  container**; **providers forbid the function form**.
+- **All configuration lives on the Blueprint under dotted `stone.*` keys.** It is built once, before
+  any event, by introspecting decorators or by imperative meta-modules.
+- Constructors are **private/protected**; expose a `static create()`.
+- ESM only (`"type": "module"`), TypeScript strict, `ts-standard` lint, Vitest (aim for 100%),
+  conventional commits.
+
+## A minimal app
+
+```ts
+import { StoneApp, IncomingEvent } from '@stone-js/core'
+import { Routing, Get } from '@stone-js/router'
+
+@Routing()
+@StoneApp({ name: 'my-app' })
+class Application {
+  @Get('/hello')
+  hello (event: IncomingEvent) {
+    return { message: `Hello ${event.get<string>('name', 'world')}` }
+  }
+}
+```
+
+The same class can be served over HTTP, in a Lambda, in the browser, or on the edge: you change the
+**adapter**, not the domain. See the `stone-js-adapters` skill.
+
+## 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
+   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.
+3. Reach for an official module rather than re-implementing: validation, auth, authz, resources,
+   openapi, testing, realtime, event-bus, queue, cache. Declare internal deps as `workspace:*`.
+4. **Every bug fix earns a behavioral test** (exercise real behavior, not mocks).
+
+## Anti-patterns to reject
+
+- Importing `reflect-metadata` or enabling `experimentalDecorators`.
+- Putting HTTP/CLI specifics in the core/domain.
+- Passing the container to a function-form module, or using a function-form provider.
+- Storing durable content in a module's `docs/` folder (it is TypeDoc output, wiped each build).

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

@@ -0,0 +1,57 @@
+---
+name: stone-js-adapters
+description: Use when choosing where a Stone.js app runs or adding a deploy target (Node HTTP, AWS Lambda, browser SPA, edge/WinterCG, CLI). Explains the "build once, deploy anywhere" model, how an adapter turns a platform cause into an IncomingEvent, and how the runtime collapse selects an adapter. Inspect targets with the `stone_adapters` MCP tool.
+---
+
+# Adapters: build once, deploy anywhere
+
+An adapter is the **Integration** dimension of the Continuum: it captures a raw platform *cause*,
+normalizes it into an *intention* (`IncomingEvent`), lets the kernel apply the domain, then turns
+the response back into a native *effect*. The domain and routes never change; you add or switch an
+adapter.
+
+## The adapters
+
+| Target | Package |
+|---|---|
+| Node HTTP server | `@stone-js/node-http-adapter` |
+| AWS Lambda (generic / HTTP) | `@stone-js/aws-lambda-adapter`, `@stone-js/aws-lambda-http-adapter` |
+| Web standard / edge (Cloudflare, Deno, Bun, Vercel, Netlify) | `@stone-js/fetch-adapter`, `@stone-js/edge-adapter` |
+| Browser SPA | `@stone-js/browser-adapter` |
+| CLI | `@stone-js/node-cli-adapter` |
+
+Enable one by adding its decorator/blueprint to the app (e.g. `@NodeHttp()`), alongside `@StoneApp`
+and `@Routing`.
+
+```ts
+import { NodeHttp } from '@stone-js/node-http-adapter'
+import { Routing } from '@stone-js/router'
+import { StoneApp } from '@stone-js/core'
+
+@NodeHttp()
+@Routing()
+@StoneApp({ name: 'my-app' })
+class Application {}
+```
+
+## How selection works (the runtime collapse)
+
+When several adapters are registered, the kernel selects one per invocation, in order: a single
+adapter wins outright; else the one marked `current: true`; else a match on `stone.adapter.platform`;
+else a match on `alias`; else the one marked `default: true`. So one build can target many
+platforms, and the environment decides which context applies.
+
+## Rules
+
+- Never leak a platform's request/response object into the domain; the adapter is the only place
+  that speaks the platform's dialect.
+- An adapter's job is Integration **only**: cause to `IncomingEvent`, and response to effect. It
+  must not own routing or a dispatcher; the kernel routes.
+- CLI commands are contributed by modules to `stone.adapter.commands` and discovered by the CLI
+  through introspection (that is how `stone mcp` itself is added by `@stone-js/mcp-dev`).
+
+## 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`
+the knowledge base when picking a target or debugging selection.

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

@@ -0,0 +1,66 @@
+---
+name: stone-js-routing
+description: Use when adding or changing routes, controllers, or HTTP endpoints in a Stone.js app with @stone-js/router. Covers the routing decorators, controllers, route groups, middleware, and the universal (node/browser) router. Verify live routes with the `stone_routes` MCP tool.
+---
+
+# Routing in Stone.js
+
+`@stone-js/router` is a universal router (node and browser). Enable it on the app with `@Routing()`,
+then declare routes with decorators or imperative definitions. Routing is platform-agnostic: the
+same routes answer over any HTTP adapter.
+
+## Route handlers on the app
+
+```ts
+import { Routing, Get, Post } from '@stone-js/router'
+import { StoneApp, IncomingEvent } from '@stone-js/core'
+
+@Routing()
+@StoneApp({ name: 'my-app' })
+class Application {
+  @Get('/users')
+  list () { return this.service.all() }
+
+  @Post('/users')
+  create (event: IncomingEvent) { return this.service.create(event.get('body')) }
+}
+```
+
+## Controllers and groups
+
+Group related routes on a controller with `@Controller('/prefix')`, then `@Get`, `@Post`, `@Put`,
+`@Patch`, `@Delete`, `@Options`, `@Any`, or `@Match`. `@Page` declares a view/component route.
+
+```ts
+import { Controller, Get } from '@stone-js/router'
+
+@Controller('/api/users')
+class UserController {
+  @Get('/')            // GET /api/users
+  index () { /* ... */ }
+
+  @Get('/:id')         // GET /api/users/:id
+  show (event: IncomingEvent) { return this.repo.find(event.get('params').id) }
+}
+```
+
+## Key points
+
+- A handler returns a plain value; the response is built by the layers, not by you.
+- Bind path params, apply per-route `middleware`, set `rules` (param regexps), `defaults`, and
+  `bindings` on the route definition; all are introspectable.
+- The router is also the app's kernel event handler when `@Routing()` is set.
+- Prefer decorators, but the imperative form (route definitions under `stone.router.definitions`)
+  is available and equivalent.
+
+## Verify with the MCP tools
+
+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.
+
+## Do not
+
+- Do not read the request/response as platform objects in a handler; use the `IncomingEvent` API.
+- Do not hand-roll URL parsing or a second router; the framework's matchers handle host, method,
+  protocol, and URI.