mcp-rune 0.107.0
★ Be star #1 Get started →
mcp-rune
NEW v0.107.0-alpha · MCP Apps, OAuth 2.1, GraphRAG — all derived Read →

Turn your data model into a complete MCP server.

Every MCP integration starts the same way: hand-wiring route handlers, prompt templates, and auth flows for every model you ship. Declare your schema once — mcp-rune derives the tools, prompts, OAuth, search, and interactive UI that agents need.

Get started →
$ npm i @mcp-rune/mcp-rune
MIT — stays MIT Node 20+ / Bun TypeScript & JavaScript Zero external services Ship by lunch
THE PROBLEM
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.

Add OAuth, prompt templates, and search — and you're maintaining hundreds of files that all say the same thing your schema already says.

WITHOUT MCP-RUNE
WITH MCP-RUNE
✕ 10 models × 5 route handlers = 50 files
✓ 1 model definition per model
✕ Manual Zod schemas per route
✓ Derived from attributes
✕ OAuth wiring from scratch
✓ Built-in, spec-compliant OAuth 2.1
✕ Agent guesses your business rules
✓ Encoded in DomainRegistry
✕ Tool list grows with every model
✓ A fixed set of tools, regardless of model count
ONE SPEC → SIX SURFACES

Declare once. Derive everything.

~/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 →
retrieval GraphRAG index vectors · edges · domain · 5 modes →
oauth OAuth 2.0 PRM · DCR · authorize · token →
app ui://book/create fieldsets · two-column layout →
§ 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

A fixed tool set serves 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
RETRIEVAL · SEMANTIC GRAPH

Retrieval that understands
your domain.

Most MCP servers can only hand the agent raw rows. mcp-rune indexes an entire dataset three ways — vectors, a relationship graph, and your domain vocabulary — then answers by meaning, aggregate, or stratified sample. The agent reasons over findings, never the whole table.

tools/analysis · the GraphRAG loop opt-in · ANALYSIS_ENABLED=true
The retrieval / GraphRAG pipeline: analysis_ingest auto-paginates an API model into offline storage; records are indexed as vectors (MiniLM 384-dim pgvector), edges (multi-hop relationship graph) and domain grounding; analysis_query answers in five modes (describe, aggregate, filter, sample as SQL; semantic as cosine recall) with nine summary strategies; the LLM stores recallable findings and synthesises the answer with zero raw rows in context.
vectors

Recall by meaning

Every page summary and stored finding is embedded with all-MiniLM-L6-v2 (384-dim) into local pgvector. The semantic mode ranks by cosine distance — "rule failures about rating" finds the right memory, no keywords.

analysis_query · mode: semantic
graph

Walk the relationships

Multi-hop ingest follows associations across models and stores the edges. The four GraphRAG-aware strategies — relationship-coverage, concept-touch — read that graph, not just flat fields.

multi-hop ingest → edges[]
domain

Grounded in your terms

A registry of concepts and business rules grounds findings in your vocabulary. The rule-violation strategy evaluates every rule against every record and embeds the result as a queryable memory.

DomainRegistry · concepts · rules
map-reduce

Act without re-exposing

analysis_act mutates a filtered subset server-side — matched IDs never return to context. Five query modes; proximity sampling spreads a sample evenly across a date window.

describe · aggregate · filter · sample · semantic
SIX TOOLS
analysis_ingestanalysis_queryanalysis_storeanalysis_actanalysis_summarizeanalysis_clear
local embeddings · no external vector DB, no embedding API
MCP APPS · RENDERED, NOT DESCRIBED

Real interactive UI,
inside the host.

Six generic app factories turn the same model spec into forms, tables, detail views, search and pickers — rendered inside Claude Desktop and any MCP Apps host. These are the actual generated surfaces, on mcp-rune's default theme.

List view — list_records_app
List view table · multi-select
list_records_app

Sortable, multi-select table with filter chips, pagination, and a send-to-conversation selection bar.

Model form — update_model_form
Model form form · validation
update_model_form

Fields derived straight from attributesConfig — enums, numeric ranges, embedded text, required markers.

Autocomplete picker — autocomplete_picker
Autocomplete picker search · single-select
autocomplete_picker

Live association lookup with highlighted matches and keyboard pick — fetched through the same EndpointResolver.

Workflow launcher — workflow_panel
Workflow launcher launcher · grouped
workflow_panel

Grouped, browsable workflow cards the agent can run — wired to suggest_workflow and get_workflow_step.

One attributesConfig powers tools, prompts and apps — they never drift. Light + dark, host-adaptive. Zero per-model HTML. Explore the default app theme →
FOR TEAMS & API OWNERS

Your product already has a data model. Make it AI-accessible.

You don't think "I want to build an MCP server." You think "I want my product to work with Claude, Cursor, and Copilot." mcp-rune gives AI agents a first-class interface to your existing API — in a day, not a sprint.

◈ SaaS with an API

Expose your product to every AI host

Point mcp-rune at your existing REST API and data model. It generates the MCP surface — tools, prompts, OAuth, interactive forms — so Claude, Cursor, and any MCP-compatible host can work with your product natively.

schema → MCP server → every AI host
◇ Internal tools

Agents that understand your domain

Encode your business rules, workflows, and vocabulary in the DomainRegistry. The agent validates before it writes, follows your multi-step processes, and speaks your terminology — not generic CRUD.

DomainRegistry · workflows · rules
◉ Data platforms

Semantic search + analysis for any host

The retrieval layer indexes your dataset three ways — vectors, relationship graph, and domain grounding. Agents reason over findings, not raw rows. No external vector DB, no embedding API — local pgvector.

analysis_ingest · analysis_query · local
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
mcp-rune v0.107.0 · MIT · 2026
DocsCLIAPIAdoptersGitHubRoadmap