modelcontextprotocol
diff --git a/‎examples/chat-ui/.gitignore
Lines changed: 30 additions & 0 deletions b/‎examples/chat-ui/.gitignore
Lines changed: 30 additions & 0 deletions
diff --git a/‎examples/chat-ui/.prettierrc
Lines changed: 7 additions & 0 deletions b/‎examples/chat-ui/.prettierrc
Lines changed: 7 additions & 0 deletions
diff --git a/‎examples/chat-ui/AGENT.md
Lines changed: 73 additions & 0 deletions b/‎examples/chat-ui/AGENT.md
Lines changed: 73 additions & 0 deletions
diff --git a/‎examples/chat-ui/README.md
Lines changed: 30 additions & 0 deletions b/‎examples/chat-ui/README.md
Lines changed: 30 additions & 0 deletions
diff --git a/‎examples/chat-ui/api/index.ts
Lines changed: 118 additions & 0 deletions b/‎examples/chat-ui/api/index.ts
Lines changed: 118 additions & 0 deletions
diff --git a/‎examples/chat-ui/e2e/build.spec.ts
Lines changed: 45 additions & 0 deletions b/‎examples/chat-ui/e2e/build.spec.ts
Lines changed: 45 additions & 0 deletions
@@ -0,0 +1,30 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+.wrangler
+
+# Playwright test results
+test-results/
+playwright-report/
@@ -0,0 +1,7 @@
+{
+  "trailingComma": "es5",
+  "tabWidth": 2,
+  "semi": false,
+  "singleQuote": true,
+  "printWidth": 140
+}
@@ -0,0 +1,73 @@
+# AI Chat Template - Development Guide
+
+## Commands
+- **Dev server**: `pnpm dev`
+- **Build**: `pnpm build` (runs TypeScript compilation then Vite build)
+- **Lint**: `pnpm lint` (ESLint)
+- **Deploy**: `pnpm deploy` (builds and deploys with Wrangler)
+- **Test**: `pnpm test` (Playwright E2E tests)
+- **Test UI**: `pnpm test:ui` (Playwright test runner with UI)
+- **Test headed**: `pnpm test:headed` (Run tests in visible browser)
+
+## Code Style
+- **Formatting**: Prettier with 2-space tabs, single quotes, no semicolons, 140 char line width
+- **Imports**: Use `.tsx`/`.ts` extensions in imports, group by external/internal
+- **Components**: React FC with explicit typing, PascalCase names
+- **Hooks**: Custom hooks start with `use`, camelCase
+- **Types**: Define interfaces in `src/types/index.ts`, use `type` for unions
+- **Files**: Use PascalCase for components, camelCase for hooks/utilities
+- **State**: Use proper TypeScript typing for all state variables
+- **Error handling**: Use try/catch blocks with proper error propagation
+- **Database**: IndexedDB with typed interfaces, async/await pattern
+- **Styling**: Tailwind CSS classes, responsive design patterns
+
+## Tech Stack
+React 19, TypeScript, Vite, Tailwind CSS, Hono API, Cloudflare Workers, IndexedDB, React Router, use-mcp
+
+## Chat UI Specific Guidelines
+
+### Background Animation
+- Use CSS `hue-rotate` filter for color cycling (more performant than gradient animation)
+- Isolate animations to `::before` pseudo-elements with `z-index: -1` to prevent inheritance
+- Use `background-size: 100% 100vh` and `background-repeat: repeat-y` for repeating patterns
+- Initialize with random animation delay using CSS custom properties
+
+### Modal Patterns
+- Use `rgba(0,0,0,0.8)` for modal backdrops (avoid gradients that cause banding)
+- Implement click-outside-to-dismiss with `onClick` on backdrop and `stopPropagation` on content
+- Add `cursor-pointer` to all clickable elements including close buttons
+- Use `document.body.style.overflow = 'hidden'` to prevent background scrolling
+
+### MCP Server Management
+- Store multiple servers in localStorage as JSON array (`mcpServers`)
+- Track tool counts separately (`mcpServerToolCounts`) for disabled servers
+- Use server-specific IDs for state management
+- Each MCP server gets unique `useMcp` hook instance for proper isolation
+- OAuth state parameter automatically handles multiple server differentiation
+
+### State Persistence
+- Use localStorage for user preferences (model selection, server configurations)
+- Use sessionStorage for temporary state (single server URL in legacy components)
+- Clear related data when removing servers or models
+
+### UI Indicators
+- Use emoji-based indicators (🧠 for models, 🔌 for MCP servers)
+- Format counts as `enabled/total` (e.g., "1/2 servers, 3/5 tools")
+- Place model selector on left, MCP servers on right for balance
+- Show "none" instead of red symbols for cleaner unconfigured states
+
+### Component Organization
+- Keep disabled components in React tree but hidden with CSS (`{false && ...}`)
+- This prevents MCP connections from being destroyed when modals close
+- Use conditional rendering sparingly, prefer CSS visibility for stateful components
+
+### Routing and OAuth
+- Use React Router for OAuth callback routes (`/oauth/callback`)
+- OAuth callback should match main app styling with loading indicators
+- use-mcp library handles multiple server OAuth flows automatically via state parameters
+
+### Performance Considerations
+- Avoid animating gradients directly (causes repainting)
+- Use transform and filter animations (hardware accelerated)
+- Aggregate tools from multiple sources efficiently
+- Minimize localStorage reads in render loops
@@ -0,0 +1,30 @@
+# AI chat template
+
+An unofficial template for ⚛️ React ⨉ ⚡️ Vite ⨉ ⛅️ Cloudflare Workers AI.
+
+Full-stack AI chat application using Workers for the APIs (using the Cloudflare [vite-plugin](https://www.npmjs.com/package/@cloudflare/vite-plugin)) and Vite for the React application (hosted using [Workers Static Assets](https://developers.cloudflare.com/workers/static-assets/)). Provides chat functionality with [Workers AI](https://developers.cloudflare.com/workers-ai/), stores conversations in the browser's [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API), and uses [ai-sdk](https://sdk.vercel.ai/docs/introduction), [tailwindcss](https://tailwindcss.com/) and [workers-ai-provider](https://github.com/cloudflare/workers-ai-provider).
+
+## Get started
+
+Create the project using [create-cloudflare](https://www.npmjs.com/package/create-cloudflare):
+
+```sh
+npm create cloudflare@latest -- --template thomasgauvin/ai-chat-template
+```
+
+Run the project and deploy it:
+
+```sh
+cd <project-name>
+npm install
+npm run dev
+```
+
+```
+npm run deploy
+```
+
+## What's next?
+
+- Change the name of the package (in `package.json`)
+- Change the name of the worker (in `wrangler.jsonc`)
@@ -0,0 +1,118 @@
+import type { LanguageModelV1StreamPart } from 'ai'
+import { streamText, extractReasoningMiddleware, wrapLanguageModel } from 'ai'
+import { createWorkersAI } from 'workers-ai-provider'
+import { Hono } from 'hono'
+
+interface Env {
+  ASSETS: Fetcher
+  AI: Ai
+}
+
+type message = {
+  role: 'system' | 'user' | 'assistant' | 'data'
+  content: string
+}
+
+const app = new Hono<{ Bindings: Env }>()
+
+// Handle the /api/chat endpoint
+app.post('/api/chat', async (c) => {
+  try {
+    const { messages, reasoning }: { messages: message[]; reasoning: boolean } = await c.req.json()
+
+    const workersai = createWorkersAI({ binding: c.env.AI })
+
+    // Choose model based on reasoning preference
+    const model = reasoning
+      ? wrapLanguageModel({
+          model: workersai('@cf/deepseek-ai/deepseek-r1-distill-qwen-32b'),
+          middleware: [
+            extractReasoningMiddleware({ tagName: 'think' }),
+            //custom middleware to inject <think> tag at the beginning of a reasoning if it is missing
+            {
+              wrapGenerate: async ({ doGenerate }) => {
+                const result = await doGenerate()
+
+                if (!result.text?.includes('<think>')) {
+                  result.text = `<think>${result.text}`
+                }
+
+                return result
+              },
+              wrapStream: async ({ doStream }) => {
+                const { stream, ...rest } = await doStream()
+
+                let generatedText = ''
+                const transformStream = new TransformStream<LanguageModelV1StreamPart, LanguageModelV1StreamPart>({
+                  transform(chunk, controller) {
+                    //we are manually adding the <think> tag because some times, distills of reasoning models omit it
+                    if (chunk.type === 'text-delta') {
+                      if (!generatedText.includes('<think>')) {
+                        generatedText += '<think>'
+                        controller.enqueue({
+                          type: 'text-delta',
+                          textDelta: '<think>',
+                        })
+                      }
+                      generatedText += chunk.textDelta
+                    }
+
+                    controller.enqueue(chunk)
+                  },
+                })
+
+                return {
+                  stream: stream.pipeThrough(transformStream),
+                  ...rest,
+                }
+              },
+            },
+          ],
+        })
+      : workersai('@cf/meta/llama-3.3-70b-instruct-fp8-fast')
+
+    const systemPrompt: message = {
+      role: 'system',
+      content: `
+        - Do not wrap your responses in html tags.
+        - Do not apply any formatting to your responses.
+        - You are an expert conversational chatbot. Your objective is to be as helpful as possible.
+        - You must keep your responses relevant to the user's prompt.
+        - You must respond with a maximum of 512 tokens (300 words). 
+        - You must respond clearly and concisely, and explain your logic if required.
+        - You must not provide any personal information.
+        - Do not respond with your own personal opinions, and avoid topics unrelated to the user's prompt.
+        ${
+          messages.length <= 1 &&
+          `- Important REMINDER: You MUST provide a 5 word title at the END of your response using <chat-title> </chat-title> tags. 
+          If you do not do this, this session will error.
+          For example, <chat-title>Hello and Welcome</chat-title> Hi, how can I help you today?
+          `
+        }
+      `,
+    }
+
+    const text = await streamText({
+      model,
+      messages: [systemPrompt, ...messages],
+      maxTokens: 2048,
+      maxRetries: 3,
+    })
+
+    return text.toDataStreamResponse({
+      sendReasoning: true,
+    })
+  } catch (error) {
+    return c.json({ error: `Chat completion failed. ${(error as Error)?.message}` }, 500)
+  }
+})
+
+// Handle static assets and fallback routes
+app.all('*', async (c) => {
+  if (c.env.ASSETS) {
+    return c.env.ASSETS.fetch(c.req.raw)
+  }
+  return c.text('Not found', 404)
+})
+
+export default app
@@ -0,0 +1,45 @@
+import { test, expect } from '@playwright/test'
+import { exec } from 'child_process'
+import { promisify } from 'util'
+
+const execAsync = promisify(exec)
+
+interface ExecError extends Error {
+  stdout?: string
+  stderr?: string
+}
+
+test.describe('Build Tests', () => {
+  test('should build without type errors', async () => {
+    try {
+      const { stderr } = await execAsync('pnpm build', {
+        cwd: process.cwd(),
+        timeout: 60000,
+      })
+
+      // Check for TypeScript compilation errors
+      expect(stderr).not.toContain('error TS')
+      expect(stderr).not.toContain('Type error')
+    } catch (error) {
+      const execError = error as ExecError
+      console.error('Build failed:', execError.stdout, execError.stderr)
+      throw new Error(`Build failed: ${execError.message}`)
+    }
+  })
+
+  test('should lint without errors', async () => {
+    try {
+      const { stderr } = await execAsync('pnpm lint', {
+        cwd: process.cwd(),
+        timeout: 30000,
+      })
+
+      // ESLint should pass without errors
+      expect(stderr).not.toContain('error')
+    } catch (error) {
+      const execError = error as ExecError
+      console.error('Lint failed:', execError.stdout, execError.stderr)
+      throw new Error(`Lint failed: ${execError.message}`)
+    }
+  })
+})