DOCS v0.107.0 · synced with main

The Guides.

Read the framework end to end, or jump to the part you need. Every guide is paired with runnable examples in TypeScript and JavaScript, and links straight to its source on GitHub.

guides

all of docs/guides

sections

balance 3·5·3·4·6·1·1·4·7

quickstarts

a 2-part tutorial

↗

on GitHub

mcp-rune / mcp-rune

★ FEATURED view all ↗

01 / 03

START

Quickstart

10 minutes to a running MCP server. Scaffold, declare one model, ship.

The DSL at the heart of mcp-rune. Sections, field groups, three strategies.

Build rich UIs that render inside Claude Desktop. Bi-directional protocol.

18 min Read →

Spot what you can extend Extensible

The plug mark flags guides with an extension point — a place to drop in your own plugin, hook, strategy or override. 22 of 49 guides expose one.

0. SECTION

About

2 GUIDES

What mcp-rune is and the thinking behind it — start here if you want the why before the how.

§ 01 Philosophy The worldview behind every API decision — the rune metaphor, the two-tier architecture, and the seven invariants the framework is held to. concepts live 6 min → § 02 Why mcp-rune? Why mcp-rune exists and how it compares to protocol wrappers, API converters, and FastMCP — plus when it is not the right fit. concepts live 5 min →

I. SECTION

Getting Started

2 GUIDES

Your first day with mcp-rune — install, scaffold, and run a server end to end.

§ 01 Quickstart Tutorial · 1/2 Scaffold a project, register your first model, and call a tool from Claude Desktop in one terminal session. clisetup live 8 min → § 02 Project structure Where models, prompts, tools, apps and the domain registry live in a generated mcp-rune project. layout live 4 min →

II. SECTION

The Model

1 EXTENSIBLE 6 GUIDES

The Model is mcp-rune's single source of truth. This chapter teaches what a Model declaration is — attributes, kinds, associations, validation — and the definition-vs-consumption split the rest of the framework is built on.

§ 01 Derivation overview A one-page map of every framework surface derived from your Model declaration, with pointers to the chapter that covers each. reference new 3 min → § 02 Defining a model BaseModel, the four static fields the framework reads, and the smallest realistic example drawn from the tasks server. modelscore new 6 min → § 03 Attributes and kinds Extensible Register custom kinds via AppRegistry({ kinds }) How an attribute value moves through three representations — wire shape, validation, render — and the unified kind taxonomy under src/mcp/models/kinds/. modelsreference live 8 min → § 04 Associations belongsTo and hasMany. How foreign keys are inferred, and what pickers, validators, forms, and graph edges get for free. models new 6 min → § 05 Validation and defaults required, default, validation: { min, max }. Where each one fires in the validate → write lifecycle, and the prompt-defaults vs payload-defaults split. modelsvalidation new 5 min → § 06 Definition vs consumption Why models/ holds the declaration and model-layer/, data-layer/, analysis-layer/ hold the consumers. The architectural split the eslint guard enforces. architecture new 4 min →

III. SECTION

The Prompt

2 EXTENSIBLE 4 GUIDES

The first thing that reads a Model. Where the Model defines the nouns, the Prompt defines the verbs of reasoning — how an LLM should think about and fill the form your Model implies.

§ 01 Prompt creation Extensible askPrompts · per-section content enrichment BasePrompt: sections, fieldGroups, formStrategy, promptContent, and derivePromptSchema. By the end you can read book-prompt.ts line by line. coredsl live 14 min → § 02 Prompt derivation The five-layer architecture: schema → grouping → section docs → assembly → behavioral instructions. architecture live 11 min → § 03 Sections & field groups User-facing sections versus validation-facing field groups, and how layouts flow between them. ui live 6 min → § 04 Stateful strategies Extensible Implement a custom StatefulStrategy Turn-taking, section-by-section validation, and the StatefulStrategy API for 20+ field workflows. advanced live 9 min →

IV. SECTION

Tools

2 EXTENSIBLE 4 GUIDES

What executes against the Model. The three peer interfaces every tool consumes via DI, the 9 bundled polymorphic tools that serve every model uniformly, and the path to writing custom tools when a bespoke verb doesn't fit.

