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

#Add the command

Enable it with the @McpDev() decorator (or register mcpDevBlueprint). Your app gains one command, stone mcp.

app/Application.tsts

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

@McpDev()
@StoneApp({ name: 'my-app' })
export class Application {}

#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).

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

#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/