diff --git a/apps/docs/package.json b/apps/docs/package.json index 42e3501..8b85c61 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -14,6 +14,7 @@ }, "dependencies": { "@astrojs/starlight": "^0.41.4", + "@fold-run/tokens": "workspace:*", "astro": "^7.1.3", "lucide-astro": "^0.556.0", "sharp": "^0.35.3", diff --git a/apps/docs/src/content/docs/getting-started.mdx b/apps/docs/src/content/docs/getting-started.mdx index 1d59b7c..d8de132 100644 --- a/apps/docs/src/content/docs/getting-started.mdx +++ b/apps/docs/src/content/docs/getting-started.mdx @@ -99,3 +99,20 @@ walkthrough federates two servers behind one endpoint. then walk the [production checklist](/deployment/#production-checklist). + +## Next steps + +The on-ramp ends here; these are the four things most deployments reach for next. + +- [Configuration](/configuration/): every block you just wrote, field by field, plus the ones + you have not needed yet. +- [Security model](/security/): what fold trusts, what it refuses, and where a credential is + allowed to travel. Read this before the gateway faces anything real. +- [Deployment](/deployment/): the same config on Docker, Kubernetes or a VM, and the + [production checklist](/deployment/#production-checklist) that goes with it. +- [Operations](/operations/): hot reload, shared state across a fleet, metrics, traces, and + the health surfaces your probes want. + +If you would rather see it running before reading further, the +[live demo](/try-the-demo/) federates three public MCP servers behind one endpoint. + diff --git a/apps/docs/src/content/docs/index.mdx b/apps/docs/src/content/docs/index.mdx index f0d2d32..d721b22 100644 --- a/apps/docs/src/content/docs/index.mdx +++ b/apps/docs/src/content/docs/index.mdx @@ -1,54 +1,114 @@ --- title: fold description: The enterprise MCP gateway — one governed endpoint between every MCP client and every MCP server. -template: splash -hero: - title: The enterprise MCP gateway. - tagline: >- - One governed endpoint between every MCP client and every MCP server. - Federation, auth, policy, tenancy, budgets, and audit, built on the - official MCP Go SDK on both sides of the proxy. - actions: - - text: Get started - link: /getting-started/ - - text: Use cases - link: /use-cases/ - variant: secondary - - text: GitHub - link: https://github.com/fold-run/fold - variant: minimal --- -import { CardGrid } from '@astrojs/starlight/components'; +import { CardGrid, LinkCard } from '@astrojs/starlight/components'; import Card from '../../components/Card.astro'; -import { BadgeCheck, Container, Network, ShieldCheck } from 'lucide-astro'; +import { BookOpen, Rocket } from 'lucide-astro'; + +fold is a single Go binary that presents any number of upstream MCP (Model Context Protocol) +servers as one governed virtual server: one endpoint, one policy, one audit trail. It is built +on the official MCP Go SDK on both sides of the proxy, and the official conformance suite runs +through it on every merge. + +Before running it against anything that matters: + +1. **[Describe your upstreams](/configuration/)** in one config file, validated at load. +2. **[Put a policy in front of them](/security/)** — fold is deny-by-default, and an empty + allowlist denies everything. - - Register any number of upstreams — internal teams or vendors, any - language, any SDK. fold fans out lists, merges and namespaces results - (`gh__create_pr`), routes named calls to their owner, and degrades - gracefully when an upstream is down. Upstreams can even - [register themselves](/discovery/). - - - OAuth 2.0 resource server, Enterprise-Managed Authorization (ID-JAG), - RFC 8693 token exchange per upstream, deny-by-default allowlists with - per-principal visibility, and an audit event for every request — - including the denials. Group principals into - [tenants](/tenancy/) for a shared allowance, a shared rate-limit - bucket, and a bounded view of the federation. - - - The official MCP conformance suite runs through fold on every merge — - [40/40 checks](/conformance/), including sampling, elicitation, and - subscriptions bridged through the gateway — plus a CI gate on added - proxy latency (< 5 ms p50; ~0.2 ms typical). + + A governed endpoint in 60 seconds, from one config file and one binary. + + [Start here →](/getting-started/) - - A single ~22 MB distroless container or static Go binary. Hot config - reload without dropping the listener, Redis-shared state so a fleet - behaves as one, Prometheus metrics, OpenTelemetry tracing, and health - surfaces for your probes. [Operations →](/operations/) + + The same thing on your own machine, against upstreams you already have. + + [Run it →](/run-it-locally/) + +## Federate + + + + + + + + +## Govern + + + + + + + + +## Operate + + + + + + + + +## Everything else + +[Use cases](/use-cases/) is the shortest route to whether fold fits what you have. +[Defaults](/defaults/) lists every value fold picks for you and why. +[Embedding in Go](/embedding/) is for putting the gateway inside your own binary. +The source is on [GitHub](https://github.com/fold-run/fold) under Apache-2.0. diff --git a/apps/docs/src/styles/fold.css b/apps/docs/src/styles/fold.css index 9ddf62d..a9153e5 100644 --- a/apps/docs/src/styles/fold.css +++ b/apps/docs/src/styles/fold.css @@ -5,132 +5,31 @@ * current-page rail, the focus ring, the brand mark. Machined 0–2px radii. No * gradients; elevation by background-step, not shadow. */ -/* ===== fonts — self-hosted IBM Plex Sans (ITF free license) + Geist Mono (OFL) ===== */ -@font-face { - font-family: "Geist Mono"; - font-style: normal; - font-weight: 400; - font-display: swap; - src: url(/fonts/GeistMono-400-latin-ext.woff2) format("woff2"); - unicode-range: - U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF; -} -@font-face { - font-family: "Geist Mono"; - font-style: normal; - font-weight: 400; - font-display: swap; - src: url(/fonts/GeistMono-400-latin.woff2) format("woff2"); - unicode-range: - U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; -} -@font-face { - font-family: "Geist Mono"; - font-style: normal; - font-weight: 600; - font-display: swap; - src: url(/fonts/GeistMono-600-latin-ext.woff2) format("woff2"); - unicode-range: - U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF; -} -@font-face { - font-family: "Geist Mono"; - font-style: normal; - font-weight: 600; - font-display: swap; - src: url(/fonts/GeistMono-600-latin.woff2) format("woff2"); - unicode-range: - U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; -} -@font-face { - font-family: "IBM Plex Sans"; - font-style: normal; - font-weight: 400; - font-display: swap; - src: url(/fonts/IBMPlexSans-400-latin-ext.woff2) format("woff2"); - unicode-range: - U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF; -} -@font-face { - font-family: "IBM Plex Sans"; - font-style: normal; - font-weight: 400; - font-display: swap; - src: url(/fonts/IBMPlexSans-400-latin.woff2) format("woff2"); - unicode-range: - U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; -} -@font-face { - font-family: "IBM Plex Sans"; - font-style: normal; - font-weight: 500; - font-display: swap; - src: url(/fonts/IBMPlexSans-500-latin-ext.woff2) format("woff2"); - unicode-range: - U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF; -} -@font-face { - font-family: "IBM Plex Sans"; - font-style: normal; - font-weight: 500; - font-display: swap; - src: url(/fonts/IBMPlexSans-500-latin.woff2) format("woff2"); - unicode-range: - U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; -} -@font-face { - font-family: "IBM Plex Sans"; - font-style: normal; - font-weight: 600; - font-display: swap; - src: url(/fonts/IBMPlexSans-600-latin-ext.woff2) format("woff2"); - unicode-range: - U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF; -} -@font-face { - font-family: "IBM Plex Sans"; - font-style: normal; - font-weight: 600; - font-display: swap; - src: url(/fonts/IBMPlexSans-600-latin.woff2) format("woff2"); - unicode-range: - U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; -} -@font-face { - font-family: "IBM Plex Sans"; - font-style: normal; - font-weight: 700; - font-display: swap; - src: url(/fonts/IBMPlexSans-700-latin-ext.woff2) format("woff2"); - unicode-range: - U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF; -} -@font-face { - font-family: "IBM Plex Sans"; - font-style: normal; - font-weight: 700; - font-display: swap; - src: url(/fonts/IBMPlexSans-700-latin.woff2) format("woff2"); - unicode-range: - U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; -} +@import "@fold-run/tokens/fonts.css"; +@import "@fold-run/tokens/vars.css"; /* ===== Starlight custom fonts (documented custom-font pattern) ===== */ :root { --sl-font: "IBM Plex Sans", ui-sans-serif, sans-serif; --sl-font-mono: "Geist Mono", ui-monospace, monospace; } -/* ===== DARK (canonical) — Starlight styles dark via bare :root ===== */ +/* ===== DARK (canonical) — Starlight styles dark via bare :root ===== + * Values come from @fold-run/tokens; this block only maps them onto + * Starlight's variable system, so a colour changes in one place for both + * origins. The two exceptions are called out below. */ :root { /* neutral ramp: Signal → Backplane */ - --sl-color-white: #ffffff; /* Signal (18.73:1 on Backplane) */ - --sl-color-gray-1: #e0e0e0; /* Carrier */ - --sl-color-gray-2: #bcbcbc; /* Static — body text (9.86:1) */ + --sl-color-white: var(--color-fg); /* Signal (18.73:1 on Backplane) */ + --sl-color-gray-1: var(--color-carrier); /* Carrier */ + --sl-color-gray-2: var(--color-static); /* Static — body text (9.86:1) */ + /* gray-3/gray-4 are Starlight ramp intermediates with no counterpart in the + * site's token contract: fold-line is #6e6e6e and trace-hi #3d3d3d, neither + * of which is these. Mapping them would move pixels, so they stay local. */ --sl-color-gray-3: #8a8a8a; --sl-color-gray-4: #4d4d4d; - --sl-color-gray-5: #2b2b2b; /* Trace — hairlines */ - --sl-color-gray-6: #1a1a1a; /* Rack — panels, nav, sidebar */ - --sl-color-black: #121212; /* Backplane — page ground */ + --sl-color-gray-5: var(--color-trace); /* Trace — hairlines */ + --sl-color-gray-6: var(--color-rack); /* Rack — panels, nav, sidebar */ + --sl-color-black: var(--color-bg); /* Backplane — page ground */ /* ===== accents ===== * Live is licensed to proof only, exactly as on the site: the current-page @@ -139,19 +38,19 @@ * affordance the colour used to carry. A docs page is mostly links; when * every one of them was Live the accent stopped meaning anything, and the * body copy had to compete with a field of chartreuse. */ - --sl-color-accent-low: #2b2b2b; /* neutral surface tint */ - --sl-color-accent: #ffffff; - --sl-color-accent-high: #e0e0e0; - --sl-color-text-accent: #ffffff; /* links, current nav — 18.7:1 */ - --sl-color-bg-accent: #ffffff; /* buttons… */ - --sl-color-text-invert: #121212; /* …carry ink text (18.7:1) */ + --sl-color-accent-low: var(--color-trace); /* neutral surface tint */ + --sl-color-accent: var(--color-action); + --sl-color-accent-high: var(--color-carrier); + --sl-color-text-accent: var(--color-action); /* links, current nav — 18.7:1 */ + --sl-color-bg-accent: var(--color-action); /* buttons… */ + --sl-color-text-invert: var(--color-action-ink); /* …carry ink text (18.7:1) */ - --fold-live: #d6ff00; /* proof, status, focus — never an action */ + --fold-live: var(--color-accent); /* proof, status, focus — never an action */ /* hairlines are Trace, everywhere */ - --sl-color-hairline-light: #2b2b2b; - --sl-color-hairline: #2b2b2b; - --sl-color-hairline-shade: #121212; + --sl-color-hairline-light: var(--color-trace); + --sl-color-hairline: var(--color-trace); + --sl-color-hairline-shade: var(--color-bg); /* flat by conviction: no shadows on dark */ --sl-shadow-sm: none; @@ -159,13 +58,13 @@ --sl-shadow-lg: none; /* machined corners for the search UI */ - --sl-search-corners: 2px; + --sl-search-corners: var(--radius); /* fold-local tokens (theme-flipped below) */ --fold-rail: var(--fold-live); /* current-page rail — a licensed Live use */ - --fold-rail-fill: #1a1a1a; /* current-page fill: Rack */ - --fold-inline-code-bg: #1a1a1a; /* Rack */ - --fold-inline-code-border: #2b2b2b; /* Trace */ + --fold-rail-fill: var(--color-rack); /* current-page fill: Rack */ + --fold-inline-code-bg: var(--color-rack); /* Rack */ + --fold-inline-code-border: var(--color-trace); /* Trace */ } /* ===== LIGHT — Paper ground, ink ramp, AA Live Ink ===== @@ -219,7 +118,7 @@ --ec-brdRad: 1px; --ec-brdCol: var(--sl-color-hairline); --ec-frm-frameBoxShdCssVal: none; - --ec-codeBg: #1a1a1a; /* Rack — code surfaces */ + --ec-codeBg: var(--color-rack); /* Rack — code surfaces */ } :root:root[data-theme="light"] { --ec-codeBg: #f6f6f6; @@ -268,10 +167,31 @@ button[data-open-modal] { } /* ===== quiet, technical detailing kept from the previous theme ===== */ -/* Tables read as ledgers: hairlines, no zebra shouting. */ +/* Tables read as ledgers: 12px muted headers, a hairline under every row, no + vertical rules and no zebra. The comment above these has claimed this for a + while; only the font-size was actually set. Same grammar as the site's + proof band and capability index — rows separated by rules, nothing boxed. */ .sl-markdown-content table { + border-collapse: collapse; font-size: var(--sl-text-sm); } +.sl-markdown-content th { + font-size: 0.75rem; + font-weight: 500; + color: var(--sl-color-gray-2); + border: 0; + border-bottom: 1px solid var(--sl-color-hairline); + padding: 0.5rem 0.75rem; + text-align: left; +} +.sl-markdown-content td { + border: 0; + border-bottom: 1px solid var(--sl-color-hairline); + padding: 0.5rem 0.75rem; +} +.sl-markdown-content tr:nth-child(2n) { + background-color: transparent; +} /* fold cards (custom Card.astro): full styling, both themes */ .sl-markdown-content .card { @@ -288,7 +208,7 @@ button[data-open-modal] { --fold-card-bg: #f6f6f6; } :root:not([data-theme="light"]) .sl-markdown-content .card { - --fold-card-bg: #1a1a1a; + --fold-card-bg: var(--color-rack); } .sl-markdown-content .card .title { display: flex; @@ -368,3 +288,110 @@ a.sl-link-button.secondary { .sl-markdown-content .card .title .icon svg { color: var(--sl-color-gray-3); } + +/* ===== content typography ===== + * DESIGN.md §3 asks for `text-wrap: balance` on h1-h4 and `pretty` on prose, + * and for a 70ch measure. The site does all three; the docs did none of them, + * so a heading could strand one word on its own line and a paragraph ran the + * full width of a wide viewport. */ +.sl-markdown-content :is(h1, h2, h3, h4), +h1[data-page-title] { + text-wrap: balance; +} +.sl-markdown-content { + text-wrap: pretty; +} + +/* Direct children only. A measure on the container would drag tables, code + blocks and card grids in with the prose; those want the full column. */ +.sl-markdown-content > p, +.sl-markdown-content > ul, +.sl-markdown-content > ol, +.sl-markdown-content > blockquote { + max-width: 70ch; +} + +/* ===== group labels ===== + * The sidebar's group headings and the table of contents heading take the + * site's label rank: 11px tracked caps in Static. Static rather than gray-3 + * (#8a8a8a): at this size that is 4.4:1 on Rack, and a heading is text. + * Without this the group label sat at the same weight and size as the page + * links under it, so the sidebar read as one flat list of nineteen items. */ +.sidebar-content summary .group-label .large, +.right-sidebar-panel h2 { + font-size: 0.6875rem; + font-weight: 500; + text-transform: uppercase; + letter-spacing: 0.05em; + /* gray-2, not --color-static: the shared token carries the dark value only, + because Phase 1 left the hand-tuned light ramp local to this file. Static + on Paper is 1.7:1. gray-2 flips with the theme and holds AA in both. */ + color: var(--sl-color-gray-2); +} +.sidebar-content summary { + padding-block: 0.35rem; +} + +/* ===== search ===== + * The same machined field the site's controls use, rather than Starlight's + * default. Below Starlight's 50rem breakpoint the control collapses to an + * icon: a true square with the glass centred, not a squashed capsule. + * + * The doubled attribute is the same trick the Expressive Code block above + * uses. Starlight styles this control with + * `button:where(.astro-pqodzqrd)[data-open-modal]`; `:where()` contributes no + * specificity, so that rule *ties* a plain `button[data-open-modal]` and the + * winner is decided by injection order — which is not something this file + * should depend on. Doubling the attribute outranks it outright without + * widening what the selector matches. */ +button[data-open-modal][data-open-modal] { + border: 1px solid var(--sl-color-hairline); + border-radius: 2px; + background-color: var(--sl-color-gray-6); + color: var(--sl-color-gray-2); + font-size: var(--sl-text-sm); + transition: + border-color 0.15s cubic-bezier(0.25, 1, 0.5, 1), + color 0.15s cubic-bezier(0.25, 1, 0.5, 1); +} +button[data-open-modal][data-open-modal]:hover { + border-color: var(--sl-color-gray-4); + color: var(--sl-color-white); +} +button[data-open-modal][data-open-modal] kbd { + background-color: transparent; + border: 1px solid var(--sl-color-hairline); + border-radius: 2px; + font-family: var(--sl-font-mono); +} +@media (max-width: 49.9375rem) { + button[data-open-modal][data-open-modal] { + width: 2.5rem; + height: 2.5rem; + padding: 0; + align-items: center; + justify-content: center; + } +} +@media (min-width: 50rem) { + button[data-open-modal][data-open-modal] { + height: 2rem; + padding-block: 0; + align-items: center; + } +} + +/* Search dialog: a hairline panel on Backplane, no shadow (DESIGN.md §4). */ +dialog[aria-label="Search"] { + background-color: var(--sl-color-black); + border: 1px solid var(--sl-color-hairline); + box-shadow: none; +} +dialog[aria-label="Search"]::backdrop { + background-color: color-mix(in srgb, #000 60%, transparent); +} +@media (min-width: 50rem) { + dialog[aria-label="Search"] { + border-radius: 2px; + } +} diff --git a/apps/site/astro.config.mjs b/apps/site/astro.config.mjs index 3ab6007..c2050ea 100644 --- a/apps/site/astro.config.mjs +++ b/apps/site/astro.config.mjs @@ -1,6 +1,34 @@ // @ts-check +import mdx from '@astrojs/mdx'; +import sitemap from '@astrojs/sitemap'; import { defineConfig } from 'astro/config'; +import rehypeAutolinkHeadings from 'rehype-autolink-headings'; +import rehypeSlug from 'rehype-slug'; +import { rehypeHeadingId } from './rehype-heading-id.mjs'; export default defineConfig({ site: 'https://fold.run', + integrations: [mdx(), sitemap()], + markdown: { + // Off deliberately. The posts were authored with straight quotes, and + // SmartyPants both changes them under us and gets them wrong: it read an + // opening quote after an em dash as a closing one, printing ”not mine”. + smartypants: false, + // Posts used to carry hand-written `id`s and a literal `#` anchor on every + // heading, which meant a renamed heading silently broke its own deep link. + // These generate the same markup from the heading text instead. + rehypePlugins: [ + // Before rehype-slug, which only fills in an id when one is absent. + rehypeHeadingId, + rehypeSlug, + [ + rehypeAutolinkHeadings, + { + behavior: 'append', + properties: { class: 'h-anchor', ariaLabel: 'Link to this section' }, + content: { type: 'text', value: '#' }, + }, + ], + ], + }, }); diff --git a/apps/site/package.json b/apps/site/package.json index 4532bdd..4480f07 100644 --- a/apps/site/package.json +++ b/apps/site/package.json @@ -12,10 +12,17 @@ "deploy": "astro build && wrangler deploy" }, "dependencies": { - "astro": "^7.1.3" + "@astrojs/mdx": "^7.0.8", + "@astrojs/rss": "^4.0.19", + "@astrojs/sitemap": "^3.7.3", + "@fold-run/tokens": "workspace:*", + "astro": "^7.1.3", + "rehype-autolink-headings": "^7.1.0", + "rehype-slug": "^6.0.0" }, "devDependencies": { "typescript": "^6.0.3", + "unist-util-visit": "^5.1.0", "wrangler": "catalog:" } } diff --git a/apps/site/rehype-heading-id.mjs b/apps/site/rehype-heading-id.mjs new file mode 100644 index 0000000..3b81833 --- /dev/null +++ b/apps/site/rehype-heading-id.mjs @@ -0,0 +1,26 @@ +import { visit } from 'unist-util-visit'; + +/** + * Lets a Markdown heading pin its own slug: `## Some long title {#short-id}`. + * + * rehype-slug derives an id from the heading text, which is right for new + * headings and wrong for the ones migrated out of the hand-written posts — + * those carried shorter ids than their text would generate, and a fragment is + * the one kind of link a server cannot redirect. Pinning the legacy id keeps + * every published deep link working. + * + * Runs before rehype-slug, which only assigns an id when one is absent. + */ +export function rehypeHeadingId() { + return (tree) => { + visit(tree, 'element', (node) => { + if (!/^h[1-6]$/.test(node.tagName)) return; + const last = node.children.at(-1); + if (last?.type !== 'text') return; + const m = last.value.match(/^([\s\S]*?)\s*\{#([\w-]+)\}\s*$/); + if (!m) return; + last.value = m[1]; + node.properties = { ...node.properties, id: m[2] }; + }); + }; +} diff --git a/apps/site/src/components/Closing.astro b/apps/site/src/components/Closing.astro new file mode 100644 index 0000000..5abeb06 --- /dev/null +++ b/apps/site/src/components/Closing.astro @@ -0,0 +1,42 @@ +--- +// The closing CTA band that ends every page. It was written out four times, +// byte for byte, across the home page, the blog index and both posts; the copy +// is the same on all of them because it is the site's one ask. +// +// Styles are the global `.closing` recipe in styles/primitives.css rather than +// scoped here, because the band is full-bleed and its rules interlock with the +// footer hairline directly below it. +import { LINKS } from '../lib/nav'; + +interface Props { + /** Override the heading where a page has earned a more specific ask. */ + heading?: string; + cta?: string; + href?: string; +} + +const { + heading = 'Start where it hurts.', + cta = 'Get started', + href = `${LINKS.docs}/getting-started/`, +} = Astro.props; +--- + +
+
+

{heading}

+

+ + A single passthrough upstream in front of your most-used server is one config file away. + Governance grows from there. + +

+ {cta} +
+
diff --git a/apps/site/src/components/CodePanel.astro b/apps/site/src/components/CodePanel.astro new file mode 100644 index 0000000..49bfeef --- /dev/null +++ b/apps/site/src/components/CodePanel.astro @@ -0,0 +1,40 @@ +--- +// The signature code surface: Rack ground, machined 2px corner, a context tag, +// and a copy affordance — the three things DESIGN.json names as this +// component's constraint. The blog shipped the first two only: the copy button +// and its handler lived in index.astro and never reached those pages. The +// handler now sits in Base.astro, so every panel on the site gets it. +// +// Code arrives as a string prop rather than as children, and it is the only +// shape that survives both callers. Astro collapses whitespace in slotted +// children, and MDX markdown-parses the children of a multi-line JSX block, so +// a
 spanning a blank line is torn in half. A prop is inert to both.
+// The value is HTML: the highlight spans (.k keyword, .c comment) are authored
+// by hand, because DESIGN.md keeps syntax on the neutral ramp rather than
+// letting a highlighter spend a second accent.
+
+interface Props {
+  /** Context tag, top-left: a filename, a language, or what the block is. */
+  tag: string;
+  /** Describes the block for a reader tabbing through the scroll region. */
+  label: string;
+  /** Pre-highlighted HTML. Newlines and indentation are preserved verbatim. */
+  code: string;
+  /** Set false for a block that is a drawing rather than something runnable. */
+  copy?: boolean;
+}
+
+const { tag, label, code, copy = true } = Astro.props;
+---
+
+
+
+ {tag}{ + copy && ( + + ) + } +
+
diff --git a/apps/site/src/content.config.ts b/apps/site/src/content.config.ts new file mode 100644 index 0000000..9cf5889 --- /dev/null +++ b/apps/site/src/content.config.ts @@ -0,0 +1,36 @@ +import { defineCollection, z } from 'astro:content'; +import { glob } from 'astro/loaders'; + +// Posts and changelog entries were previously hard-coded: the blog index kept +// its own list of `.post-row` items ("Add new posts as .post-row items in the +// list below"), and nothing else on the site knew a post existed. These +// collections are what let the index, the feed, the sitemap and llms.txt all +// render from one source. +const blog = defineCollection({ + loader: glob({ base: './src/content/blog', pattern: '**/*.mdx' }), + schema: z.object({ + title: z.string(), + description: z.string(), + /** Publication date; also the sort key and the feed's pubDate. */ + date: z.coerce.date(), + category: z.string().default('engineering'), + /** The index's one-line pitch. Falls back to `description`. */ + teaser: z.string().optional(), + /** Absolute-from-root social card. A post wants one that names the post. */ + ogImage: z.string().optional(), + draft: z.boolean().default(false), + }), +}); + +const changelog = defineCollection({ + loader: glob({ base: './src/content/changelog', pattern: '**/*.md' }), + schema: z.object({ + /** Release date, newest first. */ + date: z.coerce.date(), + title: z.string(), + /** The gateway version this entry ships, when it names one. */ + version: z.string().optional(), + }), +}); + +export const collections = { blog, changelog }; diff --git a/apps/site/src/content/blog/federating-mcp-tasks.mdx b/apps/site/src/content/blog/federating-mcp-tasks.mdx new file mode 100644 index 0000000..7a9f76c --- /dev/null +++ b/apps/site/src/content/blog/federating-mcp-tasks.mdx @@ -0,0 +1,140 @@ +--- +title: "Federating MCP tasks: affinity routing over opaque ids" +description: "The MCP tasks extension standardized long-running work \u2014 and task ids outlive any session. Putting one gateway in front of N task-running servers forces an ownership problem, and the solution generalizes." +date: 2026-08-04 +category: engineering +ogImage: /og/federating-mcp-tasks.png +--- + +{/* +// Every number and permalink below resolves to something a hostile reader +// can click. Publish = site deploy. Markup from the approved stardust +// redesign (stardust/migrated/blog/federating-mcp-tasks/index.html). +*/} + +import CodePanel from '../../components/CodePanel.astro'; +import { WORDMARK_PATH, wordmarkTransform } from '../../lib/wordmark'; + +{/* Source permalinks are pinned to the commit the post describes, so a later + refactor cannot silently repoint them at unrelated lines. */} +export const SHA = '5173174afc90efb57f1ccae78cf59d6d3ab3a30a'; + +The MCP [tasks extension](https://modelcontextprotocol.io/seps/1686) standardized long-running work: a tool call mints a task, and the client polls it with nothing but an opaque id — across requests, sessions, even processes. That's great news for clients — and a real problem for anything in the middle. This post is about what task ids do to a gateway fronting N task-running servers, and the mechanism that solves it. Everything below ships in [fold](https://github.com/fold-run/fold), the open-source enterprise MCP gateway, and every claim links to the code. + +## The problem, concretely + +fold presents many MCP servers as one governed virtual server: one endpoint, one merged tool list, namespaced names (`gh__create_pr`, `jobs__start_job`). + + + +A client calls `jobs__start_job`; the task is born on the jobs server and its id travels back through fold. Every later `tasks/get`, `tasks/cancel`, `tasks/result`, and `tasks/update` for that id must reach that server — and the request carries nothing but the opaque id. No namespaced tool name, no routing hint, and no session to lean on: clients persist task ids and come back for them tomorrow, on a fresh connection, possibly through a different gateway instance. + +## The answers that don't work \{#the-answers-that-don-t-work\} +**Rewriting the id** — smuggling the owner into the id the client sees — breaks every client that persists one the moment your encoding changes, and turns an opaque protocol object into a contract you now own forever. fold treats task ids exactly like resource URIs: never rewritten. + +**Broadcasting** every task call to all N upstreams costs N× amplification on every poll, and it's a correctness bug, not just a cost: `tasks/cancel` fanned out is a destructive write sent to N−1 servers that never minted the task, and two upstreams can independently mint colliding ids. + +**Punting to the client** ("remember which server you created it on") recreates the N×M topology sprawl the gateway exists to remove — and it breaks outright when policy deliberately hides topology from the client, which in an enterprise deployment it does. + +## The mechanism: an affinity index with a probe fallback + +Ownership is remembered instead of encoded: + +- **Recorded at mint.** A `tools/call` result that advertises a task it created pins `taskId → upstream` as it passes through, so the polls that follow skip discovery entirely. +- **Probe fallback.** A task fold never saw minted — another gateway instance, an evicted record, an id shared out-of-band — is located by fanning a read-only `tasks/get` out once: the owner answers, everyone else is a healthy "not mine". Mutating methods are never fanned out; fold locates first, then acts on the owner alone. +- **Ownership is principal-bound.** The mint records who created the task. Another caller's `tasks/get` for that id answers exactly like an unknown id — no existence leak, no probe spent on it — and `tasks/list` merges every upstream but shows each principal only its own tasks. +- **Honest misses.** An id no upstream recognizes answers `-32002`, and the owning upstream's own errors pass through verbatim — the gateway stays invisible. + +
+ {/* authored fold-line diagram: the poll path, labels drawn from the article's own terms */} + + {/* active route: client -> fold -> owner (the affinity pin) */} + + + {/* dashed fold-lines: the read-only probe to the non-owners */} + + + {/* client node */} + + client + {/* the gateway node carries the wordmark; the folded corner it + used to wear was the retired square-tile mark's dog-ear */} + + + {/* upstream nodes */} + + + + upstream + owner + upstream + {/* annotations: measurement marks, pattern-paper style */} + tasks/get "job-42" + pinned at mint + read-only probe + "not mine" + +
+ +// gateway/tasks.go — the poll path: affinity, then probe +if v, ok := g.taskOwner.Load(taskID); ok { + // a task minted for a different principal is answered exactly like + // an unknown id — the denial must not reveal existence + return u.callTask(ctx, method, raw) +} +// Probe: read-only tasks/get across upstreams — the owner answers, +// everyone else is a healthy "no". Never fan out a mutating method. +owner := g.locateTaskOwner(ctx, rt, taskID)`} +/> + +gateway/tasks.go#L148 — the real thing, including the probe + +Governance rides along for free: a task-creating call is a tool call, so deny-by-default policy applies at mint, and every poll that follows is an audit record like any other request. + +## What about fan-in? + +The extension's companion story is `subscriptions/listen` — one notification stream south, N streams north, merged. fold doesn't implement it yet, and says so [in the README](https://github.com/fold-run/fold#not-implemented) rather than in a footnote: the official Go SDK currently supports the 2026-07-28 protocol on its streamable HTTP server only in stateless mode, and fold's session-keyed bridging (sampling, elicitation, per-client streams) requires stateful sessions. + +What ships today is the fan-in the protocol already exercises: list-changed and resource-updated notifications from every upstream fan out to the clients that care, proxied results are origin-tagged (`_meta["run.fold/upstream"]`), and a drift canary in the test suite fails the moment the SDK lifts the restriction — the gap closes when it can, and CI notices before we do. + +## The transferable lesson + +None of this is MCP-specific. Federating any protocol whose resources outlive their transport reduces to the same shape: an ownership index for stateful resources, recorded at mint, with a read-only probe path for the records you'll inevitably miss. Fronting N job APIs with one endpoint, aggregating webhooks, sharding a queue behind a facade — same checklist: + +- Namespace what you own at the boundary; never rewrite identifiers clients persist. +- Record ownership at mint time; keep a probe path for the records you'll inevitably miss. +- Probe with reads, act with writes — never fan out a mutating method. +- Bind ownership to the caller, and make a denial indistinguishable from a miss. +- Fail closed on index misses, and audit them. + +## Try it + +`go run github.com/fold-run/fold/cmd/fold@latest` — or `docker run ghcr.io/fold-run/fold` — puts the gateway in front of your servers in a minute ([walkthrough](https://docs.fold.run/run-it-locally/)). The integration suite runs the whole story against real MCP servers from the official Go SDK — gateway/tasks_test.go is the receipts. [docs.fold.run](https://docs.fold.run/) · [github.com/fold-run/fold](https://github.com/fold-run/fold) (Apache-2.0). The conformance results are [in CI, on every merge](https://docs.fold.run/conformance/) — check them. diff --git a/apps/site/src/content/blog/tenancy-one-bucket.mdx b/apps/site/src/content/blog/tenancy-one-bucket.mdx new file mode 100644 index 0000000..580aee1 --- /dev/null +++ b/apps/site/src/content/blog/tenancy-one-bucket.mdx @@ -0,0 +1,91 @@ +--- +title: "One bucket, not ten: tenancy in an MCP gateway" +description: "A tenant groups principals and governs them as one. The line the design holds above all is that it never authenticates them. Budgets charge narrowest-first, rate limits check widest-first, and ambiguity is refused rather than resolved." +date: 2026-08-10 +category: engineering +ogImage: /og/tenancy-one-bucket.png +--- + +{/* +// Sourced from docs.fold.run/tenancy/ and /consumption/, which curate fold's +// README and design notes. Unlike the tasks post, this one does NOT pin a +// commit SHA: the tenancy implementation lives in fold-run/fold and no verified +// SHA was available when this was written, so it links to docs and the repo +// root rather than to invented line ranges. Add permalinks when a SHA is known. +*/} + +import CodePanel from '../../components/CodePanel.astro'; + +Put a gateway in front of a federation and someone will eventually ask for the same four things at once: team A sees these tools, gets this allowance, cannot flood team B, and shows up separately in the audit trail. Every one of those was already possible in [fold](https://github.com/fold-run/fold). Assembling them was the problem: four unrelated mechanisms, and the word *tenant* appearing nowhere in the config, the audit stream, or the metrics. This post is about what it took to make that one object, and the two decisions inside it that were not obvious. + +## What a tenant is not + +One line shapes everything else: **a tenant groups principals, it does not authenticate them.** It is derived from the verified principal, after authentication has already happened. It is never presented alongside a token, and it is never a trust anchor. [Policy](https://docs.fold.run/configuration/#policy) remains the sole authority on what may be invoked. + +That sounds like a restriction and it is really a safety property. The moment a tenant id can be asserted by a caller, it becomes a credential, and a weak one: a string that grants an allowance and a view of the federation. Deriving it instead means the worst a confused tenant mapping can do is give someone the wrong budget. It can never give them authority they did not already authenticate into. + +The feature is additive by construction. Declare no tenants and a deployment behaves exactly as it did before tenancy existed, which is the only honest way to ship a cross-cutting dimension into something already in production. + +## One bucket, not ten + +This is the distinction that motivates the whole object. fold already had `server.rateLimit.perPrincipalPerMinute`, which gives each *person* a bucket. Ten agents on one team therefore hold ten allowances between them, and "team A cannot flood team B" is simply not what that setting says. A tenant's `rateLimit` is one bucket shared by every principal in it. That is the sentence people thought they were already buying. + +"tenants": [ + { + "id": "acme", + "subjects": { "claims": { "org_id": "acme-prod" } }, // the shape policy rules already use + "budget": { "period": "month", "upstreamCalls": 500000 }, + "rateLimit": { "requestsPerMinute": 2000 }, // one bucket for the whole tenant + "upstreams": ["billing", "crm"] // optional; all upstreams if omitted + } +]`} +/> + +`subjects` reuses the selector shape policy rules already use (`groups`, `subs`, `issuers`, `claims`), because an operator who has written one policy rule should not have to learn a second grammar to write a tenant. A tenant with no selector would capture every caller, so it is rejected at load rather than quietly swallowing the federation. + +## Two orderings, deliberately opposite \{#two-orderings\} +Once an allowance can sit at three scopes (upstream, tenant, server) you have to decide what order to consult them in. fold uses opposite orders for the two mechanisms, and the asymmetry is the interesting part. + +- **Budgets charge narrowest-first**: upstream, then tenant, then server. A request that is going to be refused must not spend a wider allowance on its way to the refusal. Charge the server budget first and a tenant that is over its own limit still burns the organisation's monthly allowance every time it is turned away. +- **Rate limits check widest-first**: global, then tenant, then per-principal. A flood should be refused before it costs any routing work. The cheapest possible answer to a stampede is the one you can give without looking anything up. + +Stated together they look inconsistent. They are not: both orderings minimise what a refusal costs, and the two mechanisms simply have different costs to minimise. A budget's cost is *allowance*, so consult the allowance you are least willing to waste last. A rate limit's cost is *work*, so consult the check that is cheapest to fail first. + +The two also refuse different things, which is why both exist. A rate limit answers "how fast" and then forgets; a sliding window smooths a burst and lets it go. A [budget](https://docs.fold.run/consumption/) answers "how much this month" and remembers, accumulating until the period rolls over. Smoothing a burst is the correct behaviour for protecting a fragile upstream and the wrong one for bounding a month's spend. + +## Visibility happens at the fan-out, not the result \{#visibility-at-the-fan-out\} +`upstreams` bounds which upstreams a tenant's callers reach, and it is evaluated **before** policy. Filtering at the fan-out rather than the result has consequences that are easy to miss and worth stating: + +- An upstream outside the subset is **never asked**. It costs no request, no budget, and no partial-failure entry when it happens to be down. A tenant is not exposed to the health of infrastructure it cannot reach. +- A named invocation against one is refused ahead of the policy engine, with `-32042`. +- `tasks/*` is the deliberate exception. Those answer "no upstream owns that id" rather than issuing a denial, matching the posture that path already takes for another principal's task. Where a refusal would confirm that something exists, it does not refuse. +- A viewer's [console](https://docs.fold.run/console/) shows *their* tenant's federation, not the operator's. That closes the one place a dashboard could otherwise show a customer the shape of a topology its own traffic is refused. + +## Ambiguity is refused, not resolved \{#ambiguity-is-refused\} +A principal belongs to at most one tenant. Where two selectors overlap, fold refuses rather than picking a winner. The alternative is precedence, and precedence in this position is a trap: assigning a caller by declaration order hands them another tenant's allowance and another tenant's view of the federation on the day somebody reorders a list. That is a config edit with no visible blast radius and a real one. + +Some overlap is catchable at validation, and is caught there. Some is only decidable against a real principal, because two selectors can collide for some callers and not others; that is caught at request time and refused there instead. A principal matching no tenant simply has none, and is governed exactly as it was before tenancy existed. + +## Ten thousand tenants, 97 nanoseconds \{#resolution-cost\} +Tenant resolution runs on every request, so it cannot be a scan. Two selector shapes cover what a per-customer document actually repeats: one claim equalling one value, or one group. Both are indexed at snapshot time, and the two indexes are keyed from opposite sides: the claim index by what the tenant requires, the group index by what the principal holds. + +Ten thousand tenants resolve in **97 ns with zero allocations**, which is the same cost as ten. A linear scan was 450 µs at that size. Compound selectors still scan, so keep those in the tens rather than the thousands. Methodology and the full table are on [the benchmarks page](https://docs.fold.run/benchmarks/), including the hardware and the caveats. + +## New names, not new labels + +With tenants configured, the dimension shows up in both observability surfaces: `tenant` on every audit event its principals produce, denials included, and two new metrics, `fold_tenant_requests_total{tenant,outcome}` and `fold_tenant_upstream_calls_total{tenant}`. The second counts the unit a tenant budget is charged in, so an allowance can be watched being spent rather than discovered exhausted. + +Those are new metric *names* rather than a `tenant` label added to the existing ones, and that was not a stylistic choice. Label sets are frozen by fold's [compatibility contract](https://docs.fold.run/embedding/#what-is-api). Adding a label to an existing series changes its identity in Prometheus and breaks every dashboard, alert, and recording rule built on it. A feature that silently rewrites an operator's alerting is not additive, whatever the config file says. + +## The transferable lesson + +Multi-tenancy in a proxy is usually described as an isolation feature. Most of the work here was not isolation, it was deciding what a tenant is *allowed to be*: not a credential, not a precedence rule, not a new label on an existing series. Each of those three would have been the shorter implementation, and each would have handed an operator a sharp edge pointing at something they already depended on. + +The general shape: when you add a dimension to a system that is already running, the interesting constraints are almost never in the new code path. They are in what the new dimension is forbidden from touching. + +## Try it + +Tenants are reloadable, unlike `server.budget`, because customers sign up on their own schedule and a reload has to be able to add one. The full field reference is at [docs.fold.run/tenancy](https://docs.fold.run/tenancy/); budgets and metering are at [/consumption](https://docs.fold.run/consumption/); the source is on [GitHub](https://github.com/fold-run/fold) under Apache-2.0. diff --git a/apps/site/src/content/changelog/2026-08-13-v1.12.0.md b/apps/site/src/content/changelog/2026-08-13-v1.12.0.md new file mode 100644 index 0000000..946c804 --- /dev/null +++ b/apps/site/src/content/changelog/2026-08-13-v1.12.0.md @@ -0,0 +1,10 @@ +--- +date: 2026-08-13 +title: "Governance in both directions, and one seam for judgement fold does not make itself." +version: v1.12.0 +--- + +- Deny-by-default now applies to the reverse direction. +- Policy learned depth: deny rules, argument constraints, and annotation gating. +- fold notices when an upstream rewrites what it advertises. +- The external decision hook, promised since v1.0, exists. diff --git a/apps/site/src/content/changelog/2026-08-13-v1.12.1.md b/apps/site/src/content/changelog/2026-08-13-v1.12.1.md new file mode 100644 index 0000000..198b170 --- /dev/null +++ b/apps/site/src/content/changelog/2026-08-13-v1.12.1.md @@ -0,0 +1,9 @@ +--- +date: 2026-08-13 +title: "Per-caller upstream credentials were only half-implemented; this is the other half." +version: v1.12.1 +--- + +- An upstream whose credential comes from the caller now holds one session per principal. +- `/health` stopped tearing down the upstreams it cannot probe. +- The exchanged-token fetch gates are bounded. diff --git a/apps/site/src/content/changelog/2026-08-13-v1.12.2.md b/apps/site/src/content/changelog/2026-08-13-v1.12.2.md new file mode 100644 index 0000000..8787400 --- /dev/null +++ b/apps/site/src/content/changelog/2026-08-13-v1.12.2.md @@ -0,0 +1,7 @@ +--- +date: 2026-08-13 +title: "The images v1.12.1 should have published." +version: v1.12.2 +--- + +- v1.12.1 shipped binaries and a chart but no container images. diff --git a/apps/site/src/content/changelog/2026-08-14-v1.13.0.md b/apps/site/src/content/changelog/2026-08-14-v1.13.0.md new file mode 100644 index 0000000..3eb3551 --- /dev/null +++ b/apps/site/src/content/changelog/2026-08-14-v1.13.0.md @@ -0,0 +1,7 @@ +--- +date: 2026-08-14 +title: "An audit sink that authenticates no longer forces its token into the config." +version: v1.13.0 +--- + +- A webhook audit sink can take its bearer token by reference. diff --git a/apps/site/src/content/changelog/2026-08-15-v1.14.0.md b/apps/site/src/content/changelog/2026-08-15-v1.14.0.md new file mode 100644 index 0000000..4e0513d --- /dev/null +++ b/apps/site/src/content/changelog/2026-08-15-v1.14.0.md @@ -0,0 +1,9 @@ +--- +date: 2026-08-15 +title: "Interactive apps survive the trip through the gateway." +version: v1.14.0 +--- + +- An MCP App's interface belongs to the upstream that published it. +- A client's rendering declaration now reaches the upstream. +- The embedded console leads with what is wrong. diff --git a/apps/site/src/content/changelog/2026-08-25-v1.15.0.md b/apps/site/src/content/changelog/2026-08-25-v1.15.0.md new file mode 100644 index 0000000..12673bd --- /dev/null +++ b/apps/site/src/content/changelog/2026-08-25-v1.15.0.md @@ -0,0 +1,17 @@ +--- +date: 2026-08-25 +title: "An audit against the specification, and the breaking change it forced." +version: v1.15.0 +--- + +- Every error code fold mints has changed, because the protocol reserved the range they were in. +- The gateway can keep its own streams alive. +- A routing header the caller sent stopped at the gateway. +- The protocol-era transition is now instrumented and written down rather than assumed. +- A retry that answered an upstream's question arrived looking like a first attempt. +- A client had to be refused before it could learn which scopes it needed. +- Every federated list went out with an invalid cache scope. +- Policy and tenant selectors match on OAuth scopes, and a scope denial says what would fix it. +- A caller could tell an upstream what protocol version, client identity, and capabilities it was talking to. +- EMA advertised an authorization server that answered 404. +- Nothing bounded what an upstream could return. diff --git a/apps/site/src/layouts/Base.astro b/apps/site/src/layouts/Base.astro index a9da501..99c67ce 100644 --- a/apps/site/src/layouts/Base.astro +++ b/apps/site/src/layouts/Base.astro @@ -3,6 +3,7 @@ // the canon header/footer from the stardust redesign (stardust/canon/*). // Page-specific section styles live in each page, not here. import Wordmark from '../components/Wordmark.astro'; +import { headerNav, LINKS } from '../lib/nav'; interface Props { title: string; @@ -52,776 +53,20 @@ const { + {jsonld &&