agent-fox/CLAUDE.md

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

# 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 $refs
4. Parses into Module (from tags or path prefixes) and Endpoint records in PostgreSQL
5. User gets a project ID + API key
6. LLM connects to MCP service at /mcp/:projectId with API key
7. 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.