§ 01 The three layers DataLayer, ModelLayer, AnalysisLayer — the three peer interfaces every Tool, App, and Prompt receives via DI. The eslint guard that keeps the boundary trustworthy. architecturecore new 8 min → § 02 Polymorphic tools The 9 bundled tools (6 CRUD + 3 form-strategy) that serve every model. Why the surface doesn't grow when your model count does. tools new 6 min → § 03 Tool creation Extensible Server-specific tools · interceptors · validators Writing a BaseTool subclass when a bespoke verb doesn't fit the polymorphic shape. Pipeline, interceptors, validators. tools live 13 min → § 04 Workflow creation Extensible Author multi-step workflow definitions Multi-step LLM-driven workflows. get_workflow_step, contextHints, the fetch-analyze loop pattern. workflows live 15 min →

V. SECTION

Apps

2 EXTENSIBLE 3 GUIDES

Where Tools serve the LLM, Apps serve the human. Schema-driven HTML interfaces that render inside MCP clients, consuming the same three layers Tools do plus a bidirectional iframe message protocol.

§ 01 MCP apps Extensible Ship your own sandboxed HTML apps Schema-driven HTML forms rendered inside the client. ontoolinput, ontoolresult, callServerTool — the whole protocol. appsui live 18 min → § 02 Apps architecture How the framework resolves a ui:// resource, sandboxes the iframe, and wires bidirectional message channels. appsprotocol live 8 min → § 03 Model form customization Extensible Per-fieldGroup layout overrides BaseAppForm, per-fieldGroup overrides, horizontal grids, row layouts. When the synthesized default form doesn't fit. appsui live 7 min →

VI. SECTION

The Three Layers Up Close

6 EXTENSIBLE 9 GUIDES

Part I taught Tools and Apps to call three injected layers without knowing how any of them are implemented. This is where you decide what's behind each interface — which adapter, which wire convention, which API client, which search shape.

§ 01 Data layer Extensible Implement a custom DataLayer The per-request backend I/O seam. Built-in implementations (in-memory stub, ModelService, SearchEnabledDataLayer). When to swap. adapterdata new 6 min → § 02 Model service The default DataLayer adapter. How ModelService composes EndpointResolver + ApiClient + convention to route every CRUD call. adapterdata new 7 min → § 03 API configuration Extensible Custom actions on a model API The static api block: endpoint, convention, namespace, readOnly, custom actions, and compound IDs — the declaration ModelService, ApiClient, and conventions all read from. modelshttp live 12 min → § 04 API client Extensible Implement a custom ApiClient Universal CRUD HTTP contract ModelService depends on. Override when axios isn't enough or you need custom retry/auth/telemetry. adapterhttp live 7 min → § 05 API convention Extensible Implement a custom API convention Wire-format shape: payload wrapping, association ID translation, response unwrapping. Default moved BaseModel → DataLayer in v0.85.0. adapterwire live 8 min → § 06 Search request shaper Extensible Implement a custom search request shaper Translate { query, filters, page, perPage } into your API's request shape — Ransack, Elasticsearch DSL, JSON:API. Renamed from SearchAdapter in v0.77.0. adaptersearch live 6 min → § 07 Search filters Extensible Register custom filter types The typed filter contract the shaper consumes — text · enum · relation · date_range · integer_range. Both sides of an integration. search live 11 min → § 08 Model layer The synchronous, per-model-bound interface: model + resolveDerivedFields. Kinds are shared vocabulary read beside it. No I/O. architecturecore new 5 min → § 09 Analysis layer The per-model-bound, per-request interface. extractEdges, buildEmbeddingText, walkHops. The substrate Part III's analysis tools call into. architectureanalysis new 5 min →

VII. SECTION

Auth & Transport

2 GUIDES

OAuth 2.0 the spec-compliant way — PRM, DCR, PKCE, resource indicators — plus the dual transport story (stdio for local, HTTP for multi-user) and the observability primitives built on top.

§ 01 OAuth 2.0 Discovery RFC 9728 PRM · RFC 8414 server metadata · RFC 7591 DCR · RFC 7636 PKCE · RFC 8707 resource indicators. authrfc live 9 min → § 02 Transport & observability StdioServer vs HttpServer from one factory; structured logging, distributed tracing, error tracking, request-ID correlation. transportobservability live 6 min →

VIII. SECTION

Domain Knowledge

2 EXTENSIBLE 2 GUIDES

