From 85346ce80584dbfa0915c4c28bd4d269016b3e2a Mon Sep 17 00:00:00 2001
From: YANG JIANKUAN <tim.yee@hotmail.com>
Date: Thu, 2 Apr 2026 16:05:29 +0800
Subject: [PATCH] docs: add CLAUDE.md for Claude Code context

---
 CLAUDE.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..c0d3aab
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,67 @@
+# 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.