Metadata-Version: 2.4
Name: frontone
Version: 0.1.2
Summary: MCP server that clones a backend GitHub repo, analyzes it, and scaffolds a complete React + Vite frontend.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: aja-codeintel>=0.1.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: gitpython>=3.1.0

﻿# frontone

MCP server that clones a backend GitHub repo, analyzes it using `aja-codeintel`,
and scaffolds a complete **React + Vite** frontend with domain-aware design system.

Works with any MCP client: Claude Code, Cursor, GitHub Copilot (VS Code), Windsurf.
No API key required.

---

## Install

```bash
pip install frontone
```

---

## Setup by client

### Claude Code

Add to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "frontone": {
      "command": "frontone",
      "env": {
        "GITHUB_TOKEN": "ghp_yourtoken"
      }
    }
  }
}
```

Then in Claude Code chat:

```
analyze_repo https://github.com/user/my-spring-app
```

or to fully scaffold:

```
scaffold_frontend https://github.com/user/my-spring-app
```

---

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "frontone": {
      "command": "frontone",
      "env": {
        "GITHUB_TOKEN": "ghp_yourtoken"
      }
    }
  }
}
```

---

### GitHub Copilot (VS Code)

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "frontone": {
      "command": "frontone",
      "env": {
        "GITHUB_TOKEN": "ghp_yourtoken"
      }
    }
  }
}
```

---

## Tools exposed

### `analyze_repo(repo_url)`

Clones the repo and returns a complete structured JSON overview with everything
the AI needs to build a working frontend:

| Field | What it contains |
|---|---|
| `models` | Entity classes with all field names and types |
| `relationships` | ManyToOne / OneToMany / ManyToMany edges |
| `dtos` | Request / response / shared DTOs with fields |
| `endpoints` | All routes with method, path, access (PUBLIC / AUTH / ADMIN) |
| `swagger` | Live OpenAPI spec if app is running, otherwise runtime URL |
| `auth` | JWT / OAuth2 / Session detection + how to send tokens |
| `base_path` | Global API prefix (e.g. `/api`) + ready-to-use axios baseURL |
| `pagination` | Spring Data Page response shape + which endpoints are paginated |
| `validation` | `@NotNull` / `@Size` / `@Email` etc. per field — used to build Zod schemas |
| `enums` | All enum types and their values — rendered as dropdowns |

---

### `scaffold_frontend(repo_url)`

Does everything `analyze_repo` does, then auto-detects the domain and writes
a complete React + Vite project to `C:/<repo-name>-frontend/`.

**Domain detection** — picks design system automatically:

| Domain | Detected from models | Design |
|---|---|---|
| `finance` | BankAccount, Transaction, Balance, Operation | Dark · emerald accent · monospace amounts |
| `healthcare` | Patient, Doctor, Appointment, Pet, Vet, Visit | Light · sky accent · rounded cards |
| `ecommerce` | Product, Order, Cart, Inventory, Category | Dark · orange accent · status badges |
| `social` | Post, Comment, Like, Follow, Feed | Dark · purple accent · engagement rows |
| `admin` | anything else | Light · indigo accent · compact tables |

**Generated file structure:**

```
C:/<repo-name>-frontend/
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
├── tailwind.config.ts
├── .env.example
└── src/
    ├── main.tsx
    ├── App.tsx
    ├── types/
    │   └── index.ts                  (all models, DTOs, enums, PageResponse<T>)
    ├── lib/
    │   ├── axios.ts                  (baseURL + JWT interceptor + 401 redirect)
    │   ├── queryClient.ts
    │   └── utils.ts
    ├── api/
    │   ├── auth.ts                   (login, register, logout)
    │   └── <entity>.ts               (getAll, getById, create, update, remove)
    ├── store/
    │   └── authStore.ts              (Zustand, token persisted to localStorage)
    ├── components/
    │   ├── layout/
    │   │   ├── Sidebar.tsx           (working nav links, active state, mobile drawer)
    │   │   ├── Topbar.tsx            (user info, logout button)
    │   │   ├── Layout.tsx
    │   │   └── AuthGuard.tsx         (redirects to /login if no token)
    │   ├── ui/
    │   │   ├── Button.tsx
    │   │   ├── Input.tsx
    │   │   ├── Badge.tsx
    │   │   ├── Modal.tsx
    │   │   ├── DataTable.tsx
    │   │   ├── Pagination.tsx        (only on paginated endpoints)
    │   │   ├── StatCard.tsx
    │   │   ├── EmptyState.tsx
    │   │   ├── Skeleton.tsx
    │   │   ├── ConfirmDialog.tsx
    │   │   ├── SearchInput.tsx
    │   │   └── Select.tsx
    │   ├── <Entity>Columns.tsx       (column definitions per entity)
    │   └── charts/
    │       └── <Entity>Chart.tsx     (Recharts, only for entities with numeric fields)
    ├── pages/
    │   ├── Register.tsx              (only if /register endpoint exists)
    │   ├── Login.tsx
    │   ├── Dashboard.tsx             (stat cards + charts + recent items)
    │   ├── <Entity>List.tsx          (search, sort, pagination, delete confirm)
    │   ├── <Entity>Detail.tsx
    │   ├── <Entity>Form.tsx          (create + edit, Zod validation, enum dropdowns)
    │   └── admin/
    │       ├── UserList.tsx          (only if /admin/ endpoints exist)
    │       └── UserForm.tsx
    └── routes/
        └── index.tsx                 (all routes, protected by AuthGuard)
```

**After scaffolding:**

```bash
cd C:/<repo-name>-frontend
npm install
npm run dev
```

---

## What the generated frontend does

- **Auth flow in correct order** — Register (if endpoint exists) → Login → protected routes
- **Every API call is typed** — uses exact paths from the backend, never guessed
- **Pagination** — only on endpoints that actually return `Page<T>`, with correct `?page=0&size=20` params
- **Forms with real validation** — Zod schemas built from `@NotNull`, `@Size`, `@Email`, `@Min`/`@Max` annotations
- **Enum dropdowns** — Select components populated with real enum values from the backend
- **Working sidebar** — every link points to a real route, active state via `useLocation()`
- **Charts on Dashboard** — Recharts AreaChart / BarChart using real entity data
- **Skeleton loading** — every async component has a loading state
- **Delete confirmation** — every delete action shows a ConfirmDialog before calling the API

---

## Private repos

Set `GITHUB_TOKEN` env variable. frontone injects it into the clone URL automatically.

```bash
set GITHUB_TOKEN=ghp_yourtoken    # Windows
export GITHUB_TOKEN=ghp_yourtoken # Mac/Linux
```

---

## How it works

```
You → MCP client (Claude / Cursor / Copilot)
            ↓
      frontone MCP server
            ↓
      git clone repo to C:/
            ↓
      aja-codeintel deep analysis
        · models + fields
        · relationships
        · DTOs + fields
        · endpoints + auth roles
        · JWT / OAuth2 / Session detection
        · API base path prefix
        · Spring Data pagination detection
        · @NotNull / @Size / @Email validation constraints
        · enum types + values
        · live Swagger / OpenAPI fetch
            ↓
      detect domain → pick design system
            ↓
      build ordered file manifest
            ↓
      generate all React + Vite files
            ↓
      write to C:/<repo-name>-frontend/
            ↓
      return summary JSON to MCP client
```
