superlore

The company knowledge base your agents run on.

Your agents turn specs, transcripts, and brainstorms into rich, structured docs — canvases, boards, timelines — that compound into one company knowledge base every agent can read over MCP.

One corpus. Humans and agents.

Open source · MCP-native · Deploy anywhere

What is superlore

Half your docs are read by agents now, not people. Every other tool just bolts an MCP onto the old way of writing them — serving scraped, lossy HTML instead of the structured source. superlore rethinks the document itself, for a world where AI writes, reads, and maintains it.

You author your knowledge once, in MDX, and the same structured content becomes two things at the same time:

• Humans get a clean, interactive, visual knowledge base — whiteboards, boards, timelines, entity cards, tables, and diagrams that make complex knowledge legible at a glance. Not flat pages.
• Agents get a built-in MCP server over the same source — clean, typed, structured knowledge they search and read directly. Not a screenshot of a component; the data behind it.

The board a human sees IS the typed graph an agent reads — queryable structure, not a flat image.

This is the non-negotiable idea: every component is dual-representation. It renders for people and serializes for agents, from one authored instance. No second authoring step. No drift.

        author + deploy                          consume
   you ──────────────▶  superlore KB (MDX)  ──────────────▶  agents (MCP)
   (via agent skills)        │
                             └──────────────▶  humans (visual site)

The money shot: one block, two faces

Write a single fenced superlore-canvas block in your MDX:

```superlore-canvas
{
  "title": "URL shortener",
  "direction": "right",
  "groups": [
    { "id": "edge", "label": "Edge", "frame": true, "intent": "gray" },
    { "id": "svc",  "label": "Services", "frame": true, "intent": "blue" },
    { "id": "data", "label": "Data", "frame": true, "intent": "green" }
  ],
  "nodes": [
    { "id": "gw",       "kind": "icon",     "icon": "shield", "label": "API gateway",     "group": "edge" },
    { "id": "create",   "kind": "rounded",  "label": "Shorten API",      "group": "svc" },
    { "id": "redirect", "kind": "rounded",  "label": "Redirect service", "group": "svc" },
    { "id": "hit",      "kind": "diamond",  "label": "Cache hit?",       "group": "svc" },
    { "id": "cache",    "kind": "cylinder", "label": "Redis cache",      "group": "data" },
    { "id": "db",       "kind": "cylinder", "label": "Links DB",         "group": "data" }
  ],
  "edges": [
    { "from": "gw",       "to": "create",   "label": "POST /shorten" },
    { "from": "gw",       "to": "redirect", "label": "GET /:slug" },
    { "from": "redirect", "to": "hit" },
    { "from": "hit",      "to": "cache",    "label": "yes" },
    { "from": "hit",      "to": "db",       "label": "no", "rel": "depends-on" }
  ]
}
```

Face 1 — the human surface. superlore auto-designs and auto-lays-out a polished, interactive whiteboard. No colours, sizes, or positions to pick. Drag nodes, drop stickies, hit Copy spec to round-trip your edits back to JSON.

Face 2 — the agent surface. The exact same block is a typed graph the MCP serves. An agent calls get_component_data("url-shortener") and gets the data, never the pixels:

{
  "kind": "diagram",
  "syntax": "canvas",
  "graph": {
    "nodes": [
      { "id": "gw", "kind": "icon", "label": "API gateway", "group": "edge" },
      { "id": "create", "kind": "rounded", "label": "Shorten API", "group": "svc" },
      { "id": "redirect", "kind": "rounded", "label": "Redirect service", "group": "svc" },
      { "id": "hit", "kind": "diamond", "label": "Cache hit?", "group": "svc" },
      { "id": "cache", "kind": "cylinder", "label": "Redis cache", "group": "data" },
      { "id": "db", "kind": "cylinder", "label": "Links DB", "group": "data" }
    ],
    "edges": [
      { "from": "gw", "to": "create", "label": "POST /shorten" },
      { "from": "gw", "to": "redirect", "label": "GET /:slug" },
      { "from": "redirect", "to": "hit" },
      { "from": "hit", "to": "cache", "label": "yes" },
      { "from": "hit", "to": "db", "label": "no", "rel": "depends-on" }
    ]
  }
}

Both lanes are derived from the same spec — they are provably one object, not a second, drifting mock-up.

Features

| | | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Dual-representation components | Canvas · Timeline · Board · EntityCard · Table · Decision · Comparison · Roster · Checklist · Releases · Schedule · Walkthrough — each renders for humans and serializes to a typed knowledge face for the MCP. | | The Canvas — FigJam, in code | Declare nodes, edges, and groups; superlore auto-designs and auto-lays-out an interactive whiteboard (React Flow + ELK), with a full shape library, sketch mode, edit-as-whiteboard, and a vertical library of templates. The board is the typed graph. | | MCP-native | Every superlore deploys an MCP server at /api/mcp over the same content the site renders — five first-class tools: search, get_page, list, navigate, get_component_data. Not a scrape; the structured index the site is built from. | | The Viewer | Drop in any .mdx and see it render live — boards, timelines, diagrams — with FigJam-style comments and export. No site, no build. | | Editor extension | superlore Preview for VS Code · Cursor · Windsurf: rich live preview of every component as you type, FigJam-style comment pins anchored in flow coordinates, and Copy to Agent — turn a review thread into a ready-to-paste prompt that closes the loop. | | One-config auth | Auth.js v5 + Google SSO, off by default. Flip it on with env vars — gate the whole site or just the MCP, restrict to a workspace domain or an email allowlist. The MCP inherits the same policy via proxy.ts; the two can never drift. | | Theme-equal design system | Light and dark are co-equal, derived from one token set, defaulting to system. Set one accent colour and the whole thing re-skins — for both themes. Flat, clean, no emoji in core UI. | | Deploy anywhere | It's MDX in your repo. Ship to Vercel, Cloudflare, or your own box — your knowledge stays yours. We never host your data. | | Agent skills | Ship-along skills so an agent can scaffold, author ("vibe"), and deploy a KB without ever learning how superlore works. | | Open source | Apache-2.0 licensed. |

