80 lines
4.8 KiB
Markdown
80 lines
4.8 KiB
Markdown
# 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.
|