Stone.js · MCP dev server

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, the reference implementation of the Continuum Architecture: write your domain once, and the context (runtime, protocol, caller) applies to it at run time.

Install

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

Usage

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:

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

One command writes .mcp.json for you (create or merge, never clobbering your own config):

npx stone mcp --init

That is the whole setup: you never start the server yourself. It speaks MCP over stdio, so 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 a 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.

The command hands the MCP SDK 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 running npx stone mcp in a terminal lets you read those logs live. Useful for debugging, never required.

npx is used because @stone-js/cli is a dev dependency of your project: the bare stone command only resolves if you also installed it globally (npm i -g @stone-js/cli). Inside a package script the prefix is unnecessary.

Or add the entry yourself (Claude Code, Cursor, Claude Desktop, …):

{ "mcpServers": {
  "stone": { "command": "npx", "args": ["stone", "mcp"] }
} }

.mcp.json can be committed or .gitignored 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_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 configuration (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. | | 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:

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

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:

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 (stone-js, stone-js-routing, stone-js-adapters) under 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:

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.

License

MIT © Evens Pierre ("Mr. Stone") and the Stone.js contributors.