r mcp-rune 0.1.0
⌕ Search docs ⌘K
★ 1,243 Get started →
NEW v0.1.0-alpha · MCP Apps for CRUD, schema-derived Read →

The framework for model-driven MCP servers.

Declare your models once. mcp-rune derives the prompts agents can follow, generic CRUD tools, semantic search, OAuth 2.0, and rich MCP Apps — from the same spec.

Get started →
$ npm i mcp-rune
MIT Node 20+ / Bun TypeScript & JavaScript Zero external services
~/library-mcp · rune dev
ready in 412ms
src/models/book.ts source of truth 
// one declarative class — that's it
export class Book extends BaseModel {
  static attributes = {
    title:        string().required(),
    theme_id:     enum(Theme),
    duration_min: integer().range(30, 180),
    summary:      text().embed(),
  }
  static filters = { theme_id, duration_min }
  static api = { base: '/api/v1/books' }
}
↳ derives 6 surfaces
derived surfaces generated · 0 lines hand-written
prompt BookPrompt sections · validation · askPrompts →
tools 5 CRUD tools list · find · create · update · delete →
search SearchService theme_id, duration_min · paginated →
analysis AnalysisMemories pgvector · 384-dim · k=24 →
oauth OAuth 2.0 PRM · DCR · authorize · token →
app ui://book/create fieldsets · two-column layout →
FOUNDING ADOPTER
Seat 01
SEAT 01 OPEN
SEAT 02 OPEN
SEAT 03 OPEN
Three founding seats. Lifetime LTS, direct line to the maintainer, vote on every RFC.
Read the charter →
§ FRAMEWORKSIX PILLARS

One spec. Six production surfaces.

Each pillar is generated from the same attributesConfig. No duplicated config. No glue. No drift between agent, UI, and API.

polymorphic crud 10 models · still 8 tools
YOUR MODELS · N
📖 Book
◐ User
◇ Project
▤ Order
▣ Asset
◉ Activity
▦ Invoice
◈ Team
◔ Comment
◇ Tag
8 polymorphic tools
TOOLS · 8 (CONSTANT)
list_models
find_records
create_model
update_model
delete_model
search_records
get_filters_guide
bulk_action_models
01 POLYMORPHIC CRUD

Eight tools serve every model in your domain.

Most MCP frameworks scale tool count with model count — 10 models × 5 verbs = 50 handlers, a tool list that overflows the picker, and an LLM that struggles to choose. mcp-rune keeps the surface flat: eight polymorphic tools accept the model name as a parameter and dispatch to the right resolver. Add the hundredth model — the tool list still reads list_models, find_records, create_model.

  • ✓ Compound IDs for nested resources — titles/42/assets/7 — no separate nested tools
  • ✓ Bulk operations built-in — bulk_action_models handles batch create / update / delete
  • ✓ Category-driven auth — tools declare DATA / STRATEGY / DOMAIN — the framework infers requirements
prompt strategies strategy: hybrid
THREE STRATEGIES · ONE API
stateless < 10 fields
getDocumentation
hybrid 10–20 fields ● ACTIVE
getDocumentationvalidateFieldsgenerateSummary
stateful 20+ fields
+ validateSection+ getProgress
validateSection · in_progress 5/7
✓
identity
title, author
✓
classification
theme, tags
✓
reading_status
status, started_at
✓
metrics
rating, pages_read
!
narrative
summary too short (4 words)
○
lending
borrower_id, due_date
○
review
review_text, would_recommend
↳ generated from fieldGroups + derivePromptSchema(Book)
02 PROMPT STRATEGIES

Make a 25-field form fillable by an agent.

How does an LLM correctly fill a long form? Most servers don't try. mcp-rune ships three strategies — stateless, hybrid, and stateful — that adapt validation UX to form complexity. The hybrid path validates fields and generates summaries on demand; the stateful path walks the agent through one section at a time, reporting progress and catching errors before the final write.

  • ✓ derivePromptSchema(Model) — fieldDefinitions come straight from your model spec
  • ✓ fieldGroups + sections — tell the agent which fields belong together and why
  • ✓ PromptContentGenerator pipeline — flow diagram → guidance → sections → summary → reference tables
interactive mcp apps
Bookshelf · MCP host
ui://book/create
Add "Designing Data-Intensive Applications" to my reading list — Kleppmann, I'm about halfway through.
k
Got it. Drafted a record — review the fields below and save when you're happy. · create_model / book
+ Create book schema-driven · two-column
Designing Data-Intensive Applications
Martin Kleppmann
reading ▾
★★★★★
312 / 624
5 of 5 required fields complete
rendered by ui://book/create · same schema as form / list / detail / search
03 INTERACTIVE MCP APPS

Schema-driven UI rendered inside the host.

Tools handle text. Apps render real interactive UI — forms, lists, detail views, search, autocomplete pickers, multi-selects — inside Claude Desktop, Cursor, VS Code, anywhere that speaks the MCP Apps extension. Six generic factories cover the surface; adding a new model form is one registry entry and zero new HTML. The same attributesConfig powers the tools, prompts, and apps — so they never drift.

  • ✓ Six app types — Model Form · List View · Record Detail · Search View · Autocomplete · Multi-Select
  • ✓ Two-column / sectioned layouts — derived from fieldGroups; no per-model markup
  • ✓ Live association lookups — autocomplete pickers fetch through the same EndpointResolver
