+ "usage": "# Usage Instructions\n\nYou can start customizing the template frontend by modifying `src/App.tsx`. The page auto-updates as you edit the file.\n\nThe chat API is powered by Cloudflare Agents (Which is a wrapper on Durable Objects) and accessible through the worker at `/api/chat/:sessionId/*` routes defined in `worker/userRoutes.ts`. **Use it!**\n\nThe agent system uses Durable Objects for persistent state management and conversation history. `/api/chat/:sessionId/*` should be used without modifications for any conversation support. There is also a control plane durable object for session management name AppController.\n\nThere are already several models presupplied with the template along with proper configuration (apikeys and base url). You should develop using them instead of adding mock methods.\n\n- Built with:\n * **React + Vite** for fast frontend development with hot module replacement\n * **Cloudflare Agents SDK** for stateful agent management with persistent Durable Objects\n * **Model Context Protocol (MCP)** client for real server integration\n * **OpenAI SDK** for AI model integration via Cloudflare AI Gateway\n * **Production MCP Servers** including Cloudflare Bindings and Observability\n * **Tailwind CSS** for utility-first styling with glass morphism effects\n * **Framer Motion** for smooth chat animations and loading states\n * **Lucide Icons** (React) for modern, consistent iconography\n * **Shadcn/UI** (v2.3.0) for accessible chat components built on Radix UI primitives\n * **TypeScript** for type safety and extensible architecture\n * **Durable Objects** for control plane for database or session management\n\n- Agent Features:\n * **Real MCP Integration**: Connects to actual MCP servers, not simulated implementations\n * **Cloudflare MCP Servers**: Direct integration with Cloudflare Bindings and Observability servers\n * **Intelligent Tool Usage**: AI automatically detects when to use tools (D1, R2, Workers, Web browsing)\n * **Multi-Model Support**: Switch between GPT-4o, Gemini 2.0/2.5 Flash/Pro, Claude Opus 4\n * **Production Tools**: Query D1 databases, manage R2 buckets, get Worker analytics\n * **Web Browsing**: Browse and extract content from web pages through MCP server\n * **Persistent Conversations**: Maintains chat history using Durable Objects state in Cloudflare Agents.\n * **Tool Visualization**: Shows which tools were used with results in the chat interface\n\n- Adding New MCP Servers:\n * **Step 1**: Add server configuration to `initializeCloudflareServers()` in `worker/mcp-client.ts`\n * **Step 2**: Tools are automatically discovered and registered from MCP server definitions\n * **Step 3**: The system automatically routes tool calls to appropriate MCP servers\n * **Real Protocol**: Uses actual MCP protocol for server communication, not simulation\n\n- Environment Variables:\n * **CF_AI_BASE_URL**: Cloudflare AI Gateway base URL (required)\n * **CF_AI_API_KEY**: API key for AI Gateway access (required)\n * **CHAT_AGENT**: Durable Object binding name for agent persistence\n\n- Restrictions:\n * **Environment variables**: CF_AI_BASE_URL and CF_AI_API_KEY must be configured\n * **API keys**: Never expose API keys to client-side - they're server-side only in worker\n * **Tool Safety**: Tool functions should validate inputs and handle errors gracefully\n * **Use Agents SDK patterns**: Extend Agent class, use setState for persistence\n\n- Styling:\n * Must generate **fully responsive** and beautiful UI with agent-focused design\n * Use Shadcn preinstalled components rather than writing custom ones when possible\n * Use **Tailwind's spacing, layout, and typography utilities** for all components\n * Include tool interaction indicators and loading states for better UX\n\n- Components:\n * All Shadcn components are available and can be imported from `@/components/ui/...`\n * Current chat uses: `Button`, `Input`, `Card`, `Select`, `Badge` for the interface\n * Tool results are displayed with badges and icons from the UI library\n * Do not write custom components if shadcn components are available\n * Icons from Lucide should be imported directly from `lucide-react`\n\n- Animation:\n * Use `framer-motion`'s `motion` components for chat message animations\n * Animate tool usage indicators, model selection, and loading states\n * You can integrate variants and transitions using Tailwind utility classes alongside motion props\n\n- Worker Architecture (Backend, APIs):\n * **`worker/agent.ts`**: Main agent class \n * **`worker/userRoutes.ts`**: HTTP routing for agent API and session managementå\n * **`worker/chat.ts`**: OpenAI integration and conversation logic \n * **`worker/mcp-client.ts`**: MCP client for real server integration\n * **`worker/tools.ts`**: Tool routing and MCP server coordination\n * **`worker/config.ts`**: Centralized configuration\n * **`worker/types.ts`**: TypeScript interfaces and type definitions\n * **`worker/app-controller.ts`**: Control plane durable object for session management\n\n---\n\n## Available MCP Servers and Tools\n\nThe template uses the official MCP SDK with Cloudflare's production servers:\n\n### Cloudflare Documentation MCP Server:\n- Access to Cloudflare documentation and resources\n- Connected via `https://docs.mcp.cloudflare.com/sse`\n\n### Cloudflare Browser MCP Server:\n- Web browsing capabilities through Cloudflare\n- Connected via `https://browser.mcp.cloudflare.com/sse`\n\n### Custom Tools:\n- **`get_weather`** - Weather information (example custom tool)\n\n### MCP Server Integration Example\n\nAdding a new MCP server (in `worker/mcp-client.ts`):\n\n```typescript\nconst MCP_SERVERS: MCPServerConfig[] = [\n {\n name: 'cloudflare-docs',\n command: 'npx',\n args: ['mcp-remote', 'https://docs.mcp.cloudflare.com/sse']\n },\n];\n```\n\nThe system automatically:\n- Connects to MCP servers using proper transport\n- Uses official MCP SDK schemas for validation\n- Discovers tools with proper error handling\n- Routes tool calls to the correct server\n- Parses results using MCP result schemas\n\nComponents available:\n```sh\n$ ls -1 src/components/ui\naccordion.tsx\nalert-dialog.tsx\nalert.tsx\naspect-ratio.tsx\navatar.tsx\nbadge.tsx\nbreadcrumb.tsx\nbutton.tsx\ncalendar.tsx\ncard.tsx\ncarousel.tsx\nchart.tsx\ncheckbox.tsx\ncollapsible.tsx\ncommand.tsx\ncontext-menu.tsx\ndialog.tsx\ndrawer.tsx\ndropdown-menu.tsx\nform.tsx\nhover-card.tsx\ninput-otp.tsx\ninput.tsx\nlabel.tsx\nmenubar.tsx\nnavigation-menu.tsx\npagination.tsx\npopover.tsx\nprogress.tsx\nradio-group.tsx\nresizable.tsx\nscroll-area.tsx\nselect.tsx\nseparator.tsx\nsheet.tsx\nsidebar.tsx\nskeleton.tsx\nslider.tsx\nsonner.tsx\nswitch.tsx\ntable.tsx\ntabs.tsx\ntextarea.tsx\ntoast.tsx\ntoggle-group.tsx\ntoggle.tsx\ntooltip.tsx\n```\n\n# Important Notes\n- Conversations and persistence are already handled by the template. Utilize existing utilities and apis to build something greater.\n\n# Available bindings:\n**Only The following bindings are to be used in the project! Do not use any other bindings or remove/replace any of the bindings**\n- `CHAT_AGENT`: A durable object binding for the chat agent\n- `APP_CONTROLLER`: A durable object binding for the app controller\n\n# IMPORTANT NOTE: If AI capabilities are required, you must inform the user that although this project has AI capaibilities, there is no way to pass API keys and thus AI inferencing won't work. Users must export the app to their github, then make necessary changes and deploy it themselves to have it work. This is due to security reasons but we are implementing it in a secure way, and this would be available soon.\nAdd the above note in an appropriate and visible location in the app - like in the footer or in the chat interface or as a modal"
0 commit comments