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

User imports OpenAPI doc (JSON/YAML/URL) via web UI
Server validates with @apidevtools/swagger-parser, dereferences all $refs
Parses into Module (from tags or path prefixes) and Endpoint records in PostgreSQL
User gets a project ID + API key
LLM connects to MCP service at /mcp/:projectId with API key
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.

3.5 KiB Raw Blame History