analysis memories pgvector · 384-dim · all-MiniLM-L6-v2
FIVE-TOOL PIPELINE
ingest query act store clear
analysis_ingest ● done · 6.4s
12,847 records
from FeedbackRecord · batched 256 · embedded title+summary
analysis_act aggregates, filters, and stratifies findings — no records cross the context boundary.
analysis_query k=24 · clusters
"group customer feedback by theme, last 90 days"
performance
1,243
billing
982
integrations
741
onboarding
516
mobile-ux
402
docs
287
persisted · 1h TTL 6 of 24 shown
04 ANALYSIS MEMORIES

Map-reduce thousands of records — without the context window.

Asking an agent "what are people complaining about this quarter?" doesn't fit in 100k tokens. mcp-rune's analysis layer ingests entire datasets into local pgvector, groups them into themes, and returns aggregates — counts, distributions, clusters — instead of raw rows. The agent acts on findings, not on records. Five tools cover the whole loop: ingest, query, act, store, clear.

  • ✓ analysis_ingest — batch records by 256, embed with all-MiniLM-L6-v2, 1h TTL by default
  • ✓ analysis_query + analysis_act — cluster, filter, stratify, count — without flooding context
  • ✓ analysis_store — promote a finding from ephemeral to persistent for cross-session use
domain intelligence suggest_workflow · check_business_rules
workflow onboard_new_user get_workflow_step · suggest_workflow
✓ create_user
create_model · user
2 assign_role
update_model · user
3 send_welcome
send_notification
rules check_business_rules
✓ email is unique across organization
✓ role.level ≤ inviter.role.level
✕ inviter still has open seats (used 12/10)
✓ department exists in directory
knowledge get_domain_context
"seat"
A licensed user slot on a workspace plan. Seats are billed monthly per workspace; reassigning a seat closes the previous user's sessions within 24h.
#billing#identity#workspaces
05 DOMAIN INTELLIGENCE

Workflows, business rules, and knowledge agents can read.

A clean MCP server still leaves the agent to guess your business logic. The Domain module lets you encode it explicitly: WorkflowDefinition for multi-step operations, business rules the agent validates before write, and a knowledge store for terminology and policy. suggest_workflow lets the agent ask the framework what to do next.

  • ✓ Workflows — declarative step graphs; get_workflow_step walks the agent through
  • ✓ check_business_rules — preflight validation against your domain invariants
  • ✓ get_domain_context — definitions, synonyms, links — surface the vocabulary on demand
oauth 2.1 + pkce openid-client · audience-restricted
FLOW · DISCOVERY → AUTHORIZE → TOKEN → INTROSPECT
01 Discovery
GET /.well-known/oauth-protected-resource
RFC 9728 · returns resource + auth server URLs
02 Authorize
GET /oauth/authorize?code_challenge=…&resource=…
RFC 7636 PKCE · RFC 8707 resource indicator
03 Token
POST /oauth/token
Returns aud-restricted token · refresh in background
introspect → { active: true, aud: "https://mcp.example.com/mcp", scope: "read write" }
✓ aud matches resourceUri · token cached 60s · LRU 100
RFC 7662 · 8707
IMPLEMENTED: RFC 6749RFC 7591RFC 7636 (PKCE)RFC 7662RFC 8414RFC 8707RFC 9728CIMD draftOIDC Core 1.0
06 OAUTH 2.1 + PKCE

Production OAuth — discovery, DCR, PKCE, audience-restricted tokens.

Built on openid-client with mandatory PKCE on every flow. Discovery via RFC 9728 + 8414. Dynamic Client Registration via RFC 7591, or use a Client ID Metadata Document with no pre-shared secret. RFC 8707 resource indicators bind tokens to your server's audience — preventing token-confusion attacks across services.

  • ✓ Three client strategies — pre-registered · DCR · CIMD — your call
  • ✓ Audience-restricted tokens — aud is checked on every request; mismatched tokens are rejected
  • ✓ Cached introspection — 60s TTL, 100-entry LRU — auto refresh with 5-minute buffer
ARCHITECTURE

Five layers, bottom up.

Data flows from your model config up through grouping, documentation, assembly, and behavior. Each layer is replaceable — and nothing duplicates.

L5
Behavioral generateStatefulGuidanceInstructions() · turn-taking · validation · mode selection
L4
Assembly PromptContentGenerator.build() · composes all layers into final promptContent
L3
Section Docs per-section field tables, enum tables, content notes
L2
Grouping sections + fieldGroups · workflow structure, field organization
L1
Schema Derivation derivePromptSchema() · fieldDefinitions from model attributes
↑ data flows bottom-up · model config → field definitions → grouped sections → assembled docs → behavior

Ship a complete MCP server.
By lunch.

Scaffold a project, generate your first model, and run it locally in one terminal session. Auth, search, prompts, and apps all come along.

Read the quickstart → ★ Star on GitHub
r mcp-rune v0.1.0-alpha · MIT · 2026
DocsCLIAPIAdoptersGitHubChangelog