Models tell the framework about your data. Domain tells the framework about your business — the declarative layer of concepts, business rules, multi-step workflow definitions, and diagram templates the LLM can reach for.

§ 01 Domain knowledge framework Extensible Register concepts · rules · workflows · diagrams DomainConcept, BusinessRule, WorkflowDefinition, DomainModule — the declarative domain registry and how to wire it with InMemoryDomainAdapter. domain live 24 min → § 02 Domain adapters Extensible Implement a custom DomainAdapter DomainAdapter interface and InMemoryDomainAdapter — storage backends for domain registries, rule evaluation semantics, and the remote-adapter roadmap. domainadapter new 4 min →

IX. SECTION

Retrieval & GraphRAG

1 EXTENSIBLE 6 GUIDES

mcp-rune's retrieval stack: records become vectors, a relationship graph, and domain-grounded memories you can query by meaning, aggregate, or stratified sample — map-reduce over thousands of rows without flooding the context window.

§ 01 Analysis quickstart Tutorial · 2/2 Part 2 of the Quickstart: bring up pgvector and walk the nine summary strategies (plus path and record-semantic queries) end to end against the bookshelf-graph fixtures. analysistutorial new 12 min → § 02 GraphRAG overview Start here. How vectors, a relationship graph, and domain grounding combine into GraphRAG over your own models — and which guide owns each piece. retrievalgraphrag new 7 min → § 03 Analysis memories The six analysis_* tools: ingest thousands of paginated records, embed findings into local pgvector, recall by meaning. The engine under GraphRAG. retrievalvector live 22 min → § 04 Summary strategies Extensible Implement a custom summary strategy Nine page-summary strategies — five field-level, four GraphRAG-aware (edges + domain). The LLM's semantic starter pack. retrievalstrategy live 5 min → § 05 Proximity sampling Date-windowed, bucket-stratified sampling for analysis_query — representative records around a date, not the densest day. retrievalsampling live 6 min → § 06 Transient context protocol Server-to-client protocol for collapsing transient tool results after a follow-up call has consumed them. protocolcontext live 5 min →

X. SECTION

Extensions

6 EXTENSIBLE 7 GUIDES

Add new capability on top of the framework without forking — HTTP routes, tool-flow hooks, custom MCP apps, and DataLayer verbs beyond plain CRUD. The seams every chapter so far has been hinting at.

§ 01 Extensions overview Tour the seams: convention, client, data layer, search shaper, and the three extension shapes. overview live 3 min → § 02 Extension recipes Extensible Recipes — start here to pick the right extension surface Inverse map — "I want to do X, which seam does that?" Copy-pasteable starting points for the common extension patterns. extensionscookbook live 9 min → § 03 Authoring extensions Extensible Walk through writing an extension end to end End-to-end walkthrough of writing an extension from scratch. Pick HttpExtension or ToolFlowExtension based on lifetime. extensionsauthoring live 7 min → § 04 API extensions Extensible Author API extensions — tools + DataLayer methods Contribute MCP tools and DataLayer mixin methods beyond pure CRUD — custom verbs, search subsystems, bulk operations, RPC. extensionsapi live 7 min → § 05 Tool-flow extensions Extensible Author tool-flow extensions Sibling to HttpExtension: modify the MCP tool surface and the runtime context threaded into app tool handlers. extensionstools live 7 min → § 06 HTTP extensions Extensible Author HTTP extensions (routes + middleware) Opt-in HTTP extensions add routes and middleware on top of the framework's OAuth, status, and MCP transport endpoints. extensionshttp live 4 min → § 07 Writing a custom MCP app Extensible Write a custom MCP app Build an additional MCP app: kind taxonomy, formatter registry, form-schema generator, selection store, theming. appsauthoring live 7 min →

XI. SECTION

Reference

2 GUIDES

API surface and configuration reference — subpath imports, database tables, and environment variables.

§ 01 Subpath imports Every subpath the package exposes and what lives where. reference live 4 min → § 02 Database reference PostgreSQL + pgvector tables, migration runner pattern, full env-var reference. referenceanalysis live 6 min →

Something missing?

Every guide lives next to the code that implements it. Open a PR against docs/guides/ — or file an RFC if you'd like the framework to grow.

Open RFC → Edit on GitHub ↗