# 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. 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).
- **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 `deps` build stage + volume mounts for hot reload. Web uses Vite `build` stage. Shared must be built inside container before server/mcp start.

### 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.