mirror of
https://github.com/Shubhamsaboo/awesome-llm-apps.git
synced 2026-08-28 19:11:53 +08:00
docs: trim boilerplate from generative UI agent READMEs
Slim the generative_ui_agents example READMEs to user-facing content, removing generic boilerplate (Troubleshooting, Contributing, License sections) and deep internal dev/ops notes that belong in app dev docs. - ai-mcp-app-builder: drop Scripts reference tables, E2B template build, Agent-and-UI internals, React-keys RCA, Render walkthrough, and the lockfile note (144 -> 68 lines) - generative-ui-starter-project: drop boilerplate sections; collapse the repeated npm/pnpm/yarn/bun blocks to a single example (208 -> 162) - ai-financial-coach-agent: drop boilerplate sections; collapse package- manager blocks; rename duplicate "Documentation" heading to "Customization" (137 -> 80) - ai-dashboard-canvas-agent: drop Troubleshooting/Contributing/License (91 -> 69) - mcp-apps-generative-ui-showcase, ai-shadcn-component-generator: drop License section (short demo/deploy sections kept) Short deploy/demo sections retained; no broken references introduced.
This commit is contained in:
Shubhamsaboo
@@ -67,25 +67,3 @@ pnpm run dev
|
||||
- [ADK](https://google.github.io/adk-docs/)
|
||||
- [CopilotKit](https://github.com/CopilotKit/CopilotKit)
|
||||
- [AG-UI](https://docs.ag-ui.com/introduction)
|
||||
|
||||
---
|
||||
|
||||
### 🐛 Troubleshooting
|
||||
|
||||
**Agent connection issues?**
|
||||
|
||||
- Ensure ADK agent runs on port `8000`
|
||||
- Double-check `GOOGLE_API_KEY`
|
||||
- Confirm both servers boot without errors
|
||||
|
||||
---
|
||||
|
||||
### 🤝 Contributing
|
||||
|
||||
PRs and issues welcome — this Canvas is meant to be hacked on.
|
||||
|
||||
---
|
||||
|
||||
### 📄 License
|
||||
|
||||
MIT — see [LICENSE](./LICENSE) for details.
|
||||
|
||||
@@ -19,36 +19,16 @@ https://github.com/user-attachments/assets/edd4fa8d-ecc5-4b5d-90ff-27b21af5af94
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. Install dependencies using your preferred package manager:
|
||||
1. Install dependencies (npm, or pnpm/yarn/bun):
|
||||
|
||||
```bash
|
||||
# Using npm (default)
|
||||
npm install
|
||||
|
||||
# Using pnpm
|
||||
pnpm install
|
||||
|
||||
# Using yarn
|
||||
yarn install
|
||||
|
||||
# Using bun
|
||||
bun install
|
||||
```
|
||||
|
||||
2. Install Python dependencies for the ADK agent:
|
||||
|
||||
```bash
|
||||
# Using npm (default)
|
||||
npm run install:agent
|
||||
|
||||
# Using pnpm
|
||||
pnpm install:agent
|
||||
|
||||
# Using yarn
|
||||
yarn install:agent
|
||||
|
||||
# Using bun
|
||||
bun run install:agent
|
||||
```
|
||||
|
||||
> **Note:** This will automatically setup a `.venv` (virtual environment) inside the `agent` directory.
|
||||
@@ -68,17 +48,7 @@ export GOOGLE_API_KEY="your-google-api-key-here"
|
||||
4. Start the development server:
|
||||
|
||||
```bash
|
||||
# Using npm (default)
|
||||
npm run dev
|
||||
|
||||
# Using pnpm
|
||||
pnpm dev
|
||||
|
||||
# Using yarn
|
||||
yarn dev
|
||||
|
||||
# Using bun
|
||||
bun run dev
|
||||
```
|
||||
|
||||
This will start both the UI and agent servers concurrently.
|
||||
@@ -95,7 +65,7 @@ The following scripts can also be run using your preferred package manager:
|
||||
- `start` - Starts the production server
|
||||
- `install:agent` - Installs Python dependencies for the agent
|
||||
|
||||
## Documentation
|
||||
## Customization
|
||||
|
||||
The main UI component is in `src/app/page.tsx`. You can:
|
||||
|
||||
@@ -108,30 +78,3 @@ The main UI component is in `src/app/page.tsx`. You can:
|
||||
- [ADK Documentation](https://google.github.io/adk-docs/) - Learn more about the ADK and its features
|
||||
- [CopilotKit Documentation](https://docs.copilotkit.ai) - Explore CopilotKit's capabilities
|
||||
- [Next.js Documentation](https://nextjs.org/docs) - Learn about Next.js features and API
|
||||
|
||||
## Contributing
|
||||
|
||||
Feel free to submit issues and enhancement requests! This starter is designed to be easily extensible.
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the LICENSE file for details.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Agent Connection Issues
|
||||
|
||||
If you see "I'm having trouble connecting to my tools", make sure:
|
||||
|
||||
1. The ADK agent is running on port 8000
|
||||
2. Your Google API key is set correctly
|
||||
3. Both servers started successfully
|
||||
|
||||
### Python Dependencies
|
||||
|
||||
If you encounter Python import errors:
|
||||
|
||||
```bash
|
||||
cd agent
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
@@ -14,8 +14,6 @@ https://github.com/user-attachments/assets/4bb35806-5e42-43c0-a8fe-01c0d1e5b8b3
|
||||
- [pnpm](https://pnpm.io/installation) (required for the workspace)
|
||||
- OpenAI API key (`OPENAI_API_KEY`); optional **`OPENAI_MODEL`** for `/api/mastra-agent` (default **`gpt-5.5`**)
|
||||
|
||||
> **Lockfile:** **`pnpm-lock.yaml` is committed** and should stay in version control so installs are reproducible (`--frozen-lockfile`). This repo’s `.gitignore` only excludes `package-lock.json`, `yarn.lock`, and `bun.lockb` — not pnpm’s lockfile.
|
||||
|
||||
## Getting started
|
||||
|
||||
From the project root (`generative_ui_agents/ai-mcp-app-builder`):
|
||||
@@ -39,59 +37,6 @@ pnpm dev
|
||||
|
||||
Open the URL shown by Next (usually `http://localhost:3000`).
|
||||
|
||||
## Scripts reference
|
||||
|
||||
### Root (`package.json`)
|
||||
|
||||
| Script | Description |
|
||||
| --------------------------- | ------------------------------------------------------------------------------- |
|
||||
| `pnpm dev` | Turbo: all packages’ `dev` scripts |
|
||||
| `pnpm build` | Turbo: all packages’ `build` (for `web`, runs **`prebuild`** first — see below) |
|
||||
| `pnpm lint` | Turbo lint |
|
||||
| `pnpm clean` / `pnpm fresh` | Remove installs / lockfile helpers (see script definitions) |
|
||||
|
||||
### `apps/web`
|
||||
|
||||
| Script | Description |
|
||||
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `pnpm dev` | Next.js dev (Turbopack) |
|
||||
| `pnpm build` | Runs **`prebuild`** → **`pack-download-kit`** (writes **`.download-kit/base.tar.gz`** for full app kit download), then **`next build`** |
|
||||
| `pnpm pack-download-kit` | Regenerate **`.download-kit/base.tar.gz`** without a full Next build |
|
||||
| `pnpm start` | Production Next server |
|
||||
| `pnpm lint` | ESLint |
|
||||
| `pnpm run test:download-kit` | Integration test: Next + E2B + **`POST /api/workspace/download`** (see **`apps/web/test/`)** |
|
||||
| `pnpm run test:e2b-download` | Smoke test: E2B tarball only |
|
||||
| `pnpm run dev:mcp` | Starts the **Three.js** sample MCP from **`apps/threejs-server`** (for local MCP alongside web) |
|
||||
|
||||
Manual scripts under **`apps/web/test/`**: run from **`apps/web`** as `node test/<file>.mjs` (paths and env documented in each file).
|
||||
|
||||
### E2B sandbox template (`apps/mcp-use-server`)
|
||||
|
||||
The agent provisions sandboxes from an E2B **template** defined in **`template.ts`**. Rebuild the image when you change dependencies, tools, or widgets there.
|
||||
|
||||
| Script | When to use | Command (from repo root) |
|
||||
| --------------------------------------- | ------------------------------ | ----------------------------------------------------------------------- |
|
||||
| **Dev template** (`mcp-use-server-dev`) | Day-to-day iteration | `cd apps/mcp-use-server && npx tsx --env-file=../../.env build.dev.ts` |
|
||||
| **Prod template** (`mcp-use-server`) | Stable snapshot for production | `cd apps/mcp-use-server && npx tsx --env-file=../../.env build.prod.ts` |
|
||||
|
||||
Requirements: **`E2B_API_KEY`** in `.env` (or environment). The CLI prints a **`BuildInfo`** object; set **`E2B_TEMPLATE`** to **`templateId`** from that output (and the same in your hosting dashboard). Template **name** (e.g. `mcp-use-server-dev`) is not the same as **`templateId`**.
|
||||
|
||||
## Agent and UI
|
||||
|
||||
The app title is **MCP App builder** (subtitle **Powered by CopilotKit**), logo **`apps/web/app/image.png`**, agent route **`/api/mastra-agent`**. Header CTAs use **`NEXT_PUBLIC_HEADER_*`** (and **`NEXT_PUBLIC_GITHUB_REPO_URL`** for the secondary link; code default points at **this demo repo**). Chat starters: **`NEXT_PUBLIC_CHAT_STARTER_PROMPTS`** (JSON) or **three** built-in bounded demos — tic tac toe, tip calculator, dice roller. Reference CopilotKit route: **`apps/web/app/api/copilotkit/route.ts`**.
|
||||
|
||||
**Starter prompts** use **`useCopilotChatSuggestions`** (`ChatSuggestions.tsx`) with v2 **`CopilotChat`**.
|
||||
|
||||
**Post-provision test chips:** frontend action **`show_mcp_test_prompts`** (`McpTestPromptsAction.tsx`) — JSON string of `{ label, message }[]` for clickable chips (**`appendMessage`**).
|
||||
|
||||
**Download:** **`restart_server`** / sidebar download can return a **full app kit** (`.tar.gz`): E2B workspace merged into **`mcp-apps-starter/`** when **`apps/web/.download-kit/base.tar.gz`** exists (created by **`pnpm build`** / **`prebuild`** in `apps/web`). Otherwise download is **MCP-only**.
|
||||
|
||||
**Debug agent traffic:** set **`MASTRA_AGENT_DEBUG=1`** in `.env` for verbose **`/api/mastra-agent`** logs (see `.env.example`).
|
||||
|
||||
### Duplicate React keys (Mastra agent) — RCA and fix
|
||||
|
||||
Mastra can reuse the same `messageId` for tool-call parents and text events; CopilotKit then collides keys. **`mastra-agent/route.ts`** remaps ids when collisions are detected — see inline comments.
|
||||
|
||||
## Dynamic MCP UI (sidebar)
|
||||
|
||||
- **MCP servers:** add/remove by URL (+ optional `serverId`); list is sent as **`x-mcp-servers`**. Built-in default: **Excalidraw** (`https://mcp.excalidraw.com`). Override via **`NEXT_PUBLIC_DEFAULT_MCP_SERVERS`** / **`DEFAULT_MCP_SERVERS`**.
|
||||
@@ -112,19 +57,6 @@ Mastra can reuse the same `messageId` for tool-call parents and text events; Cop
|
||||
| `E2B_TEMPLATE` | **`templateId`** from `Template.build` output after **`build.dev.ts`** / **`build.prod.ts`** |
|
||||
| `E2B_REPO_URL` | Used when **`E2B_TEMPLATE`** is empty — clones repo into sandbox (slower cold start). Default in code: **`mcp-use-server-template`** GitHub URL |
|
||||
|
||||
## Hosting on Render
|
||||
|
||||
1. Push this repo to GitHub/GitLab.
|
||||
2. In the Render dashboard, go to **Blueprints** and select your repo — Render auto-detects `render.yaml`.
|
||||
3. Set secret env vars in the dashboard: at least **`OPENAI_API_KEY`**; for sandboxes add **`E2B_API_KEY`** + **`E2B_TEMPLATE`**.
|
||||
4. Deploy. The Blueprint configures build/start commands, `NODE_VERSION`, and `HOSTNAME` automatically.
|
||||
|
||||
Render runs a long-lived Node.js process (not serverless), so there are no per-function timeout limits.
|
||||
|
||||
### Agent tool pattern (sidebar preview)
|
||||
|
||||
Widget tools should include **`_meta["ui/previewData"]`** for offline sidebar preview (example: **`apps/mcp-use-server/tools/product-search.ts`**).
|
||||
|
||||
## Documentation
|
||||
|
||||
**UI entry:** `apps/web/app/page.tsx` (theme, layout, CopilotKit wiring).
|
||||
@@ -134,11 +66,3 @@ Widget tools should include **`_meta["ui/previewData"]`** for offline sidebar pr
|
||||
- [CopilotKit](https://docs.copilotkit.ai)
|
||||
- [Next.js](https://nextjs.org/docs)
|
||||
- [MCP Apps / UI](https://mcpui.dev/guide/introduction)
|
||||
|
||||
## Contributing
|
||||
|
||||
Issues and PRs welcome.
|
||||
|
||||
## License
|
||||
|
||||
MIT — see **LICENSE**.
|
||||
|
||||
@@ -58,7 +58,3 @@ UI runs at [localhost:5173](http://localhost:5173). Runtime on 4000, agent on 81
|
||||
[](https://render.com/deploy)
|
||||
|
||||
Or connect your repo — `render.yaml` defines everything.
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
@@ -20,20 +20,10 @@ https://github.com/user-attachments/assets/47761912-d46a-4fb3-b9bd-cb41ddd02e34
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. Install dependencies using your preferred package manager:
|
||||
1. Install dependencies (npm, or pnpm/yarn/bun):
|
||||
|
||||
```bash
|
||||
# Using npm (default)
|
||||
npm install
|
||||
|
||||
# Using pnpm
|
||||
pnpm install
|
||||
|
||||
# Using yarn
|
||||
yarn install
|
||||
|
||||
# Using bun
|
||||
bun install
|
||||
```
|
||||
|
||||
This will also install the Python agent dependencies via `uv sync`.
|
||||
@@ -53,17 +43,7 @@ OPENAI_API_KEY=your-openai-api-key-here
|
||||
3. Start the development server:
|
||||
|
||||
```bash
|
||||
# Using npm (default)
|
||||
npm run dev
|
||||
|
||||
# Using pnpm
|
||||
pnpm dev
|
||||
|
||||
# Using yarn
|
||||
yarn dev
|
||||
|
||||
# Using bun
|
||||
bun run dev
|
||||
```
|
||||
|
||||
This will start both the UI and agent servers concurrently.
|
||||
@@ -180,29 +160,3 @@ Both patterns use the same catalog on the frontend — the difference is where t
|
||||
|
||||
- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/) - Learn more about LangGraph and its features
|
||||
- [CopilotKit Documentation](https://docs.copilotkit.ai) - Explore CopilotKit's capabilities
|
||||
|
||||
## Contributing
|
||||
|
||||
Feel free to submit issues and enhancement requests! This starter is designed to be easily extensible.
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the LICENSE file for details.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Agent Connection Issues
|
||||
|
||||
If you see "I'm having trouble connecting to my tools", make sure:
|
||||
|
||||
1. The LangGraph agent is running on port 8123
|
||||
2. Your OpenAI API key is set correctly
|
||||
3. Both servers started successfully
|
||||
|
||||
### Python Dependencies
|
||||
|
||||
If you encounter Python import errors:
|
||||
|
||||
```bash
|
||||
npm run install:agent
|
||||
```
|
||||
|
||||
@@ -137,7 +137,3 @@ The demo is deployed on Railway with two services:
|
||||
| MCP Server | https://mcp-server-production-bbb4.up.railway.app |
|
||||
|
||||
For production, set `MCP_SERVER_URL` environment variable to point to your deployed MCP server.
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
Reference in New Issue
Block a user