@mcp-rune/mcp-rune

mcp-rune.dev

Documentation · Quickstart · Examples · Discord · GitHub

Building an MCP server by hand means writing N tool handlers, N schemas,
OAuth from scratch, and an agent that still guesses your business rules.

mcp-rune derives all of that from one model definition. Define your models once —
it derives the prompts, tools, apps and docs an agent needs, then indexes your
whole dataset so the agent retrieves by meaning, not raw rows.
One spec, an entire server.

Install

npm install @mcp-rune/mcp-rune

New here? Start with the Quickstart — a real MCP server running in under ten minutes, no database or backend required.

Want to poke at a running example first? Scaffold the bookshelf example with one command — a 30-line model, a complete server:

npx @mcp-rune/create new my-app --template bookshelf

A taste

Write a model. That's the spec.

import { BaseModel } from '@mcp-rune/mcp-rune'

export class Book extends BaseModel {
  static override attributes = {
    title: { type: 'string', required: true },
    author: { type: 'string', required: true },
    status: { type: 'enum', values: ['reading', 'done'] },
    rating: { type: 'integer', validation: { min: 1, max: 5 } }
  }
}

From that one declaration, mcp-rune registers the full agent surface — and the tool list does not grow as you add models:

• Generic CRUD tools — list_models, find_records, create_model, update_model, delete_model cover every model you define.
• Prompts agents can follow — sections, validation, enum tables and turn-taking, derived from your attributes.
• Interactive MCP Apps — schema-driven create/edit/search UIs rendered inside Claude Desktop. No per-model HTML.
• OAuth 2.0, spec-compliant — discovery the way Inspector and strict clients expect (RFC 6749 / 8414 / 8707 / 9728).
• Docs, generated — every model and tool documents itself.

Both TypeScript and JavaScript are first-class — every example in the docs ships in both.

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, filter, or stratified sample. The agent reasons over findings, never the whole table.

• Recall by meaning — page summaries and stored findings are embedded with all-MiniLM-L6-v2 (384-dim) into local pgvector; the semantic mode ranks by cosine distance, no keywords.
• Walk the relationships — multi-hop ingest follows associations across models and stores the edges; the GraphRAG-aware summary strategies read that graph, not just flat fields.
• Grounded in your terms — a registry of concepts and business rules grounds every finding in your vocabulary.
• Act without re-exposing — analysis_act mutates a filtered subset server-side; matched IDs never return to the agent's context.

Six tools — analysis_ingest · analysis_query · analysis_store · analysis_act · analysis_summarize · analysis_clear — opt-in via ANALYSIS_ENABLED=true. Off by default — nothing loads, nothing runs, no startup cost until you turn it on. Local embeddings: no external vector DB, no embedding API.

Documentation

Visit the official documentation for the full guide library. Good places to start:

• Quickstart — your first server in ten minutes
• Project structure — where models, prompts, tools and apps live
• Prompt creation — the DSL that turns attributes into agent-fillable forms
• MCP Apps — interactive HTML UIs inside the client
• Analysis & GraphRAG — bring up pgvector and query thousands of records by meaning
• Data layer — the seam between the framework and any backend

Support

Having trouble? Ask in the official mcp-rune Discord — the community is happy to help you get unstuck.

For partnerships, security reports, or anything 1:1, email [e-mail].

Contributing

New contributors welcome! Check out the Contributors Guide to get started, then browse the good first issues.

Join us on Discord to meet other contributors — we'll help you land your first contribution in no time.

License

MIT © the mcp-rune authors. No telemetry. Self-hosted by default.

_{Built in the open · Star us on GitHub ✦}