Extensions

MCP dev server

A coding agent is only as good as its context. @stone-js/mcp-dev gives it three things through one command, stone mcp: the framework’s knowledge, a read-only view of this app, and any tools you add. The MCP SDK owns the protocol and runs the handlers in-process, so these dev helpers never touch your domain or the kernel.

#Install

terminalbash

npm i -D @stone-js/mcp-dev

#Nothing to declare

Installing it is the setup. This is dev tooling, so the CLI auto-discovers its plugin from your devDependencies and that plugin registers stone mcp. There is nothing to add to app/: no decorator, no blueprint. A development tool in an application's module graph would make a production build depend on a package the application does not need, for a feature nobody uses in production.

Configure it where the build is configured, if you want to:

stone.config.mjsjs

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

One command writes .mcp.json for you. It creates or merges the entry and never clobbers your own config, so a coding agent (Claude Code, Cursor, Claude Desktop, …) discovers the server:

terminalbash

npx stone mcp --init

That is the whole setup. You never start the server yourself. It speaks MCP over stdio, which means the transport is the child process's own standard input and output: your agent reads .mcp.json, spawns its own stone mcp process, and performs the handshake. A server you launch in your terminal has no channel to your agent and would simply sit there. Restart your agent session after the first --init so it picks the entry up.

#Framework-knowledge tools

The agent queries the framework live instead of guessing from stale training data.

Tool	Type	Description
stone_search	`query`	Search concepts, modules, best-practices and gaps.
stone_concept	`id?`	Explain a core concept (omit id to list them).
stone_modules	`()`	The ecosystem modules and what each does.
stone_best_practices	`()`	Conventions and anti-patterns, with rationale.
stone_gaps	`()`	What the framework does not (yet) provide.
stone_brief	`()`	The full agent brief (llms-full.txt).

#App-introspection tools

These read your app’s resolved blueprint, so the agent understands the app you are building, not just the framework. They are read-only and redact secret-looking config.

Tool	Type	Description
stone_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 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).
stone_config	`key?`	A resolved stone.* value by dotted key (secrets redacted).
stone_describes	`()`	Which application the answers describe, and how the server knows.

The agent reads the app the way the framework does: one blueprint, one source of truth.

#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. Answering from it without saying so is how an agent ends up confidently describing an app that does not exist.

So the running application publishes its own truth, and the build arranges it, not your application. Introspection is a development concern: this package ships a CLI plugin, the CLI auto-discovers it from your direct dependencies, and on a development build it injects a hook that writes the resolved configuration to .stone/app-context.json. Your app never imports this module, and a production build carries none of it.

terminalbash

npm i -D @stone-js/mcp-dev

Run stone dev once and the agent sees the real thing: the platform you actually run, your adapters, your resolved config. Until then the server answers from its own boot and names, through stone_describes, which of its answers not to trust. Opt out with mcpDev: { publishContext: false }, which generates nothing at all rather than shipping code that decides not to run.

Publishing is on outside production and off in it, since nothing there reads it. Override it either way with mcpDev: { publishContext: true }.

#Your own tools

Add project-specific tools. They run in-process and receive their arguments directly. Set the server name, instructions, or the GitHub report tools under stone.mcpDev.

app/Application.tsts

import { McpDev } from '@stone-js/mcp-dev'

@McpDev({
  name: 'my-app-dev',
  tools: [
    { name: 'db_schema', description: 'Return the current DB schema', handler: () => readSchema() }
  ]
})
@StoneApp({ name: 'my-app' })
export class Application {}

#Agent Skills

The package ships Agent Skills(stone-js, stone-js-routing, stone-js-adapters): portable SKILL.md folders that teach a skills-compatible agent the framework’s conventions on demand. The tools introspect the app; the skills say how to build it. Copy the ones you want into your agent’s skills directory.

terminalbash

mkdir -p .claude/skills
cp -R node_modules/@stone-js/mcp-dev/skills/stone-js* .claude/skills/