{"id":"docs/fastapp-agent-project-bootstrap","source":"docs","sourceLabel":"docs/","sourcePath":"docs/FASTAPP_AGENT_PROJECT_BOOTSTRAP.md","routePath":"/fastapp/public-docs/page/docs/fastapp-agent-project-bootstrap","rawPath":"/fastapp/public-docs/raw/docs/fastapp-agent-project-bootstrap","slug":["docs","fastapp-agent-project-bootstrap"],"slugPath":"docs/fastapp-agent-project-bootstrap","title":"FastApp Agent Project Bootstrap","description":"This document defines the first structured LLM/MCP ready agent surface for FastApp.","headings":["FastApp Agent Project Bootstrap","Goal","Why This Layer Exists","First Agent","Routes","MCP Transport","Tool Model","Tool Families","Dry Run Support","Current Orchestration Status","Suggested Next Steps"],"wordCount":622,"markdown":"# FastApp Agent Project Bootstrap\r\n\r\nThis document defines the first structured LLM/MCP-ready agent surface for FastApp.\r\n\r\n## Goal\r\n\r\nExpose one agent that can:\r\n\r\n- Read public FastApp documentation.\r\n- Inspect existing apps.\r\n- Create or update a generic app through Nuxt APIs.\r\n- Operate records inside a generic app through `/api/v1/data/:app/:object`.\r\n\r\n## Why This Layer Exists\r\n\r\nThe existing `fastapp-agent` route is useful as a prompt-driven playground, but it is not a stable integration contract for external orchestration. A project-level agent surface needs:\r\n\r\n- A fixed agent identity.\r\n- A typed tool catalog.\r\n- Machine-readable input schemas.\r\n- A deterministic execution endpoint.\r\n- Public discovery routes that LLM and MCP wrappers can consume.\r\n\r\n## First Agent\r\n\r\nAgent id: `fastapp-generic-app-operator`\r\n\r\nResponsibilities:\r\n\r\n- Retrieve public docs before acting.\r\n- Inspect apps before mutating them.\r\n- Create or patch apps through `/api/app`.\r\n- List, create, patch, and delete records through `/api/v1/data`.\r\n- Apply granular schema mutations for modules, objects, properties, relations, actions, and pages.\r\n- Manage permissions and memberships through structured RBAC tools.\r\n\r\n## Routes\r\n\r\nPublic discovery:\r\n\r\n- `/fastapp/public-docs/llms.txt`\r\n- `/fastapp/public-docs/manifest.json`\r\n- `/fastapp/public-docs/agents.json`\r\n\r\nExecution:\r\n\r\n- `GET /api/agent/catalog`\r\n- `POST /api/agent/execute`\r\n- `GET /api/mcp`\r\n- `POST /api/mcp`\r\n\r\n## MCP Transport\r\n\r\n`POST /api/mcp` exposes a JSON-RPC transport over the same agent registry and executor.\r\nIt does not define a second tool contract; `tools/list` reads `server/utils/agents/registry.ts`\r\nand `tools/call` forwards execution to `/api/agent/execute`.\r\n\r\nSupported methods:\r\n\r\n- `initialize`\r\n- `tools/list` (`listTools` alias)\r\n- `tools/call` (`callTool` alias)\r\n\r\nExample `tools/call` payload:\r\n\r\n```json\r\n{\r\n  \"jsonrpc\": \"2.0\",\r\n  \"id\": \"1\",\r\n  \"method\": \"tools/call\",\r\n  \"params\": {\r\n    \"agentId\": \"fastapp-generic-app-operator\",\r\n    \"name\": \"create_record\",\r\n    \"arguments\": {\r\n      \"app\": \"crm\",\r\n      \"object\": \"lead\",\r\n      \"data\": { \"name\": \"Ada\" }\r\n    },\r\n    \"dryRun\": true\r\n  }\r\n}\r\n```\r\n\r\nWrite behavior is inherited from `/api/agent/execute`: writes default to dry-run previews,\r\nRBAC is enforced by the underlying Nuxt routes, and execution/audit logs are emitted by the\r\nagent executor plus the MCP adapter.\r\n\r\n## Tool Model\r\n\r\nEach tool definition contains:\r\n\r\n- `name`\r\n- `title`\r\n- `description`\r\n- `readOnly`\r\n- `api` binding to an existing Nuxt route\r\n- `inputSchema`\r\n- optional `examples`\r\n\r\nThe executor validates input against the declared schema before forwarding the call to the underlying Nuxt API.\r\n\r\n## Tool Families\r\n\r\n- Discovery: public docs and app catalog lookup.\r\n- App lifecycle: create, patch, delete full apps.\r\n- App schema: upsert and delete modules, objects, properties, relations, actions, and pages.\r\n- Data: list, create, patch, and delete generic object records.\r\n- Data intelligence: aggregate, profile, and suggest filters for any object using the same generic data route and RBAC constraints.\r\n- RBAC: list roles, permissions, and memberships; create/update/delete permissions; assign/update/remove memberships.\r\n\r\nCurrent limitation:\r\n\r\n- Role creation is still blocked by the existing backend policy in `/api/v1/data/:app/role`.\r\n\r\n## Dry Run Support\r\n\r\n`POST /api/agent/execute` accepts `dryRun: true`.\r\n\r\nIn dry-run mode the executor does not mutate state. It returns the exact internal request shape that would be sent to the Nuxt API. This is useful for:\r\n\r\n- tool debugging\r\n- MCP wrappers\r\n- approval workflows\r\n- prompt iteration\r\n\r\n## Current Orchestration Status\r\n\r\nImplemented in the unified `/api/fastapp-agent` route:\r\n\r\n- Server-side multi-step tool loop over the shared agent catalog.\r\n- Server-managed prompt assembly with a small frontend instruction hint.\r\n- Compiled generic app context for object/property/relation/action ranking.\r\n- Conditional planner and verifier calls to reduce token usage on simple requests.\r\n- Write-policy handling that converts backend mutations to dry-run previews unless explicit confirmation is present.\r\n- Generic record field matching through aliases, normalized names, property metadata, and semantic schema scoring.\r\n- Frontend `ui_apply_filters` action that syncs tool queries to generic table/list filters and sort.\r\n- Generic data intelligence tools: `aggregate_records`, `profile_object_data`, and `suggest_filters`.\r\n- Dynamic CRUD view capability context so the agent can see generic filter/sort/search/write support, active fields, metric fields, date fields, relation fields, and current query state.\r\n- Resilient agent routing: stale browser `agent_id` values fall back to `fastapp-generic-app-operator`, and the frontend Copilot scopes saved execution agents to the app that produced them.\r\n- App-scoped data routes in the playground legacy path instead of hardcoded object-only endpoints.\r\n\r\n## Suggested Next Steps\r\n\r\n1. Add persistent per-user/per-app agent memory for compressed summaries, preferences, and previous decisions.\r\n2. Add structured frontend result cards for aggregate/profile/list tool outputs instead of relying on assistant prose parsing.\r\n3. Add a dedicated frontend approval UI for dry-run write previews.\r\n4. Keep MCP clients aligned with `/api/agent/catalog` and `/api/agent/execute` as tools evolve.\r\n5. Continue migrating remaining legacy playground delta/data action flows to structured tool previews.\r\n6. Add pgvector-backed schema/document retrieval when compiled context ranking is not enough.\r\n"}