# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Agent Fox is a SaaS product that provides MCP (Model Context Protocol) services for API documentation. It lets LLMs efficiently query OpenAPI docs through multi-level retrieval instead of dumping entire documents into context.

## Commands

```bash
# Development (requires Docker for PostgreSQL)
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

# Or run services individually (requires local PostgreSQL on port 5432)
pnpm dev:server    # Express API on :3000
pnpm dev:mcp       # MCP service on :3001
pnpm dev:web       # Vite dev server on :5173

# Database
pnpm db:generate   # Generate Prisma client after schema changes
pnpm db:migrate    # Create and apply migrations
pnpm db:push       # Push schema directly (dev only)

# Build all packages
pnpm build
```

## Architecture

pnpm monorepo with 4 packages sharing TypeScript config (`tsconfig.base.json`):

- **`packages/shared`** — Prisma client + shared types. All other packages depend on this. Must be built first (`tsc`) before server/mcp can run.
- **`packages/server`** (port 3000) — Express 5 backend API. JWT auth, project CRUD, OpenAPI import/parsing, module/endpoint management.
- **`packages/mcp`** (port 3001) — Independent Express process exposing MCP tools via Streamable HTTP transport. Authenticates with project-level API keys (not user JWTs).
- **`packages/web`** (port 5173) — React 19 + Vite + TailwindCSS SPA. Proxies `/api` to server in dev mode.

### Data Flow

1. User imports OpenAPI doc (JSON/YAML/URL) via web UI
2. For URL imports, frontend fetches the content (supports localhost/intranet), falling back to server proxy `/api/fetch-spec` for CORS-blocked URLs. Server receives parsed spec objects only.
3. Server validates with `@apidevtools/swagger-parser`, dereferences all `$ref`s
3. Parses into Module (from tags or path prefixes) and Endpoint records in PostgreSQL
4. User gets a project ID + API key
5. LLM connects to MCP service at `/mcp/:projectId` with API key
6. MCP provides 5 tools for progressive drill-down (overview → modules → endpoints → detail → search)

### MCP Tools (in `packages/mcp/src/tools/`)

The 5 tools are designed for minimal token usage per call (~200-2000 tokens each vs 10,000+ for full doc dump):

- `get_project_overview` — project name, version, module summary
- `list_modules` — modules with descriptions
- `list_endpoints(moduleId)` — endpoint summaries in a module
- `get_endpoint_detail(endpointId)` — full params, request body, responses
- `search_endpoints(keyword, moduleId?)` — cross-endpoint keyword search

### Key Patterns

- **API responses**: All endpoints return `{ success: boolean, data?: T, error?: { code, message } }`
- **Auth**: User auth uses JWT dual-token (15min access + 7d refresh). MCP auth uses project API keys (`afk_` prefix, bcrypt hashed).
- **OAuth**: Google/GitHub via server-side flow. Redirect URL passed through OAuth state store. `validateState()` returns `{ valid, redirect }`. Apple login not yet implemented.
- **MCP SDK imports**: Use `@modelcontextprotocol/sdk/server/mcp.js` (not `@modelcontextprotocol/server`). Tool registration uses `server.tool(name, description, zodShape, handler)`.
- **Swagger 2.0 + OpenAPI 3.x**: Parser handles both. For Swagger 2, body params are converted to requestBody format.
- **Docker dev mode**: Server/MCP use `build` stage + volume mounts for hot reload. Shared must be built inside container before server/mcp start.
- **Docker production**: Dockerfiles use `npm install` + global `tsc` (not pnpm — symlinks break on overlay2). `workspace:*` refs are replaced with `file:` refs via `sed`.

### Deployment

- **Production**: Docker Compose on `ubuntu@43.130.35.66:/opt/1panel/apps/agentfox`. Deploy via `/deploy` skill.
- **Port mapping**: web=8088 (80 is OpenResty), server=3000, mcp=3001. PostgreSQL is internal only (no host port).
- **`.env`**: Local `.env` is the single source of truth, synced to server on deploy. `.env.example` must stay aligned.
- **Nginx**: Web container's nginx proxies `/api/` → server, `/mcp/` → mcp. External Nginx only needs to proxy to port 8088.
- **Migrations**: `scripts/migrate-and-start.sh` auto-runs `prisma migrate deploy` before server starts. Always create migrations for schema changes (`prisma migrate dev --name <name> --create-only`), never rely on `db push` alone.
- **Domain**: `www.agentfoxapp.com` — not hardcoded anywhere, configured via `OAUTH_CALLBACK_BASE_URL` and `FRONTEND_URL` env vars.

### Database (Prisma schema at `prisma/schema.prisma`)

Core models: User → Project → Module → Endpoint. Project stores full dereferenced OpenAPI spec as JSONB. Module tracks its source (tag/path_prefix/manual). Endpoint stores parameters, requestBody, responses as JSONB.