diff --git a/README.md b/README.md index 26ce43b..a39f247 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,51 @@ -# bEvr Stack +# MCP Data Visualization Lab -A modern full-stack TypeScript monorepo with end-to-end type safety, using Bun, -Effect, Vite, and React. Heavily inspired by the [bhvr](https://bhvr.dev/) stack -but the addition of Effect and Turborepo. Includes a Model Context Protocol -(MCP) server for AI assistant integrations. +Generative UI for data visualization. This lab explores how MCP Apps and web +components can give LLM chat applications first-class data visualization tools. +The goal is to prove a white-label approach: a baseline chart library that can +be branded and embedded into chat experiences. -![screenshot of client app](./e2e/smoke.spec.ts-snapshots/app-layout-chromium-darwin.png) +![screenshot of client app](./e2e/smoke.spec.ts-snapshots/screenshot.png) -## Features +MCPJam Inspector: https://app.mcpjam.com/shared/edu-mcp-app-live/1CD8UxW3lT1FwVFXcGZM_ -- **End-to-end TypeScript**: Full type safety from client to server -- **Shared Domain**: Common types and utilities across all apps -- **Effect Integration**: Built for composable, functional programming with - [Effect](https://effect.website) -- **MCP Server**: [Model Context Protocol](https://modelcontextprotocol.io/) - server for AI assistant tools and resources -- **Modern Tooling**: [Turborepo](https://turbo.build/), [Bun](https://bun.sh/), - [Vite](https://vitejs.dev/), and [React](https://react.dev/) -- **Zero Config**: Pre-configured linting and formatting with - [Biome](https://biomejs.dev) -- **Flexible Deployment**: Deploy anywhere without vendor lock-in +## What This Lab Explores + +- MCP App patterns for data visualization in LLM chat +- Web component chart primitives built with Plot +- A white-label design system driven by host CSS variables +- Composition between web components and visualization vocabularies + +## Goals + +1. Build web component charts with Plot +2. Expose UI tools to LLMs for controlling and interacting with charts +3. Create a design system that adapts to host interfaces +4. Provide chart tools for: + - Line chart + - Bar chart + - Scatterplot +5. Bonus: publish components as a package or registry + +## Achieved So Far + +- Bar chart MCP App widget +- Line chart MCP App widget +- Scatterplot MCP App widget +- MCP server wiring to serve MCP Apps to chat clients + +## What’s Next + +- Expand the chart catalog (compositional layouts, multi-series, annotations) +- Theming system based on host CSS variables +- Connect to a real data source (Postgres-backed reporting dashboard) +- Explore web component composition patterns for chart vocabularies + +## Side Quests + +- Build a separate MCP server for the reporting dashboard and connect it to chat +- Prove a host-injected theming system for MCP Apps +- Test composition patterns with Plot/D3 and vocabulary primitives ## Quick Start @@ -36,7 +62,7 @@ bun run build ### Formatting and Linting -Format and lint the codebase using Ultracite: +Format and lint the codebase using Biome: ```bash # Format code @@ -46,7 +72,7 @@ bun format bun lint # Type check -bun run type-check +bun type-check ``` ### Testing @@ -99,7 +125,10 @@ should be committed to git. Update them when UI changes are intentional. │ ├── config-typescript/ # TypeScript configurations │ ├── domain/ # Shared Schema definitions │ ├── observability/ # OpenTelemetry setup -│ └── presence/ # Presence tracking service +│ ├── presence/ # Presence tracking service +│ ├── widget-bar-chart/ # MCP App bar chart widget +│ ├── widget-line-chart/ # MCP App line chart widget +│ └── widget-scatterplot/ # MCP App scatterplot widget ├── docker-compose.yaml # Docker Compose configuration for deployment ├── package.json # Root package.json with workspaces └── turbo.json # Turborepo configuration @@ -122,6 +151,9 @@ should be committed to git. Update them when UI changes are intentional. | `@repo/ai` | AI tooling and service layers built on [@effect/ai](https://github.com/tim-smart/effect-io-ai) | | `@repo/observability` | Shared OpenTelemetry setup | | `@repo/presence` | Presence tracking service for WebSocket clients | +| `widget-bar-chart` | MCP App bar chart widget | +| `widget-line-chart` | MCP App line chart widget | +| `widget-scatterplot` | MCP App scatterplot widget | ## Development @@ -178,6 +210,7 @@ import { ApiResponse } from "@repo/domain/Api"; ## Learn More -- [Turborepo](https://turborepo.com/docs) +- [MCP Apps Spec](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx) +- [MCP UI](https://github.com/MCP-UI-Org/mcp-ui) - [Effect](https://effect.website/docs/introduction) -- [Vite](https://vitejs.dev/guide/) +- [Plot](https://observablehq.com/plot/) diff --git a/apps/client/README.md b/apps/client/README.md index 0bb9f77..17fb797 100644 --- a/apps/client/README.md +++ b/apps/client/README.md @@ -1,7 +1,7 @@ # Client App React frontend built with Vite and TypeScript, part of the -[bEvr stack](../../README.md). +[MCP Data Visualization Lab](../../README.md). ## Stack @@ -79,4 +79,4 @@ Tests are colocated with source files using the `*.test.tsx` pattern. - [React Documentation](https://react.dev) - [Vite Documentation](https://vitejs.dev) -- [bEvr Stack Overview](../../README.md) +- [Lab Overview](../../README.md) diff --git a/apps/server-mcp/README.md b/apps/server-mcp/README.md index 03add60..08d3bcc 100644 --- a/apps/server-mcp/README.md +++ b/apps/server-mcp/README.md @@ -2,7 +2,7 @@ [Model Context Protocol](https://modelcontextprotocol.io/) server built with [Effect Platform](https://effect.website/docs/platform) and TypeScript, part of -the [bEvr stack](../../README.md). +the [MCP Data Visualization Lab](../../README.md). ## Stack @@ -95,4 +95,4 @@ const UserToolkitLive = UserToolkit.toLayer({ - [Model Context Protocol Documentation](https://modelcontextprotocol.io/) - [@effect/ai Documentation](https://github.com/tim-smart/effect-io-ai) - [Effect Documentation](https://effect.website) -- [bEvr Stack Overview](../../README.md) +- [Lab Overview](../../README.md) diff --git a/apps/server/README.md b/apps/server/README.md index 004b124..19db10f 100644 --- a/apps/server/README.md +++ b/apps/server/README.md @@ -1,7 +1,7 @@ # Server API [Effect Platform](https://effect.website/docs/platform) backend API with -TypeScript, part of the [bEvr stack](../../README.md). +TypeScript, part of the [MCP Data Visualization Lab](../../README.md). ## Stack @@ -94,4 +94,4 @@ automatically handles Effect execution and error propagation. ## Learn More - [Effect Documentation](https://effect.website) -- [bEvr Stack Overview](../../README.md) +- [Lab Overview](../../README.md) diff --git a/e2e/README.md b/e2e/README.md index 5d339ee..48076c2 100644 --- a/e2e/README.md +++ b/e2e/README.md @@ -1,6 +1,6 @@ # E2E Tests -End-to-end tests using Playwright. +End-to-end tests using Playwright for the MCP Data Visualization Lab. ## Running Tests diff --git a/e2e/smoke.spec.ts-snapshots/screenshot.png b/e2e/smoke.spec.ts-snapshots/screenshot.png new file mode 100644 index 0000000..9b212f4 Binary files /dev/null and b/e2e/smoke.spec.ts-snapshots/screenshot.png differ diff --git a/packages/ai/README.md b/packages/ai/README.md index 875335f..187914d 100644 --- a/packages/ai/README.md +++ b/packages/ai/README.md @@ -1,7 +1,7 @@ # @repo/ai -Shared AI tooling for the [bEvr stack](../../README.md), built with Effect and -@effect/ai. +Shared AI tooling for the [MCP Data Visualization Lab](../../README.md), built with +Effect and @effect/ai. ## Overview @@ -51,4 +51,4 @@ const AppLive = ChatService.Default.pipe(Layer.provideMerge(AiLive)); ## Learn More - [@effect/ai Documentation](https://github.com/tim-smart/effect-io-ai) -- [bEvr Stack Overview](../../README.md) +- [Lab Overview](../../README.md) diff --git a/packages/domain/README.md b/packages/domain/README.md index 20e4155..b702bb7 100644 --- a/packages/domain/README.md +++ b/packages/domain/README.md @@ -1,7 +1,7 @@ # @repo/domain -Shared types and schemas for the [bEvr stack](../../README.md), built with -Effect Schema. +Shared types and schemas for the [MCP Data Visualization Lab](../../README.md), +built with Effect Schema. ## Overview @@ -44,4 +44,4 @@ src/ ## Learn More - [Effect Schema Documentation](https://effect.website/docs/schema) -- [bEvr Stack Overview](../../README.md) +- [Lab Overview](../../README.md) diff --git a/packages/observability/README.md b/packages/observability/README.md index 5f36149..c5cf59e 100644 --- a/packages/observability/README.md +++ b/packages/observability/README.md @@ -1,6 +1,7 @@ # @repo/observability -Shared OpenTelemetry setup for the [bEvr stack](../../README.md) using Effect. +Shared OpenTelemetry setup for the [MCP Data Visualization Lab](../../README.md) +using Effect. ## Overview @@ -53,4 +54,4 @@ const HttpLive = HttpLayerRouter.serve(Router).pipe( ## Learn More - [Effect OpenTelemetry](https://effect.website/docs/guides/opentelemetry) -- [bEvr Stack Overview](../../README.md) +- [Lab Overview](../../README.md) diff --git a/packages/presence/README.md b/packages/presence/README.md index e6b8bc0..aa86b66 100644 --- a/packages/presence/README.md +++ b/packages/presence/README.md @@ -1,7 +1,8 @@ # @repo/presence -Presence tracking service for the [bEvr stack](../../README.md). Maintains -connected client state and publishes presence events for WebSocket flows. +Presence tracking service for the [MCP Data Visualization Lab](../../README.md). +Maintains connected client state and publishes presence events for WebSocket +flows. ## Overview @@ -51,4 +52,4 @@ const program = Effect.gen(function* () { ## Learn More -- [bEvr Stack Overview](../../README.md) +- [Lab Overview](../../README.md) diff --git a/packages/widget-bar-chart/README.md b/packages/widget-bar-chart/README.md index c42cb8d..9f46f1f 100644 --- a/packages/widget-bar-chart/README.md +++ b/packages/widget-bar-chart/README.md @@ -1,6 +1,6 @@ # Bar Chart Widget -Builds a single-file MCP UI widget that renders a bar chart. +Single-file MCP App widget that renders a bar chart. ## Scripts diff --git a/packages/widget-line-chart/README.md b/packages/widget-line-chart/README.md index e713669..c67da3f 100644 --- a/packages/widget-line-chart/README.md +++ b/packages/widget-line-chart/README.md @@ -1,6 +1,6 @@ # Line Chart Widget -Builds a single-file MCP UI widget that renders a line chart. +Single-file MCP App widget that renders a line chart. ## Scripts diff --git a/packages/widget-scatterplot/README.md b/packages/widget-scatterplot/README.md index f945441..6a0a794 100644 --- a/packages/widget-scatterplot/README.md +++ b/packages/widget-scatterplot/README.md @@ -1,6 +1,6 @@ # Scatterplot Widget -Builds a single-file MCP UI widget that renders a scatterplot. +Single-file MCP App widget that renders a scatterplot. ## Scripts