From c556f07a66e03943ee4bf53098cb16e0e0f5df18 Mon Sep 17 00:00:00 2001 From: Jeremiah Lowin <153965+jlowin@users.noreply.github.com> Date: Thu, 23 Jul 2026 19:47:57 -0400 Subject: [PATCH] Archive v3 docs and publish v4 as the primary version (#4613) * Archive v3 docs under /v3 and publish v4 as the primary version * Label primary docs version v4.0.0 (alpha 1) * Add What's New in v4 page; fix upgrade-guide phrasing; point banner at What's New * Rewrite What's New around v4's new capabilities, not the sampling deprecation * Lead What's New with the SDK v2 engine swap and the SEPs it brings * State ships now (link Session State); tasks arrive next alpha * Exclude docs/v3 frozen snapshots from doc-example import validation --- docs/css/style.css | 36 + docs/docs.json | 10 +- .../upgrading/from-fastmcp-3.mdx | 2 +- docs/getting-started/whats-new.mdx | 71 + docs/v3-banner.js | 39 + docs/v3-navigation.json | 312 ++ docs/v3/apps/architecture.mdx | 118 + docs/v3/apps/demos/bar-chart.py | 23 + docs/v3/apps/demos/contacts.py | 78 + docs/v3/apps/demos/dashboard.py | 68 + docs/v3/apps/demos/data-table.py | 24 + docs/v3/apps/demos/hitchhikers.py | 461 ++ docs/v3/apps/demos/pie-chart.py | 21 + docs/v3/apps/demos/reactive.py | 66 + docs/v3/apps/demos/team-directory-reactive.py | 116 + docs/v3/apps/demos/team-directory.py | 39 + docs/v3/apps/development.mdx | 65 + docs/v3/apps/examples.mdx | 92 + docs/v3/apps/fastmcp-app.mdx | 470 +++ docs/v3/apps/generative.mdx | 134 + docs/v3/apps/images/app-approval.png | Bin 0 -> 584871 bytes docs/v3/apps/images/app-chart.png | Bin 0 -> 6176 bytes docs/v3/apps/images/app-choice.png | Bin 0 -> 549003 bytes docs/v3/apps/images/app-contacts.png | Bin 0 -> 600792 bytes docs/v3/apps/images/app-datatable.png | 0 docs/v3/apps/images/app-example-map.png | Bin 0 -> 1927572 bytes docs/v3/apps/images/app-example-quiz.png | Bin 0 -> 600313 bytes .../images/app-example-sales-dashboard.png | Bin 0 -> 699754 bytes .../images/app-example-system-dashboard.png | Bin 0 -> 763291 bytes docs/v3/apps/images/app-file-upload.png | Bin 0 -> 568007 bytes docs/v3/apps/images/app-form.png | Bin 0 -> 593872 bytes docs/v3/apps/images/app-greet.png | Bin 0 -> 273260 bytes docs/v3/apps/images/app-overview.png | Bin 0 -> 54875 bytes docs/v3/apps/images/app-quickstart-dev-2.png | Bin 0 -> 599710 bytes docs/v3/apps/images/app-quickstart-dev.png | Bin 0 -> 667946 bytes docs/v3/apps/images/app-quickstart.png | Bin 0 -> 654323 bytes docs/v3/apps/images/app-showcase.png | Bin 0 -> 1025325 bytes docs/v3/apps/images/dev-app.png | Bin 0 -> 330041 bytes docs/v3/apps/images/generative-ui.mp4 | Bin 0 -> 2355019 bytes docs/v3/apps/low-level.mdx | 304 ++ docs/v3/apps/overview.mdx | 73 + docs/v3/apps/prefab.mdx | 297 ++ docs/v3/apps/providers/approval.mdx | 80 + docs/v3/apps/providers/choice.mdx | 72 + docs/v3/apps/providers/file-upload.mdx | 129 + docs/v3/apps/providers/form.mdx | 105 + docs/v3/apps/quickstart.mdx | 197 + docs/v3/changelog.mdx | 3759 +++++++++++++++++ docs/v3/cli/auth.mdx | 85 + docs/v3/cli/client.mdx | 144 + docs/v3/cli/generate-cli.mdx | 106 + docs/v3/cli/inspecting.mdx | 72 + docs/v3/cli/install-mcp.mdx | 146 + docs/v3/cli/overview.mdx | 104 + docs/v3/cli/running.mdx | 166 + docs/v3/clients/auth/bearer.mdx | 88 + docs/v3/clients/auth/cimd.mdx | 138 + docs/v3/clients/auth/oauth.mdx | 186 + docs/v3/clients/cli.mdx | 161 + docs/v3/clients/client-only-package.mdx | 89 + docs/v3/clients/client.mdx | 237 ++ docs/v3/clients/elicitation.mdx | 138 + docs/v3/clients/fastmcp-remote.mdx | 169 + docs/v3/clients/generate-cli.mdx | 166 + docs/v3/clients/logging.mdx | 92 + docs/v3/clients/notifications.mdx | 155 + docs/v3/clients/progress.mdx | 67 + docs/v3/clients/prompts.mdx | 147 + docs/v3/clients/resources.mdx | 110 + docs/v3/clients/roots.mdx | 45 + docs/v3/clients/sampling.mdx | 190 + docs/v3/clients/tasks.mdx | 182 + docs/v3/clients/tools.mdx | 183 + docs/v3/clients/transports.mdx | 267 ++ docs/v3/community/README.md | 22 + docs/v3/community/showcase.mdx | 65 + docs/v3/deployment/http.mdx | 924 ++++ docs/v3/deployment/prefect-horizon.mdx | 120 + docs/v3/deployment/running-server.mdx | 286 ++ docs/v3/deployment/sandboxed-agents.mdx | 262 ++ docs/v3/deployment/server-configuration.mdx | 640 +++ docs/v3/development/contributing.mdx | 198 + docs/v3/development/releases.mdx | 79 + docs/v3/development/tests.mdx | 396 ++ .../v3-notes/auth-provider-env-vars.mdx | 73 + docs/v3/development/v3-notes/v3-features.mdx | 1481 +++++++ docs/v3/getting-started/installation.mdx | 118 + docs/v3/getting-started/quickstart.mdx | 164 + .../upgrading/from-fastmcp-2.mdx | 444 ++ .../upgrading/from-low-level-sdk.mdx | 592 +++ .../upgrading/from-mcp-sdk.mdx | 166 + docs/v3/getting-started/welcome.mdx | 134 + docs/v3/integrations/anthropic.mdx | 228 + docs/v3/integrations/auth0.mdx | 195 + docs/v3/integrations/authkit.mdx | 106 + docs/v3/integrations/aws-cognito.mdx | 278 ++ docs/v3/integrations/azure.mdx | 542 +++ docs/v3/integrations/chatgpt.mdx | 157 + docs/v3/integrations/claude-code.mdx | 177 + docs/v3/integrations/claude-desktop.mdx | 299 ++ docs/v3/integrations/cursor-install-mcp.png | Bin 0 -> 47873 bytes docs/v3/integrations/cursor.mdx | 284 ++ docs/v3/integrations/descope.mdx | 113 + docs/v3/integrations/discord.mdx | 183 + .../v3/integrations/eunomia-authorization.mdx | 129 + docs/v3/integrations/fastapi.mdx | 445 ++ docs/v3/integrations/gemini-cli.mdx | 173 + docs/v3/integrations/gemini.mdx | 108 + docs/v3/integrations/github.mdx | 175 + docs/v3/integrations/google.mdx | 189 + docs/v3/integrations/goose.mdx | 178 + docs/v3/integrations/huggingface.mdx | 304 ++ .../images/authkit/enable_dcr.png | Bin 0 -> 823147 bytes .../images/oci/ociaddapplication.png | Bin 0 -> 183418 bytes .../images/oci/ocieditdomainsettings.png | Bin 0 -> 38629 bytes .../oci/ocieditdomainsettingsbutton.png | Bin 0 -> 69439 bytes .../images/oci/ocioauthconfiguration.png | Bin 0 -> 61118 bytes .../images/permit/abac_condition_example.png | Bin 0 -> 83666 bytes .../images/permit/abac_policy_example.png | Bin 0 -> 21882 bytes .../images/permit/policy_mapping.png | Bin 0 -> 16437 bytes .../images/permit/role_assignement.png | Bin 0 -> 74254 bytes docs/v3/integrations/keycloak.mdx | 141 + .../integrations/mcp-json-configuration.mdx | 514 +++ docs/v3/integrations/oci.mdx | 248 ++ docs/v3/integrations/openai.mdx | 227 + docs/v3/integrations/openapi.mdx | 456 ++ docs/v3/integrations/permit.mdx | 352 ++ docs/v3/integrations/propelauth.mdx | 164 + docs/v3/integrations/pydantic-ai.mdx | 137 + docs/v3/integrations/scalekit.mdx | 155 + docs/v3/integrations/supabase.mdx | 123 + docs/v3/integrations/workos.mdx | 200 + docs/v3/more/faq.mdx | 25 + docs/v3/more/settings.mdx | 99 + docs/v3/patterns/cli.mdx | 851 ++++ docs/v3/patterns/contrib.mdx | 45 + docs/v3/patterns/testing.mdx | 104 + docs/v3/servers/auth/authentication.mdx | 252 ++ docs/v3/servers/auth/full-oauth-server.mdx | 229 + docs/v3/servers/auth/multi-auth.mdx | 95 + docs/v3/servers/auth/oauth-proxy.mdx | 741 ++++ docs/v3/servers/auth/oidc-proxy.mdx | 287 ++ docs/v3/servers/auth/remote-oauth.mdx | 240 ++ docs/v3/servers/auth/token-verification.mdx | 426 ++ docs/v3/servers/authorization.mdx | 384 ++ docs/v3/servers/composition.mdx | 237 ++ docs/v3/servers/context.mdx | 480 +++ docs/v3/servers/dependency-injection.mdx | 433 ++ docs/v3/servers/elicitation.mdx | 379 ++ docs/v3/servers/icons.mdx | 151 + docs/v3/servers/lifespan.mdx | 148 + docs/v3/servers/logging.mdx | 87 + docs/v3/servers/middleware.mdx | 959 +++++ docs/v3/servers/pagination.mdx | 93 + docs/v3/servers/progress.mdx | 51 + docs/v3/servers/prompts.mdx | 481 +++ docs/v3/servers/providers/custom.mdx | 245 ++ docs/v3/servers/providers/filesystem.mdx | 256 ++ docs/v3/servers/providers/local.mdx | 161 + docs/v3/servers/providers/overview.mdx | 81 + docs/v3/servers/providers/proxy.mdx | 353 ++ docs/v3/servers/providers/skills.mdx | 301 ++ docs/v3/servers/resources.mdx | 747 ++++ docs/v3/servers/sampling.mdx | 573 +++ docs/v3/servers/server.mdx | 285 ++ docs/v3/servers/storage-backends.mdx | 296 ++ docs/v3/servers/tasks.mdx | 263 ++ docs/v3/servers/telemetry.mdx | 345 ++ docs/v3/servers/testing.mdx | 104 + docs/v3/servers/tool-fingerprinting.mdx | 156 + docs/v3/servers/tools.mdx | 1143 +++++ docs/v3/servers/transforms/code-mode.mdx | 361 ++ docs/v3/servers/transforms/namespace.mdx | 63 + docs/v3/servers/transforms/namespacing.mdx | 9 + .../servers/transforms/prompts-as-tools.mdx | 130 + .../servers/transforms/resources-as-tools.mdx | 111 + docs/v3/servers/transforms/tool-search.mdx | 173 + .../transforms/tool-transformation.mdx | 230 + docs/v3/servers/transforms/transforms.mdx | 173 + docs/v3/servers/versioning.mdx | 336 ++ docs/v3/servers/visibility.mdx | 452 ++ docs/v3/tutorials/create-mcp-server.mdx | 198 + docs/v3/tutorials/mcp.mdx | 120 + docs/v3/tutorials/rest-api.mdx | 203 + docs/v3/updates.mdx | 743 ++++ tests/docs/test_doc_examples.py | 9 +- 186 files changed, 39927 insertions(+), 8 deletions(-) create mode 100644 docs/getting-started/whats-new.mdx create mode 100644 docs/v3-banner.js create mode 100644 docs/v3-navigation.json create mode 100644 docs/v3/apps/architecture.mdx create mode 100644 docs/v3/apps/demos/bar-chart.py create mode 100644 docs/v3/apps/demos/contacts.py create mode 100644 docs/v3/apps/demos/dashboard.py create mode 100644 docs/v3/apps/demos/data-table.py create mode 100644 docs/v3/apps/demos/hitchhikers.py create mode 100644 docs/v3/apps/demos/pie-chart.py create mode 100644 docs/v3/apps/demos/reactive.py create mode 100644 docs/v3/apps/demos/team-directory-reactive.py create mode 100644 docs/v3/apps/demos/team-directory.py create mode 100644 docs/v3/apps/development.mdx create mode 100644 docs/v3/apps/examples.mdx create mode 100644 docs/v3/apps/fastmcp-app.mdx create mode 100644 docs/v3/apps/generative.mdx create mode 100644 docs/v3/apps/images/app-approval.png create mode 100644 docs/v3/apps/images/app-chart.png create mode 100644 docs/v3/apps/images/app-choice.png create mode 100644 docs/v3/apps/images/app-contacts.png create mode 100644 docs/v3/apps/images/app-datatable.png create mode 100644 docs/v3/apps/images/app-example-map.png create mode 100644 docs/v3/apps/images/app-example-quiz.png create mode 100644 docs/v3/apps/images/app-example-sales-dashboard.png create mode 100644 docs/v3/apps/images/app-example-system-dashboard.png create mode 100644 docs/v3/apps/images/app-file-upload.png create mode 100644 docs/v3/apps/images/app-form.png create mode 100644 docs/v3/apps/images/app-greet.png create mode 100644 docs/v3/apps/images/app-overview.png create mode 100644 docs/v3/apps/images/app-quickstart-dev-2.png create mode 100644 docs/v3/apps/images/app-quickstart-dev.png create mode 100644 docs/v3/apps/images/app-quickstart.png create mode 100644 docs/v3/apps/images/app-showcase.png create mode 100644 docs/v3/apps/images/dev-app.png create mode 100644 docs/v3/apps/images/generative-ui.mp4 create mode 100644 docs/v3/apps/low-level.mdx create mode 100644 docs/v3/apps/overview.mdx create mode 100644 docs/v3/apps/prefab.mdx create mode 100644 docs/v3/apps/providers/approval.mdx create mode 100644 docs/v3/apps/providers/choice.mdx create mode 100644 docs/v3/apps/providers/file-upload.mdx create mode 100644 docs/v3/apps/providers/form.mdx create mode 100644 docs/v3/apps/quickstart.mdx create mode 100644 docs/v3/changelog.mdx create mode 100644 docs/v3/cli/auth.mdx create mode 100644 docs/v3/cli/client.mdx create mode 100644 docs/v3/cli/generate-cli.mdx create mode 100644 docs/v3/cli/inspecting.mdx create mode 100644 docs/v3/cli/install-mcp.mdx create mode 100644 docs/v3/cli/overview.mdx create mode 100644 docs/v3/cli/running.mdx create mode 100644 docs/v3/clients/auth/bearer.mdx create mode 100644 docs/v3/clients/auth/cimd.mdx create mode 100644 docs/v3/clients/auth/oauth.mdx create mode 100644 docs/v3/clients/cli.mdx create mode 100644 docs/v3/clients/client-only-package.mdx create mode 100644 docs/v3/clients/client.mdx create mode 100644 docs/v3/clients/elicitation.mdx create mode 100644 docs/v3/clients/fastmcp-remote.mdx create mode 100644 docs/v3/clients/generate-cli.mdx create mode 100644 docs/v3/clients/logging.mdx create mode 100644 docs/v3/clients/notifications.mdx create mode 100644 docs/v3/clients/progress.mdx create mode 100644 docs/v3/clients/prompts.mdx create mode 100644 docs/v3/clients/resources.mdx create mode 100644 docs/v3/clients/roots.mdx create mode 100644 docs/v3/clients/sampling.mdx create mode 100644 docs/v3/clients/tasks.mdx create mode 100644 docs/v3/clients/tools.mdx create mode 100644 docs/v3/clients/transports.mdx create mode 100644 docs/v3/community/README.md create mode 100644 docs/v3/community/showcase.mdx create mode 100644 docs/v3/deployment/http.mdx create mode 100644 docs/v3/deployment/prefect-horizon.mdx create mode 100644 docs/v3/deployment/running-server.mdx create mode 100644 docs/v3/deployment/sandboxed-agents.mdx create mode 100644 docs/v3/deployment/server-configuration.mdx create mode 100644 docs/v3/development/contributing.mdx create mode 100644 docs/v3/development/releases.mdx create mode 100644 docs/v3/development/tests.mdx create mode 100644 docs/v3/development/v3-notes/auth-provider-env-vars.mdx create mode 100644 docs/v3/development/v3-notes/v3-features.mdx create mode 100644 docs/v3/getting-started/installation.mdx create mode 100644 docs/v3/getting-started/quickstart.mdx create mode 100644 docs/v3/getting-started/upgrading/from-fastmcp-2.mdx create mode 100644 docs/v3/getting-started/upgrading/from-low-level-sdk.mdx create mode 100644 docs/v3/getting-started/upgrading/from-mcp-sdk.mdx create mode 100644 docs/v3/getting-started/welcome.mdx create mode 100644 docs/v3/integrations/anthropic.mdx create mode 100644 docs/v3/integrations/auth0.mdx create mode 100644 docs/v3/integrations/authkit.mdx create mode 100644 docs/v3/integrations/aws-cognito.mdx create mode 100644 docs/v3/integrations/azure.mdx create mode 100644 docs/v3/integrations/chatgpt.mdx create mode 100644 docs/v3/integrations/claude-code.mdx create mode 100644 docs/v3/integrations/claude-desktop.mdx create mode 100644 docs/v3/integrations/cursor-install-mcp.png create mode 100644 docs/v3/integrations/cursor.mdx create mode 100644 docs/v3/integrations/descope.mdx create mode 100644 docs/v3/integrations/discord.mdx create mode 100644 docs/v3/integrations/eunomia-authorization.mdx create mode 100644 docs/v3/integrations/fastapi.mdx create mode 100644 docs/v3/integrations/gemini-cli.mdx create mode 100644 docs/v3/integrations/gemini.mdx create mode 100644 docs/v3/integrations/github.mdx create mode 100644 docs/v3/integrations/google.mdx create mode 100644 docs/v3/integrations/goose.mdx create mode 100644 docs/v3/integrations/huggingface.mdx create mode 100644 docs/v3/integrations/images/authkit/enable_dcr.png create mode 100644 docs/v3/integrations/images/oci/ociaddapplication.png create mode 100644 docs/v3/integrations/images/oci/ocieditdomainsettings.png create mode 100644 docs/v3/integrations/images/oci/ocieditdomainsettingsbutton.png create mode 100644 docs/v3/integrations/images/oci/ocioauthconfiguration.png create mode 100644 docs/v3/integrations/images/permit/abac_condition_example.png create mode 100644 docs/v3/integrations/images/permit/abac_policy_example.png create mode 100644 docs/v3/integrations/images/permit/policy_mapping.png create mode 100644 docs/v3/integrations/images/permit/role_assignement.png create mode 100644 docs/v3/integrations/keycloak.mdx create mode 100644 docs/v3/integrations/mcp-json-configuration.mdx create mode 100644 docs/v3/integrations/oci.mdx create mode 100644 docs/v3/integrations/openai.mdx create mode 100644 docs/v3/integrations/openapi.mdx create mode 100644 docs/v3/integrations/permit.mdx create mode 100644 docs/v3/integrations/propelauth.mdx create mode 100644 docs/v3/integrations/pydantic-ai.mdx create mode 100644 docs/v3/integrations/scalekit.mdx create mode 100644 docs/v3/integrations/supabase.mdx create mode 100644 docs/v3/integrations/workos.mdx create mode 100644 docs/v3/more/faq.mdx create mode 100644 docs/v3/more/settings.mdx create mode 100644 docs/v3/patterns/cli.mdx create mode 100644 docs/v3/patterns/contrib.mdx create mode 100644 docs/v3/patterns/testing.mdx create mode 100644 docs/v3/servers/auth/authentication.mdx create mode 100644 docs/v3/servers/auth/full-oauth-server.mdx create mode 100644 docs/v3/servers/auth/multi-auth.mdx create mode 100644 docs/v3/servers/auth/oauth-proxy.mdx create mode 100644 docs/v3/servers/auth/oidc-proxy.mdx create mode 100644 docs/v3/servers/auth/remote-oauth.mdx create mode 100644 docs/v3/servers/auth/token-verification.mdx create mode 100644 docs/v3/servers/authorization.mdx create mode 100644 docs/v3/servers/composition.mdx create mode 100644 docs/v3/servers/context.mdx create mode 100644 docs/v3/servers/dependency-injection.mdx create mode 100644 docs/v3/servers/elicitation.mdx create mode 100644 docs/v3/servers/icons.mdx create mode 100644 docs/v3/servers/lifespan.mdx create mode 100644 docs/v3/servers/logging.mdx create mode 100644 docs/v3/servers/middleware.mdx create mode 100644 docs/v3/servers/pagination.mdx create mode 100644 docs/v3/servers/progress.mdx create mode 100644 docs/v3/servers/prompts.mdx create mode 100644 docs/v3/servers/providers/custom.mdx create mode 100644 docs/v3/servers/providers/filesystem.mdx create mode 100644 docs/v3/servers/providers/local.mdx create mode 100644 docs/v3/servers/providers/overview.mdx create mode 100644 docs/v3/servers/providers/proxy.mdx create mode 100644 docs/v3/servers/providers/skills.mdx create mode 100644 docs/v3/servers/resources.mdx create mode 100644 docs/v3/servers/sampling.mdx create mode 100644 docs/v3/servers/server.mdx create mode 100644 docs/v3/servers/storage-backends.mdx create mode 100644 docs/v3/servers/tasks.mdx create mode 100644 docs/v3/servers/telemetry.mdx create mode 100644 docs/v3/servers/testing.mdx create mode 100644 docs/v3/servers/tool-fingerprinting.mdx create mode 100644 docs/v3/servers/tools.mdx create mode 100644 docs/v3/servers/transforms/code-mode.mdx create mode 100644 docs/v3/servers/transforms/namespace.mdx create mode 100644 docs/v3/servers/transforms/namespacing.mdx create mode 100644 docs/v3/servers/transforms/prompts-as-tools.mdx create mode 100644 docs/v3/servers/transforms/resources-as-tools.mdx create mode 100644 docs/v3/servers/transforms/tool-search.mdx create mode 100644 docs/v3/servers/transforms/tool-transformation.mdx create mode 100644 docs/v3/servers/transforms/transforms.mdx create mode 100644 docs/v3/servers/versioning.mdx create mode 100644 docs/v3/servers/visibility.mdx create mode 100644 docs/v3/tutorials/create-mcp-server.mdx create mode 100644 docs/v3/tutorials/mcp.mdx create mode 100644 docs/v3/tutorials/rest-api.mdx create mode 100644 docs/v3/updates.mdx diff --git a/docs/css/style.css b/docs/css/style.css index 99844f692..94d58b4bf 100644 --- a/docs/css/style.css +++ b/docs/css/style.css @@ -57,6 +57,42 @@ h6 code:not(pre code) { background: linear-gradient(135deg, #2d00f7 0%, #4cc9f0 100%); } +/* V3 banner - inside content-container, breaks out of padding with negative margins */ +#v3-banner { + display: block; + background: linear-gradient(135deg, #4cc9f0 0%, #2d00f7 100%); + color: white; + text-align: center; + padding: 10px 16px; + font-size: 0.875rem; + font-weight: 600; + box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1); + margin: -2rem -2rem 1.5rem -2rem; + width: calc(100% + 4rem); + border-radius: 8px 8px 0 0; +} + +#v3-banner a { + color: white; + text-decoration: underline; + font-weight: 700; +} + +#v3-banner a:hover { + opacity: 0.9; +} + +@media (min-width: 1024px) { + #v3-banner { + margin: -3rem -4rem 1.5rem -4rem; + width: calc(100% + 8rem); + } +} + +.dark #v3-banner { + background: linear-gradient(135deg, #2d00f7 0%, #4cc9f0 100%); +} + diff --git a/docs/docs.json b/docs/docs.json index c358e9518..97dcdd572 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -16,7 +16,7 @@ "dark": "#475569", "light": "#1e3a5f" }, - "content": "Meet [Prefect Horizon](https://prefect.io/horizon?utm_source=gofastmcp&utm_medium=docs&utm_campaign=docs_banner&utm_content=sitewide_banner), the enterprise MCP gateway built by the team behind FastMCP" + "content": "FastMCP 4 is in alpha — you're reading the v4 docs. [What's new](/getting-started/whats-new) · [FastMCP 3 docs](/v3/getting-started/welcome)" }, "colors": { "dark": "#f72585", @@ -89,7 +89,8 @@ "pages": [ "getting-started/welcome", "getting-started/installation", - "getting-started/quickstart" + "getting-started/quickstart", + "getting-started/whats-new" ] }, { @@ -412,7 +413,10 @@ "icon": "code" } ], - "version": "v3" + "version": "v4.0.0 (alpha 1)" + }, + { + "$ref": "./v3-navigation.json" }, { "$ref": "./v2-navigation.json" diff --git a/docs/getting-started/upgrading/from-fastmcp-3.mdx b/docs/getting-started/upgrading/from-fastmcp-3.mdx index a3fd233fd..82c95992b 100644 --- a/docs/getting-started/upgrading/from-fastmcp-3.mdx +++ b/docs/getting-started/upgrading/from-fastmcp-3.mdx @@ -76,7 +76,7 @@ A few client behaviors that touch the SDK are preserved so you don't have to cha ## What you must change -Three things are on you. +Everything above, FastMCP handled for you. What remains lives in your own code, where FastMCP can't reach it — your imports, how you construct errors, the custom HTTP clients you hand to a transport, and any place you reach past FastMCP's surfaces into the raw SDK objects. Each surfaces as a clear failure at import or call time, and each is a mechanical fix. **Your own `mcp.types` imports.** FastMCP can re-export types, but it can't rewrite imports in your code. Any `from mcp.types import X` or `import mcp.types` in your server or client fails at import time with: diff --git a/docs/getting-started/whats-new.mdx b/docs/getting-started/whats-new.mdx new file mode 100644 index 000000000..c0a83dd59 --- /dev/null +++ b/docs/getting-started/whats-new.mdx @@ -0,0 +1,71 @@ +--- +title: "What's New in FastMCP 4" +sidebarTitle: "What's New" +description: The capabilities that define FastMCP 4 — a rebuilt engine, a new protocol era, and a stateless protocol made practical. +icon: sparkles +--- + +FastMCP 4 is a major version because its engine changed. The framework is now built on the MCP Python SDK v2, a ground-up rebuild of the protocol layer, and on that foundation it adds a new protocol era, first-class extensions, stateless state, enterprise identity, and more. Most FastMCP 3 servers run on it untouched — the major version signals how much moved underneath, and what that movement unlocks. + + +FastMCP 4 is in **alpha**. Everything below is available today except background tasks, which arrive in the next alpha. Pin an exact version and expect sharp edges. + + +## Built on the MCP Python SDK v2 + +The defining change in FastMCP 4 is the one you mostly can't see. The MCP Python SDK v2 rewrote the protocol layer end to end: it split the protocol types into a standalone `mcp_types` package, renamed every wire field from camelCase to snake_case, replaced the server's request-handling model, and made server-side middleware and multi-era serving first-class. FastMCP absorbs nearly all of it — your reads stay working through a compatibility bridge, and the handful of changes left in your code are mechanical. + +The major version is the signal. Even where your surface is unchanged, the behavior underneath is substantially different, and bumping to 4.0 is how we tell you that plainly rather than slipping a new engine in under a patch release. + +The rebuild also pulls the protocol's recent evolution forward in a single step. A batch of accepted MCP proposals arrives with SDK v2, and FastMCP 4 surfaces each one: capability-negotiated extensions (SEP-2133), multi-round-trip elicitation for sessionless connections (SEP-2322), response cache hints (SEP-2549), spec-standard error codes (SEP-2164), the enterprise identity-assertion grant (SEP-990), and the sessionless `2026-07-28` protocol itself, which removes server-initiated requests (SEP-2577). The rest of this page is what those add up to. + +## Every protocol era + +A FastMCP 4 server answers clients across the protocol transition from one deployment. The MCP SDK negotiates the era per connection — the sessionless `2026-07-28` protocol for clients that have moved forward, the session-based handshake for everyone else — and any replica behind a plain load balancer can serve a modern request. This supersedes FastMCP's earlier "latest protocol only" stance: you adopt the new protocol without forking your deployment or gating clients by version. + +The modern protocol is sessionless, so it drops the server's ability to call back into the client mid-request (SEP-2577). Imperative `ctx.elicit` and `ctx.list_roots` move to a request-shaped pattern on modern connections, and server-initiated sampling — which has no such replacement — is [deprecated](/servers/sampling). Everything else about writing a server is unchanged. + +## State without a session + +A stateless protocol raises an obvious question: if every request is a fresh connection, where does a tool keep a shopping cart, a conversation, or a running total? FastMCP 4 follows the MCP working group's own decision to reject protocol-level sessions in favor of *explicit state handles* (SEP-2567) — the server hands out an identifier, and the client passes it back. + +Two shapes cover the cases. `UserSession` is injected like `Context` and keyed to the authenticated user, so a tool reads and writes one bucket of state with nothing to pass around. `SessionId` is an explicit handle a tool mints and the caller supplies as an argument, for when one user holds many independent states. Both store their data server-side in the storage backend, keyed to the authenticated user — so a handle is inert in anyone else's hands. See [Session State](/servers/sessions). + +## Background tasks + +Long-running work runs as a background task: the server accepts the call, returns a handle, and the client polls for the result while the work proceeds. Tasks left the core MCP spec during the SDK v2 rebuild and returned as the `io.modelcontextprotocol/tasks` extension (SEP-2663), which FastMCP 4 implements end to end in the optional `fastmcp-tasks` package. The durable execution engine that made FastMCP 3's tasks reliable carries straight over, and `@mcp.tool(task=True)` remains the only authoring surface — so the wire protocol modernizing underneath costs you no code change. See [Background Tasks](/development/v4-notes/background-tasks) for the design; the runtime arrives in the next alpha. + +## Server extensions + +Background tasks are the first capability built on a more general one: FastMCP 4 makes MCP extensions — capability-negotiated protocol features named by a reverse-DNS string (SEP-2133) — a first-class surface. `FastMCP.add_extension()` lets an extension advertise a capability, add request methods, intercept `tools/call`, and run a lifespan hook, all with full access to the component registry, `Context`, and auth. The same extensions flow through the client with `Client(extensions=...)`. A cross-cutting protocol feature stops being surgery on core and becomes a supported plugin. + +## Enterprise identity + +FastMCP 4 ships a complete server-side implementation of identity assertion (SEP-990): enterprise "on-behalf-of" access, where a corporate identity provider issues a signed assertion, the user's agent presents it, and the server mints a short-lived token — no browser login and no per-user consent screen. Behind one parameter on the existing auth providers, FastMCP performs the full signature verification, binding checks, replay rejection, and scoped token issuance. + +```python +from fastmcp import FastMCP +from fastmcp.server.auth import IdentityAssertion, OAuthProxy + +auth = OAuthProxy( + # existing upstream configuration unchanged + identity_assertion=IdentityAssertion(trusted_issuers=["https://login.acme-corp.com"]), +) +mcp = FastMCP("Internal API", auth=auth) +``` + +The asserted subject flows into the normal auth context, so tools read it through `get_access_token()` like any other identity. See [Identity Assertion](/servers/auth/oauth-proxy#identity-assertion-sep-990). + +## Faster and safer + +Two more capabilities arrive by default. Response caching (SEP-2549) lets a server stamp freshness hints on its results that a caching [client](/clients/client#response-caching) reuses without a round trip, and a distributed `KeyValueResponseCacheStore` backs that cache with Redis or any key-value store, so a fleet of clients or proxy replicas shares fills. + +```python +from fastmcp import FastMCP + +mcp = FastMCP("Weather", cache_ttl=300, cache_scope="public") +``` + +Security tightened in the same release: every templated resource screens its parameters for path traversal, absolute paths, and null bytes before the handler runs — [path security](/servers/resources#path-security) on by default, covering mounted and proxied templates too. + +When you're ready to move a server to v4, [Upgrading from FastMCP 3](/getting-started/upgrading/from-fastmcp-3) walks through every change and what it looks like in practice. diff --git a/docs/v3-banner.js b/docs/v3-banner.js new file mode 100644 index 000000000..6ddaa2d73 --- /dev/null +++ b/docs/v3-banner.js @@ -0,0 +1,39 @@ +// Add v3 banner inside content-container with negative margins +(function() { + if (typeof window === 'undefined') return; + + function addBanner() { + const isV3 = window.location.pathname.includes('/v3/'); + const container = document.getElementById('content-container'); + let banner = document.getElementById('v3-banner'); + + if (isV3 && container) { + if (!banner) { + banner = document.createElement('div'); + banner.id = 'v3-banner'; + banner.innerHTML = 'These are the docs for FastMCP 3. FastMCP 4 is now available.'; + container.insertBefore(banner, container.firstChild); + } + } else if (!isV3 && banner) { + banner.remove(); + } + } + + function run() { + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', addBanner); + } else { + addBanner(); + } + } + + run(); + + let lastUrl = location.href; + new MutationObserver(() => { + if (location.href !== lastUrl) { + lastUrl = location.href; + setTimeout(addBanner, 100); + } + }).observe(document.body, {subtree: true, childList: true}); +})(); diff --git a/docs/v3-navigation.json b/docs/v3-navigation.json new file mode 100644 index 000000000..24c451b2a --- /dev/null +++ b/docs/v3-navigation.json @@ -0,0 +1,312 @@ +{ + "dropdowns": [ + { + "dropdown": "Documentation", + "groups": [ + { + "group": "Get Started", + "pages": [ + "v3/getting-started/welcome", + "v3/getting-started/installation", + "v3/getting-started/quickstart" + ] + }, + { + "group": "Servers", + "pages": [ + "v3/servers/server", + { + "collapsed": true, + "group": "Core Components", + "icon": "toolbox", + "pages": [ + "v3/servers/tools", + "v3/servers/resources", + "v3/servers/prompts", + "v3/servers/context" + ] + }, + { + "collapsed": true, + "group": "Working with Tools", + "icon": "wand-magic-sparkles", + "pages": [ + "v3/servers/transforms/transforms", + "v3/servers/transforms/tool-transformation", + "v3/servers/transforms/code-mode", + "v3/servers/transforms/tool-search", + "v3/servers/transforms/namespace", + "v3/servers/visibility", + "v3/servers/transforms/resources-as-tools", + "v3/servers/transforms/prompts-as-tools", + "v3/servers/tool-fingerprinting" + ] + }, + { + "collapsed": true, + "group": "MCP Providers", + "icon": "layer-group", + "pages": [ + "v3/servers/providers/overview", + "v3/servers/providers/local", + "v3/servers/providers/filesystem", + "v3/servers/providers/proxy", + "v3/servers/providers/skills", + "v3/servers/composition", + "v3/servers/providers/custom" + ] + }, + { + "collapsed": true, + "group": "Interactivity", + "icon": "comments", + "pages": [ + "v3/servers/elicitation", + "v3/servers/sampling", + "v3/servers/progress", + "v3/servers/logging", + "v3/servers/pagination", + "v3/servers/icons" + ] + }, + { + "collapsed": true, + "group": "Extensibility", + "icon": "puzzle-piece", + "pages": [ + "v3/servers/middleware", + "v3/servers/dependency-injection", + "v3/servers/lifespan", + "v3/servers/storage-backends", + "v3/servers/tasks", + "v3/servers/versioning" + ] + }, + { + "collapsed": true, + "group": "Auth", + "icon": "shield-check", + "pages": [ + { + "collapsed": true, + "group": "Authentication", + "icon": "key", + "pages": [ + "v3/servers/auth/authentication", + "v3/servers/auth/token-verification", + "v3/servers/auth/remote-oauth", + "v3/servers/auth/oauth-proxy", + "v3/servers/auth/oidc-proxy", + "v3/servers/auth/full-oauth-server", + "v3/servers/auth/multi-auth" + ] + }, + "v3/servers/authorization" + ] + }, + { + "collapsed": true, + "group": "Deployment", + "icon": "rocket", + "pages": [ + "v3/deployment/running-server", + "v3/deployment/http", + "v3/deployment/sandboxed-agents", + "v3/deployment/prefect-horizon", + "v3/deployment/server-configuration", + "v3/servers/testing", + "v3/servers/telemetry" + ] + } + ] + }, + { + "group": "Apps", + "pages": [ + "v3/apps/overview", + "v3/apps/quickstart", + "v3/apps/fastmcp-app", + "v3/apps/prefab", + "v3/apps/generative", + "v3/apps/low-level", + { + "collapsed": true, + "group": "Reference", + "icon": "book", + "pages": [ + { + "collapsed": true, + "group": "Prefab Providers", + "icon": "cube", + "pages": [ + "v3/apps/providers/approval", + "v3/apps/providers/choice", + "v3/apps/providers/file-upload", + "v3/apps/providers/form" + ] + }, + "v3/apps/development", + "v3/apps/examples", + "v3/apps/architecture" + ] + } + ] + }, + { + "group": "Clients", + "pages": [ + "v3/clients/client", + "v3/clients/client-only-package", + "v3/clients/transports", + "v3/clients/fastmcp-remote", + { + "collapsed": true, + "group": "Operations", + "icon": "toolbox", + "pages": [ + "v3/clients/tools", + "v3/clients/resources", + "v3/clients/prompts", + "v3/clients/sampling", + "v3/clients/elicitation", + "v3/clients/tasks", + "v3/clients/progress", + "v3/clients/logging", + "v3/clients/roots", + "v3/clients/notifications" + ], + "tag": "UPDATED" + }, + { + "collapsed": true, + "group": "Authentication", + "icon": "key", + "pages": [ + "v3/clients/auth/oauth", + "v3/clients/auth/cimd", + "v3/clients/auth/bearer" + ], + "tag": "UPDATED" + } + ] + }, + { + "group": "Integrations", + "pages": [ + { + "collapsed": true, + "group": "Auth", + "icon": "key", + "pages": [ + "v3/integrations/auth0", + "v3/integrations/authkit", + "v3/integrations/aws-cognito", + "v3/integrations/azure", + "v3/integrations/descope", + "v3/integrations/discord", + "v3/integrations/eunomia-authorization", + "v3/integrations/github", + "v3/integrations/google", + "v3/integrations/huggingface", + "v3/integrations/keycloak", + "v3/integrations/oci", + "v3/integrations/permit", + "v3/integrations/propelauth", + "v3/integrations/scalekit", + "v3/integrations/supabase", + "v3/integrations/workos" + ] + }, + { + "collapsed": true, + "group": "Web Frameworks", + "icon": "code", + "pages": [ + "v3/integrations/fastapi", + "v3/integrations/openapi" + ] + }, + { + "collapsed": true, + "group": "AI Assistants", + "icon": "robot", + "pages": [ + "v3/integrations/chatgpt", + "v3/integrations/claude-code", + "v3/integrations/claude-desktop", + "v3/integrations/cursor", + "v3/integrations/gemini-cli", + "v3/integrations/goose" + ] + }, + { + "collapsed": true, + "group": "AI SDKs", + "icon": "microchip", + "pages": [ + "v3/integrations/anthropic", + "v3/integrations/gemini", + "v3/integrations/openai", + "v3/integrations/pydantic-ai" + ] + }, + "v3/integrations/mcp-json-configuration" + ] + }, + { + "group": "More", + "pages": [ + "v3/more/settings", + { + "collapsed": true, + "group": "CLI", + "icon": "terminal", + "pages": [ + "v3/cli/overview", + "v3/cli/running", + "v3/cli/install-mcp", + "v3/cli/inspecting", + "v3/cli/client", + "v3/cli/generate-cli", + "v3/cli/auth" + ] + }, + { + "collapsed": true, + "group": "Upgrading", + "icon": "up", + "pages": [ + "v3/getting-started/upgrading/from-fastmcp-2", + "v3/getting-started/upgrading/from-mcp-sdk", + "v3/getting-started/upgrading/from-low-level-sdk" + ] + }, + { + "collapsed": true, + "group": "Development", + "icon": "code", + "pages": [ + "v3/development/contributing", + "v3/development/tests", + "v3/development/releases", + "v3/patterns/contrib" + ] + }, + { + "collapsed": true, + "group": "What's New", + "icon": "sparkles", + "pages": [ + "v3/updates", + "v3/changelog" + ] + }, + "v3/more/faq" + ] + } + ], + "icon": "book" + } + ], + "version": "v3.4.4" +} diff --git a/docs/v3/apps/architecture.mdx b/docs/v3/apps/architecture.mdx new file mode 100644 index 000000000..7ecab2aa3 --- /dev/null +++ b/docs/v3/apps/architecture.mdx @@ -0,0 +1,118 @@ +--- +title: Architecture +sidebarTitle: Architecture +description: How FastMCP apps work under the hood — from Python to pixels. +icon: sitemap +--- + +import { VersionBadge } from '/snippets/version-badge.mdx' + + + +You don't need this page to build apps. It's for when something isn't rendering the way you expect, when UI tool calls aren't reaching your server, or when you're writing [custom HTML apps](/apps/low-level) and need to understand the protocol directly. + +## The pipeline + +An MCP app moves through five stages from Python to pixels: + +``` +Python components → JSON tree → structuredContent → Renderer iframe → Host UI +``` + +You write Prefab components. FastMCP serializes them to a JSON component tree and delivers it as `structuredContent` on the tool result. The host loads the Prefab renderer in a sandboxed iframe, pushes the JSON in, and the renderer paints the UI. If the UI calls server tools, it talks back through the same `postMessage` channel. + +The sections below walk each stage. + +## Tool registration + +When you mark a tool with `app=True` or `@app.ui()`, FastMCP wires up the metadata and renderer resource that the protocol requires. + +### The `app=True` flag + +`app` on `@mcp.tool` accepts `True`, an `AppConfig`, or a dict. When you pass `True`, FastMCP checks whether the tool's return type is a Prefab type (`PrefabApp`, `Component`, or unions containing them). If it qualifies, FastMCP expands `True` into a full `AppConfig` — setting the renderer URI, CSP headers, and visibility — and stores it in the tool's `meta["ui"]` dict. + +This expansion also registers the shared Prefab renderer resource (below). The tool and the renderer are linked through a `resourceUri` field in the metadata: the tool says "render me with `ui://prefab/renderer.html`" and the host fetches that resource when it displays the result. + +Type inference works the same way. If the return type is a Prefab type and you haven't set `app` explicitly, FastMCP auto-wires the metadata as if you'd written `app=True`. + +### FastMCPApp registration + +`FastMCPApp` uses the same mechanism but adds two things. First, it tags every tool — both `@app.ui()` entry points and `@app.tool()` backends — with `meta["fastmcp"]["app"]` set to the app's name. That tag lets the server identify which app a tool belongs to when routing UI calls. + +Second, it sets `meta["ui"]["visibility"]` to control who can see each tool. Entry points default to `["model"]` (LLM-visible). Backend tools default to `["app"]` (UI-only). Hosts use this to filter the tool list. + +## Serialization + +When a Prefab tool runs, its return value — a `PrefabApp` or a bare `Component` — becomes a JSON blob the renderer can interpret. + +### `PrefabApp.to_json()` + +The entry point is `PrefabApp.to_json()`. It walks the component tree and produces a JSON object with three top-level keys: `view` (the component tree), `state` (initial state values), and `_meta` (routing metadata). + +FastMCP passes a `tool_resolver` callback to `to_json()`. Whenever the tree contains a `CallTool` action that references a function (not a string), the resolver converts it to a `ResolvedTool` with the function's registered name. This is how `CallTool(save_contact)` becomes `CallTool("save_contact")` on the wire. The resolver also handles `unwrap_result` — a flag telling the renderer to unwrap single-value results from the `{"result": value}` envelope FastMCP uses for schema compliance. + +### The `_meta.fastmcp.app` tag + +After `to_json()` produces the tree, FastMCP injects `_meta.fastmcp.app` with the app's name (if the tool belongs to a `FastMCPApp`). This tag rides along inside `structuredContent` all the way to the renderer. + +When the renderer calls a backend tool, it includes `_meta.fastmcp.app` in the `CallTool` request. The server sees this tag and routes the call through a special path that bypasses transforms (below). + +### ToolResult assembly + +The final tool result has two parts: `content` (a list of `TextContent` blocks for the LLM) and `structuredContent` (the JSON tree for the renderer). By default, Prefab tools send `"[Rendered Prefab UI]"` as the text content — just enough for the LLM to know something was rendered. If you return a `ToolResult` explicitly, you control both halves. + +## Tool call routing + +Normal tool calls go through the provider chain, which applies transforms (namespace prefixes, visibility filters) before resolving by name. App UI calls need a different path. + +### The `get_app_tool` bypass + +Backend tools are typically hidden from the model (`visibility=["app"]`). Visibility transforms would filter them out of normal resolution. And namespace transforms might rename them — `save_contact` becomes `contacts_save_contact` — while the renderer still uses the original name. + +`get_app_tool` solves both problems. When the server sees `_meta.fastmcp.app` on an incoming `CallTool` request, it calls `get_app_tool(app_name, tool_name)` instead of the normal `get_tool(name)`. This walks the provider tree directly, skipping transforms. It finds the tool by its original registered name and verifies that its `meta["fastmcp"]["app"]` matches the expected app. + +That's why `CallTool("save_contact")` keeps working when the server is mounted under a namespace. The renderer sends the original name plus the app identity; the server uses `get_app_tool` to find it without transforms in the way. + +Authorization still applies. `get_app_tool` bypasses transforms but runs auth checks against the tool's `auth` config before executing. + +### Provider delegation + +`get_app_tool` is defined on the `Provider` base class and overridden by aggregate and wrapped providers. Aggregate providers fan out the lookup across child providers in parallel. Wrapped providers (like `FastMCPProvider`, which wraps a nested `FastMCP` server) delegate to the inner server's `get_app_tool`. Backend tools are reachable through any depth of composition. + +## The renderer + +The Prefab renderer is a self-contained JavaScript application that interprets the JSON component tree and renders it as a React UI. + +### The shared resource + +FastMCP registers the renderer as a `ui://prefab/renderer.html` resource with MIME type `text/html;profile=mcp-app`. The HTML is bundled inside the `prefab-ui` Python package; `get_renderer_html()` returns it as a string. All Prefab tools on a server share this single resource. + +The resource also carries CSP metadata (via `get_renderer_csp()`) declaring the CDN domains the renderer needs. Hosts use this to configure the iframe's Content Security Policy. + +### `postMessage` communication + +The renderer lives in a sandboxed iframe and communicates with the host using `postMessage`. The protocol follows the [MCP Apps extension](https://modelcontextprotocol.io/docs/extensions/apps) spec: + +The host pushes the tool result (with `structuredContent`) into the iframe. The renderer parses the component tree, initializes state, and renders the UI. When the user interacts — submitting a form, clicking a button — and the interaction triggers a `CallTool` action, the renderer sends a `callServerTool` message back to the host via `postMessage`. The host forwards it as a regular MCP `tools/call` request to the server, including `_meta.fastmcp.app` for routing. + +The response flows back the same way: server → host → iframe via `postMessage`, and the renderer updates state with the result. + +### AppBridge + +The `@modelcontextprotocol/ext-apps` JavaScript SDK provides the `App` class (sometimes called AppBridge) that manages the `postMessage` handshake. It handles connection negotiation, tool result delivery, server tool calls, and host context (safe area insets, theme preferences). The Prefab renderer uses it internally; you only touch it directly when building [custom HTML apps](/apps/low-level). + +## The dev server + +`fastmcp dev apps` simulates the host-side behavior locally without a real MCP client. + +### Proxy architecture + +Two HTTP servers. Your MCP server runs on port 8000 with the Streamable HTTP transport. The dev UI runs on port 8080 and serves a picker page that lists your app tools. + +A reverse proxy at `/mcp` on the dev server forwards requests to your MCP server. This matters because the renderer iframe runs on `localhost:8080` and your MCP server runs on `localhost:8000` — without the proxy, the renderer's `callServerTool` requests would be cross-origin and the browser would block them. The proxy keeps everything same-origin from the iframe's perspective. + +### The launch flow + +When you select a tool and click launch, the dev UI calls the tool through the proxy, receives the `structuredContent` response, and opens a new tab. That tab loads the tool's renderer resource (via the proxy), creates an AppBridge, and pushes the tool result into the renderer. From here on it matches what a real host provides: the renderer displays the UI, and any `CallTool` actions route back through the proxy to your server. + +Auto-reload is on by default, so changes to your server code restart the MCP server automatically. The dev UI keeps running — relaunch the tool to see changes. diff --git a/docs/v3/apps/demos/bar-chart.py b/docs/v3/apps/demos/bar-chart.py new file mode 100644 index 000000000..e2430b981 --- /dev/null +++ b/docs/v3/apps/demos/bar-chart.py @@ -0,0 +1,23 @@ +from prefab_ui.app import PrefabApp +from prefab_ui.components import Column +from prefab_ui.components.charts import BarChart, ChartSeries + +data = [ + {"quarter": "Q1", "revenue": 42000, "costs": 28000}, + {"quarter": "Q2", "revenue": 51000, "costs": 31000}, + {"quarter": "Q3", "revenue": 47000, "costs": 29000}, + {"quarter": "Q4", "revenue": 63000, "costs": 35000}, +] + +with PrefabApp() as app: + with Column(css_class="p-6"): + BarChart( + data=data, + series=[ + ChartSeries(data_key="revenue", label="Revenue"), + ChartSeries(data_key="costs", label="Costs"), + ], + x_axis="quarter", + show_legend=True, + height=250, + ) diff --git a/docs/v3/apps/demos/contacts.py b/docs/v3/apps/demos/contacts.py new file mode 100644 index 000000000..0cbe60c0b --- /dev/null +++ b/docs/v3/apps/demos/contacts.py @@ -0,0 +1,78 @@ +from prefab_ui.actions import ShowToast +from prefab_ui.app import PrefabApp +from prefab_ui.components import ( + H3, + Badge, + Button, + Column, + DataTable, + DataTableColumn, + Form, + Input, + Row, + Select, + SelectOption, + Separator, +) + +contacts = [ + {"name": "Arthur Dent", "email": "arthur@earth.com", "category": "Customer"}, + {"name": "Ford Prefect", "email": "ford@betelgeuse.org", "category": "Partner"}, + { + "name": "Trillian Astra", + "email": "trillian@heartofgold.com", + "category": "Customer", + }, + {"name": "Zaphod Beeblebrox", "email": "zaphod@galaxy.gov", "category": "Vendor"}, +] + +rows = [ + { + "name": c["name"], + "email": c["email"], + "category": Badge( + c["category"], + variant="success" + if c["category"] == "Customer" + else "secondary" + if c["category"] == "Partner" + else "outline", + ), + } + for c in contacts +] + +with PrefabApp() as app: + with Column(gap=4, css_class="p-6"): + DataTable( + columns=[ + DataTableColumn(key="name", header="Name", sortable=True), + DataTableColumn(key="email", header="Email"), + DataTableColumn(key="category", header="Category"), + ], + rows=rows, + search=True, + ) + + Separator() + + H3("Add Contact") + with Form( + on_submit=ShowToast( + "Contact saved! (preview demo — no backend wired)", + variant="success", + ), + ): + with Row(gap=4): + Input(name="name", label="Name", placeholder="Full name", required=True) + Input( + name="email", + label="Email", + placeholder="name@example.com", + required=True, + ) + with Select(name="category", label="Category"): + SelectOption(value="Customer", label="Customer") + SelectOption(value="Partner", label="Partner") + SelectOption(value="Vendor", label="Vendor") + Button("Save Contact") diff --git a/docs/v3/apps/demos/dashboard.py b/docs/v3/apps/demos/dashboard.py new file mode 100644 index 000000000..06fe6285d --- /dev/null +++ b/docs/v3/apps/demos/dashboard.py @@ -0,0 +1,68 @@ +from prefab_ui.app import PrefabApp +from prefab_ui.components import ( + Badge, + Column, + DataTable, + DataTableColumn, + Row, + Separator, +) +from prefab_ui.components.charts import BarChart, ChartSeries +from prefab_ui.components.metric import Metric + +monthly = [ + {"month": "Jan", "revenue": 48200, "costs": 31000}, + {"month": "Feb", "revenue": 52100, "costs": 32500}, + {"month": "Mar", "revenue": 61800, "costs": 34200}, + {"month": "Apr", "revenue": 58400, "costs": 33800}, +] + +deals = [ + {"account": "Acme Corp", "value": "$84,000", "stage": "Won"}, + {"account": "Globex Inc", "value": "$52,000", "stage": "Negotiation"}, + {"account": "Initech", "value": "$31,500", "stage": "Proposal"}, + {"account": "Wayne Enterprises", "value": "$45,000", "stage": "Lost"}, +] + +rows = [ + { + "account": d["account"], + "value": d["value"], + "stage": Badge( + d["stage"], + variant="success" + if d["stage"] == "Won" + else "destructive" + if d["stage"] == "Lost" + else "secondary", + ), + } + for d in deals +] + +total = sum(m["revenue"] for m in monthly) + +with PrefabApp() as app: + with Column(gap=4, css_class="p-6"): + with Row(gap=6): + Metric(label="Revenue (Q1-Q4)", value=f"${total:,}") + Metric(label="Deals", value=f"{len(deals)}") + BarChart( + data=monthly, + series=[ + ChartSeries(data_key="revenue", label="Revenue"), + ChartSeries(data_key="costs", label="Costs"), + ], + x_axis="month", + show_legend=True, + height=200, + ) + Separator() + DataTable( + columns=[ + DataTableColumn(key="account", header="Account", sortable=True), + DataTableColumn(key="value", header="Value", sortable=True), + DataTableColumn(key="stage", header="Stage"), + ], + rows=rows, + ) diff --git a/docs/v3/apps/demos/data-table.py b/docs/v3/apps/demos/data-table.py new file mode 100644 index 000000000..5100237bf --- /dev/null +++ b/docs/v3/apps/demos/data-table.py @@ -0,0 +1,24 @@ +from prefab_ui.app import PrefabApp +from prefab_ui.components import Column, DataTable, DataTableColumn + +employees = [ + {"name": "Alice Chen", "role": "Staff Engineer", "dept": "Platform"}, + {"name": "Bob Martinez", "role": "Lead Designer", "dept": "Design"}, + {"name": "Carol Johnson", "role": "Senior Engineer", "dept": "Platform"}, + {"name": "David Kim", "role": "Product Manager", "dept": "Product"}, + {"name": "Eva Mueller", "role": "Engineer", "dept": "Platform"}, + {"name": "Frank Lee", "role": "Data Scientist", "dept": "ML"}, + {"name": "Grace Park", "role": "Eng Manager", "dept": "Platform"}, +] + +with PrefabApp() as app: + with Column(gap=4, css_class="p-6"): + DataTable( + columns=[ + DataTableColumn(key="name", header="Name", sortable=True), + DataTableColumn(key="role", header="Role", sortable=True), + DataTableColumn(key="dept", header="Dept", sortable=True), + ], + rows=employees, + search=True, + ) diff --git a/docs/v3/apps/demos/hitchhikers.py b/docs/v3/apps/demos/hitchhikers.py new file mode 100644 index 000000000..1554e5165 --- /dev/null +++ b/docs/v3/apps/demos/hitchhikers.py @@ -0,0 +1,461 @@ +"""The Hitchhiker's Guide dashboard from the Prefab welcome page. + +Run with: + prefab serve examples/hitchhikers-guide/dashboard.py + prefab export examples/hitchhikers-guide/dashboard.py +""" + +from prefab_ui import PrefabApp +from prefab_ui.actions import SetInterval, SetState, ShowToast +from prefab_ui.components import ( + Alert, + AlertDescription, + AlertTitle, + Badge, + Button, + Card, + CardContent, + CardDescription, + CardFooter, + CardHeader, + CardTitle, + Carousel, + Checkbox, + Column, + Combobox, + ComboboxOption, + DataTable, + DataTableColumn, + DatePicker, + Dialog, + Grid, + GridItem, + HoverCard, + Loader, + Metric, + Muted, + P, + Progress, + Radio, + RadioGroup, + Ring, + Row, + Separator, + Slider, + Switch, + Text, + Tooltip, +) +from prefab_ui.components.charts import ( + BarChart, + ChartSeries, + RadarChart, + Sparkline, +) +from prefab_ui.components.control_flow import Else, If +from prefab_ui.rx import Rx + +ctx_tick = Rx("ctx_tick") + +# Context window: climbs from 24% to ~78%, then resets +ctx_pct = (ctx_tick % 20) * 3 + 20 +ctx_variant = (ctx_pct > 70).then( + "destructive", (ctx_pct <= 33).then("success", "default") +) + +with PrefabApp( + title="Prefab Showcase", + state={"ctx_tick": 0, "improbability": 42}, + on_mount=SetInterval( + 400, + on_tick=SetState("ctx_tick", ctx_tick + 1), + ), +) as app: + with Grid(columns={"default": 1, "md": 2, "lg": 4}, gap=4): + # ── Col 1 ───────────────────────────────────────────────────────── + with Column(gap=4): + with Card(): + with CardHeader(): + CardTitle("Register Towel") + CardDescription("The most important item in the galaxy") + with CardContent(): + with Column(gap=3): + with Combobox( + placeholder="Type...", + search_placeholder="Search types...", + ): + ComboboxOption("Bath", value="bath") + ComboboxOption("Beach", value="beach") + ComboboxOption("Interstellar", value="interstellar") + ComboboxOption("Microfiber", value="micro") + DatePicker(placeholder="Registration date") + with CardFooter(): + with Row(gap=2): + with Dialog( + title="Towel Registered!", + description="Your towel has been added to the galactic registry.", + ): + Button("Register") + Text("Don't forget to bring it.") + Button("Cancel", variant="outline") + with If("{{ !pressed }}"): + Button( + "This is probably the best button to press.", + variant="success", + on_click=SetState("pressed", True), + ) + with Else(): + Button( + "Please do not press this button again.", + variant="destructive", + on_click=SetState("pressed", False), + ) + + with Card(): + with CardHeader(): + CardTitle("Ship Status") + with CardContent(): + with Column(gap=3): + with Row( + align="center", + css_class="justify-between", + ): + Text("heart-of-gold") + with HoverCard(open_delay=0, close_delay=200): + Badge("In Orbit", variant="default") + with Column(gap=2): + Text("heart-of-gold") + Muted("Deployed 2h ago") + Progress( + value=100, + max=100, + variant="success", + ) + Progress( + value=100, + max=100, + indicator_class="bg-yellow-400", + ) + with Row( + align="center", + css_class="justify-between", + ): + Text("vogon-poetry") + with Tooltip("64% — ETA 12 min", delay=0): + with Badge(variant="secondary"): + Loader(size="sm") + Text("Deploying") + Progress(value=64, max=100) + with Row( + align="center", + css_class="justify-between", + ): + Text("deep-thought") + with Tooltip( + "Computing... 7.5 million years remaining", + delay=0, + ): + with Badge(variant="outline"): + Loader(size="sm", variant="ios") + Text("Soon...") + Progress(value=12, max=100) + with Card(): + with CardHeader(): + CardTitle("Planet Ratings") + with CardContent(): + RadarChart( + data=[ + {"axis": "Views", "earth": 30, "mag": 95}, + {"axis": "Fjords", "earth": 65, "mag": 100}, + {"axis": "Pubs", "earth": 90, "mag": 10}, + {"axis": "Mice", "earth": 40, "mag": 85}, + {"axis": "Tea", "earth": 95, "mag": 15}, + {"axis": "Safety", "earth": 45, "mag": 70}, + ], + series=[ + ChartSeries(dataKey="earth", label="Earth"), + ChartSeries(dataKey="mag", label="Magrathea"), + ], + axis_key="axis", + height=200, + show_legend=True, + show_tooltip=True, + ) + + # ── Col 2 ───────────────────────────────────────────────────────── + with Column(gap=4): + with Card(): + with CardHeader(): + CardTitle("Survival Odds") + with CardContent(css_class="w-fit mx-auto"): + Ring( + value=42, + label="42%", + variant="info", + size="lg", + thickness=12, + indicator_class="group-hover:drop-shadow-[0_0_24px_rgba(59,130,246,0.9)]", + ) + with Card(): + with CardHeader(): + with Row(gap=2, align="center"): + CardTitle("Improbability Drive") + Loader( + variant="pulse", + size="sm", + css_class="text-blue-500", + ) + with CardContent(): + with Column(gap=2): + Slider( + min=0, + max=100, + value=42, + name="improbability", + ) + with Row( + align="center", + css_class="justify-between", + ): + Muted("Probable") + Muted("Infinite") + with Carousel(auto_advance=3000, show_controls=False, direction="up"): + with Alert(variant="success", icon="circle-check"): + AlertTitle("Don't Panic") + AlertDescription("Normality achieved.") + with Alert(variant="destructive", icon="triangle-alert"): + AlertTitle("Display Department") + AlertDescription("Beware of the leopard.") + with Card(): + with CardHeader(): + CardTitle("Prefect Horizon Config") + with CardContent(): + with Column(gap=3): + Switch( + label="Auto-scale agents", + value=True, + name="autoscale", + ) + Separator() + Switch( + label="Code Mode", + value=True, + name="code_mode", + ) + Separator() + Switch( + label="Tool call caching", + value=False, + name="cache", + ) + with CardFooter(): + Button( + "Save Preferences", + on_click=ShowToast("Preferences saved!"), + ) + with Card(): + with CardHeader(): + CardTitle("Travel Class") + with CardContent(): + with RadioGroup(name="travel_class"): + Radio(option="economy", label="Economy") + Radio(option="business", label="Business Class") + Radio( + option="improbability", + label="Infinite Improbability", + value=True, + ) + + # ── Cols 3–4: summary row, chart, then 2-col grid below ───────── + with GridItem(css_class="md:col-span-2"): + with Column(gap=4): + with Grid(columns=2, gap=4, css_class="h-32"): + with Card(): + with CardHeader(): + CardTitle("Context Window") + with CardContent(): + with Column( + gap=6, + justify="center", + css_class="h-full", + ): + with Row( + align="center", + css_class="justify-between", + ): + Text(f"{ctx_pct}% used") + Muted(f"{ctx_pct * 2}k / 200k tokens") + with Tooltip( + "Auto-compact buffer: 12%", + delay=0, + ): + Progress( + value=ctx_pct, + max=100, + variant=ctx_variant, + ) + with Card(css_class="pb-0 gap-0"): + with CardContent(): + Metric( + label="Fjords designed", + value="1,847", + delta="+3 coastlines", + ) + Sparkline( + data=[ + 820, + 950, + 1100, + 980, + 1250, + 1400, + 1350, + 1500, + 1680, + 1847, + ], + variant="success", + fill=True, + css_class="h-16", + ) + with Card(): + with CardHeader(): + CardTitle("Towel Incidents") + with CardContent(): + BarChart( + data=[ + {"month": "Jan", "lost": 8, "found": 5}, + {"month": "Feb", "lost": 24, "found": 15}, + {"month": "Mar", "lost": 12, "found": 28}, + {"month": "Apr", "lost": 35, "found": 19}, + {"month": "May", "lost": 18, "found": 38}, + {"month": "Jun", "lost": 42, "found": 30}, + ], + series=[ + ChartSeries(dataKey="lost", label="Lost"), + ChartSeries(dataKey="found", label="Found"), + ], + x_axis="month", + height=200, + bar_radius=4, + show_legend=True, + show_tooltip=True, + show_grid=True, + ) + + with Grid(columns=2, gap=4): + with Column(gap=4): + with Card(): + with CardContent(): + with Column(gap=2): + Checkbox(label="Towel packed", value=True) + Checkbox(label="Guide charged", value=True) + Checkbox( + label="Babel fish inserted", + value=False, + ) + with Card(): + with CardHeader(): + CardTitle("Marvin's Mood") + with CardContent(): + with Column(gap=3): + P("How's life?") + with Column(gap=2): + Button( + "Meh", + on_click=ShowToast( + "Noted. Enthusiasm levels nominal." + ), + ) + Button( + "Depressed", + variant="info", + on_click=ShowToast( + "I think you ought to " + "know I'm feeling very " + "depressed." + ), + ) + Button( + "Don't talk to me about life", + variant="warning", + on_click=ShowToast( + "Brain the size of a " + "planet and they ask me " + "to pick up a piece of " + "paper." + ), + ) + + with Column(gap=4): + with Card(): + with CardContent(): + with Row(gap=2, align="center"): + Loader(variant="dots", size="sm") + Muted("Marvin is thinking...") + with Card(): + with CardContent(): + DataTable( + columns=[ + DataTableColumn( + key="crew", + header="Crew", + sortable=True, + ), + DataTableColumn( + key="species", + header="Species", + sortable=True, + ), + DataTableColumn( + key="towel", + header="Towel?", + sortable=True, + ), + DataTableColumn( + key="status", + header="Status", + sortable=True, + ), + ], + rows=[ + { + "crew": "Arthur Dent", + "species": "Human", + "towel": "Yes", + "status": "Confused", + }, + { + "crew": "Ford Prefect", + "species": "Betelgeusian", + "towel": "Always", + "status": "Drinking", + }, + { + "crew": "Zaphod", + "species": "Betelgeusian", + "towel": "Lost it", + "status": "Presidential", + }, + { + "crew": "Trillian", + "species": "Human", + "towel": "Yes", + "status": "Navigating", + }, + { + "crew": "Marvin", + "species": "Android", + "towel": "No point", + "status": "Depressed", + }, + { + "crew": "Slartibartfast", + "species": "Magrathean", + "towel": "Somewhere", + "status": "Designing", + }, + ], + search=True, + paginated=False, + ) diff --git a/docs/v3/apps/demos/pie-chart.py b/docs/v3/apps/demos/pie-chart.py new file mode 100644 index 000000000..c1fb489e4 --- /dev/null +++ b/docs/v3/apps/demos/pie-chart.py @@ -0,0 +1,21 @@ +from prefab_ui.app import PrefabApp +from prefab_ui.components import Column +from prefab_ui.components.charts import PieChart + +data = [ + {"category": "Bug", "count": 42}, + {"category": "Feature", "count": 28}, + {"category": "Docs", "count": 15}, + {"category": "Infra", "count": 10}, +] + +with PrefabApp() as app: + with Column(css_class="p-6"): + PieChart( + data=data, + data_key="count", + name_key="category", + inner_radius=50, + show_legend=True, + height=240, + ) diff --git a/docs/v3/apps/demos/reactive.py b/docs/v3/apps/demos/reactive.py new file mode 100644 index 000000000..16f2f9829 --- /dev/null +++ b/docs/v3/apps/demos/reactive.py @@ -0,0 +1,66 @@ +from prefab_ui.app import PrefabApp +from prefab_ui.components import ( + Column, + Row, + Select, + SelectOption, + Switch, + Text, +) +from prefab_ui.components.charts import BarChart, ChartSeries +from prefab_ui.components.control_flow import If +from prefab_ui.components.metric import Metric +from prefab_ui.rx import Rx + +region = Rx("region") + +north = [ + {"month": "Jan", "sales": 22000}, + {"month": "Feb", "sales": 25500}, + {"month": "Mar", "sales": 24200}, +] +south = [ + {"month": "Jan", "sales": 5800}, + {"month": "Feb", "sales": 6400}, + {"month": "Mar", "sales": 5600}, +] +west = [ + {"month": "Jan", "sales": 6000}, + {"month": "Feb", "sales": 6000}, + {"month": "Mar", "sales": 5600}, +] + +with PrefabApp( + state={ + "region": "north", + "north": north, + "south": south, + "west": west, + "show_target": True, + }, +) as app: + with Column( + gap=4, + css_class="p-6", + let={ + "data": "{{ region == 'south' ? south : region == 'west' ? west : north }}", + }, + ): + with Row(gap=4, align="center"): + with Select(name="region", css_class="w-40"): + SelectOption(value="north", label="North") + SelectOption(value="south", label="South") + SelectOption(value="west", label="West") + Switch(name="show_target", css_class="ml-auto") + Text("Show target", css_class="text-sm text-muted-foreground") + BarChart( + data=Rx("data"), + series=[ChartSeries(data_key="sales", label="Sales")], + x_axis="month", + height=200, + ) + with If(Rx("show_target")): + Metric( + label="Q1 Target", + value="$75,000", + ) diff --git a/docs/v3/apps/demos/team-directory-reactive.py b/docs/v3/apps/demos/team-directory-reactive.py new file mode 100644 index 000000000..b6aa004f7 --- /dev/null +++ b/docs/v3/apps/demos/team-directory-reactive.py @@ -0,0 +1,116 @@ +from collections import Counter + +from prefab_ui.actions import SetState +from prefab_ui.app import PrefabApp +from prefab_ui.components import ( + H3, + Badge, + Card, + CardContent, + CardHeader, + Column, + DataTable, + DataTableColumn, + Grid, + Row, + Small, + Text, +) +from prefab_ui.components.charts import PieChart +from prefab_ui.components.control_flow import If +from prefab_ui.rx import STATE, Rx + +MEMBERS = [ + { + "name": "Alice Chen", + "role": "Staff Engineer", + "office": "San Francisco", + "email": "alice@company.com", + "projects": 3, + }, + { + "name": "Bob Martinez", + "role": "Lead Designer", + "office": "New York", + "email": "bob@company.com", + "projects": 5, + }, + { + "name": "Carol Johnson", + "role": "Senior Engineer", + "office": "London", + "email": "carol@company.com", + "projects": 2, + }, + { + "name": "David Kim", + "role": "Product Manager", + "office": "San Francisco", + "email": "david@company.com", + "projects": 7, + }, + { + "name": "Eva Mueller", + "role": "Engineer", + "office": "Berlin", + "email": "eva@company.com", + "projects": 1, + }, + { + "name": "Frank Lee", + "role": "Data Scientist", + "office": "San Francisco", + "email": "frank@company.com", + "projects": 4, + }, + { + "name": "Grace Park", + "role": "Engineering Manager", + "office": "New York", + "email": "grace@company.com", + "projects": 6, + }, +] + +OFFICE_COUNTS = [ + {"office": office, "count": count} + for office, count in Counter(m["office"] for m in MEMBERS).items() +] + +with PrefabApp(state={"selected": None}) as app: + with Column(gap=4, css_class="p-6"): + with Grid(columns=[1, 2], gap=4): + PieChart( + data=OFFICE_COUNTS, + data_key="count", + name_key="office", + show_legend=True, + ) + DataTable( + columns=[ + DataTableColumn(key="name", header="Name", sortable=True), + DataTableColumn(key="role", header="Role", sortable=True), + DataTableColumn(key="office", header="Office", sortable=True), + ], + rows=MEMBERS, + search=True, + on_row_click=SetState("selected", Rx("$event")), + ) + + with If(STATE.selected): + with Card(): + with CardHeader(): + with Row(gap=2, align="center"): + H3(Rx("selected.name")) + Badge(Rx("selected.office")) + with CardContent(): + with Grid(columns=3, gap=4): + with Column(gap=0): + Small("Role") + Text(Rx("selected.role")) + with Column(gap=0): + Small("Email") + Text(Rx("selected.email")) + with Column(gap=0): + Small("Active Projects") + Text(Rx("selected.projects")) diff --git a/docs/v3/apps/demos/team-directory.py b/docs/v3/apps/demos/team-directory.py new file mode 100644 index 000000000..7cfe21bc9 --- /dev/null +++ b/docs/v3/apps/demos/team-directory.py @@ -0,0 +1,39 @@ +from collections import Counter + +from prefab_ui.app import PrefabApp +from prefab_ui.components import Column, DataTable, DataTableColumn, Grid +from prefab_ui.components.charts import PieChart + +members = [ + {"name": "Alice Chen", "role": "Staff Engineer", "office": "San Francisco"}, + {"name": "Bob Martinez", "role": "Lead Designer", "office": "New York"}, + {"name": "Carol Johnson", "role": "Senior Engineer", "office": "London"}, + {"name": "David Kim", "role": "Product Manager", "office": "San Francisco"}, + {"name": "Eva Mueller", "role": "Engineer", "office": "Berlin"}, + {"name": "Frank Lee", "role": "Data Scientist", "office": "San Francisco"}, + {"name": "Grace Park", "role": "Engineering Manager", "office": "New York"}, +] + +office_counts = [ + {"office": office, "count": count} + for office, count in Counter(m["office"] for m in members).items() +] + +with PrefabApp() as app: + with Column(gap=4, css_class="p-6"): + with Grid(columns=[1, 2], gap=4): + PieChart( + data=office_counts, + data_key="count", + name_key="office", + show_legend=True, + ) + DataTable( + columns=[ + DataTableColumn(key="name", header="Name", sortable=True), + DataTableColumn(key="role", header="Role", sortable=True), + DataTableColumn(key="office", header="Office", sortable=True), + ], + rows=members, + search=True, + ) diff --git a/docs/v3/apps/development.mdx b/docs/v3/apps/development.mdx new file mode 100644 index 000000000..0d3a71ac7 --- /dev/null +++ b/docs/v3/apps/development.mdx @@ -0,0 +1,65 @@ +--- +title: Development +sidebarTitle: Development +description: Preview and test your app tools locally without a full MCP host. +icon: flask +--- + +import { VersionBadge } from '/snippets/version-badge.mdx' + + + + + The dev UI showing a rendered Prefab app with the MCP inspector panel + + +`fastmcp dev apps` gives you a browser preview for your app tools without needing an MCP host client. It starts your server and a local dev UI side by side: you pick a tool, fill in its arguments, and the rendered result opens in a new tab. + +Works with both [Interactive Tools](/apps/prefab) and [custom HTML apps](/apps/low-level). + +## Quick start + +```bash +fastmcp dev apps server.py +``` + +The dev UI opens at `http://localhost:8080`. Your MCP server runs on port 8000 with auto-reload enabled by default — save a file and the server restarts automatically. + +## How it works + +The dev server does three things: + +The **picker page** connects to your MCP server, finds all tools with UI metadata, and renders a form for each one. The forms are auto-generated from the tool's input schema — text fields, dropdowns, checkboxes, all wired up. + +When you submit a form, the dev server **calls your tool** via the MCP protocol and opens the result in a new tab. The result page loads the tool's UI resource (the Prefab renderer or your custom HTML) inside an AppBridge — the same protocol that real MCP hosts use. + +A **reverse proxy** on `/mcp` forwards requests from the browser to your MCP server, avoiding CORS issues that would otherwise block the iframe-based renderer from talking to a different port. + +## MCP inspector + +The dev UI includes an inspector panel on the left side that captures MCP traffic in real time. It shows JSON-RPC messages flowing between the browser and your server — requests, responses, and AppBridge `postMessage` traffic. + +Each entry shows direction, method, timing, and a smart summary. Click any entry to expand the full JSON-RPC body. The panel auto-scrolls to new messages unless you've scrolled up to inspect older ones. + +The inspector is useful for debugging: you can see exactly what arguments your tool received, what it returned, and how the AppBridge communicated with the renderer. + +## Options + +```bash +fastmcp dev apps server.py:mcp --mcp-port 9000 --dev-port 9090 --no-reload +``` + +| Option | Flag | Default | Description | +| ------ | ---- | ------- | ----------- | +| MCP Port | `--mcp-port` | `8000` | Port for your MCP server | +| Dev Port | `--dev-port` | `8080` | Port for the dev UI | +| Auto-Reload | `--reload` / `--no-reload` | On | Watch files and restart the server on changes | + +## Multiple tools + +If your server has multiple app tools, the picker shows a dropdown. Each tool gets its own form and launch button. The tool's `title` is displayed when available, falling back to the tool name. + +```bash +# Server with multiple app tools +fastmcp dev apps examples/apps/contacts/contacts_server.py +``` diff --git a/docs/v3/apps/examples.mdx b/docs/v3/apps/examples.mdx new file mode 100644 index 000000000..5078120e7 --- /dev/null +++ b/docs/v3/apps/examples.mdx @@ -0,0 +1,92 @@ +--- +title: Examples +sidebarTitle: Examples +description: Example apps you can run right now. +icon: images +--- + +import { VersionBadge } from '/snippets/version-badge.mdx' + + + +Each tile below is a working FastMCP server you can run with `fastmcp dev apps` or connect to from any MCP host. Source lives in `examples/apps/` in the repository. + + + +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +## Running the examples + +Preview any example in your browser with the dev server: + +```bash +pip install "fastmcp[apps]" +fastmcp dev apps examples/apps/sales_dashboard/sales_dashboard_server.py +``` + +The dev UI lets you pick a tool and fill in arguments. In a real deployment the LLM provides those arguments from conversation context — the quiz example especially shines when connected to a host like Goose or Claude Desktop, where the LLM generates the questions itself. + +## Standalone apps + +### Sales dashboard + +A full dashboard with KPI metrics, revenue trends, segment breakdown, and a deal pipeline table. Shows what you can build with a single `app=True` tool and Prefab's chart and data components. + +```bash +fastmcp dev apps examples/apps/sales_dashboard/sales_dashboard_server.py +``` + +### System monitor + +Reads live CPU, memory, and disk stats from your machine using `psutil`. Auto-refreshes via `SetInterval` calling a backend tool, with a dropdown to control the refresh rate. The chart accumulates up to 100 data points over time. + +```bash +pip install psutil +fastmcp dev apps examples/apps/system_monitor/system_monitor_server.py +``` + +### Quiz + +The LLM generates trivia questions and passes them to the tool. The user answers via buttons, sees correct/incorrect feedback, and tracks score across questions. Demonstrates multi-turn client-side state with FastMCPApp. + +```bash +fastmcp dev apps examples/apps/quiz/quiz_server.py +``` + +### Interactive map + +Accepts addresses or place names, geocodes them via OpenStreetMap Nominatim (free, no API key), and renders an interactive Leaflet map using Prefab's `Embed` component with inline HTML. A reminder that Prefab apps can break out of built-in components when they need to. + +```bash +fastmcp dev apps examples/apps/map/map_server.py +``` + +For ready-made building blocks like approvals, choice pickers, file uploads, and Pydantic forms, see the [Providers](/apps/providers/approval) group. diff --git a/docs/v3/apps/fastmcp-app.mdx b/docs/v3/apps/fastmcp-app.mdx new file mode 100644 index 000000000..55b3b7ed7 --- /dev/null +++ b/docs/v3/apps/fastmcp-app.mdx @@ -0,0 +1,470 @@ +--- +title: FastMCPApp +sidebarTitle: FastMCPApp +description: Wire an interactive UI to backend tools with managed visibility and composition safety. +icon: puzzle-piece +tag: NEW +--- + +import { VersionBadge } from '/snippets/version-badge.mdx' +import PrefabPinWarning from '/snippets/prefab-pin-warning.mdx' +import { PrefabDemoFrame } from '/snippets/prefab-demo-frame.mdx' + + + + + + + +Search a list, fill out a form, click save, the list updates. That pattern — UI that reads and writes data on the server — needs two things: backend tools that actually do the work, and a way to call them from the UI. `FastMCPApp` handles the wiring. + +You'll build up to the contacts app above by the end of this page. Let's start with something smaller. + +## A minimal interactive app + +The smallest interactive app: a form that saves a note, and a list that updates when the user submits. + +```python +from prefab_ui.actions import SetState, ShowToast +from prefab_ui.actions.mcp import CallTool +from prefab_ui.app import PrefabApp +from prefab_ui.components import ( + Badge, Button, Column, ForEach, Form, Heading, + Input, Row, Separator, Text, +) +from prefab_ui.rx import RESULT +from fastmcp import FastMCP, FastMCPApp + +app = FastMCPApp("Notes") +notes_db: list[dict] = [] + + +@app.tool() +def add_note(title: str, body: str) -> list[dict]: + """Save a note and return all notes.""" + notes_db.append({"title": title, "body": body}) + return list(notes_db) + + +@app.ui() +def notes_app() -> PrefabApp: + """Open the notes app.""" + with Column(gap=6, css_class="p-6") as view: + Heading("Notes") + + with ForEach("notes") as note: + with Row(gap=2, align="center"): + Text(note.title, css_class="font-semibold") + Badge(note.body) + + Separator() + + with Form( + on_submit=CallTool( + "add_note", + on_success=[ + SetState("notes", RESULT), + ShowToast("Note saved!", variant="success"), + ], + on_error=ShowToast("Failed to save", variant="error"), + ) + ): + Input(name="title", label="Title", required=True) + Input(name="body", label="Body", required=True) + Button("Add Note") + + return PrefabApp(view=view, state={"notes": list(notes_db)}) + + +mcp = FastMCP("Notes Server", providers=[app]) +``` + +The model sees one tool: `notes_app`. Calling it opens the UI. When the user submits the form, `CallTool("add_note")` fires, the server saves the note, returns the updated list, and `SetState("notes", RESULT)` writes that list back into state. `ForEach("notes")` re-renders. The model never sees `add_note` — it's UI-only. + +## Why not just `@mcp.tool(app=True)`? + +A fair question. Any [Interactive Tool](/apps/prefab) can call a server tool — there's nothing stopping you from putting `CallTool("add_note")` inside a regular `@mcp.tool(app=True)`. It works for one or two tools. Things get harder once the app grows: + +- Which tools should the model see, and which are UI-only? +- What happens to `CallTool("add_note")` when you mount this server under a namespace and the tool becomes `notes_add_note`? +- How do you keep it all wired correctly as you compose servers? + +`FastMCPApp` owns these concerns. Entry points register as model-visible. Backend tools register as UI-only by default. Backend tools get globally stable identifiers that survive namespacing, and `CallTool` accepts function references, so references stay valid when you compose servers. + +The rest of this page covers each piece in turn. + +## `@app.ui()` — entry points + +Entry points are what the model sees. They return a `PrefabApp` and default to `visibility=["model"]`, showing up in the LLM tool list but not callable from within the UI. + +```python +@app.ui() +def dashboard() -> PrefabApp: + """The model calls this to open the dashboard.""" + with Column(gap=4, css_class="p-6") as view: + Heading("Dashboard") + ... + return PrefabApp(view=view) +``` + +`@app.ui()` supports the same options as `@mcp.tool`: `name`, `description`, `title`, `tags`, `icons`, `auth`, and `timeout`. + +## `@app.tool()` — backend tools + +Backend tools do the work. By default they're visible only to the UI (`visibility=["app"]`), not the model. + +```python +@app.tool() +def save_contact(name: str, email: str) -> list[dict]: + """Save a contact and return the updated list.""" + db.append({"name": name, "email": email}) + return list(db) +``` + +If you want a tool callable by both the model and the UI, pass `model=True`: + +```python +@app.tool(model=True) +def list_contacts() -> list[dict]: + """Both the model and the UI can call this.""" + return list(db) +``` + +Backend tools support `name`, `description`, `auth`, and `timeout`. + +## `CallTool` — UI → backend + +`CallTool` is how the UI invokes a backend tool. Pass the tool's name (or a direct function reference): + +```python +from prefab_ui.actions.mcp import CallTool + +CallTool("save_contact", arguments={"name": "Alice", "email": "alice@example.com"}) + +# Or a function reference — resolves to a stable global key +CallTool(save_contact, arguments={...}) +``` + +Arguments can reference state with `Rx`: + +```python +from prefab_ui.rx import STATE + +CallTool("search", arguments={"query": STATE.search_term}) +``` + +### Handling results + +Server calls are async. Use `on_success` and `on_error` callbacks: + +```python +from prefab_ui.actions import SetState, ShowToast +from prefab_ui.rx import RESULT + +CallTool( + "save_contact", + on_success=[ + SetState("contacts", RESULT), + ShowToast("Saved!", variant="success"), + ], + on_error=ShowToast("Something went wrong", variant="error"), +) +``` + +`RESULT` is a reactive reference to the tool's return value, available inside `on_success`. `ERROR` (from `prefab_ui.rx`) is the counterpart inside `on_error`. Callbacks can be a single action or a list; they execute in order and short-circuit on error. + +### `result_key` shorthand + +When a tool's return value should replace a state key, use `result_key`: + +```python +CallTool("list_contacts", result_key="contacts") + +# same as: +CallTool("list_contacts", on_success=SetState("contacts", RESULT)) +``` + +## Actions + +`CallTool` is one of several actions. Actions attach to handlers like `on_click`, `on_submit`, and `on_change`. + +Client-side actions run instantly in the browser, no server round-trip: + +```python +from prefab_ui.actions import SetState, ToggleState, AppendState, PopState, ShowToast + +SetState("count", 42) +ToggleState("expanded") +AppendState("items", {"name": "New Item"}) +PopState("items", 0) +ShowToast("Done!", variant="success") +``` + +Pass a list to chain actions: + +```python +Button( + "Reset", + on_click=[ + SetState("query", ""), + SetState("results", []), + ShowToast("Cleared"), + ], +) +``` + +### Loading states + +A common pattern: disable a button and show a spinner while a call is in flight. + +```python +from prefab_ui.rx import Rx + +saving = Rx("saving") + +Button( + saving.then("Saving...", "Save"), + disabled=saving, + on_click=[ + SetState("saving", True), + CallTool( + "save_data", + on_success=[ + SetState("saving", False), + SetState("result", RESULT), + ShowToast("Saved!", variant="success"), + ], + on_error=[ + SetState("saving", False), + ShowToast("Failed", variant="error"), + ], + ), + ], +) + +# PrefabApp(view=view, state={"saving": False, ...}) +``` + +## Forms + +Forms collect input and submit it to a tool. When submitted, named input values become the tool's arguments. + +### Manual forms + +```python +from prefab_ui.components import Form, Input, Select, SelectOption, Textarea, Button + +with Form( + on_submit=CallTool( + "create_ticket", + on_success=ShowToast("Ticket created!", variant="success"), + ) +): + Input(name="title", label="Title", required=True) + with Select(name="priority", label="Priority"): + SelectOption("Low", value="low") + SelectOption("Medium", value="medium") + SelectOption("High", value="high") + Textarea(name="description", label="Description") + Button("Create Ticket") +``` + +On submit, `CallTool` receives `{"title": ..., "priority": ..., "description": ...}`. + +### Forms from Pydantic models + +For structured input, `Form.from_model()` generates the whole form — inputs, labels, validation: + +```python +from typing import Literal +from pydantic import BaseModel, Field + +class BugReport(BaseModel): + title: str = Field(title="Bug Title") + severity: Literal["low", "medium", "high", "critical"] = Field( + title="Severity", default="medium" + ) + description: str = Field(title="Description") + + +@app.ui() +def report_bug() -> PrefabApp: + with Column(gap=4, css_class="p-6") as view: + Heading("Report a Bug") + Form.from_model( + BugReport, + on_submit=CallTool( + "create_bug", + on_success=ShowToast("Bug filed!", variant="success"), + ), + ) + return PrefabApp(view=view) + + +@app.tool() +def create_bug(data: BugReport) -> str: + return f"Created: {data.title}" +``` + +`str` becomes a text input, `Literal` becomes a select, `bool` becomes a checkbox. Field titles and defaults are respected. + +## Composition and namespacing + +The reason `FastMCPApp` exists — and why you'd pick it over plain `@mcp.tool(app=True)` with string-based `CallTool` — is composition safety. + +When you mount a server under a namespace, tool names get prefixed: + +```python +platform = FastMCP("Platform") +platform.mount("contacts", contacts_server) + +# "save_contact" becomes "contacts_save_contact" +``` + +`CallTool("save_contact")` would now be broken. But `CallTool(save_contact)` with a function reference resolves to a globally stable identifier that bypasses the namespace. Your app works the same whether standalone or mounted. + +### Mounting + +`FastMCPApp` is a Provider. Add it to a server with `providers=` or `add_provider`: + +```python +mcp = FastMCP("Platform", providers=[app]) + +# or +mcp = FastMCP("Platform") +mcp.add_provider(app) +``` + +Multiple apps can coexist; each gets its own global keys, so there's no collision even if two apps have a tool named `save`. + +```python +mcp = FastMCP("Platform", providers=[contacts_app, inventory_app, billing_app]) +``` + +### Running standalone + +For development, `FastMCPApp` has a `run()` shortcut that wraps itself in a temporary `FastMCP` server: + +```python +app = FastMCPApp("Contacts") +# ... register tools ... + +if __name__ == "__main__": + app.run() +``` + +## A full example: contact manager + +This brings everything together — entry point, backend tools, Pydantic form, manual form, state, actions, and multi-visibility. + +```python expandable +from __future__ import annotations + +from typing import Literal + +from prefab_ui.actions import SetState, ShowToast +from prefab_ui.actions.mcp import CallTool +from prefab_ui.app import PrefabApp +from prefab_ui.components import ( + Badge, Button, Column, ForEach, Form, + Heading, Input, Muted, Row, Separator, Text, +) +from prefab_ui.rx import RESULT, Rx +from pydantic import BaseModel, Field +from fastmcp import FastMCP, FastMCPApp + +contacts_db: list[dict] = [ + {"name": "Arthur Dent", "email": "arthur@earth.com", "category": "Customer"}, + {"name": "Ford Prefect", "email": "ford@betelgeuse.org", "category": "Partner"}, +] + + +class ContactModel(BaseModel): + name: str = Field(title="Full Name", min_length=1) + email: str = Field(title="Email") + category: Literal["Customer", "Vendor", "Partner", "Other"] = "Other" + + +app = FastMCPApp("Contacts") + + +@app.tool() +def save_contact(data: ContactModel) -> list[dict]: + """Save a new contact and return the updated list.""" + contacts_db.append(data.model_dump()) + return list(contacts_db) + + +@app.tool() +def search_contacts(query: str) -> list[dict]: + """Filter contacts by name or email.""" + q = query.lower() + return [ + c for c in contacts_db + if q in c["name"].lower() or q in c["email"].lower() + ] + + +@app.tool(model=True) +def list_contacts() -> list[dict]: + """Return all contacts. Visible to both the model and the UI.""" + return list(contacts_db) + + +@app.ui() +def contact_manager() -> PrefabApp: + """Open the contact manager.""" + with Column(gap=6, css_class="p-6") as view: + Heading("Contacts") + + with ForEach("contacts") as contact: + with Row(gap=2, align="center"): + Text(contact.name, css_class="font-medium") + Muted(contact.email) + Badge(contact.category) + + Separator() + + Heading("Add Contact", level=3) + Form.from_model( + ContactModel, + on_submit=CallTool( + "save_contact", + on_success=[ + SetState("contacts", RESULT), + ShowToast("Contact saved!", variant="success"), + ], + on_error=ShowToast("Failed to save", variant="error"), + ), + ) + + Separator() + + Heading("Search", level=3) + with Form( + on_submit=CallTool( + "search_contacts", + arguments={"query": Rx("query")}, + on_success=SetState("contacts", RESULT), + ) + ): + Input(name="query", placeholder="Search by name or email...") + Button("Search") + + return PrefabApp(view=view, state={"contacts": list(contacts_db)}) + + +mcp = FastMCP("Contacts Server", providers=[app]) + +if __name__ == "__main__": + mcp.run() +``` + +Also available as a runnable server at `examples/apps/contacts/contacts_server.py`. + +## Next steps + +- **[Interactive Tools](/apps/prefab)** — the building blocks: charts, tables, dashboards, reactive state +- **[Examples](/apps/examples)** — complete working servers +- **[Development](/apps/development)** — preview and test app tools locally +- **[Prefab UI docs](https://prefab.prefect.io)** — full component reference diff --git a/docs/v3/apps/generative.mdx b/docs/v3/apps/generative.mdx new file mode 100644 index 000000000..b6293d32b --- /dev/null +++ b/docs/v3/apps/generative.mdx @@ -0,0 +1,134 @@ +--- +title: Generative UI +sidebarTitle: Generative UI +description: Let the LLM build custom Prefab UIs on the fly. +icon: wand-magic-sparkles +tag: NEW +--- + +import { VersionBadge } from '/snippets/version-badge.mdx' + + + +