Requirements

superlore is a component library, theme, and MCP server you drop into your docs app.

| | | | ------------ | ------------ | | Node | ≥ 20 | | Next.js | 16 | | React | 19 | | Fumadocs | ui + core 16 | | Tailwind | v4 |

superlore targets Next.js 16 — middleware is proxy.ts (not middleware.ts), and request APIs like cookies() / headers() are async. Don't port a Next 15-era snippet.

Quickstart

The fastest path is to let your agent build it — install the superlore plugin, then ask:

/plugin marketplace add KrishnanSG/superlore
/plugin install superlore@superlore

Make me a docs site with superlore

Your agent scaffolds the project, writes superlore.json, seeds pages, wires the MCP, and previews it. Prefer a terminal? curl -fsSL https://superlore.vercel.app/install.sh | sh, then superlore init.

Or add it to an app

npm i superlore

Import the theme — two lines. superlore/css bundles the base styles it sits on and registers its own components, so there's no @source to wire up:

@import "tailwindcss";
@import "superlore/css";

Wire the components in, and author MDX:

// mdx-components.tsx
import { getMDXComponents } from "superlore";

export function useMDXComponents(components) {
  return getMDXComponents(components);
}

---
title: Q3 Roadmap
summary: What ships this quarter and when.
tags: [roadmap]
---

<Timeline
  items={[
    { date: "2026-07-01", title: "Kickoff", status: "done" },
    { date: "2026-Q3", title: "GA launch", status: "planned" },
  ]}
/>

That single Timeline renders a polished, accessible list for humans and serializes to a structured { kind: "timeline", items: [...] } your agent reads over the MCP. You did not write the data twice — there is one source. The package ships subpath exports for each surface: superlore, superlore/mcp, superlore/auth, superlore/frontmatter, and superlore/css.

See Getting started for the full wiring (MCP route, frontmatter schema, auth).

MCP

Every superlore deploy exposes a Model Context Protocol server at /api/mcp over Streamable HTTP, serving the same structured index the site renders. Point any MCP-capable client at it:

{
  "mcpServers": {
    "superlore": {
      "type": "http",
      "url": "https://your-kb.dev/api/mcp"
    }
  }
}

It exposes five first-class tools over the typed content:

| Tool | Arguments | Returns | | -------------------- | -------------------------- | ------------------------------------------------------------- | | search | query, limit? | Ranked page hits across the corpus | | get_page | path | Frontmatter + ordered knowledge nodes for one page | | list | kind?, tag?, entityType? | Filtered knowledge nodes across the corpus | | navigate | target | Outgoing refs + backlinks — the corpus as a graph | | get_component_data | id | The typed data behind a single component (its knowledge face) |

If a deploy gates the site (Auth.js / SSO), the MCP inherits the same policy — gating the site automatically gates the agent surface. See the MCP docs.

Built with superlore

Shipped a knowledge base with superlore? Add the badge to your README:

[![Built with superlore](https://superlore.vercel.app/built-with-superlore.svg)](https://superlore.vercel.app)

The badge also lives at /built-with-superlore.svg on your own deploy — see Built with superlore for HTML and React snippets.

Project structure

This is a pnpm + Turbo monorepo.

| Path | What | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | packages/superlore/ | The core library — dual-representation components, theme, MCP server, auth, content model. Subpath exports: ., ./mcp, ./auth, ./frontmatter, ./css. | | templates/starter/ | The npm create superlore starter KB (planned). | | apps/docs/ | superlore's own docs, built with superlore — the canonical, MCP-enabled reference. | | extensions/vscode/ | superlore Preview — the VS Code / Cursor / Windsurf extension. | | skills/ | Agent skills shipped to consumers: Canvas authoring today; scaffold / author / deploy planned. | | brand/ | The Fold mark, colour tokens, and voice. | | docs/ | Internal project docs — architecture, roadmap. |

Documentation

| Doc | What | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | Getting started | Install, wire it into your app, author your first dual-representation page. | | Canvas | The FigJam-style whiteboard authored in MDX. | | Components | The full library, each with a live example and its knowledge face. | | Agents & MCP | The five tools, how to connect, and authoring for agents. | | Enabling auth | Gate the site (and the MCP) with Google SSO — optional, off by default. | | DESIGN.md | The visual system — colour tokens, type scale, components. |

Status

superlore is live. superlore and superlore-cli are on npm; the docs site (apps/docs) — itself built with superlore — runs the Canvas, the MCP server, and the Viewer in production, alongside a VS Code / Cursor / Windsurf extension. It's pre-1.0, so the public API can still shift between minor versions — pin a version and watch releases.

Contributing

superlore is built to go open and grow a community. Read CONTRIBUTING.md and the CODE_OF_CONDUCT.md, and see SECURITY.md to report a vulnerability. PRs welcome.

License

Apache-2.0 © Krishnan S G