# FastApp Agent Project Bootstrap

This document defines the first structured LLM/MCP-ready agent surface for FastApp.

## Goal

Expose one agent that can:

- Read public FastApp documentation.
- Inspect existing apps.
- Create or update a generic app through Nuxt APIs.
- Operate records inside a generic app through `/api/v1/data/:app/:object`.

## Why This Layer Exists

The 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:

- A fixed agent identity.
- A typed tool catalog.
- Machine-readable input schemas.
- A deterministic execution endpoint.
- Public discovery routes that LLM and MCP wrappers can consume.

## First Agent

Agent id: `fastapp-generic-app-operator`

Responsibilities:

- Retrieve public docs before acting.
- Inspect apps before mutating them.
- Create or patch apps through `/api/app`.
- List, create, patch, and delete records through `/api/v1/data`.
- Apply granular schema mutations for modules, objects, properties, relations, actions, and pages.
- Manage permissions and memberships through structured RBAC tools.

## Routes

Public discovery:

- `/fastapp/public-docs/llms.txt`
- `/fastapp/public-docs/manifest.json`
- `/fastapp/public-docs/agents.json`

Execution:

- `GET /api/agent/catalog`
- `POST /api/agent/execute`
- `GET /api/mcp`
- `POST /api/mcp`

## MCP Transport

`POST /api/mcp` exposes a JSON-RPC transport over the same agent registry and executor.
It does not define a second tool contract; `tools/list` reads `server/utils/agents/registry.ts`
and `tools/call` forwards execution to `/api/agent/execute`.

Supported methods:

- `initialize`
- `tools/list` (`listTools` alias)
- `tools/call` (`callTool` alias)

Example `tools/call` payload:

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "agentId": "fastapp-generic-app-operator",
    "name": "create_record",
    "arguments": {
      "app": "crm",
      "object": "lead",
      "data": { "name": "Ada" }
    },
    "dryRun": true
  }
}
```

Write behavior is inherited from `/api/agent/execute`: writes default to dry-run previews,
RBAC is enforced by the underlying Nuxt routes, and execution/audit logs are emitted by the
agent executor plus the MCP adapter.

## Tool Model

Each tool definition contains:

- `name`
- `title`
- `description`
- `readOnly`
- `api` binding to an existing Nuxt route
- `inputSchema`
- optional `examples`

The executor validates input against the declared schema before forwarding the call to the underlying Nuxt API.

## Tool Families

- Discovery: public docs and app catalog lookup.
- App lifecycle: create, patch, delete full apps.
- App schema: upsert and delete modules, objects, properties, relations, actions, and pages.
- Data: list, create, patch, and delete generic object records.
- Data intelligence: aggregate, profile, and suggest filters for any object using the same generic data route and RBAC constraints.
- RBAC: list roles, permissions, and memberships; create/update/delete permissions; assign/update/remove memberships.

Current limitation:

- Role creation is still blocked by the existing backend policy in `/api/v1/data/:app/role`.

## Dry Run Support

`POST /api/agent/execute` accepts `dryRun: true`.

In 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:

- tool debugging
- MCP wrappers
- approval workflows
- prompt iteration

## Current Orchestration Status

Implemented in the unified `/api/fastapp-agent` route:

- Server-side multi-step tool loop over the shared agent catalog.
- Server-managed prompt assembly with a small frontend instruction hint.
- Compiled generic app context for object/property/relation/action ranking.
- Conditional planner and verifier calls to reduce token usage on simple requests.
- Write-policy handling that converts backend mutations to dry-run previews unless explicit confirmation is present.
- Generic record field matching through aliases, normalized names, property metadata, and semantic schema scoring.
- Frontend `ui_apply_filters` action that syncs tool queries to generic table/list filters and sort.
- Generic data intelligence tools: `aggregate_records`, `profile_object_data`, and `suggest_filters`.
- 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.
- 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.
- App-scoped data routes in the playground legacy path instead of hardcoded object-only endpoints.

## Suggested Next Steps

1. Add persistent per-user/per-app agent memory for compressed summaries, preferences, and previous decisions.
2. Add structured frontend result cards for aggregate/profile/list tool outputs instead of relying on assistant prose parsing.
3. Add a dedicated frontend approval UI for dry-run write previews.
4. Keep MCP clients aligned with `/api/agent/catalog` and `/api/agent/execute` as tools evolve.
5. Continue migrating remaining legacy playground delta/data action flows to structured tool previews.
6. Add pgvector-backed schema/document retrieval when compiled context ranking is not enough.